diff --git a/en/python/resources/beta/index.md b/en/python/resources/beta/index.md index 714d1bc1..2c6f3a39 100644 --- a/en/python/resources/beta/index.md +++ b/en/python/resources/beta/index.md @@ -1,4656 +1,3949 @@ # Beta -# ChatKit - -## Domain Types +# Responses -### ChatKit Workflow +## -- `class ChatKitWorkflow: …` +`beta.responses.connect()` - Workflow metadata and state returned for the session. +**** `` - - `id: str` +Connect to a persistent Responses API WebSocket. Send `response.create` events and receive response stream events over the socket. - Identifier of the workflow backing the session. +### Example - - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` +```python +import os +from openai import OpenAI - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +client.beta.responses.connect() +``` - - `str` +## Create a model response - - `bool` +`beta.responses.create(ResponseCreateParams**kwargs) -> BetaResponse` - - `float` +**post** `/responses?beta=true` - - `tracing: Tracing` +Creates a model response. Provide [text](https://platform.openai.com/docs/guides/text) or +[image](https://platform.openai.com/docs/guides/images) inputs to generate [text](https://platform.openai.com/docs/guides/text) +or [JSON](https://platform.openai.com/docs/guides/structured-outputs) outputs. Have the model call +your own [custom code](https://platform.openai.com/docs/guides/function-calling) or use built-in +[tools](https://platform.openai.com/docs/guides/tools) like [web search](https://platform.openai.com/docs/guides/tools-web-search) +or [file search](https://platform.openai.com/docs/guides/tools-file-search) to use your own data +as input for the model's response. - Tracing settings applied to the workflow. +### Parameters - - `enabled: bool` +- `background: Optional[bool]` - Indicates whether tracing is enabled. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `version: Optional[str]` +- `context_management: Optional[Iterable[ContextManagement]]` - Specific workflow version used for the session. Defaults to null when using the latest deployment. + Context management configuration for this request. -# Sessions + - `type: str` -## Cancel chat session + The context management entry type. Currently only 'compaction' is supported. -`beta.chatkit.sessions.cancel(strsession_id) -> ChatSession` + - `compact_threshold: Optional[int]` -**post** `/chatkit/sessions/{session_id}/cancel` + Token threshold at which compaction should be triggered for this entry. -Cancel chat session +- `conversation: Optional[Conversation]` -### Parameters + The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. -- `session_id: str` + - `str` -### Returns + The unique ID of the conversation. -- `class ChatSession: …` + - `class BetaResponseConversationParam: …` - Represents a ChatKit session and its resolved configuration. + The conversation that this response belongs to. - `id: str` - Identifier for the ChatKit session. + The unique ID of the conversation. - - `chatkit_configuration: ChatSessionChatKitConfiguration` +- `include: Optional[List[BetaResponseIncludable]]` - Resolved ChatKit feature configuration for the session. + Specify additional output data to include in the model response. Currently supported values are: - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - Automatic thread titling preferences. + - `"file_search_call.results"` - - `enabled: bool` + - `"web_search_call.results"` - Whether automatic thread titling is enabled. + - `"web_search_call.action.sources"` - - `file_upload: ChatSessionFileUpload` + - `"message.input_image.image_url"` - Upload settings for the session. + - `"computer_call_output.output.image_url"` - - `enabled: bool` + - `"code_interpreter_call.outputs"` - Indicates if uploads are enabled for the session. + - `"reasoning.encrypted_content"` - - `max_file_size: Optional[int]` + - `"message.output_text.logprobs"` - Maximum upload size in megabytes. +- `input: Optional[Union[str, BetaResponseInputParam]]` - - `max_files: Optional[int]` + Text, image, or file inputs to the model, used to generate a response. - Maximum number of uploads allowed during the session. + Learn more: - - `history: ChatSessionHistory` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Image inputs](https://platform.openai.com/docs/guides/images) + - [File inputs](https://platform.openai.com/docs/guides/pdf-files) + - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) + - [Function calling](https://platform.openai.com/docs/guides/function-calling) - History retention configuration. + - `str` - - `enabled: bool` + A text input to the model, equivalent to a text input with the + `user` role. - Indicates if chat history is persisted for the session. + - `Iterable[BetaResponseInputItemParam]` - - `recent_threads: Optional[int]` + - `class BetaEasyInputMessage: …` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `client_secret: str` + - `content: Union[str, BetaResponseInputMessageContentList]` - Ephemeral client secret that authenticates session requests. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `expires_at: int` + - `str` - Unix timestamp (in seconds) for when the session expires. + A text input to the model. - - `max_requests_per_1_minute: int` + - `List[BetaResponseInputContent]` - Convenience copy of the per-minute request limit. + - `class BetaResponseInputText: …` - - `object: Literal["chatkit.session"]` + A text input to the model. - Type discriminator that is always `chatkit.session`. + - `text: str` - - `"chatkit.session"` + The text input to the model. - - `rate_limits: ChatSessionRateLimits` + - `type: Literal["input_text"]` - Resolved rate limit values. + The type of the input item. Always `input_text`. - - `max_requests_per_1_minute: int` + - `"input_text"` - Maximum allowed requests per one-minute window. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `status: ChatSessionStatus` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Current lifecycle state of the session. + - `mode: Literal["explicit"]` - - `"active"` + The breakpoint mode. Always `explicit`. - - `"expired"` + - `"explicit"` - - `"cancelled"` + - `class BetaResponseInputImage: …` - - `user: str` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - User identifier associated with the session. + - `detail: Literal["low", "high", "auto", "original"]` - - `workflow: ChatKitWorkflow` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Workflow metadata for the session. + - `"low"` - - `id: str` + - `"high"` - Identifier of the workflow backing the session. + - `"auto"` - - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` + - `"original"` - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `type: Literal["input_image"]` - - `str` + The type of the input item. Always `input_image`. - - `bool` + - `"input_image"` - - `float` + - `file_id: Optional[str]` - - `tracing: Tracing` + The ID of the file to be sent to the model. - Tracing settings applied to the workflow. + - `image_url: Optional[str]` - - `enabled: bool` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Indicates whether tracing is enabled. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `version: Optional[str]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `mode: Literal["explicit"]` -### Example + The breakpoint mode. Always `explicit`. -```python -import os -from openai import OpenAI + - `"explicit"` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -chat_session = client.beta.chatkit.sessions.cancel( - "cksess_123", -) -print(chat_session.id) -``` + - `class BetaResponseInputFile: …` -#### Response + A file input to the model. -```json -{ - "id": "id", - "chatkit_configuration": { - "automatic_thread_titling": { - "enabled": true - }, - "file_upload": { - "enabled": true, - "max_file_size": 0, - "max_files": 0 - }, - "history": { - "enabled": true, - "recent_threads": 0 - } - }, - "client_secret": "client_secret", - "expires_at": 0, - "max_requests_per_1_minute": 0, - "object": "chatkit.session", - "rate_limits": { - "max_requests_per_1_minute": 0 - }, - "status": "active", - "user": "user", - "workflow": { - "id": "id", - "state_variables": { - "foo": "string" - }, - "tracing": { - "enabled": true - }, - "version": "version" - } -} -``` + - `type: Literal["input_file"]` -### Example + The type of the input item. Always `input_file`. -```python -from openai import OpenAI + - `"input_file"` -client = OpenAI() -chat_session = client.beta.chatkit.sessions.cancel( - "cksess_123", -) -print(chat_session.id) -``` + - `detail: Optional[Literal["auto", "low", "high"]]` -#### Response + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. -```json -{ - "id": "cksess_123", - "object": "chatkit.session", - "workflow": { - "id": "workflow_alpha", - "version": "1" - }, - "scope": { - "customer_id": "cust_456" - }, - "max_requests_per_1_minute": 30, - "ttl_seconds": 900, - "status": "cancelled", - "cancelled_at": 1712345678 -} -``` + - `"auto"` -## Create ChatKit session + - `"low"` -`beta.chatkit.sessions.create(SessionCreateParams**kwargs) -> ChatSession` + - `"high"` -**post** `/chatkit/sessions` + - `file_data: Optional[str]` -Create ChatKit session + The content of the file to be sent to the model. -### Parameters + - `file_id: Optional[str]` -- `user: str` + The ID of the file to be sent to the model. - A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. + - `file_url: Optional[str]` -- `workflow: ChatSessionWorkflowParam` + The URL of the file to be sent to the model. - Workflow that powers the session. + - `filename: Optional[str]` - - `id: str` + The name of the file to be sent to the model. - Identifier for the workflow invoked by the session. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. + - `mode: Literal["explicit"]` - - `str` + The breakpoint mode. Always `explicit`. - - `bool` + - `"explicit"` - - `float` + - `role: Literal["user", "assistant", "system", "developer"]` - - `tracing: Optional[Tracing]` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. + - `"user"` - - `enabled: Optional[bool]` + - `"assistant"` - Whether tracing is enabled during the session. Defaults to true. + - `"system"` - - `version: Optional[str]` + - `"developer"` - Specific workflow version to run. Defaults to the latest deployed version. + - `phase: Optional[Literal["commentary", "final_answer"]]` -- `chatkit_configuration: Optional[ChatSessionChatKitConfigurationParam]` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - Optional overrides for ChatKit runtime configuration features + - `"commentary"` - - `automatic_thread_titling: Optional[AutomaticThreadTitling]` + - `"final_answer"` - Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. + - `type: Optional[Literal["message"]]` - - `enabled: Optional[bool]` + The type of the message input. Always `message`. - Enable automatic thread title generation. Defaults to true. + - `"message"` - - `file_upload: Optional[FileUpload]` + - `class Message: …` - Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `enabled: Optional[bool]` + - `content: BetaResponseInputMessageContentList` - Enable uploads for this session. Defaults to false. + A list of one or many input items to the model, containing different content + types. - - `max_file_size: Optional[int]` + - `class BetaResponseInputText: …` - Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. + A text input to the model. - - `max_files: Optional[int]` + - `class BetaResponseInputImage: …` - Maximum number of files that can be uploaded to the session. Defaults to 10. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `history: Optional[History]` + - `class BetaResponseInputFile: …` - Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). + A file input to the model. - - `enabled: Optional[bool]` + - `role: Literal["user", "system", "developer"]` - Enables chat users to access previous ChatKit threads. Defaults to true. + The role of the message input. One of `user`, `system`, or `developer`. - - `recent_threads: Optional[int]` + - `"user"` - Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. + - `"system"` -- `expires_after: Optional[ChatSessionExpiresAfterParam]` + - `"developer"` - Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. + - `agent: Optional[MessageAgent]` - - `anchor: Literal["created_at"]` + The agent that produced this item. - Base timestamp used to calculate expiration. Currently fixed to `created_at`. + - `agent_name: str` - - `"created_at"` + The canonical name of the agent that produced this item. - - `seconds: int` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Number of seconds after the anchor when the session expires. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -- `rate_limits: Optional[ChatSessionRateLimitsParam]` + - `"in_progress"` - Optional override for per-minute request limits. When omitted, defaults to 10. + - `"completed"` - - `max_requests_per_1_minute: Optional[int]` + - `"incomplete"` - Maximum number of requests allowed per minute for the session. Defaults to 10. + - `type: Optional[Literal["message"]]` -### Returns + The type of the message input. Always set to `message`. -- `class ChatSession: …` + - `"message"` - Represents a ChatKit session and its resolved configuration. + - `class BetaResponseOutputMessage: …` - - `id: str` + An output message from the model. - Identifier for the ChatKit session. + - `id: str` - - `chatkit_configuration: ChatSessionChatKitConfiguration` + The unique ID of the output message. - Resolved ChatKit feature configuration for the session. + - `content: List[Content]` - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + The content of the output message. - Automatic thread titling preferences. + - `class BetaResponseOutputText: …` - - `enabled: bool` + A text output from the model. - Whether automatic thread titling is enabled. + - `annotations: List[Annotation]` - - `file_upload: ChatSessionFileUpload` + The annotations of the text output. - Upload settings for the session. + - `class AnnotationFileCitation: …` - - `enabled: bool` + A citation to a file. - Indicates if uploads are enabled for the session. + - `file_id: str` - - `max_file_size: Optional[int]` + The ID of the file. - Maximum upload size in megabytes. + - `filename: str` - - `max_files: Optional[int]` + The filename of the file cited. - Maximum number of uploads allowed during the session. + - `index: int` - - `history: ChatSessionHistory` + The index of the file in the list of files. - History retention configuration. + - `type: Literal["file_citation"]` - - `enabled: bool` + The type of the file citation. Always `file_citation`. - Indicates if chat history is persisted for the session. + - `"file_citation"` - - `recent_threads: Optional[int]` + - `class AnnotationURLCitation: …` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + A citation for a web resource used to generate a model response. - - `client_secret: str` + - `end_index: int` - Ephemeral client secret that authenticates session requests. + The index of the last character of the URL citation in the message. - - `expires_at: int` + - `start_index: int` - Unix timestamp (in seconds) for when the session expires. + The index of the first character of the URL citation in the message. - - `max_requests_per_1_minute: int` + - `title: str` - Convenience copy of the per-minute request limit. + The title of the web resource. - - `object: Literal["chatkit.session"]` + - `type: Literal["url_citation"]` - Type discriminator that is always `chatkit.session`. + The type of the URL citation. Always `url_citation`. - - `"chatkit.session"` + - `"url_citation"` - - `rate_limits: ChatSessionRateLimits` + - `url: str` - Resolved rate limit values. + The URL of the web resource. - - `max_requests_per_1_minute: int` + - `class AnnotationContainerFileCitation: …` - Maximum allowed requests per one-minute window. + A citation for a container file used to generate a model response. - - `status: ChatSessionStatus` + - `container_id: str` - Current lifecycle state of the session. + The ID of the container file. - - `"active"` + - `end_index: int` - - `"expired"` + The index of the last character of the container file citation in the message. - - `"cancelled"` + - `file_id: str` - - `user: str` + The ID of the file. - User identifier associated with the session. + - `filename: str` - - `workflow: ChatKitWorkflow` + The filename of the container file cited. - Workflow metadata for the session. + - `start_index: int` - - `id: str` + The index of the first character of the container file citation in the message. - Identifier of the workflow backing the session. + - `type: Literal["container_file_citation"]` - - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` + The type of the container file citation. Always `container_file_citation`. - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `"container_file_citation"` - - `str` + - `class AnnotationFilePath: …` - - `bool` + A path to a file. - - `float` + - `file_id: str` - - `tracing: Tracing` + The ID of the file. - Tracing settings applied to the workflow. + - `index: int` - - `enabled: bool` + The index of the file in the list of files. - Indicates whether tracing is enabled. + - `type: Literal["file_path"]` - - `version: Optional[str]` + The type of the file path. Always `file_path`. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `"file_path"` -### Example + - `text: str` -```python -import os -from openai import OpenAI + The text output from the model. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -chat_session = client.beta.chatkit.sessions.create( - user="x", - workflow={ - "id": "id" - }, -) -print(chat_session.id) -``` + - `type: Literal["output_text"]` -#### Response + The type of the output text. Always `output_text`. -```json -{ - "id": "id", - "chatkit_configuration": { - "automatic_thread_titling": { - "enabled": true - }, - "file_upload": { - "enabled": true, - "max_file_size": 0, - "max_files": 0 - }, - "history": { - "enabled": true, - "recent_threads": 0 - } - }, - "client_secret": "client_secret", - "expires_at": 0, - "max_requests_per_1_minute": 0, - "object": "chatkit.session", - "rate_limits": { - "max_requests_per_1_minute": 0 - }, - "status": "active", - "user": "user", - "workflow": { - "id": "id", - "state_variables": { - "foo": "string" - }, - "tracing": { - "enabled": true - }, - "version": "version" - } -} -``` + - `"output_text"` -### Example + - `logprobs: Optional[List[Logprob]]` -```python -from openai import OpenAI + - `token: str` -client = OpenAI() -chat_session = client.beta.chatkit.sessions.create( - user="user", - workflow={ - "id": "id" - }, -) -print(chat_session.id) -``` + - `bytes: List[int]` -#### Response + - `logprob: float` -```json -{ - "client_secret": "chatkit_token_123", - "expires_at": 1735689600, - "workflow": { - "id": "workflow_alpha", - "version": "2024-10-01" - }, - "scope": { - "project": "alpha", - "environment": "staging" - }, - "max_requests_per_1_minute": 60, - "max_requests_per_session": 500, - "status": "active" -} -``` + - `top_logprobs: List[LogprobTopLogprob]` -# Threads + - `token: str` -## List ChatKit thread items + - `bytes: List[int]` -`beta.chatkit.threads.list_items(strthread_id, ThreadListItemsParams**kwargs) -> SyncConversationCursorPage[Data]` + - `logprob: float` -**get** `/chatkit/threads/{thread_id}/items` + - `class BetaResponseOutputRefusal: …` -List ChatKit thread items + A refusal from the model. -### Parameters + - `refusal: str` -- `thread_id: str` + The refusal explanation from the model. -- `after: Optional[str]` + - `type: Literal["refusal"]` - List items created after this thread item ID. Defaults to null for the first page. + The type of the refusal. Always `refusal`. -- `before: Optional[str]` + - `"refusal"` - List items created before this thread item ID. Defaults to null for the newest results. + - `role: Literal["assistant"]` -- `limit: Optional[int]` + The role of the output message. Always `assistant`. - Maximum number of thread items to return. Defaults to 20. + - `"assistant"` -- `order: Optional[Literal["asc", "desc"]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - Sort order for results by creation time. Defaults to `desc`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"asc"` + - `"in_progress"` - - `"desc"` + - `"completed"` -### Returns + - `"incomplete"` -- `Data` + - `type: Literal["message"]` - - `class ChatKitThreadUserMessageItem: …` + The type of the output message. Always `message`. - User-authored messages within a thread. + - `"message"` - - `id: str` + - `agent: Optional[Agent]` - Identifier of the thread item. + The agent that produced this item. - - `attachments: List[ChatKitAttachment]` + - `agent_name: str` - Attachments associated with the user message. Defaults to an empty list. + The canonical name of the agent that produced this item. - - `id: str` + - `phase: Optional[Literal["commentary", "final_answer"]]` - Identifier for the attachment. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `mime_type: str` + - `"commentary"` - MIME type of the attachment. + - `"final_answer"` - - `name: str` + - `class BetaResponseFileSearchToolCall: …` - Original display name for the attachment. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `preview_url: Optional[str]` + - `id: str` - Preview URL for rendering the attachment inline. + The unique ID of the file search tool call. - - `type: Literal["image", "file"]` + - `queries: List[str]` - Attachment discriminator. + The queries used to search for files. - - `"image"` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - - `"file"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `content: List[Content]` + - `"in_progress"` - Ordered content elements supplied by the user. + - `"searching"` - - `class ContentInputText: …` + - `"completed"` - Text block that a user contributed to the thread. + - `"incomplete"` - - `text: str` + - `"failed"` - Plain-text content supplied by the user. + - `type: Literal["file_search_call"]` - - `type: Literal["input_text"]` + The type of the file search tool call. Always `file_search_call`. - Type discriminator that is always `input_text`. + - `"file_search_call"` - - `"input_text"` + - `agent: Optional[Agent]` - - `class ContentQuotedText: …` + The agent that produced this item. - Quoted snippet that the user referenced in their message. + - `agent_name: str` - - `text: str` + The canonical name of the agent that produced this item. - Quoted text content. + - `results: Optional[List[Result]]` - - `type: Literal["quoted_text"]` + The results of the file search tool call. - Type discriminator that is always `quoted_text`. + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - - `"quoted_text"` + 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, booleans, or numbers. - - `created_at: int` + - `str` - Unix timestamp (in seconds) for when the item was created. + - `float` - - `inference_options: Optional[InferenceOptions]` + - `bool` - Inference overrides applied to the message. Defaults to null when unset. + - `file_id: Optional[str]` - - `model: Optional[str]` + The unique ID of the file. - Model name that generated the response. Defaults to null when using the session default. + - `filename: Optional[str]` - - `tool_choice: Optional[InferenceOptionsToolChoice]` + The name of the file. - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `score: Optional[float]` - - `id: str` + The relevance score of the file - a value between 0 and 1. - Identifier of the requested tool. + - `text: Optional[str]` - - `object: Literal["chatkit.thread_item"]` + The text that was retrieved from the file. - Type discriminator that is always `chatkit.thread_item`. + - `class BetaResponseComputerToolCall: …` - - `"chatkit.thread_item"` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `thread_id: str` + - `id: str` - Identifier of the parent thread. + The unique ID of the computer call. - - `type: Literal["chatkit.user_message"]` + - `call_id: str` - - `"chatkit.user_message"` + An identifier used when responding to the tool call with output. - - `class ChatKitThreadAssistantMessageItem: …` + - `pending_safety_checks: List[PendingSafetyCheck]` - Assistant-authored message within a thread. + The pending safety checks for the computer call. - `id: str` - Identifier of the thread item. + The ID of the pending safety check. - - `content: List[ChatKitResponseOutputText]` + - `code: Optional[str]` - Ordered assistant response segments. + The type of the pending safety check. - - `annotations: List[Annotation]` + - `message: Optional[str]` - Ordered list of annotations attached to the response text. + Details about the pending safety check. - - `class AnnotationFile: …` + - `status: Literal["in_progress", "completed", "incomplete"]` - Annotation that references an uploaded file. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `source: AnnotationFileSource` + - `"in_progress"` - File attachment referenced by the annotation. + - `"completed"` - - `filename: str` + - `"incomplete"` - Filename referenced by the annotation. + - `type: Literal["computer_call"]` - - `type: Literal["file"]` + The type of the computer call. Always `computer_call`. - Type discriminator that is always `file`. + - `"computer_call"` - - `"file"` + - `action: Optional[BetaComputerAction]` - - `type: Literal["file"]` + A click action. - Type discriminator that is always `file` for this annotation. + - `class Click: …` - - `"file"` + A click action. - - `class AnnotationURL: …` + - `button: Literal["left", "right", "wheel", 2 more]` - Annotation that references a URL. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `source: AnnotationURLSource` + - `"left"` - URL referenced by the annotation. + - `"right"` - - `type: Literal["url"]` + - `"wheel"` - Type discriminator that is always `url`. + - `"back"` - - `"url"` + - `"forward"` - - `url: str` + - `type: Literal["click"]` - URL referenced by the annotation. + Specifies the event type. For a click action, this property is always `click`. - - `type: Literal["url"]` + - `"click"` - Type discriminator that is always `url` for this annotation. + - `x: int` - - `"url"` + The x-coordinate where the click occurred. - - `text: str` + - `y: int` - Assistant generated text. + The y-coordinate where the click occurred. - - `type: Literal["output_text"]` + - `keys: Optional[List[str]]` - Type discriminator that is always `output_text`. + The keys being held while clicking. - - `"output_text"` + - `class DoubleClick: …` - - `created_at: int` + A double click action. - Unix timestamp (in seconds) for when the item was created. + - `keys: Optional[List[str]]` - - `object: Literal["chatkit.thread_item"]` + The keys being held while double-clicking. - Type discriminator that is always `chatkit.thread_item`. + - `type: Literal["double_click"]` - - `"chatkit.thread_item"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `thread_id: str` + - `"double_click"` - Identifier of the parent thread. + - `x: int` - - `type: Literal["chatkit.assistant_message"]` + The x-coordinate where the double click occurred. - Type discriminator that is always `chatkit.assistant_message`. + - `y: int` - - `"chatkit.assistant_message"` + The y-coordinate where the double click occurred. - - `class ChatKitWidgetItem: …` + - `class Drag: …` - Thread item that renders a widget payload. + A drag action. - - `id: str` + - `path: List[DragPath]` - Identifier of the thread item. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `created_at: int` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - Unix timestamp (in seconds) for when the item was created. + - `x: int` - - `object: Literal["chatkit.thread_item"]` + The x-coordinate. - Type discriminator that is always `chatkit.thread_item`. + - `y: int` - - `"chatkit.thread_item"` + The y-coordinate. - - `thread_id: str` + - `type: Literal["drag"]` - Identifier of the parent thread. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `type: Literal["chatkit.widget"]` + - `"drag"` - Type discriminator that is always `chatkit.widget`. + - `keys: Optional[List[str]]` - - `"chatkit.widget"` + The keys being held while dragging the mouse. - - `widget: str` + - `class Keypress: …` - Serialized widget payload rendered in the UI. + A collection of keypresses the model would like to perform. - - `class DataChatKitClientToolCall: …` + - `keys: List[str]` - Record of a client side tool invocation initiated by the assistant. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `id: str` + - `type: Literal["keypress"]` - Identifier of the thread item. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `arguments: str` + - `"keypress"` - JSON-encoded arguments that were sent to the tool. + - `class Move: …` - - `call_id: str` + A mouse move action. - Identifier for the client tool call. + - `type: Literal["move"]` - - `created_at: int` + Specifies the event type. For a move action, this property is always set to `move`. - Unix timestamp (in seconds) for when the item was created. + - `"move"` - - `name: str` + - `x: int` - Tool name that was invoked. + The x-coordinate to move to. - - `object: Literal["chatkit.thread_item"]` + - `y: int` - Type discriminator that is always `chatkit.thread_item`. + The y-coordinate to move to. - - `"chatkit.thread_item"` + - `keys: Optional[List[str]]` - - `output: Optional[str]` + The keys being held while moving the mouse. - JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + - `class Screenshot: …` - - `status: Literal["in_progress", "completed"]` + A screenshot action. - Execution status for the tool call. + - `type: Literal["screenshot"]` - - `"in_progress"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"completed"` + - `"screenshot"` - - `thread_id: str` + - `class Scroll: …` - Identifier of the parent thread. + A scroll action. - - `type: Literal["chatkit.client_tool_call"]` + - `scroll_x: int` - Type discriminator that is always `chatkit.client_tool_call`. + The horizontal scroll distance. - - `"chatkit.client_tool_call"` + - `scroll_y: int` - - `class DataChatKitTask: …` + The vertical scroll distance. - Task emitted by the workflow to show progress and status updates. + - `type: Literal["scroll"]` - - `id: str` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - Identifier of the thread item. + - `"scroll"` - - `created_at: int` + - `x: int` - Unix timestamp (in seconds) for when the item was created. + The x-coordinate where the scroll occurred. - - `heading: Optional[str]` + - `y: int` - Optional heading for the task. Defaults to null when not provided. + The y-coordinate where the scroll occurred. - - `object: Literal["chatkit.thread_item"]` + - `keys: Optional[List[str]]` - Type discriminator that is always `chatkit.thread_item`. + The keys being held while scrolling. - - `"chatkit.thread_item"` + - `class Type: …` - - `summary: Optional[str]` + An action to type in text. - Optional summary that describes the task. Defaults to null when omitted. + - `text: str` - - `task_type: Literal["custom", "thought"]` + The text to type. - Subtype for the task. + - `type: Literal["type"]` - - `"custom"` + Specifies the event type. For a type action, this property is always set to `type`. - - `"thought"` + - `"type"` - - `thread_id: str` + - `class Wait: …` - Identifier of the parent thread. + A wait action. - - `type: Literal["chatkit.task"]` + - `type: Literal["wait"]` - Type discriminator that is always `chatkit.task`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"chatkit.task"` + - `"wait"` - - `class DataChatKitTaskGroup: …` + - `actions: Optional[BetaComputerActionList]` - Collection of workflow tasks grouped together in the thread. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `id: str` + - `class Click: …` - Identifier of the thread item. + A click action. - - `created_at: int` + - `class DoubleClick: …` - Unix timestamp (in seconds) for when the item was created. + A double click action. - - `object: Literal["chatkit.thread_item"]` + - `class Drag: …` - Type discriminator that is always `chatkit.thread_item`. + A drag action. - - `"chatkit.thread_item"` + - `class Keypress: …` - - `tasks: List[DataChatKitTaskGroupTask]` + A collection of keypresses the model would like to perform. - Tasks included in the group. + - `class Move: …` - - `heading: Optional[str]` + A mouse move action. - Optional heading for the grouped task. Defaults to null when not provided. + - `class Screenshot: …` - - `summary: Optional[str]` + A screenshot action. - Optional summary that describes the grouped task. Defaults to null when omitted. + - `class Scroll: …` - - `type: Literal["custom", "thought"]` + A scroll action. - Subtype for the grouped task. + - `class Type: …` - - `"custom"` + An action to type in text. - - `"thought"` + - `class Wait: …` - - `thread_id: str` + A wait action. - Identifier of the parent thread. + - `agent: Optional[Agent]` - - `type: Literal["chatkit.task_group"]` + The agent that produced this item. - Type discriminator that is always `chatkit.task_group`. + - `agent_name: str` - - `"chatkit.task_group"` + The canonical name of the agent that produced this item. -### Example + - `class ComputerCallOutput: …` -```python -import os -from openai import OpenAI + The output of a computer tool call. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -page = client.beta.chatkit.threads.list_items( - thread_id="cthr_123", -) -page = page.data[0] -print(page) -``` + - `call_id: str` -#### Response + The ID of the computer tool call that produced the output. -```json -{ - "data": [ - { - "id": "id", - "attachments": [ - { - "id": "id", - "mime_type": "mime_type", - "name": "name", - "preview_url": "https://example.com", - "type": "image" - } - ], - "content": [ - { - "text": "text", - "type": "input_text" - } - ], - "created_at": 0, - "inference_options": { - "model": "model", - "tool_choice": { - "id": "id" - } - }, - "object": "chatkit.thread_item", - "thread_id": "thread_id", - "type": "chatkit.user_message" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + - `output: BetaResponseComputerToolCallOutputScreenshot` -### Example + A computer screenshot image used with the computer use tool. -```python -from openai import OpenAI + - `type: Literal["computer_screenshot"]` -client = OpenAI() -page = client.beta.chatkit.threads.list_items( - thread_id="cthr_123", -) -page = page.data[0] -print(page) -``` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. -#### Response + - `"computer_screenshot"` -```json -{ - "data": [ - { - "id": "cthi_user_001", - "object": "chatkit.thread_item", - "type": "user_message", - "content": [ - { - "type": "input_text", - "text": "I need help debugging an onboarding issue." - } - ], - "attachments": [] - }, - { - "id": "cthi_assistant_002", - "object": "chatkit.thread_item", - "type": "assistant_message", - "content": [ - { - "type": "output_text", - "text": "Let's start by confirming the workflow version you deployed." - } - ] - } - ], - "has_more": false, - "object": "list" -} -``` + - `file_id: Optional[str]` -## Retrieve ChatKit thread + The identifier of an uploaded file that contains the screenshot. -`beta.chatkit.threads.retrieve(strthread_id) -> ChatKitThread` + - `image_url: Optional[str]` -**get** `/chatkit/threads/{thread_id}` + The URL of the screenshot image. + + - `type: Literal["computer_call_output"]` -Retrieve ChatKit thread + The type of the computer tool call output. Always `computer_call_output`. -### Parameters + - `"computer_call_output"` -- `thread_id: str` + - `id: Optional[str]` -### Returns + The ID of the computer tool call output. -- `class ChatKitThread: …` + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - Represents a ChatKit thread and its current status. + The safety checks reported by the API that have been acknowledged by the developer. - `id: str` - Identifier of the thread. + The ID of the pending safety check. - - `created_at: int` + - `code: Optional[str]` - Unix timestamp (in seconds) for when the thread was created. + The type of the pending safety check. - - `object: Literal["chatkit.thread"]` + - `message: Optional[str]` - Type discriminator that is always `chatkit.thread`. + Details about the pending safety check. - - `"chatkit.thread"` + - `agent: Optional[ComputerCallOutputAgent]` - - `status: Status` + The agent that produced this item. - Current status for the thread. Defaults to `active` for newly created threads. + - `agent_name: str` - - `class StatusActive: …` + The canonical name of the agent that produced this item. - Indicates that a thread is active. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `type: Literal["active"]` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - Status discriminator that is always `active`. + - `"in_progress"` - - `"active"` + - `"completed"` - - `class StatusLocked: …` + - `"incomplete"` - Indicates that a thread is locked and cannot accept new input. + - `class BetaResponseFunctionWebSearch: …` - - `reason: Optional[str]` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - Reason that the thread was locked. Defaults to null when no reason is recorded. + - `id: str` - - `type: Literal["locked"]` + The unique ID of the web search tool call. - Status discriminator that is always `locked`. + - `action: Action` - - `"locked"` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `class StatusClosed: …` + - `class ActionSearch: …` - Indicates that a thread has been closed. + Action type "search" - Performs a web search query. - - `reason: Optional[str]` + - `type: Literal["search"]` - Reason that the thread was closed. Defaults to null when no reason is recorded. + The action type. - - `type: Literal["closed"]` + - `"search"` - Status discriminator that is always `closed`. + - `queries: Optional[List[str]]` - - `"closed"` + The search queries. - - `title: Optional[str]` + - `query: Optional[str]` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + The search query. - - `user: str` + - `sources: Optional[List[ActionSearchSource]]` - Free-form string that identifies your end user who owns the thread. + The sources used in the search. -### Example + - `type: Literal["url"]` -```python -import os -from openai import OpenAI + The type of source. Always `url`. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -chatkit_thread = client.beta.chatkit.threads.retrieve( - "cthr_123", -) -print(chatkit_thread.id) -``` + - `"url"` -#### Response + - `url: str` -```json -{ - "id": "cthr_def456", - "created_at": 1712345600, - "object": "chatkit.thread", - "status": { - "type": "active" - }, - "title": "Demo feedback", - "user": "user_456" -} -``` + The URL of the source. -### Example + - `class ActionOpenPage: …` -```python -from openai import OpenAI + Action type "open_page" - Opens a specific URL from search results. -client = OpenAI() -chatkit_thread = client.beta.chatkit.threads.retrieve( - "cthr_123", -) -print(chatkit_thread.id) -``` + - `type: Literal["open_page"]` -#### Response + The action type. -```json -{ - "id": "cthr_abc123", - "object": "chatkit.thread", - "title": "Customer escalation", - "items": { - "data": [ - { - "id": "cthi_user_001", - "object": "chatkit.thread_item", - "type": "user_message", - "content": [ - { - "type": "input_text", - "text": "I need help debugging an onboarding issue." - } - ], - "attachments": [] - }, - { - "id": "cthi_assistant_002", - "object": "chatkit.thread_item", - "type": "assistant_message", - "content": [ - { - "type": "output_text", - "text": "Let's start by confirming the workflow version you deployed." - } - ] - } - ], - "has_more": false - } -} -``` + - `"open_page"` -## Delete ChatKit thread + - `url: Optional[str]` -`beta.chatkit.threads.delete(strthread_id) -> ThreadDeleteResponse` + The URL opened by the model. -**delete** `/chatkit/threads/{thread_id}` + - `class ActionFindInPage: …` -Delete ChatKit thread + Action type "find_in_page": Searches for a pattern within a loaded page. -### Parameters + - `pattern: str` -- `thread_id: str` + The pattern or text to search for within the page. -### Returns + - `type: Literal["find_in_page"]` -- `class ThreadDeleteResponse: …` + The action type. - Confirmation payload returned after deleting a thread. + - `"find_in_page"` - - `id: str` + - `url: str` - Identifier of the deleted thread. + The URL of the page searched for the pattern. - - `deleted: bool` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - Indicates that the thread has been deleted. + The status of the web search tool call. - - `object: Literal["chatkit.thread.deleted"]` + - `"in_progress"` - Type discriminator that is always `chatkit.thread.deleted`. + - `"searching"` - - `"chatkit.thread.deleted"` + - `"completed"` -### Example + - `"failed"` -```python -import os -from openai import OpenAI + - `type: Literal["web_search_call"]` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -thread = client.beta.chatkit.threads.delete( - "cthr_123", -) -print(thread.id) -``` + The type of the web search tool call. Always `web_search_call`. -#### Response + - `"web_search_call"` -```json -{ - "id": "id", - "deleted": true, - "object": "chatkit.thread.deleted" -} -``` + - `agent: Optional[Agent]` -### Example + The agent that produced this item. -```python -from openai import OpenAI + - `agent_name: str` -client = OpenAI() -thread = client.beta.chat_kit.threads.delete( - "cthr_123", -) -print(thread.id) -``` + The canonical name of the agent that produced this item. -## List ChatKit threads + - `class BetaResponseFunctionToolCall: …` -`beta.chatkit.threads.list(ThreadListParams**kwargs) -> SyncConversationCursorPage[ChatKitThread]` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. -**get** `/chatkit/threads` + - `arguments: str` -List ChatKit threads + A JSON string of the arguments to pass to the function. -### Parameters + - `call_id: str` -- `after: Optional[str]` + The unique ID of the function tool call generated by the model. - List items created after this thread item ID. Defaults to null for the first page. + - `name: str` -- `before: Optional[str]` + The name of the function to run. - List items created before this thread item ID. Defaults to null for the newest results. + - `type: Literal["function_call"]` -- `limit: Optional[int]` + The type of the function tool call. Always `function_call`. - Maximum number of thread items to return. Defaults to 20. + - `"function_call"` -- `order: Optional[Literal["asc", "desc"]]` + - `id: Optional[str]` - Sort order for results by creation time. Defaults to `desc`. + The unique ID of the function tool call. - - `"asc"` + - `agent: Optional[Agent]` - - `"desc"` + The agent that produced this item. -- `user: Optional[str]` + - `agent_name: str` - Filter threads that belong to this user identifier. Defaults to null to return all users. + The canonical name of the agent that produced this item. -### Returns + - `caller: Optional[Caller]` -- `class ChatKitThread: …` + The execution context that produced this tool call. - Represents a ChatKit thread and its current status. + - `class CallerDirect: …` - - `id: str` + - `type: Literal["direct"]` - Identifier of the thread. + - `"direct"` - - `created_at: int` + - `class CallerProgram: …` - Unix timestamp (in seconds) for when the thread was created. + - `caller_id: str` - - `object: Literal["chatkit.thread"]` + The call ID of the program item that produced this tool call. - Type discriminator that is always `chatkit.thread`. + - `type: Literal["program"]` - - `"chatkit.thread"` + - `"program"` - - `status: Status` + - `namespace: Optional[str]` - Current status for the thread. Defaults to `active` for newly created threads. + The namespace of the function to run. - - `class StatusActive: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Indicates that a thread is active. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: Literal["active"]` + - `"in_progress"` - Status discriminator that is always `active`. + - `"completed"` - - `"active"` + - `"incomplete"` - - `class StatusLocked: …` + - `class FunctionCallOutput: …` - Indicates that a thread is locked and cannot accept new input. + The output of a function tool call. - - `reason: Optional[str]` + - `call_id: str` - Reason that the thread was locked. Defaults to null when no reason is recorded. + The unique ID of the function tool call generated by the model. - - `type: Literal["locked"]` + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - Status discriminator that is always `locked`. + Text, image, or file output of the function tool call. - - `"locked"` + - `str` - - `class StatusClosed: …` + A JSON string of the output of the function tool call. - Indicates that a thread has been closed. + - `List[BetaResponseFunctionCallOutputItem]` - - `reason: Optional[str]` + - `class BetaResponseInputTextContent: …` - Reason that the thread was closed. Defaults to null when no reason is recorded. + A text input to the model. - - `type: Literal["closed"]` + - `text: str` - Status discriminator that is always `closed`. + The text input to the model. - - `"closed"` + - `type: Literal["input_text"]` - - `title: Optional[str]` + The type of the input item. Always `input_text`. - Optional human-readable title for the thread. Defaults to null when no title has been generated. + - `"input_text"` - - `user: str` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Free-form string that identifies your end user who owns the thread. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. -### Example + - `mode: Literal["explicit"]` -```python -import os -from openai import OpenAI + The breakpoint mode. Always `explicit`. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -page = client.beta.chatkit.threads.list() -page = page.data[0] -print(page.id) -``` + - `"explicit"` -#### Response + - `class BetaResponseInputImageContent: …` -```json -{ - "data": [ - { - "id": "cthr_def456", - "created_at": 1712345600, - "object": "chatkit.thread", - "status": { - "type": "active" - }, - "title": "Demo feedback", - "user": "user_456" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) -### Example + - `type: Literal["input_image"]` -```python -from openai import OpenAI + The type of the input item. Always `input_image`. -client = OpenAI() -page = client.beta.chatkit.threads.list() -page = page.data[0] -print(page.id) -``` + - `"input_image"` -#### Response + - `detail: Optional[Literal["low", "high", "auto", "original"]]` -```json -{ - "data": [ - { - "id": "cthr_abc123", - "object": "chatkit.thread", - "title": "Customer escalation" - }, - { - "id": "cthr_def456", - "object": "chatkit.thread", - "title": "Demo feedback" - } - ], - "has_more": false, - "object": "list" -} -``` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. -## Domain Types + - `"low"` -### Chat Session + - `"high"` -- `class ChatSession: …` + - `"auto"` - Represents a ChatKit session and its resolved configuration. + - `"original"` - - `id: str` + - `file_id: Optional[str]` - Identifier for the ChatKit session. + The ID of the file to be sent to the model. - - `chatkit_configuration: ChatSessionChatKitConfiguration` + - `image_url: Optional[str]` - Resolved ChatKit feature configuration for the session. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Automatic thread titling preferences. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `enabled: bool` + - `mode: Literal["explicit"]` - Whether automatic thread titling is enabled. + The breakpoint mode. Always `explicit`. - - `file_upload: ChatSessionFileUpload` + - `"explicit"` - Upload settings for the session. + - `class BetaResponseInputFileContent: …` - - `enabled: bool` + A file input to the model. - Indicates if uploads are enabled for the session. + - `type: Literal["input_file"]` - - `max_file_size: Optional[int]` + The type of the input item. Always `input_file`. - Maximum upload size in megabytes. + - `"input_file"` - - `max_files: Optional[int]` + - `detail: Optional[Literal["auto", "low", "high"]]` - Maximum number of uploads allowed during the session. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `history: ChatSessionHistory` + - `"auto"` - History retention configuration. + - `"low"` - - `enabled: bool` + - `"high"` - Indicates if chat history is persisted for the session. + - `file_data: Optional[str]` - - `recent_threads: Optional[int]` + The base64-encoded data of the file to be sent to the model. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `file_id: Optional[str]` - - `client_secret: str` + The ID of the file to be sent to the model. - Ephemeral client secret that authenticates session requests. + - `file_url: Optional[str]` - - `expires_at: int` + The URL of the file to be sent to the model. - Unix timestamp (in seconds) for when the session expires. + - `filename: Optional[str]` - - `max_requests_per_1_minute: int` + The name of the file to be sent to the model. - Convenience copy of the per-minute request limit. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `object: Literal["chatkit.session"]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Type discriminator that is always `chatkit.session`. + - `mode: Literal["explicit"]` - - `"chatkit.session"` + The breakpoint mode. Always `explicit`. - - `rate_limits: ChatSessionRateLimits` + - `"explicit"` - Resolved rate limit values. + - `type: Literal["function_call_output"]` - - `max_requests_per_1_minute: int` + The type of the function tool call output. Always `function_call_output`. - Maximum allowed requests per one-minute window. + - `"function_call_output"` - - `status: ChatSessionStatus` + - `id: Optional[str]` - Current lifecycle state of the session. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `"active"` + - `agent: Optional[FunctionCallOutputAgent]` - - `"expired"` + The agent that produced this item. - - `"cancelled"` + - `agent_name: str` - - `user: str` + The canonical name of the agent that produced this item. - User identifier associated with the session. + - `caller: Optional[FunctionCallOutputCaller]` - - `workflow: ChatKitWorkflow` + The execution context that produced this tool call. - Workflow metadata for the session. + - `class FunctionCallOutputCallerDirect: …` - - `id: str` + - `type: Literal["direct"]` - Identifier of the workflow backing the session. + The caller type. Always `direct`. - - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` + - `"direct"` - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `class FunctionCallOutputCallerProgram: …` - - `str` + - `caller_id: str` - - `bool` + The call ID of the program item that produced this tool call. - - `float` + - `type: Literal["program"]` - - `tracing: Tracing` + The caller type. Always `program`. - Tracing settings applied to the workflow. + - `"program"` - - `enabled: bool` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Indicates whether tracing is enabled. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `version: Optional[str]` + - `"in_progress"` - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `"completed"` -### Chat Session Automatic Thread Titling + - `"incomplete"` -- `class ChatSessionAutomaticThreadTitling: …` + - `class AgentMessage: …` - Automatic thread title preferences for the session. + A message routed between agents. - - `enabled: bool` + - `author: str` - Whether automatic thread titling is enabled. + The sending agent identity. -### Chat Session ChatKit Configuration + - `content: List[AgentMessageContent]` -- `class ChatSessionChatKitConfiguration: …` + Plaintext, image, or encrypted content sent between agents. - ChatKit configuration for the session. + - `class BetaResponseInputTextContent: …` - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + A text input to the model. - Automatic thread titling preferences. + - `class BetaResponseInputImageContent: …` - - `enabled: bool` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - Whether automatic thread titling is enabled. + - `class AgentMessageContentEncryptedContent: …` - - `file_upload: ChatSessionFileUpload` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - Upload settings for the session. + - `encrypted_content: str` - - `enabled: bool` + Opaque encrypted content. - Indicates if uploads are enabled for the session. + - `type: Literal["encrypted_content"]` - - `max_file_size: Optional[int]` + The type of the input item. Always `encrypted_content`. - Maximum upload size in megabytes. + - `"encrypted_content"` - - `max_files: Optional[int]` + - `recipient: str` - Maximum number of uploads allowed during the session. + The destination agent identity. - - `history: ChatSessionHistory` + - `type: Literal["agent_message"]` - History retention configuration. + The item type. Always `agent_message`. - - `enabled: bool` + - `"agent_message"` - Indicates if chat history is persisted for the session. + - `id: Optional[str]` - - `recent_threads: Optional[int]` + The unique ID of this agent message item. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `agent: Optional[AgentMessageAgent]` -### Chat Session ChatKit Configuration Param + The agent that produced this item. -- `class ChatSessionChatKitConfigurationParam: …` + - `agent_name: str` - Optional per-session configuration settings for ChatKit behavior. + The canonical name of the agent that produced this item. - - `automatic_thread_titling: Optional[AutomaticThreadTitling]` + - `class MultiAgentCall: …` - Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `enabled: Optional[bool]` + The multi-agent action that was executed. - Enable automatic thread title generation. Defaults to true. + - `"spawn_agent"` - - `file_upload: Optional[FileUpload]` + - `"interrupt_agent"` - Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). + - `"list_agents"` - - `enabled: Optional[bool]` + - `"send_message"` - Enable uploads for this session. Defaults to false. + - `"followup_task"` - - `max_file_size: Optional[int]` + - `"wait_agent"` - Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. + - `arguments: str` - - `max_files: Optional[int]` + The action arguments as a JSON string. - Maximum number of files that can be uploaded to the session. Defaults to 10. + - `call_id: str` - - `history: Optional[History]` + The unique ID linking this call to its output. - Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). + - `type: Literal["multi_agent_call"]` - - `enabled: Optional[bool]` + The item type. Always `multi_agent_call`. - Enables chat users to access previous ChatKit threads. Defaults to true. + - `"multi_agent_call"` - - `recent_threads: Optional[int]` + - `id: Optional[str]` - Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. + The unique ID of this multi-agent call. -### Chat Session Expires After Param + - `agent: Optional[MultiAgentCallAgent]` -- `class ChatSessionExpiresAfterParam: …` + The agent that produced this item. - Controls when the session expires relative to an anchor timestamp. + - `agent_name: str` - - `anchor: Literal["created_at"]` + The canonical name of the agent that produced this item. - Base timestamp used to calculate expiration. Currently fixed to `created_at`. + - `class MultiAgentCallOutput: …` - - `"created_at"` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `seconds: int` + The multi-agent action that produced this result. - Number of seconds after the anchor when the session expires. + - `"spawn_agent"` -### Chat Session File Upload + - `"interrupt_agent"` -- `class ChatSessionFileUpload: …` + - `"list_agents"` - Upload permissions and limits applied to the session. + - `"send_message"` - - `enabled: bool` + - `"followup_task"` - Indicates if uploads are enabled for the session. + - `"wait_agent"` - - `max_file_size: Optional[int]` + - `call_id: str` - Maximum upload size in megabytes. + The unique ID of the multi-agent call. - - `max_files: Optional[int]` + - `output: List[MultiAgentCallOutputOutput]` - Maximum number of uploads allowed during the session. + Text output returned by the multi-agent action. -### Chat Session History + - `text: str` -- `class ChatSessionHistory: …` + The text content. - History retention preferences returned for the session. + - `type: Literal["output_text"]` - - `enabled: bool` + The content type. Always `output_text`. - Indicates if chat history is persisted for the session. + - `"output_text"` - - `recent_threads: Optional[int]` + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + Citations associated with the text content. -### Chat Session Rate Limits + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` -- `class ChatSessionRateLimits: …` + - `file_id: str` - Active per-minute request limit for the session. + The ID of the file. - - `max_requests_per_1_minute: int` + - `filename: str` - Maximum allowed requests per one-minute window. + The filename of the file cited. -### Chat Session Rate Limits Param + - `index: int` -- `class ChatSessionRateLimitsParam: …` + The index of the file in the list of files. - Controls request rate limits for the session. + - `type: Literal["file_citation"]` - - `max_requests_per_1_minute: Optional[int]` + The citation type. Always `file_citation`. - Maximum number of requests allowed per minute for the session. Defaults to 10. + - `"file_citation"` -### Chat Session Status + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` -- `Literal["active", "expired", "cancelled"]` + - `end_index: int` - - `"active"` + The index of the last character of the citation in the message. - - `"expired"` + - `start_index: int` - - `"cancelled"` + The index of the first character of the citation in the message. -### Chat Session Workflow Param + - `title: str` -- `class ChatSessionWorkflowParam: …` + The title of the cited resource. - Workflow reference and overrides applied to the chat session. + - `type: Literal["url_citation"]` - - `id: str` + The citation type. Always `url_citation`. - Identifier for the workflow invoked by the session. + - `"url_citation"` - - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` + - `url: str` - State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. + The URL of the cited resource. - - `str` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` - - `bool` + - `container_id: str` - - `float` + The ID of the container. - - `tracing: Optional[Tracing]` + - `end_index: int` - Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. + The index of the last character of the citation in the message. - - `enabled: Optional[bool]` + - `file_id: str` - Whether tracing is enabled during the session. Defaults to true. + The ID of the container file. - - `version: Optional[str]` + - `filename: str` - Specific workflow version to run. Defaults to the latest deployed version. + The filename of the container file cited. -### ChatKit Attachment + - `start_index: int` -- `class ChatKitAttachment: …` + The index of the first character of the citation in the message. - Attachment metadata included on thread items. + - `type: Literal["container_file_citation"]` - - `id: str` + The citation type. Always `container_file_citation`. - Identifier for the attachment. + - `"container_file_citation"` - - `mime_type: str` + - `type: Literal["multi_agent_call_output"]` - MIME type of the attachment. + The item type. Always `multi_agent_call_output`. - - `name: str` + - `"multi_agent_call_output"` - Original display name for the attachment. + - `id: Optional[str]` - - `preview_url: Optional[str]` + The unique ID of this multi-agent call output. - Preview URL for rendering the attachment inline. + - `agent: Optional[MultiAgentCallOutputAgent]` - - `type: Literal["image", "file"]` + The agent that produced this item. - Attachment discriminator. + - `agent_name: str` - - `"image"` + The canonical name of the agent that produced this item. - - `"file"` + - `class ToolSearchCall: …` -### ChatKit Response Output Text + - `arguments: object` -- `class ChatKitResponseOutputText: …` + The arguments supplied to the tool search call. - Assistant response text accompanied by optional annotations. + - `type: Literal["tool_search_call"]` - - `annotations: List[Annotation]` + The item type. Always `tool_search_call`. - Ordered list of annotations attached to the response text. + - `"tool_search_call"` - - `class AnnotationFile: …` + - `id: Optional[str]` - Annotation that references an uploaded file. + The unique ID of this tool search call. - - `source: AnnotationFileSource` + - `agent: Optional[ToolSearchCallAgent]` - File attachment referenced by the annotation. + The agent that produced this item. - - `filename: str` + - `agent_name: str` - Filename referenced by the annotation. + The canonical name of the agent that produced this item. - - `type: Literal["file"]` + - `call_id: Optional[str]` - Type discriminator that is always `file`. + The unique ID of the tool search call generated by the model. - - `"file"` + - `execution: Optional[Literal["server", "client"]]` - - `type: Literal["file"]` + Whether tool search was executed by the server or by the client. - Type discriminator that is always `file` for this annotation. + - `"server"` - - `"file"` + - `"client"` - - `class AnnotationURL: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Annotation that references a URL. + The status of the tool search call. - - `source: AnnotationURLSource` + - `"in_progress"` - URL referenced by the annotation. + - `"completed"` - - `type: Literal["url"]` + - `"incomplete"` - Type discriminator that is always `url`. + - `class BetaResponseToolSearchOutputItemParam: …` - - `"url"` + - `tools: List[BetaTool]` - - `url: str` + The loaded tool definitions returned by the tool search output. - URL referenced by the annotation. + - `class BetaFunctionTool: …` - - `type: Literal["url"]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Type discriminator that is always `url` for this annotation. + - `name: str` - - `"url"` + The name of the function to call. - - `text: str` + - `parameters: Optional[Dict[str, object]]` - Assistant generated text. + A JSON schema object describing the parameters of the function. - - `type: Literal["output_text"]` + - `strict: Optional[bool]` - Type discriminator that is always `output_text`. + Whether strict parameter validation is enforced for this function tool. - - `"output_text"` + - `type: Literal["function"]` -### ChatKit Thread + The type of the function tool. Always `function`. -- `class ChatKitThread: …` + - `"function"` - Represents a ChatKit thread and its current status. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `id: str` + The tool invocation context(s). - Identifier of the thread. + - `"direct"` - - `created_at: int` + - `"programmatic"` - Unix timestamp (in seconds) for when the thread was created. + - `defer_loading: Optional[bool]` - - `object: Literal["chatkit.thread"]` + Whether this function is deferred and loaded via tool search. - Type discriminator that is always `chatkit.thread`. + - `description: Optional[str]` - - `"chatkit.thread"` + A description of the function. Used by the model to determine whether or not to call the function. - - `status: Status` + - `output_schema: Optional[Dict[str, object]]` - Current status for the thread. Defaults to `active` for newly created threads. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `class StatusActive: …` + - `class BetaFileSearchTool: …` - Indicates that a thread is active. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: Literal["active"]` + - `type: Literal["file_search"]` - Status discriminator that is always `active`. + The type of the file search tool. Always `file_search`. - - `"active"` + - `"file_search"` - - `class StatusLocked: …` + - `vector_store_ids: List[str]` - Indicates that a thread is locked and cannot accept new input. + The IDs of the vector stores to search. - - `reason: Optional[str]` + - `filters: Optional[Filters]` - Reason that the thread was locked. Defaults to null when no reason is recorded. + A filter to apply. - - `type: Literal["locked"]` + - `class FiltersComparisonFilter: …` - Status discriminator that is always `locked`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"locked"` + - `key: str` - - `class StatusClosed: …` + The key to compare against the value. - Indicates that a thread has been closed. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `reason: Optional[str]` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `type: Literal["closed"]` + - `"eq"` - Status discriminator that is always `closed`. + - `"ne"` - - `"closed"` + - `"gt"` - - `title: Optional[str]` + - `"gte"` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + - `"lt"` - - `user: str` + - `"lte"` - Free-form string that identifies your end user who owns the thread. + - `"in"` -### ChatKit Thread Assistant Message Item + - `"nin"` -- `class ChatKitThreadAssistantMessageItem: …` + - `value: Union[str, float, bool, List[Union[str, float]]]` - Assistant-authored message within a thread. + The value to compare against the attribute key; supports string, number, or boolean types. - - `id: str` + - `str` - Identifier of the thread item. + - `float` - - `content: List[ChatKitResponseOutputText]` + - `bool` - Ordered assistant response segments. + - `List[Union[str, float]]` - - `annotations: List[Annotation]` + - `str` - Ordered list of annotations attached to the response text. + - `float` - - `class AnnotationFile: …` + - `class FiltersCompoundFilter: …` - Annotation that references an uploaded file. + Combine multiple filters using `and` or `or`. - - `source: AnnotationFileSource` + - `filters: List[FiltersCompoundFilterFilter]` - File attachment referenced by the annotation. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `filename: str` + - `class FiltersCompoundFilterFilterComparisonFilter: …` - Filename referenced by the annotation. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: Literal["file"]` + - `key: str` - Type discriminator that is always `file`. + The key to compare against the value. - - `"file"` + - `type: Literal["eq", "ne", "gt", 5 more]` - - `type: Literal["file"]` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Type discriminator that is always `file` for this annotation. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `"file"` + - `"eq"` - - `class AnnotationURL: …` + - `"ne"` - Annotation that references a URL. + - `"gt"` - - `source: AnnotationURLSource` + - `"gte"` - URL referenced by the annotation. + - `"lt"` - - `type: Literal["url"]` + - `"lte"` - Type discriminator that is always `url`. + - `"in"` - - `"url"` + - `"nin"` - - `url: str` + - `value: Union[str, float, bool, List[Union[str, float]]]` - URL referenced by the annotation. + The value to compare against the attribute key; supports string, number, or boolean types. - - `type: Literal["url"]` + - `str` - Type discriminator that is always `url` for this annotation. + - `float` - - `"url"` + - `bool` - - `text: str` + - `List[Union[str, float]]` - Assistant generated text. + - `str` - - `type: Literal["output_text"]` + - `float` - Type discriminator that is always `output_text`. + - `object` - - `"output_text"` + - `type: Literal["and", "or"]` - - `created_at: int` + Type of operation: `and` or `or`. - Unix timestamp (in seconds) for when the item was created. + - `"and"` - - `object: Literal["chatkit.thread_item"]` + - `"or"` - Type discriminator that is always `chatkit.thread_item`. + - `max_num_results: Optional[int]` - - `"chatkit.thread_item"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `thread_id: str` + - `ranking_options: Optional[RankingOptions]` - Identifier of the parent thread. + Ranking options for search. - - `type: Literal["chatkit.assistant_message"]` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - Type discriminator that is always `chatkit.assistant_message`. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"chatkit.assistant_message"` + - `embedding_weight: float` -### ChatKit Thread Item List + The weight of the embedding in the reciprocal ranking fusion. -- `class ChatKitThreadItemList: …` + - `text_weight: float` - A paginated list of thread items rendered for the ChatKit API. + The weight of the text in the reciprocal ranking fusion. - - `data: List[Data]` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - A list of items + The ranker to use for the file search. - - `class ChatKitThreadUserMessageItem: …` + - `"auto"` - User-authored messages within a thread. + - `"default-2024-11-15"` - - `id: str` + - `score_threshold: Optional[float]` - Identifier of the thread item. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `attachments: List[ChatKitAttachment]` + - `class BetaComputerTool: …` - Attachments associated with the user message. Defaults to an empty list. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `id: str` + - `type: Literal["computer"]` - Identifier for the attachment. + The type of the computer tool. Always `computer`. - - `mime_type: str` + - `"computer"` - MIME type of the attachment. + - `class BetaComputerUsePreviewTool: …` - - `name: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Original display name for the attachment. + - `display_height: int` - - `preview_url: Optional[str]` + The height of the computer display. - Preview URL for rendering the attachment inline. + - `display_width: int` - - `type: Literal["image", "file"]` + The width of the computer display. - Attachment discriminator. + - `environment: Literal["windows", "mac", "linux", 2 more]` - - `"image"` + The type of computer environment to control. - - `"file"` + - `"windows"` - - `content: List[Content]` + - `"mac"` - Ordered content elements supplied by the user. + - `"linux"` - - `class ContentInputText: …` + - `"ubuntu"` - Text block that a user contributed to the thread. + - `"browser"` - - `text: str` + - `type: Literal["computer_use_preview"]` - Plain-text content supplied by the user. + The type of the computer use tool. Always `computer_use_preview`. - - `type: Literal["input_text"]` + - `"computer_use_preview"` - Type discriminator that is always `input_text`. + - `class BetaWebSearchTool: …` - - `"input_text"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class ContentQuotedText: …` + - `type: Literal["web_search", "web_search_2025_08_26"]` - Quoted snippet that the user referenced in their message. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `text: str` + - `"web_search"` - Quoted text content. + - `"web_search_2025_08_26"` - - `type: Literal["quoted_text"]` + - `filters: Optional[Filters]` - Type discriminator that is always `quoted_text`. + Filters for the search. - - `"quoted_text"` + - `allowed_domains: Optional[List[str]]` - - `created_at: int` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Unix timestamp (in seconds) for when the item was created. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `inference_options: Optional[InferenceOptions]` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - Inference overrides applied to the message. Defaults to null when unset. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `model: Optional[str]` + - `"low"` - Model name that generated the response. Defaults to null when using the session default. + - `"medium"` - - `tool_choice: Optional[InferenceOptionsToolChoice]` + - `"high"` - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `user_location: Optional[UserLocation]` - - `id: str` + The approximate location of the user. - Identifier of the requested tool. + - `city: Optional[str]` - - `object: Literal["chatkit.thread_item"]` + Free text input for the city of the user, e.g. `San Francisco`. - Type discriminator that is always `chatkit.thread_item`. + - `country: Optional[str]` - - `"chatkit.thread_item"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `thread_id: str` + - `region: Optional[str]` - Identifier of the parent thread. + Free text input for the region of the user, e.g. `California`. - - `type: Literal["chatkit.user_message"]` + - `timezone: Optional[str]` - - `"chatkit.user_message"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `class ChatKitThreadAssistantMessageItem: …` + - `type: Optional[Literal["approximate"]]` - Assistant-authored message within a thread. + The type of location approximation. Always `approximate`. - - `id: str` + - `"approximate"` - Identifier of the thread item. + - `class Mcp: …` - - `content: List[ChatKitResponseOutputText]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - Ordered assistant response segments. + - `server_label: str` - - `annotations: List[Annotation]` + A label for this MCP server, used to identify it in tool calls. - Ordered list of annotations attached to the response text. + - `type: Literal["mcp"]` - - `class AnnotationFile: …` + The type of the MCP tool. Always `mcp`. - Annotation that references an uploaded file. + - `"mcp"` - - `source: AnnotationFileSource` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - File attachment referenced by the annotation. + The tool invocation context(s). - - `filename: str` + - `"direct"` - Filename referenced by the annotation. + - `"programmatic"` - - `type: Literal["file"]` + - `allowed_tools: Optional[McpAllowedTools]` - Type discriminator that is always `file`. + List of allowed tool names or a filter object. - - `"file"` + - `List[str]` - - `type: Literal["file"]` + A string array of allowed tool names - Type discriminator that is always `file` for this annotation. + - `class McpAllowedToolsMcpToolFilter: …` - - `"file"` + A filter object to specify which tools are allowed. - - `class AnnotationURL: …` + - `read_only: Optional[bool]` - Annotation that references a URL. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `source: AnnotationURLSource` + - `tool_names: Optional[List[str]]` - URL referenced by the annotation. + List of allowed tool names. - - `type: Literal["url"]` + - `authorization: Optional[str]` - Type discriminator that is always `url`. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `"url"` + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `url: str` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - URL referenced by the annotation. + Currently supported `connector_id` values are: - - `type: Literal["url"]` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - Type discriminator that is always `url` for this annotation. + - `"connector_dropbox"` - - `"url"` + - `"connector_gmail"` - - `text: str` + - `"connector_googlecalendar"` - Assistant generated text. + - `"connector_googledrive"` - - `type: Literal["output_text"]` + - `"connector_microsoftteams"` - Type discriminator that is always `output_text`. + - `"connector_outlookcalendar"` - - `"output_text"` + - `"connector_outlookemail"` - - `created_at: int` + - `"connector_sharepoint"` - Unix timestamp (in seconds) for when the item was created. + - `defer_loading: Optional[bool]` - - `object: Literal["chatkit.thread_item"]` + Whether this MCP tool is deferred and discovered via tool search. - Type discriminator that is always `chatkit.thread_item`. + - `headers: Optional[Dict[str, str]]` - - `"chatkit.thread_item"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `thread_id: str` + - `require_approval: Optional[McpRequireApproval]` - Identifier of the parent thread. + Specify which of the MCP server's tools require approval. - - `type: Literal["chatkit.assistant_message"]` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - Type discriminator that is always `chatkit.assistant_message`. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"chatkit.assistant_message"` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `class ChatKitWidgetItem: …` + A filter object to specify which tools are allowed. - Thread item that renders a widget payload. + - `read_only: Optional[bool]` - - `id: str` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - Identifier of the thread item. + - `tool_names: Optional[List[str]]` - - `created_at: int` + List of allowed tool names. - Unix timestamp (in seconds) for when the item was created. + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - - `object: Literal["chatkit.thread_item"]` + A filter object to specify which tools are allowed. - Type discriminator that is always `chatkit.thread_item`. + - `read_only: Optional[bool]` - - `"chatkit.thread_item"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `thread_id: str` + - `tool_names: Optional[List[str]]` - Identifier of the parent thread. + List of allowed tool names. - - `type: Literal["chatkit.widget"]` + - `Literal["always", "never"]` - Type discriminator that is always `chatkit.widget`. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `"chatkit.widget"` + - `"always"` - - `widget: str` + - `"never"` - Serialized widget payload rendered in the UI. + - `server_description: Optional[str]` - - `class DataChatKitClientToolCall: …` + Optional description of the MCP server, used to provide more context. - Record of a client side tool invocation initiated by the assistant. + - `server_url: Optional[str]` - - `id: str` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - Identifier of the thread item. + - `tunnel_id: Optional[str]` - - `arguments: str` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - JSON-encoded arguments that were sent to the tool. + - `class CodeInterpreter: …` - - `call_id: str` + A tool that runs Python code to help generate a response to a prompt. - Identifier for the client tool call. + - `container: CodeInterpreterContainer` - - `created_at: int` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - Unix timestamp (in seconds) for when the item was created. + - `str` - - `name: str` + The container ID. - Tool name that was invoked. + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `object: Literal["chatkit.thread_item"]` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - Type discriminator that is always `chatkit.thread_item`. + - `type: Literal["auto"]` - - `"chatkit.thread_item"` + Always `auto`. - - `output: Optional[str]` + - `"auto"` - JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + - `file_ids: Optional[List[str]]` - - `status: Literal["in_progress", "completed"]` + An optional list of uploaded files to make available to your code. - Execution status for the tool call. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `"in_progress"` + The memory limit for the code interpreter container. - - `"completed"` + - `"1g"` - - `thread_id: str` + - `"4g"` - Identifier of the parent thread. + - `"16g"` - - `type: Literal["chatkit.client_tool_call"]` + - `"64g"` - Type discriminator that is always `chatkit.client_tool_call`. + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - - `"chatkit.client_tool_call"` + Network access policy for the container. - - `class DataChatKitTask: …` + - `class BetaContainerNetworkPolicyDisabled: …` - Task emitted by the workflow to show progress and status updates. + - `type: Literal["disabled"]` - - `id: str` + Disable outbound network access. Always `disabled`. - Identifier of the thread item. + - `"disabled"` - - `created_at: int` + - `class BetaContainerNetworkPolicyAllowlist: …` - Unix timestamp (in seconds) for when the item was created. + - `allowed_domains: List[str]` - - `heading: Optional[str]` + A list of allowed domains when type is `allowlist`. - Optional heading for the task. Defaults to null when not provided. + - `type: Literal["allowlist"]` - - `object: Literal["chatkit.thread_item"]` + Allow outbound network access only to specified domains. Always `allowlist`. - Type discriminator that is always `chatkit.thread_item`. + - `"allowlist"` - - `"chatkit.thread_item"` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `summary: Optional[str]` + Optional domain-scoped secrets for allowlisted domains. - Optional summary that describes the task. Defaults to null when omitted. + - `domain: str` - - `task_type: Literal["custom", "thought"]` + The domain associated with the secret. - Subtype for the task. + - `name: str` - - `"custom"` + The name of the secret to inject for the domain. - - `"thought"` + - `value: str` - - `thread_id: str` + The secret value to inject for the domain. - Identifier of the parent thread. + - `type: Literal["code_interpreter"]` - - `type: Literal["chatkit.task"]` + The type of the code interpreter tool. Always `code_interpreter`. - Type discriminator that is always `chatkit.task`. + - `"code_interpreter"` - - `"chatkit.task"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `class DataChatKitTaskGroup: …` + The tool invocation context(s). - Collection of workflow tasks grouped together in the thread. + - `"direct"` - - `id: str` + - `"programmatic"` - Identifier of the thread item. + - `class ProgrammaticToolCalling: …` - - `created_at: int` + - `type: Literal["programmatic_tool_calling"]` - Unix timestamp (in seconds) for when the item was created. + The type of the tool. Always `programmatic_tool_calling`. - - `object: Literal["chatkit.thread_item"]` + - `"programmatic_tool_calling"` - Type discriminator that is always `chatkit.thread_item`. + - `class ImageGeneration: …` - - `"chatkit.thread_item"` + A tool that generates images using the GPT image models. - - `tasks: List[DataChatKitTaskGroupTask]` + - `type: Literal["image_generation"]` - Tasks included in the group. + The type of the image generation tool. Always `image_generation`. - - `heading: Optional[str]` + - `"image_generation"` - Optional heading for the grouped task. Defaults to null when not provided. + - `action: Optional[Literal["generate", "edit", "auto"]]` - - `summary: Optional[str]` + Whether to generate a new image or edit an existing image. Default: `auto`. - Optional summary that describes the grouped task. Defaults to null when omitted. + - `"generate"` - - `type: Literal["custom", "thought"]` + - `"edit"` - Subtype for the grouped task. + - `"auto"` - - `"custom"` + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `"thought"` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `thread_id: str` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - Identifier of the parent thread. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `type: Literal["chatkit.task_group"]` + - `"transparent"` - Type discriminator that is always `chatkit.task_group`. + - `"opaque"` - - `"chatkit.task_group"` + - `"auto"` - - `first_id: Optional[str]` + - `input_fidelity: Optional[Literal["high", "low"]]` - The ID of the first item in the list. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `has_more: bool` + - `"high"` - Whether there are more items available. + - `"low"` - - `last_id: Optional[str]` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - The ID of the last item in the list. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `object: Literal["list"]` + - `file_id: Optional[str]` - The type of object returned, must be `list`. + File ID for the mask image. - - `"list"` + - `image_url: Optional[str]` -### ChatKit Thread User Message Item + Base64-encoded mask image. -- `class ChatKitThreadUserMessageItem: …` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - User-authored messages within a thread. + The image generation model to use. Default: `gpt-image-1`. - - `id: str` + - `str` - Identifier of the thread item. + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `attachments: List[ChatKitAttachment]` + The image generation model to use. Default: `gpt-image-1`. - Attachments associated with the user message. Defaults to an empty list. + - `"gpt-image-1"` - - `id: str` + - `"gpt-image-1-mini"` - Identifier for the attachment. + - `"gpt-image-2"` - - `mime_type: str` + - `"gpt-image-2-2026-04-21"` - MIME type of the attachment. + - `"gpt-image-1.5"` - - `name: str` + - `"chatgpt-image-latest"` - Original display name for the attachment. + - `moderation: Optional[Literal["auto", "low"]]` - - `preview_url: Optional[str]` + Moderation level for the generated image. Default: `auto`. - Preview URL for rendering the attachment inline. + - `"auto"` - - `type: Literal["image", "file"]` + - `"low"` - Attachment discriminator. + - `output_compression: Optional[int]` - - `"image"` + Compression level for the output image. Default: 100. - - `"file"` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `content: List[Content]` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - Ordered content elements supplied by the user. + - `"png"` - - `class ContentInputText: …` + - `"webp"` - Text block that a user contributed to the thread. + - `"jpeg"` - - `text: str` + - `partial_images: Optional[int]` - Plain-text content supplied by the user. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: Literal["input_text"]` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - Type discriminator that is always `input_text`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"input_text"` + - `"low"` - - `class ContentQuotedText: …` + - `"medium"` - Quoted snippet that the user referenced in their message. + - `"high"` - - `text: str` + - `"auto"` - Quoted text content. + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - - `type: Literal["quoted_text"]` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - Type discriminator that is always `quoted_text`. + - `str` - - `"quoted_text"` + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `created_at: int` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - Unix timestamp (in seconds) for when the item was created. + - `"1024x1024"` - - `inference_options: Optional[InferenceOptions]` + - `"1024x1536"` - Inference overrides applied to the message. Defaults to null when unset. + - `"1536x1024"` - - `model: Optional[str]` + - `"auto"` - Model name that generated the response. Defaults to null when using the session default. + - `class LocalShell: …` - - `tool_choice: Optional[InferenceOptionsToolChoice]` + A tool that allows the model to execute shell commands in a local environment. - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `type: Literal["local_shell"]` - - `id: str` + The type of the local shell tool. Always `local_shell`. - Identifier of the requested tool. + - `"local_shell"` - - `object: Literal["chatkit.thread_item"]` + - `class BetaFunctionShellTool: …` - Type discriminator that is always `chatkit.thread_item`. + A tool that allows the model to execute shell commands. - - `"chatkit.thread_item"` + - `type: Literal["shell"]` - - `thread_id: str` + The type of the shell tool. Always `shell`. - Identifier of the parent thread. + - `"shell"` - - `type: Literal["chatkit.user_message"]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"chatkit.user_message"` + The tool invocation context(s). -### ChatKit Widget Item + - `"direct"` -- `class ChatKitWidgetItem: …` + - `"programmatic"` - Thread item that renders a widget payload. + - `environment: Optional[Environment]` - - `id: str` + - `class BetaContainerAuto: …` - Identifier of the thread item. + - `type: Literal["container_auto"]` - - `created_at: int` + Automatically creates a container for this request - Unix timestamp (in seconds) for when the item was created. + - `"container_auto"` - - `object: Literal["chatkit.thread_item"]` + - `file_ids: Optional[List[str]]` - Type discriminator that is always `chatkit.thread_item`. + An optional list of uploaded files to make available to your code. - - `"chatkit.thread_item"` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `thread_id: str` + The memory limit for the container. - Identifier of the parent thread. + - `"1g"` - - `type: Literal["chatkit.widget"]` + - `"4g"` - Type discriminator that is always `chatkit.widget`. + - `"16g"` - - `"chatkit.widget"` + - `"64g"` - - `widget: str` + - `network_policy: Optional[NetworkPolicy]` - Serialized widget payload rendered in the UI. + Network access policy for the container. -### Thread Delete Response + - `class BetaContainerNetworkPolicyDisabled: …` -- `class ThreadDeleteResponse: …` + - `class BetaContainerNetworkPolicyAllowlist: …` - Confirmation payload returned after deleting a thread. + - `skills: Optional[List[Skill]]` - - `id: str` + An optional list of skills referenced by id or inline data. - Identifier of the deleted thread. + - `class BetaSkillReference: …` - - `deleted: bool` + - `skill_id: str` - Indicates that the thread has been deleted. + The ID of the referenced skill. - - `object: Literal["chatkit.thread.deleted"]` + - `type: Literal["skill_reference"]` - Type discriminator that is always `chatkit.thread.deleted`. + References a skill created with the /v1/skills endpoint. - - `"chatkit.thread.deleted"` + - `"skill_reference"` -# Assistants + - `version: Optional[str]` -## List assistants + Optional skill version. Use a positive integer or 'latest'. Omit for default. -`beta.assistants.list(AssistantListParams**kwargs) -> SyncCursorPage[Assistant]` + - `class BetaInlineSkill: …` -**get** `/assistants` + - `description: str` -List assistants + The description of the skill. -### Parameters + - `name: str` -- `after: Optional[str]` + The name of the skill. - 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. + - `source: BetaInlineSkillSource` -- `before: Optional[str]` + Inline skill payload - 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. + - `data: str` -- `limit: Optional[int]` + Base64-encoded skill zip bundle. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `media_type: Literal["application/zip"]` -- `order: Optional[Literal["asc", "desc"]]` + The media type of the inline skill payload. Must be `application/zip`. - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `"application/zip"` - - `"asc"` + - `type: Literal["base64"]` - - `"desc"` + The type of the inline skill source. Must be `base64`. -### Returns + - `"base64"` -- `class Assistant: …` + - `type: Literal["inline"]` - Represents an `assistant` that can call the model and use tools. + Defines an inline skill for this request. - - `id: str` + - `"inline"` - The identifier, which can be referenced in API endpoints. + - `class BetaLocalEnvironment: …` - - `created_at: int` + - `type: Literal["local"]` - The Unix timestamp (in seconds) for when the assistant was created. + Use a local computer environment. - - `description: Optional[str]` + - `"local"` - The description of the assistant. The maximum length is 512 characters. + - `skills: Optional[List[BetaLocalSkill]]` - - `instructions: Optional[str]` + An optional list of skills. - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `description: str` - - `metadata: Optional[Metadata]` + The description of the skill. - 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. + - `name: str` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The name of the skill. - - `model: str` + - `path: 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. + The path to the directory containing the skill. - - `name: Optional[str]` + - `class BetaContainerReference: …` - The name of the assistant. The maximum length is 256 characters. + - `container_id: str` - - `object: Literal["assistant"]` + The ID of the referenced container. - The object type, which is always `assistant`. + - `type: Literal["container_reference"]` - - `"assistant"` + References a container created with the /v1/containers endpoint - - `tools: List[object]` + - `"container_reference"` - 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 BetaCustomTool: …` - - `response_format: Optional[AssistantResponseFormatOption]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - 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`. + - `name: str` - 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). + The name of the custom tool, used to identify it in tool calls. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `type: Literal["custom"]` - **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. + The type of the custom tool. Always `custom`. - - `Literal["auto"]` + - `"custom"` - `auto` is the default value + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"auto"` + The tool invocation context(s). - - `class ResponseFormatText: …` + - `"direct"` - Default response format. Used to generate text responses. + - `"programmatic"` - - `type: Literal["text"]` + - `defer_loading: Optional[bool]` - The type of response format being defined. Always `text`. + Whether this tool should be deferred and discovered via tool search. - - `"text"` + - `description: Optional[str]` - - `class ResponseFormatJSONObject: …` + Optional description of the custom tool, used to provide more context. - 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. + - `format: Optional[Format]` - - `type: Literal["json_object"]` + The input format for the custom tool. Default is unconstrained text. - The type of response format being defined. Always `json_object`. + - `class FormatText: …` - - `"json_object"` + Unconstrained free-form text. - - `class ResponseFormatJSONSchema: …` + - `type: Literal["text"]` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + Unconstrained text format. Always `text`. - - `json_schema: JSONSchema` + - `"text"` - Structured Outputs configuration options, including a JSON Schema. + - `class FormatGrammar: …` - - `name: str` + A grammar defined by the user. - 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. + - `definition: str` - - `description: Optional[str]` + The grammar definition. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `syntax: Literal["lark", "regex"]` - - `schema: Optional[Dict[str, object]]` + The syntax of the grammar definition. One of `lark` or `regex`. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"lark"` - - `strict: Optional[bool]` + - `"regex"` - 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["grammar"]` - - `type: Literal["json_schema"]` + Grammar format. Always `grammar`. - The type of response format being defined. Always `json_schema`. + - `"grammar"` - - `"json_schema"` + - `class BetaNamespaceTool: …` - - `temperature: Optional[float]` + Groups function/custom tools under a shared namespace. - 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. + - `description: str` - - `tool_resources: Optional[ToolResources]` + A description of the namespace shown to the model. - 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. + - `name: str` - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + The namespace name used in tool calls (for example, `crm`). - - `file_ids: Optional[List[str]]` + - `tools: List[Tool]` - 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. + The function/custom tools available inside this namespace. - - `file_search: Optional[ToolResourcesFileSearch]` + - `class ToolFunction: …` - - `vector_store_ids: Optional[List[str]]` + - `name: 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. + - `type: Literal["function"]` - - `top_p: Optional[float]` + - `"function"` - 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. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - We generally recommend altering this or temperature but not both. + The tool invocation context(s). -### Example + - `"direct"` -```python -import os -from openai import OpenAI + - `"programmatic"` -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) -``` + - `defer_loading: Optional[bool]` -#### Response + Whether this function should be deferred and discovered via tool search. -```json -{ - "data": [ - { - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "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" -} -``` + - `description: Optional[str]` -### Example + - `output_schema: Optional[Dict[str, object]]` -```python -from openai import OpenAI -client = OpenAI() + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. -my_assistants = client.beta.assistants.list( - order="desc", - limit="20", -) -print(my_assistants.data) -``` + - `parameters: Optional[object]` -#### Response + - `strict: Optional[bool]` -```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 -} -``` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. -## Create assistant + - `class BetaCustomTool: …` -`beta.assistants.create(AssistantCreateParams**kwargs) -> Assistant` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) -**post** `/assistants` + - `type: Literal["namespace"]` -Create assistant + The type of the tool. Always `namespace`. -### Parameters + - `"namespace"` -- `model: Union[str, ChatModel]` + - `class BetaToolSearchTool: …` - 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. + Hosted or BYOT tool search configuration for deferred tools. - - `str` + - `type: Literal["tool_search"]` - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 78 more]` + The type of the tool. Always `tool_search`. - - `"gpt-5.6-sol"` + - `"tool_search"` - - `"gpt-5.6-terra"` + - `description: Optional[str]` - - `"gpt-5.6-luna"` + Description shown to the model for a client-executed tool search tool. - - `"gpt-5.4"` + - `execution: Optional[Literal["server", "client"]]` - - `"gpt-5.4-mini"` + Whether tool search is executed by the server or by the client. - - `"gpt-5.4-nano"` + - `"server"` - - `"gpt-5.4-mini-2026-03-17"` + - `"client"` - - `"gpt-5.4-nano-2026-03-17"` + - `parameters: Optional[object]` - - `"gpt-5.3-chat-latest"` + Parameter schema for a client-executed tool search tool. - - `"gpt-5.2"` + - `class BetaWebSearchPreviewTool: …` - - `"gpt-5.2-2025-12-11"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"gpt-5.2-chat-latest"` + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - - `"gpt-5.2-pro"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"gpt-5.2-pro-2025-12-11"` + - `"web_search_preview"` - - `"gpt-5.1"` + - `"web_search_preview_2025_03_11"` - - `"gpt-5.1-2025-11-13"` + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `"gpt-5.1-codex"` + - `"text"` - - `"gpt-5.1-mini"` + - `"image"` - - `"gpt-5.1-chat-latest"` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `"gpt-5"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `"gpt-5-mini"` + - `"low"` - - `"gpt-5-nano"` + - `"medium"` - - `"gpt-5-2025-08-07"` + - `"high"` - - `"gpt-5-mini-2025-08-07"` + - `user_location: Optional[UserLocation]` - - `"gpt-5-nano-2025-08-07"` + The user's location. - - `"gpt-5-chat-latest"` + - `type: Literal["approximate"]` - - `"gpt-4.1"` + The type of location approximation. Always `approximate`. - - `"gpt-4.1-mini"` + - `"approximate"` - - `"gpt-4.1-nano"` + - `city: Optional[str]` - - `"gpt-4.1-2025-04-14"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"gpt-4.1-mini-2025-04-14"` + - `country: Optional[str]` - - `"gpt-4.1-nano-2025-04-14"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"o4-mini"` + - `region: Optional[str]` - - `"o4-mini-2025-04-16"` + Free text input for the region of the user, e.g. `California`. - - `"o3"` + - `timezone: Optional[str]` - - `"o3-2025-04-16"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"o3-mini"` + - `class BetaApplyPatchTool: …` - - `"o3-mini-2025-01-31"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"o1"` + - `type: Literal["apply_patch"]` - - `"o1-2024-12-17"` + The type of the tool. Always `apply_patch`. - - `"o1-preview"` + - `"apply_patch"` - - `"o1-preview-2024-09-12"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"o1-mini"` + The tool invocation context(s). - - `"o1-mini-2024-09-12"` + - `"direct"` - - `"gpt-4o"` + - `"programmatic"` - - `"gpt-4o-2024-11-20"` + - `type: Literal["tool_search_output"]` - - `"gpt-4o-2024-08-06"` + The item type. Always `tool_search_output`. - - `"gpt-4o-2024-05-13"` + - `"tool_search_output"` - - `"gpt-4o-audio-preview"` + - `id: Optional[str]` - - `"gpt-4o-audio-preview-2024-10-01"` + The unique ID of this tool search output. - - `"gpt-4o-audio-preview-2024-12-17"` + - `agent: Optional[Agent]` - - `"gpt-4o-audio-preview-2025-06-03"` + The agent that produced this item. - - `"gpt-4o-mini-audio-preview"` + - `agent_name: str` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The canonical name of the agent that produced this item. - - `"gpt-4o-search-preview"` + - `call_id: Optional[str]` - - `"gpt-4o-mini-search-preview"` + The unique ID of the tool search call generated by the model. - - `"gpt-4o-search-preview-2025-03-11"` + - `execution: Optional[Literal["server", "client"]]` - - `"gpt-4o-mini-search-preview-2025-03-11"` + Whether tool search was executed by the server or by the client. - - `"chatgpt-4o-latest"` + - `"server"` - - `"codex-mini-latest"` + - `"client"` - - `"gpt-4o-mini"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"gpt-4o-mini-2024-07-18"` + The status of the tool search output. - - `"gpt-4-turbo"` + - `"in_progress"` - - `"gpt-4-turbo-2024-04-09"` + - `"completed"` - - `"gpt-4-0125-preview"` + - `"incomplete"` - - `"gpt-4-turbo-preview"` + - `class AdditionalTools: …` - - `"gpt-4-1106-preview"` + - `role: Literal["developer"]` - - `"gpt-4-vision-preview"` + The role that provided the additional tools. Only `developer` is supported. - - `"gpt-4"` + - `"developer"` - - `"gpt-4-0314"` + - `tools: List[BetaTool]` - - `"gpt-4-0613"` + A list of additional tools made available at this item. - - `"gpt-4-32k"` + - `class BetaFunctionTool: …` - - `"gpt-4-32k-0314"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"gpt-4-32k-0613"` + - `class BetaFileSearchTool: …` - - `"gpt-3.5-turbo"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `"gpt-3.5-turbo-16k"` + - `class BetaComputerTool: …` - - `"gpt-3.5-turbo-0301"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-3.5-turbo-0613"` + - `class BetaComputerUsePreviewTool: …` - - `"gpt-3.5-turbo-1106"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-3.5-turbo-0125"` + - `class BetaWebSearchTool: …` - - `"gpt-3.5-turbo-16k-0613"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). -- `description: Optional[str]` + - `class Mcp: …` - The description of the assistant. The maximum length is 512 characters. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). -- `instructions: Optional[str]` + - `class CodeInterpreter: …` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + A tool that runs Python code to help generate a response to a prompt. -- `metadata: Optional[Metadata]` + - `class ProgrammaticToolCalling: …` - 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. + - `class ImageGeneration: …` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A tool that generates images using the GPT image models. -- `name: Optional[str]` + - `class LocalShell: …` - The name of the assistant. The maximum length is 256 characters. + A tool that allows the model to execute shell commands in a local environment. -- `reasoning_effort: Optional[ReasoningEffort]` + - `class BetaFunctionShellTool: …` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + A tool that allows the model to execute shell commands. - - `"none"` + - `class BetaCustomTool: …` - - `"minimal"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `"low"` + - `class BetaNamespaceTool: …` - - `"medium"` + Groups function/custom tools under a shared namespace. - - `"high"` + - `class BetaToolSearchTool: …` - - `"xhigh"` + Hosted or BYOT tool search configuration for deferred tools. - - `"max"` + - `class BetaWebSearchPreviewTool: …` -- `response_format: Optional[AssistantResponseFormatOptionParam]` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - 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`. + - `class BetaApplyPatchTool: …` - 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). + Allows the assistant to create, delete, or update files using unified diffs. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `type: Literal["additional_tools"]` - **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. + The item type. Always `additional_tools`. - - `Literal["auto"]` + - `"additional_tools"` - `auto` is the default value + - `id: Optional[str]` - - `"auto"` + The unique ID of this additional tools item. - - `class ResponseFormatText: …` + - `agent: Optional[AdditionalToolsAgent]` - Default response format. Used to generate text responses. + The agent that produced this item. - - `type: Literal["text"]` + - `agent_name: str` - The type of response format being defined. Always `text`. + The canonical name of the agent that produced this item. - - `"text"` + - `class BetaResponseReasoningItem: …` - - `class ResponseFormatJSONObject: …` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - 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. + - `id: str` - - `type: Literal["json_object"]` + The unique identifier of the reasoning content. - The type of response format being defined. Always `json_object`. + - `summary: List[Summary]` - - `"json_object"` + Reasoning summary content. - - `class ResponseFormatJSONSchema: …` + - `text: str` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + A summary of the reasoning output from the model so far. - - `json_schema: JSONSchema` + - `type: Literal["summary_text"]` - Structured Outputs configuration options, including a JSON Schema. + The type of the object. Always `summary_text`. - - `name: str` + - `"summary_text"` - 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. + - `type: Literal["reasoning"]` - - `description: Optional[str]` + The type of the object. Always `reasoning`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"reasoning"` - - `schema: Optional[Dict[str, object]]` + - `agent: Optional[Agent]` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The agent that produced this item. - - `strict: Optional[bool]` + - `agent_name: str` - 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). + The canonical name of the agent that produced this item. - - `type: Literal["json_schema"]` + - `content: Optional[List[Content]]` - The type of response format being defined. Always `json_schema`. + Reasoning text content. - - `"json_schema"` + - `text: str` -- `temperature: Optional[float]` + The reasoning text from the model. - 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. + - `type: Literal["reasoning_text"]` -- `tool_resources: Optional[ToolResources]` + The type of the reasoning text. Always `reasoning_text`. - 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. + - `"reasoning_text"` - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + - `encrypted_content: Optional[str]` - - `file_ids: Optional[Sequence[str]]` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - 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. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `file_search: Optional[ToolResourcesFileSearch]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `vector_store_ids: Optional[Sequence[str]]` + - `"in_progress"` - 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. + - `"completed"` - - `vector_stores: Optional[Iterable[ToolResourcesFileSearchVectorStore]]` + - `"incomplete"` - 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. + - `class BetaResponseCompactionItemParam: …` - - `chunking_strategy: Optional[ToolResourcesFileSearchVectorStoreChunkingStrategy]` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + - `encrypted_content: str` - - `class ToolResourcesFileSearchVectorStoreChunkingStrategyAuto: …` + The encrypted content of the compaction summary. - The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. + - `type: Literal["compaction"]` - - `type: Literal["auto"]` + The type of the item. Always `compaction`. - Always `auto`. + - `"compaction"` - - `"auto"` + - `id: Optional[str]` - - `class ToolResourcesFileSearchVectorStoreChunkingStrategyStatic: …` + The ID of the compaction item. - - `static: ToolResourcesFileSearchVectorStoreChunkingStrategyStaticStatic` + - `agent: Optional[Agent]` - - `chunk_overlap_tokens: int` + The agent that produced this item. - The number of tokens that overlap between chunks. The default value is `400`. + - `agent_name: str` - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + The canonical name of the agent that produced this item. - - `max_chunk_size_tokens: int` + - `class ImageGenerationCall: …` - The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. + An image generation request made by the model. - - `type: Literal["static"]` + - `id: str` - Always `static`. + The unique ID of the image generation call. - - `"static"` + - `result: Optional[str]` - - `file_ids: Optional[Sequence[str]]` + The generated image encoded in base64. - 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. + - `status: Literal["in_progress", "completed", "generating", "failed"]` - - `metadata: Optional[Metadata]` + The status of the image generation call. - 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. + - `"in_progress"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"completed"` -- `tools: Optional[Iterable[object]]` + - `"generating"` - 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`. + - `"failed"` -- `top_p: Optional[float]` + - `type: Literal["image_generation_call"]` - 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. + The type of the image generation call. Always `image_generation_call`. - We generally recommend altering this or temperature but not both. + - `"image_generation_call"` -### Returns + - `agent: Optional[ImageGenerationCallAgent]` -- `class Assistant: …` + The agent that produced this item. - Represents an `assistant` that can call the model and use tools. + - `agent_name: str` - - `id: str` + The canonical name of the agent that produced this item. - The identifier, which can be referenced in API endpoints. + - `class BetaResponseCodeInterpreterToolCall: …` - - `created_at: int` + A tool call to run code. - The Unix timestamp (in seconds) for when the assistant was created. + - `id: str` - - `description: Optional[str]` + The unique ID of the code interpreter tool call. - The description of the assistant. The maximum length is 512 characters. + - `code: Optional[str]` - - `instructions: Optional[str]` + The code to run, or null if not available. - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `container_id: str` - - `metadata: Optional[Metadata]` + The ID of the container used to run the code. - 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. + - `outputs: Optional[List[Output]]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `model: str` + - `class OutputLogs: …` - 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. + The logs output from the code interpreter. - - `name: Optional[str]` + - `logs: str` - The name of the assistant. The maximum length is 256 characters. + The logs output from the code interpreter. - - `object: Literal["assistant"]` + - `type: Literal["logs"]` - The object type, which is always `assistant`. + The type of the output. Always `logs`. - - `"assistant"` + - `"logs"` - - `tools: List[object]` + - `class OutputImage: …` - 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`. + The image output from the code interpreter. - - `response_format: Optional[AssistantResponseFormatOption]` + - `type: Literal["image"]` - 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`. + The type of the output. Always `image`. - 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). + - `"image"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `url: str` - **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. + The URL of the image output from the code interpreter. - - `Literal["auto"]` + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - `auto` is the default value + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"auto"` + - `"in_progress"` - - `class ResponseFormatText: …` + - `"completed"` - Default response format. Used to generate text responses. + - `"incomplete"` - - `type: Literal["text"]` + - `"interpreting"` - The type of response format being defined. Always `text`. + - `"failed"` - - `"text"` + - `type: Literal["code_interpreter_call"]` - - `class ResponseFormatJSONObject: …` + The type of the code interpreter tool call. Always `code_interpreter_call`. - 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. + - `"code_interpreter_call"` - - `type: Literal["json_object"]` + - `agent: Optional[Agent]` - The type of response format being defined. Always `json_object`. + The agent that produced this item. - - `"json_object"` + - `agent_name: str` - - `class ResponseFormatJSONSchema: …` + The canonical name of the agent that produced this item. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `class LocalShellCall: …` - - `json_schema: JSONSchema` + A tool call to run a command on the local shell. - Structured Outputs configuration options, including a JSON Schema. + - `id: str` - - `name: str` + The unique ID of the local shell call. - 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. + - `action: LocalShellCallAction` - - `description: Optional[str]` + Execute a shell command on the server. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `command: List[str]` - - `schema: Optional[Dict[str, object]]` + The command to run. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `env: Dict[str, str]` - - `strict: Optional[bool]` + Environment variables to set for the command. - 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["exec"]` - - `type: Literal["json_schema"]` + The type of the local shell action. Always `exec`. - The type of response format being defined. Always `json_schema`. + - `"exec"` - - `"json_schema"` + - `timeout_ms: Optional[int]` - - `temperature: Optional[float]` + Optional timeout in milliseconds for the command. - 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. + - `user: Optional[str]` - - `tool_resources: Optional[ToolResources]` + Optional user to run the command as. - 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. + - `working_directory: Optional[str]` - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + Optional working directory to run the command in. - - `file_ids: Optional[List[str]]` + - `call_id: 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. + The unique ID of the local shell tool call generated by the model. - - `file_search: Optional[ToolResourcesFileSearch]` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `vector_store_ids: Optional[List[str]]` + The status of the local shell call. - 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. + - `"in_progress"` - - `top_p: Optional[float]` + - `"completed"` - 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. + - `"incomplete"` - We generally recommend altering this or temperature but not both. + - `type: Literal["local_shell_call"]` -### Example + The type of the local shell call. Always `local_shell_call`. -```python -import os -from openai import OpenAI + - `"local_shell_call"` -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) -``` + - `agent: Optional[LocalShellCallAgent]` -#### Response + The agent that produced this item. -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + - `agent_name: str` -### Code Interpreter + The canonical name of the agent that produced this item. -```python -from openai import OpenAI -client = OpenAI() + - `class LocalShellCallOutput: …` -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) -``` + The output of a local shell tool call. -#### Response + - `id: str` -```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" -} -``` + The unique ID of the local shell tool call generated by the model. -### Files + - `output: str` -```python -from openai import OpenAI -client = OpenAI() + A JSON string of the output of the local shell tool call. -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) -``` + - `type: Literal["local_shell_call_output"]` -#### Response + The type of the local shell tool call output. Always `local_shell_call_output`. -```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" -} -``` + - `"local_shell_call_output"` -## Retrieve assistant + - `agent: Optional[LocalShellCallOutputAgent]` -`beta.assistants.retrieve(strassistant_id) -> Assistant` + The agent that produced this item. -**get** `/assistants/{assistant_id}` + - `agent_name: str` -Retrieve assistant + The canonical name of the agent that produced this item. -### Parameters + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` -- `assistant_id: str` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. -### Returns + - `"in_progress"` -- `class Assistant: …` + - `"completed"` - Represents an `assistant` that can call the model and use tools. + - `"incomplete"` - - `id: str` + - `class ShellCall: …` - The identifier, which can be referenced in API endpoints. + A tool representing a request to execute one or more shell commands. - - `created_at: int` + - `action: ShellCallAction` - The Unix timestamp (in seconds) for when the assistant was created. + The shell commands and limits that describe how to run the tool call. - - `description: Optional[str]` + - `commands: List[str]` - The description of the assistant. The maximum length is 512 characters. + Ordered shell commands for the execution environment to run. - - `instructions: Optional[str]` + - `max_output_length: Optional[int]` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `metadata: Optional[Metadata]` + - `timeout_ms: Optional[int]` - 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. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `call_id: str` - - `model: str` + The unique ID of the shell tool call generated by the model. - 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. + - `type: Literal["shell_call"]` - - `name: Optional[str]` + The type of the item. Always `shell_call`. - The name of the assistant. The maximum length is 256 characters. + - `"shell_call"` - - `object: Literal["assistant"]` + - `id: Optional[str]` - The object type, which is always `assistant`. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"assistant"` + - `agent: Optional[ShellCallAgent]` - - `tools: List[object]` + The agent that produced this item. - 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`. + - `agent_name: str` - - `response_format: Optional[AssistantResponseFormatOption]` + The canonical name of the agent that produced this item. - 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`. + - `caller: Optional[ShellCallCaller]` - 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). + The execution context that produced this tool call. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `class ShellCallCallerDirect: …` - **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. + - `type: Literal["direct"]` - - `Literal["auto"]` + The caller type. Always `direct`. - `auto` is the default value + - `"direct"` - - `"auto"` + - `class ShellCallCallerProgram: …` - - `class ResponseFormatText: …` + - `caller_id: str` - Default response format. Used to generate text responses. + The call ID of the program item that produced this tool call. - - `type: Literal["text"]` + - `type: Literal["program"]` - The type of response format being defined. Always `text`. + The caller type. Always `program`. - - `"text"` + - `"program"` - - `class ResponseFormatJSONObject: …` + - `environment: Optional[ShellCallEnvironment]` - 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. + The environment to execute the shell commands in. - - `type: Literal["json_object"]` + - `class BetaLocalEnvironment: …` - The type of response format being defined. Always `json_object`. + - `class BetaContainerReference: …` - - `"json_object"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `class ResponseFormatJSONSchema: …` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"in_progress"` - - `json_schema: JSONSchema` + - `"completed"` - Structured Outputs configuration options, including a JSON Schema. + - `"incomplete"` - - `name: str` + - `class ShellCallOutput: …` - 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. + The streamed output items emitted by a shell tool call. - - `description: Optional[str]` + - `call_id: str` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The unique ID of the shell tool call generated by the model. - - `schema: Optional[Dict[str, object]]` + - `output: List[BetaResponseFunctionShellCallOutputContent]` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `strict: Optional[bool]` + - `outcome: Outcome` - 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). + The exit or timeout outcome associated with this shell call. - - `type: Literal["json_schema"]` + - `class OutcomeTimeout: …` - The type of response format being defined. Always `json_schema`. + Indicates that the shell call exceeded its configured time limit. - - `"json_schema"` + - `type: Literal["timeout"]` - - `temperature: Optional[float]` + The outcome type. Always `timeout`. - 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. + - `"timeout"` - - `tool_resources: Optional[ToolResources]` + - `class OutcomeExit: …` - 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. + Indicates that the shell commands finished and returned an exit code. - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + - `exit_code: int` - - `file_ids: Optional[List[str]]` + The exit code returned by the shell process. - 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. + - `type: Literal["exit"]` - - `file_search: Optional[ToolResourcesFileSearch]` + The outcome type. Always `exit`. - - `vector_store_ids: Optional[List[str]]` + - `"exit"` - 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. + - `stderr: str` - - `top_p: Optional[float]` + Captured stderr output for the shell call. - 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. + - `stdout: str` - We generally recommend altering this or temperature but not both. + Captured stdout output for the shell call. -### Example + - `type: Literal["shell_call_output"]` -```python -import os -from openai import OpenAI + The type of the item. Always `shell_call_output`. -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) -``` + - `"shell_call_output"` -#### Response + - `id: Optional[str]` -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + The unique ID of the shell tool call output. Populated when this item is returned via API. -### Example + - `agent: Optional[ShellCallOutputAgent]` -```python -from openai import OpenAI -client = OpenAI() + The agent that produced this item. -my_assistant = client.beta.assistants.retrieve("asst_abc123") -print(my_assistant) -``` + - `agent_name: str` -#### Response + The canonical name of the agent that produced this item. -```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" -} -``` + - `caller: Optional[ShellCallOutputCaller]` -## Modify assistant + The execution context that produced this tool call. -`beta.assistants.update(strassistant_id, AssistantUpdateParams**kwargs) -> Assistant` + - `class ShellCallOutputCallerDirect: …` -**post** `/assistants/{assistant_id}` + - `type: Literal["direct"]` -Modify assistant + The caller type. Always `direct`. -### Parameters + - `"direct"` -- `assistant_id: str` + - `class ShellCallOutputCallerProgram: …` -- `description: Optional[str]` + - `caller_id: str` - The description of the assistant. The maximum length is 512 characters. + The call ID of the program item that produced this tool call. -- `instructions: Optional[str]` + - `type: Literal["program"]` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + The caller type. Always `program`. -- `metadata: Optional[Metadata]` + - `"program"` - 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. + - `max_output_length: Optional[int]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The maximum number of UTF-8 characters captured for this shell call's combined output. -- `model: Optional[Union[str, Literal["gpt-5", "gpt-5-mini", "gpt-5-nano", 39 more]]]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - 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. + The status of the shell call output. - - `str` + - `"in_progress"` - - `Literal["gpt-5", "gpt-5-mini", "gpt-5-nano", 39 more]` + - `"completed"` - 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. + - `"incomplete"` - - `"gpt-5"` + - `class ApplyPatchCall: …` - - `"gpt-5-mini"` + A tool call representing a request to create, delete, or update files using diff patches. - - `"gpt-5-nano"` + - `call_id: str` - - `"gpt-5-2025-08-07"` + The unique ID of the apply patch tool call generated by the model. - - `"gpt-5-mini-2025-08-07"` + - `operation: ApplyPatchCallOperation` - - `"gpt-5-nano-2025-08-07"` + The specific create, delete, or update instruction for the apply_patch tool call. - - `"gpt-4.1"` + - `class ApplyPatchCallOperationCreateFile: …` - - `"gpt-4.1-mini"` + Instruction for creating a new file via the apply_patch tool. - - `"gpt-4.1-nano"` + - `diff: str` - - `"gpt-4.1-2025-04-14"` + Unified diff content to apply when creating the file. - - `"gpt-4.1-mini-2025-04-14"` + - `path: str` - - `"gpt-4.1-nano-2025-04-14"` + Path of the file to create relative to the workspace root. - - `"o3-mini"` + - `type: Literal["create_file"]` - - `"o3-mini-2025-01-31"` + The operation type. Always `create_file`. - - `"o1"` + - `"create_file"` - - `"o1-2024-12-17"` + - `class ApplyPatchCallOperationDeleteFile: …` - - `"gpt-4o"` + Instruction for deleting an existing file via the apply_patch tool. - - `"gpt-4o-2024-11-20"` + - `path: str` - - `"gpt-4o-2024-08-06"` + Path of the file to delete relative to the workspace root. - - `"gpt-4o-2024-05-13"` + - `type: Literal["delete_file"]` - - `"gpt-4o-mini"` + The operation type. Always `delete_file`. - - `"gpt-4o-mini-2024-07-18"` + - `"delete_file"` - - `"gpt-4.5-preview"` + - `class ApplyPatchCallOperationUpdateFile: …` - - `"gpt-4.5-preview-2025-02-27"` + Instruction for updating an existing file via the apply_patch tool. - - `"gpt-4-turbo"` + - `diff: str` - - `"gpt-4-turbo-2024-04-09"` + Unified diff content to apply to the existing file. - - `"gpt-4-0125-preview"` + - `path: str` - - `"gpt-4-turbo-preview"` + Path of the file to update relative to the workspace root. - - `"gpt-4-1106-preview"` + - `type: Literal["update_file"]` - - `"gpt-4-vision-preview"` + The operation type. Always `update_file`. - - `"gpt-4"` + - `"update_file"` - - `"gpt-4-0314"` + - `status: Literal["in_progress", "completed"]` - - `"gpt-4-0613"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"gpt-4-32k"` + - `"in_progress"` - - `"gpt-4-32k-0314"` + - `"completed"` - - `"gpt-4-32k-0613"` + - `type: Literal["apply_patch_call"]` - - `"gpt-3.5-turbo"` + The type of the item. Always `apply_patch_call`. - - `"gpt-3.5-turbo-16k"` + - `"apply_patch_call"` - - `"gpt-3.5-turbo-0613"` + - `id: Optional[str]` - - `"gpt-3.5-turbo-1106"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"gpt-3.5-turbo-0125"` + - `agent: Optional[ApplyPatchCallAgent]` - - `"gpt-3.5-turbo-16k-0613"` + The agent that produced this item. -- `name: Optional[str]` + - `agent_name: str` - The name of the assistant. The maximum length is 256 characters. + The canonical name of the agent that produced this item. -- `reasoning_effort: Optional[ReasoningEffort]` + - `caller: Optional[ApplyPatchCallCaller]` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The execution context that produced this tool call. - - `"none"` + - `class ApplyPatchCallCallerDirect: …` - - `"minimal"` + - `type: Literal["direct"]` - - `"low"` + The caller type. Always `direct`. - - `"medium"` + - `"direct"` - - `"high"` + - `class ApplyPatchCallCallerProgram: …` - - `"xhigh"` + - `caller_id: str` - - `"max"` + The call ID of the program item that produced this tool call. -- `response_format: Optional[AssistantResponseFormatOptionParam]` + - `type: Literal["program"]` - 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`. + The caller type. Always `program`. - 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). + - `"program"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `class ApplyPatchCallOutput: …` - **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. + The streamed output emitted by an apply patch tool call. - - `Literal["auto"]` + - `call_id: str` - `auto` is the default value + The unique ID of the apply patch tool call generated by the model. - - `"auto"` + - `status: Literal["completed", "failed"]` - - `class ResponseFormatText: …` + The status of the apply patch tool call output. One of `completed` or `failed`. - Default response format. Used to generate text responses. + - `"completed"` - - `type: Literal["text"]` + - `"failed"` - The type of response format being defined. Always `text`. + - `type: Literal["apply_patch_call_output"]` - - `"text"` + The type of the item. Always `apply_patch_call_output`. - - `class ResponseFormatJSONObject: …` + - `"apply_patch_call_output"` - 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. + - `id: Optional[str]` - - `type: Literal["json_object"]` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The type of response format being defined. Always `json_object`. + - `agent: Optional[ApplyPatchCallOutputAgent]` - - `"json_object"` + The agent that produced this item. - - `class ResponseFormatJSONSchema: …` + - `agent_name: str` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The canonical name of the agent that produced this item. - - `json_schema: JSONSchema` + - `caller: Optional[ApplyPatchCallOutputCaller]` - Structured Outputs configuration options, including a JSON Schema. + The execution context that produced this tool call. - - `name: str` + - `class ApplyPatchCallOutputCallerDirect: …` - 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. + - `type: Literal["direct"]` - - `description: Optional[str]` + The caller type. Always `direct`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"direct"` - - `schema: Optional[Dict[str, object]]` + - `class ApplyPatchCallOutputCallerProgram: …` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `caller_id: str` - - `strict: Optional[bool]` + The call ID of the program item that produced this tool call. - 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["program"]` - - `type: Literal["json_schema"]` + The caller type. Always `program`. - The type of response format being defined. Always `json_schema`. + - `"program"` - - `"json_schema"` + - `output: Optional[str]` -- `temperature: Optional[float]` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - 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. + - `class McpListTools: …` -- `tool_resources: Optional[ToolResources]` + A list of tools available on an MCP server. - 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. + - `id: str` - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + The unique ID of the list. - - `file_ids: Optional[Sequence[str]]` + - `server_label: 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. + The label of the MCP server. - - `file_search: Optional[ToolResourcesFileSearch]` + - `tools: List[McpListToolsTool]` - - `vector_store_ids: Optional[Sequence[str]]` + The tools available on the server. - 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. + - `input_schema: object` -- `tools: Optional[Iterable[object]]` + The JSON schema describing the tool's input. - 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`. + - `name: str` -- `top_p: Optional[float]` + The name of the tool. - 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. + - `annotations: Optional[object]` - We generally recommend altering this or temperature but not both. + Additional annotations about the tool. -### Returns + - `description: Optional[str]` -- `class Assistant: …` + The description of the tool. - Represents an `assistant` that can call the model and use tools. + - `type: Literal["mcp_list_tools"]` - - `id: str` + The type of the item. Always `mcp_list_tools`. - The identifier, which can be referenced in API endpoints. + - `"mcp_list_tools"` - - `created_at: int` + - `agent: Optional[McpListToolsAgent]` - The Unix timestamp (in seconds) for when the assistant was created. + The agent that produced this item. - - `description: Optional[str]` + - `agent_name: str` - The description of the assistant. The maximum length is 512 characters. + The canonical name of the agent that produced this item. - - `instructions: Optional[str]` + - `error: Optional[str]` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + Error message if the server could not list tools. - - `metadata: Optional[Metadata]` + - `class McpApprovalRequest: …` - 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. + A request for human approval of a tool invocation. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `id: str` - - `model: str` + The unique ID of the approval request. - 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. + - `arguments: str` - - `name: Optional[str]` + A JSON string of arguments for the tool. - The name of the assistant. The maximum length is 256 characters. + - `name: str` - - `object: Literal["assistant"]` + The name of the tool to run. - The object type, which is always `assistant`. + - `server_label: str` - - `"assistant"` + The label of the MCP server making the request. - - `tools: List[object]` + - `type: Literal["mcp_approval_request"]` - 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`. + The type of the item. Always `mcp_approval_request`. - - `response_format: Optional[AssistantResponseFormatOption]` + - `"mcp_approval_request"` - 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`. + - `agent: Optional[McpApprovalRequestAgent]` - 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). + The agent that produced this item. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `agent_name: str` - **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. + The canonical name of the agent that produced this item. - - `Literal["auto"]` + - `class McpApprovalResponse: …` - `auto` is the default value + A response to an MCP approval request. - - `"auto"` + - `approval_request_id: str` - - `class ResponseFormatText: …` + The ID of the approval request being answered. - Default response format. Used to generate text responses. + - `approve: bool` - - `type: Literal["text"]` + Whether the request was approved. - The type of response format being defined. Always `text`. + - `type: Literal["mcp_approval_response"]` - - `"text"` + The type of the item. Always `mcp_approval_response`. - - `class ResponseFormatJSONObject: …` + - `"mcp_approval_response"` - 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. + - `id: Optional[str]` - - `type: Literal["json_object"]` + The unique ID of the approval response - The type of response format being defined. Always `json_object`. + - `agent: Optional[McpApprovalResponseAgent]` - - `"json_object"` + The agent that produced this item. - - `class ResponseFormatJSONSchema: …` + - `agent_name: str` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The canonical name of the agent that produced this item. - - `json_schema: JSONSchema` + - `reason: Optional[str]` - Structured Outputs configuration options, including a JSON Schema. + Optional reason for the decision. - - `name: str` + - `class McpCall: …` - 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. + An invocation of a tool on an MCP server. - - `description: Optional[str]` + - `id: str` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The unique ID of the tool call. - - `schema: Optional[Dict[str, object]]` + - `arguments: str` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + A JSON string of the arguments passed to the tool. - - `strict: Optional[bool]` + - `name: str` - 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). + The name of the tool that was run. - - `type: Literal["json_schema"]` + - `server_label: str` - The type of response format being defined. Always `json_schema`. + The label of the MCP server running the tool. - - `"json_schema"` + - `type: Literal["mcp_call"]` - - `temperature: Optional[float]` + The type of the item. Always `mcp_call`. - 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. + - `"mcp_call"` - - `tool_resources: Optional[ToolResources]` + - `agent: Optional[McpCallAgent]` - 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. + The agent that produced this item. - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + - `agent_name: str` - - `file_ids: Optional[List[str]]` + The canonical name of the agent that produced this item. - 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. + - `approval_request_id: Optional[str]` - - `file_search: Optional[ToolResourcesFileSearch]` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `vector_store_ids: Optional[List[str]]` + - `error: Optional[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. + The error from the tool call, if any. - - `top_p: Optional[float]` + - `output: Optional[str]` - 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. + The output from the tool call. - We generally recommend altering this or temperature but not both. + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` -### Example + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. -```python -import os -from openai import OpenAI + - `"in_progress"` -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) -``` + - `"completed"` -#### Response + - `"incomplete"` -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + - `"calling"` -### Example + - `"failed"` -```python -from openai import OpenAI -client = OpenAI() + - `class BetaResponseCustomToolCallOutput: …` -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" -) + The output of a custom tool call from your code, being sent back to the model. -print(my_updated_assistant) -``` + - `call_id: str` -#### Response + The call ID, used to map this custom tool call output to a custom tool call. -```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" -} -``` + - `output: Union[str, List[OutputOutputContentList]]` -## Delete assistant + The output from the custom tool call generated by your code. + Can be a string or an list of output content. -`beta.assistants.delete(strassistant_id) -> AssistantDeleted` + - `str` -**delete** `/assistants/{assistant_id}` + A string of the output of the custom tool call. -Delete assistant + - `List[OutputOutputContentList]` -### Parameters + Text, image, or file output of the custom tool call. -- `assistant_id: str` + - `class BetaResponseInputText: …` -### Returns + A text input to the model. -- `class AssistantDeleted: …` + - `class BetaResponseInputImage: …` - - `id: str` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `deleted: bool` + - `class BetaResponseInputFile: …` - - `object: Literal["assistant.deleted"]` + A file input to the model. - - `"assistant.deleted"` + - `type: Literal["custom_tool_call_output"]` -### Example + The type of the custom tool call output. Always `custom_tool_call_output`. -```python -import os -from openai import OpenAI + - `"custom_tool_call_output"` -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) -``` + - `id: Optional[str]` -#### Response + The unique ID of the custom tool call output in the OpenAI platform. -```json -{ - "id": "id", - "deleted": true, - "object": "assistant.deleted" -} -``` + - `agent: Optional[Agent]` -### Example + The agent that produced this item. -```python -from openai import OpenAI -client = OpenAI() + - `agent_name: str` -response = client.beta.assistants.delete("asst_abc123") -print(response) -``` + The canonical name of the agent that produced this item. -#### Response + - `caller: Optional[Caller]` -```json -{ - "id": "asst_abc123", - "object": "assistant.deleted", - "deleted": true -} -``` + The execution context that produced this tool call. -## Domain Types + - `class CallerDirect: …` -### Assistant + - `type: Literal["direct"]` -- `class Assistant: …` + The caller type. Always `direct`. - Represents an `assistant` that can call the model and use tools. + - `"direct"` - - `id: str` + - `class CallerProgram: …` - The identifier, which can be referenced in API endpoints. + - `caller_id: str` - - `created_at: int` + The call ID of the program item that produced this tool call. - The Unix timestamp (in seconds) for when the assistant was created. + - `type: Literal["program"]` - - `description: Optional[str]` + The caller type. Always `program`. - The description of the assistant. The maximum length is 512 characters. + - `"program"` - - `instructions: Optional[str]` + - `class BetaResponseCustomToolCall: …` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + A call to a custom tool created by the model. - - `metadata: Optional[Metadata]` + - `call_id: str` - 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. + An identifier used to map this custom tool call to a tool call output. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `input: str` - - `model: str` + The input for the custom tool call generated by the model. - 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: str` - - `name: Optional[str]` + The name of the custom tool being called. - The name of the assistant. The maximum length is 256 characters. + - `type: Literal["custom_tool_call"]` - - `object: Literal["assistant"]` + The type of the custom tool call. Always `custom_tool_call`. - The object type, which is always `assistant`. + - `"custom_tool_call"` - - `"assistant"` + - `id: Optional[str]` - - `tools: List[object]` + The unique ID of the custom tool call in the OpenAI platform. - 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`. + - `agent: Optional[Agent]` - - `response_format: Optional[AssistantResponseFormatOption]` + The agent that produced this item. - 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`. + - `agent_name: str` - 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). + The canonical name of the agent that produced this item. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `caller: Optional[Caller]` - **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. + The execution context that produced this tool call. - - `Literal["auto"]` + - `class CallerDirect: …` - `auto` is the default value + - `type: Literal["direct"]` - - `"auto"` + - `"direct"` - - `class ResponseFormatText: …` + - `class CallerProgram: …` - Default response format. Used to generate text responses. + - `caller_id: str` - - `type: Literal["text"]` + The call ID of the program item that produced this tool call. - The type of response format being defined. Always `text`. + - `type: Literal["program"]` - - `"text"` + - `"program"` - - `class ResponseFormatJSONObject: …` + - `namespace: Optional[str]` - 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. + The namespace of the custom tool being called. - - `type: Literal["json_object"]` + - `class CompactionTrigger: …` - The type of response format being defined. Always `json_object`. + Compacts the current context. Must be the final input item. - - `"json_object"` + - `type: Literal["compaction_trigger"]` - - `class ResponseFormatJSONSchema: …` + The type of the item. Always `compaction_trigger`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"compaction_trigger"` - - `json_schema: JSONSchema` + - `agent: Optional[CompactionTriggerAgent]` - Structured Outputs configuration options, including a JSON Schema. + The agent that produced this item. - - `name: str` + - `agent_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. + The canonical name of the agent that produced this item. - - `description: Optional[str]` + - `class ItemReference: …` - A description of what the response format is for, used by the model to - determine how to respond in the format. + An internal identifier for an item to reference. - - `schema: Optional[Dict[str, object]]` + - `id: str` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The ID of the item to reference. - - `strict: Optional[bool]` + - `agent: Optional[ItemReferenceAgent]` - 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). + The agent that produced this item. - - `type: Literal["json_schema"]` + - `agent_name: str` - The type of response format being defined. Always `json_schema`. + The canonical name of the agent that produced this item. - - `"json_schema"` + - `type: Optional[Literal["item_reference"]]` - - `temperature: Optional[float]` + The type of item to reference. Always `item_reference`. - 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. + - `"item_reference"` - - `tool_resources: Optional[ToolResources]` + - `class Program: …` - 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. + - `id: str` - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + The unique ID of this program item. - - `file_ids: Optional[List[str]]` + - `call_id: 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. + The stable call ID of the program item. - - `file_search: Optional[ToolResourcesFileSearch]` + - `code: str` - - `vector_store_ids: Optional[List[str]]` + The JavaScript source executed by programmatic tool calling. - 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. + - `fingerprint: str` - - `top_p: Optional[float]` + Opaque program replay fingerprint that must be round-tripped. - 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. + - `type: Literal["program"]` - We generally recommend altering this or temperature but not both. + The item type. Always `program`. -### Assistant Deleted + - `"program"` -- `class AssistantDeleted: …` + - `agent: Optional[ProgramAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput: …` - `id: str` - - `deleted: bool` + The unique ID of this program output item. - - `object: Literal["assistant.deleted"]` + - `call_id: str` - - `"assistant.deleted"` + The call ID of the program item. -### Assistant Stream Event + - `result: str` -- `AssistantStreamEvent` + The result produced by the program item. - Represents an event emitted when streaming a Run. + - `status: Literal["completed", "incomplete"]` - Each event in a server-sent events stream has an `event` and `data` property: + The terminal status of the program output. - ``` - event: thread.created - data: {"id": "thread_123", "object": "thread", ...} - ``` + - `"completed"` - 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. + - `"incomplete"` - 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. + - `type: Literal["program_output"]` - - `class ThreadCreated: …` + The item type. Always `program_output`. - Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. + - `"program_output"` - - `data: Thread` + - `agent: Optional[ProgramOutputAgent]` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + The agent that produced this item. - - `id: str` + - `agent_name: str` - The identifier, which can be referenced in API endpoints. + The canonical name of the agent that produced this item. - - `created_at: int` +- `instructions: Optional[str]` - The Unix timestamp (in seconds) for when the thread was created. + A system (or developer) message inserted into the model's context. - - `metadata: Optional[Metadata]` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + +- `max_output_tokens: Optional[int]` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + +- `max_tool_calls: Optional[int]` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + +- `metadata: Optional[Dict[str, str]]` 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 @@ -4659,1986 +3952,2078 @@ print(response) Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `object: Literal["thread"]` +- `model: Optional[Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]]` - The object type, which is always `thread`. + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `"thread"` + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` - - `tool_resources: Optional[ToolResources]` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - 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. + - `"gpt-5.6-sol"` - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + - `"gpt-5.6-terra"` - - `file_ids: Optional[List[str]]` + - `"gpt-5.6-luna"` - 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. + - `"gpt-5.4"` - - `file_search: Optional[ToolResourcesFileSearch]` + - `"gpt-5.4-mini"` - - `vector_store_ids: Optional[List[str]]` + - `"gpt-5.4-nano"` - 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. + - `"gpt-5.4-mini-2026-03-17"` - - `event: Literal["thread.created"]` + - `"gpt-5.4-nano-2026-03-17"` - - `"thread.created"` + - `"gpt-5.3-chat-latest"` - - `enabled: Optional[bool]` + - `"gpt-5.2"` - Whether to enable input audio transcription. + - `"gpt-5.2-2025-12-11"` - - `class ThreadRunCreated: …` + - `"gpt-5.2-chat-latest"` - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + - `"gpt-5.2-pro"` - - `data: Run` + - `"gpt-5.2-pro-2025-12-11"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"gpt-5.1"` - - `id: str` + - `"gpt-5.1-2025-11-13"` - The identifier, which can be referenced in API endpoints. + - `"gpt-5.1-codex"` - - `assistant_id: str` + - `"gpt-5.1-mini"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `"gpt-5.1-chat-latest"` - - `cancelled_at: Optional[int]` + - `"gpt-5"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `"gpt-5-mini"` - - `completed_at: Optional[int]` + - `"gpt-5-nano"` - The Unix timestamp (in seconds) for when the run was completed. + - `"gpt-5-2025-08-07"` - - `created_at: int` + - `"gpt-5-mini-2025-08-07"` - The Unix timestamp (in seconds) for when the run was created. + - `"gpt-5-nano-2025-08-07"` - - `expires_at: Optional[int]` + - `"gpt-5-chat-latest"` - The Unix timestamp (in seconds) for when the run will expire. + - `"gpt-4.1"` - - `failed_at: Optional[int]` + - `"gpt-4.1-mini"` - The Unix timestamp (in seconds) for when the run failed. + - `"gpt-4.1-nano"` - - `incomplete_details: Optional[IncompleteDetails]` + - `"gpt-4.1-2025-04-14"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"gpt-4.1-mini-2025-04-14"` - - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` + - `"gpt-4.1-nano-2025-04-14"` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `"o4-mini"` - - `"max_completion_tokens"` + - `"o4-mini-2025-04-16"` - - `"max_prompt_tokens"` + - `"o3"` - - `instructions: str` + - `"o3-2025-04-16"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"o3-mini"` - - `last_error: Optional[LastError]` + - `"o3-mini-2025-01-31"` - The last error associated with this run. Will be `null` if there are no errors. + - `"o1"` - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` + - `"o1-2024-12-17"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"o1-preview"` - - `"server_error"` + - `"o1-preview-2024-09-12"` - - `"rate_limit_exceeded"` + - `"o1-mini"` - - `"invalid_prompt"` + - `"o1-mini-2024-09-12"` - - `message: str` + - `"gpt-4o"` - A human-readable description of the error. + - `"gpt-4o-2024-11-20"` - - `max_completion_tokens: Optional[int]` + - `"gpt-4o-2024-08-06"` - The maximum number of completion tokens specified to have been used over the course of the run. + - `"gpt-4o-2024-05-13"` - - `max_prompt_tokens: Optional[int]` + - `"gpt-4o-audio-preview"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `"gpt-4o-audio-preview-2024-10-01"` - - `metadata: Optional[Metadata]` + - `"gpt-4o-audio-preview-2024-12-17"` - 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. + - `"gpt-4o-audio-preview-2025-06-03"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"gpt-4o-mini-audio-preview"` - - `model: str` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"gpt-4o-search-preview"` - - `object: Literal["thread.run"]` + - `"gpt-4o-mini-search-preview"` - The object type, which is always `thread.run`. + - `"gpt-4o-search-preview-2025-03-11"` - - `"thread.run"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `parallel_tool_calls: bool` + - `"chatgpt-4o-latest"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `"codex-mini-latest"` - - `required_action: Optional[RequiredAction]` + - `"gpt-4o-mini"` - Details on the action required to continue the run. Will be `null` if no action is required. + - `"gpt-4o-mini-2024-07-18"` - - `submit_tool_outputs: RequiredActionSubmitToolOutputs` + - `"gpt-4-turbo"` - Details on the tool outputs needed for this run to continue. + - `"gpt-4-turbo-2024-04-09"` - - `tool_calls: List[RequiredActionFunctionToolCall]` + - `"gpt-4-0125-preview"` - A list of the relevant tool calls. + - `"gpt-4-turbo-preview"` - - `id: str` + - `"gpt-4-1106-preview"` - 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. + - `"gpt-4-vision-preview"` - - `function: Function` + - `"gpt-4"` - The function definition. + - `"gpt-4-0314"` - - `arguments: str` + - `"gpt-4-0613"` - The arguments that the model expects you to pass to the function. + - `"gpt-4-32k"` - - `name: str` + - `"gpt-4-32k-0314"` - The name of the function. + - `"gpt-4-32k-0613"` - - `type: Literal["function"]` + - `"gpt-3.5-turbo"` - The type of tool call the output is required for. For now, this is always `function`. + - `"gpt-3.5-turbo-16k"` - - `"function"` + - `"gpt-3.5-turbo-0301"` - - `type: Literal["submit_tool_outputs"]` + - `"gpt-3.5-turbo-0613"` - For now, this is always `submit_tool_outputs`. + - `"gpt-3.5-turbo-1106"` - - `"submit_tool_outputs"` + - `"gpt-3.5-turbo-0125"` - - `response_format: Optional[AssistantResponseFormatOption]` + - `"gpt-3.5-turbo-16k-0613"` - 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`. + - `"o1-pro"` - 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). + - `"o1-pro-2025-03-19"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"o3-pro"` - **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. + - `"o3-pro-2025-06-10"` - - `Literal["auto"]` + - `"o3-deep-research"` - `auto` is the default value + - `"o3-deep-research-2025-06-26"` - - `"auto"` + - `"o4-mini-deep-research"` - - `class ResponseFormatText: …` + - `"o4-mini-deep-research-2025-06-26"` - Default response format. Used to generate text responses. + - `"computer-use-preview"` - - `type: Literal["text"]` + - `"computer-use-preview-2025-03-11"` - The type of response format being defined. Always `text`. + - `"gpt-5-codex"` - - `"text"` + - `"gpt-5-pro"` - - `class ResponseFormatJSONObject: …` + - `"gpt-5-pro-2025-10-06"` - 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. + - `"gpt-5.1-codex-max"` - - `type: Literal["json_object"]` + - `str` - The type of response format being defined. Always `json_object`. +- `moderation: Optional[Moderation]` - - `"json_object"` + Configuration for running moderation on the input and output of this response. - - `class ResponseFormatJSONSchema: …` + - `model: str` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - - `json_schema: JSONSchema` + - `policy: Optional[ModerationPolicy]` - Structured Outputs configuration options, including a JSON Schema. + The policy to apply to moderated response input and output. - - `name: str` + - `input: Optional[ModerationPolicyInput]` - 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. + The moderation policy for the response input. - - `description: Optional[str]` + - `mode: Literal["score", "block"]` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"score"` - - `schema: Optional[Dict[str, object]]` + - `"block"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `output: Optional[ModerationPolicyOutput]` - - `strict: Optional[bool]` + The moderation policy for the response output. - 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). + - `mode: Literal["score", "block"]` - - `type: Literal["json_schema"]` + - `"score"` - The type of response format being defined. Always `json_schema`. + - `"block"` - - `"json_schema"` +- `multi_agent: Optional[MultiAgent]` - - `started_at: Optional[int]` + Configuration for server-hosted multi-agent execution. - The Unix timestamp (in seconds) for when the run was started. + - `enabled: bool` - - `status: object` + Whether to enable server-hosted multi-agent execution for this response. - - `thread_id: str` + - `max_concurrent_subagents: Optional[int]` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. + The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. - - `tool_choice: Optional[AssistantToolChoiceOption]` +- `parallel_tool_calls: Optional[bool]` - 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. + Whether to allow the model to run tool calls in parallel. - - `Literal["none", "auto", "required"]` +- `previous_response_id: Optional[str]` - `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. + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `"none"` +- `prompt: Optional[BetaResponsePromptParam]` - - `"auto"` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `"required"` + - `id: str` - - `class AssistantToolChoice: …` + The unique identifier of the prompt template to use. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `variables: Optional[Dict[str, Variables]]` - - `type: Literal["function", "code_interpreter", "file_search"]` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - The type of the tool. If type is `function`, the function name must be set + - `str` - - `"function"` + - `class BetaResponseInputText: …` - - `"code_interpreter"` + A text input to the model. - - `"file_search"` + - `class BetaResponseInputImage: …` - - `function: Optional[AssistantToolChoiceFunction]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `name: str` + - `class BetaResponseInputFile: …` - The name of the function to call. + A file input to the model. - - `tools: List[object]` + - `version: Optional[str]` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + Optional version of the prompt template. - - `truncation_strategy: Optional[TruncationStrategy]` +- `prompt_cache_key: Optional[str]` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `type: Literal["auto", "last_messages"]` +- `prompt_cache_options: Optional[PromptCacheOptions]` - 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`. + Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. - - `"auto"` + - `mode: Optional[Literal["implicit", "explicit"]]` - - `"last_messages"` + Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - - `last_messages: Optional[int]` + - `"implicit"` - The number of most recent messages from the thread when constructing the context for the run. + - `"explicit"` - - `usage: Optional[Usage]` + - `ttl: Optional[Literal["30m"]]` - 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.). + The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. - - `completion_tokens: int` + - `"30m"` - Number of completion tokens used over the course of the run. +- `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` - - `prompt_tokens: int` + Deprecated. Use `prompt_cache_options.ttl` instead. - Number of prompt tokens used over the course of the run. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `total_tokens: int` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - Total number of tokens used (prompt + completion). + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `temperature: Optional[float]` + - `"in_memory"` - The sampling temperature used for this run. If not set, defaults to 1. + - `"24h"` - - `top_p: Optional[float]` +- `reasoning: Optional[Reasoning]` - The nucleus sampling value used for this run. If not set, defaults to 1. + **gpt-5 and o-series models only** - - `event: Literal["thread.run.created"]` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `"thread.run.created"` + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` - - `class ThreadRunQueued: …` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. + - `"auto"` - - `data: Run` + - `"current_turn"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"all_turns"` - - `event: Literal["thread.run.queued"]` + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` - - `"thread.run.queued"` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `class ThreadRunInProgress: …` + - `"none"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. + - `"minimal"` - - `data: Run` + - `"low"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"medium"` - - `event: Literal["thread.run.in_progress"]` + - `"high"` - - `"thread.run.in_progress"` + - `"xhigh"` - - `class ThreadRunRequiresAction: …` + - `"max"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` - - `data: Run` + **Deprecated:** use `summary` instead. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `event: Literal["thread.run.requires_action"]` + - `"auto"` - - `"thread.run.requires_action"` + - `"concise"` - - `class ThreadRunCompleted: …` + - `"detailed"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. + - `mode: Optional[Union[str, Literal["standard", "pro"]]]` - - `data: Run` + Controls the reasoning execution mode for the request. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + When returned on a response, this is the effective execution mode. - - `event: Literal["thread.run.completed"]` + - `str` - - `"thread.run.completed"` + - `Literal["standard", "pro"]` - - `class ThreadRunIncomplete: …` + Controls the reasoning execution mode for the request. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. + When returned on a response, this is the effective execution mode. - - `data: Run` + - `"standard"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"pro"` - - `event: Literal["thread.run.incomplete"]` + - `summary: Optional[Literal["auto", "concise", "detailed"]]` - - `"thread.run.incomplete"` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `class ThreadRunFailed: …` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. + - `"auto"` - - `data: Run` + - `"concise"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"detailed"` - - `event: Literal["thread.run.failed"]` +- `safety_identifier: Optional[str]` - - `"thread.run.failed"` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `class ThreadRunCancelling: …` +- `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. + Specifies the processing type used for serving the request. - - `data: Run` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `event: Literal["thread.run.cancelling"]` + - `"auto"` - - `"thread.run.cancelling"` + - `"default"` - - `class ThreadRunCancelled: …` + - `"flex"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. + - `"scale"` - - `data: Run` + - `"priority"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). +- `store: Optional[bool]` - - `event: Literal["thread.run.cancelled"]` + Whether to store the generated model response for later retrieval via + API. - - `"thread.run.cancelled"` +- `stream: Optional[Literal[false]]` - - `class ThreadRunExpired: …` + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) + for more information. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. + - `false` - - `data: Run` +- `stream_options: Optional[StreamOptions]` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + Options for streaming responses. Only set this when you set `stream: true`. - - `event: Literal["thread.run.expired"]` + - `include_obfuscation: Optional[bool]` - - `"thread.run.expired"` + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events to + normalize payload sizes as a mitigation to certain side-channel attacks. + These obfuscation fields are included by default, but add a small amount + of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between + your application and the OpenAI API. - - `class ThreadRunStepCreated: …` +- `temperature: Optional[float]` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. + 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. + We generally recommend altering this or `top_p` but not both. - - `data: RunStep` +- `text: Optional[BetaResponseTextConfigParam]` - Represents a step in execution of a run. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `id: str` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - The identifier of the run step, which can be referenced in API endpoints. + - `format: Optional[BetaResponseFormatTextConfig]` - - `assistant_id: str` + An object specifying the format that the model must output. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + Configuring `{ "type": "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). - - `cancelled_at: Optional[int]` + The default format is `{ "type": "text" }` with no additional options. - The Unix timestamp (in seconds) for when the run step was cancelled. + **Not recommended for gpt-4o and newer models:** - - `completed_at: Optional[int]` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - The Unix timestamp (in seconds) for when the run step completed. + - `class Text: …` - - `created_at: int` + Default response format. Used to generate text responses. - The Unix timestamp (in seconds) for when the run step was created. + - `type: Literal["text"]` - - `expired_at: Optional[int]` + The type of response format being defined. Always `text`. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `"text"` - - `failed_at: Optional[int]` + - `class BetaResponseFormatTextJSONSchemaConfig: …` - The Unix timestamp (in seconds) for when the run step failed. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `last_error: Optional[LastError]` + - `name: str` - The last error associated with this run step. Will be `null` if there are no errors. + 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. - - `code: Literal["server_error", "rate_limit_exceeded"]` + - `schema: Dict[str, object]` - One of `server_error` or `rate_limit_exceeded`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"server_error"` + - `type: Literal["json_schema"]` - - `"rate_limit_exceeded"` + The type of response format being defined. Always `json_schema`. - - `message: str` + - `"json_schema"` - A human-readable description of the error. + - `description: Optional[str]` - - `metadata: Optional[Metadata]` + A description of what the response format is for, used by the model to + determine how to respond in the format. - 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. + - `strict: Optional[bool]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + 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). - - `object: Literal["thread.run.step"]` + - `class JSONObject: …` - The object type, which is always `thread.run.step`. + 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. - - `"thread.run.step"` + - `type: Literal["json_object"]` - - `run_id: str` + The type of response format being defined. Always `json_object`. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `"json_object"` - - `status: Literal["in_progress", "cancelled", "failed", 2 more]` + - `verbosity: Optional[Literal["low", "medium", "high"]]` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `"in_progress"` + - `"low"` - - `"cancelled"` + - `"medium"` - - `"failed"` + - `"high"` - - `"completed"` +- `tool_choice: Optional[ToolChoice]` - - `"expired"` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `step_details: StepDetails` + - `Literal["none", "auto", "required"]` - The details of the run step. + - `"none"` - - `class MessageCreationStepDetails: …` + - `"auto"` - Details of the message creation by the run step. + - `"required"` - - `message_creation: MessageCreation` + - `class BetaToolChoiceAllowed: …` - - `message_id: str` + Constrains the tools available to the model to a pre-defined set. - The ID of the message that was created by this run step. + - `mode: Literal["auto", "required"]` - - `type: Literal["message_creation"]` + Constrains the tools available to the model to a pre-defined set. - Always `message_creation`. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `"message_creation"` + `required` requires the model to call one or more of the allowed tools. - - `class ToolCallsStepDetails: …` + - `"auto"` - Details of the tool call. + - `"required"` - - `tool_calls: List[object]` + - `tools: List[Dict[str, object]]` - 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`. + A list of tool definitions that the model should be allowed to call. - - `type: Literal["tool_calls"]` + For the Responses API, the list of tool definitions might look like: - Always `tool_calls`. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `"tool_calls"` + - `type: Literal["allowed_tools"]` - - `thread_id: str` + Allowed tool configuration type. Always `allowed_tools`. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `"allowed_tools"` - - `type: Literal["message_creation", "tool_calls"]` + - `class BetaToolChoiceTypes: …` - The type of run step, which can be either `message_creation` or `tool_calls`. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `"message_creation"` + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` - - `"tool_calls"` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `usage: Optional[Usage]` + Allowed values are: - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `completion_tokens: int` + - `"file_search"` - Number of completion tokens used over the course of the run step. + - `"web_search_preview"` - - `prompt_tokens: int` + - `"computer"` - Number of prompt tokens used over the course of the run step. + - `"computer_use_preview"` - - `total_tokens: int` + - `"computer_use"` - Total number of tokens used (prompt + completion). + - `"web_search_preview_2025_03_11"` - - `event: Literal["thread.run.step.created"]` + - `"image_generation"` - - `"thread.run.step.created"` + - `"code_interpreter"` - - `class ThreadRunStepInProgress: …` + - `class BetaToolChoiceFunction: …` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. + Use this option to force the model to call a specific function. - - `data: RunStep` + - `name: str` - Represents a step in execution of a run. + The name of the function to call. - - `event: Literal["thread.run.step.in_progress"]` + - `type: Literal["function"]` - - `"thread.run.step.in_progress"` + For function calling, the type is always `function`. - - `class ThreadRunStepDelta: …` + - `"function"` - Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. + - `class BetaToolChoiceMcp: …` - - `data: RunStepDeltaEvent` + Use this option to force the model to call a specific tool on a remote MCP server. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `server_label: str` - - `id: str` + The label of the MCP server to use. - The identifier of the run step, which can be referenced in API endpoints. + - `type: Literal["mcp"]` - - `delta: object` + For MCP tools, the type is always `mcp`. - - `object: Literal["thread.run.step.delta"]` + - `"mcp"` - The object type, which is always `thread.run.step.delta`. + - `name: Optional[str]` - - `"thread.run.step.delta"` + The name of the tool to call on the server. - - `event: Literal["thread.run.step.delta"]` + - `class BetaToolChoiceCustom: …` - - `"thread.run.step.delta"` + Use this option to force the model to call a specific custom tool. - - `class ThreadRunStepCompleted: …` + - `name: str` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. + The name of the custom tool to call. - - `data: RunStep` + - `type: Literal["custom"]` - Represents a step in execution of a run. + For custom tool calling, the type is always `custom`. - - `event: Literal["thread.run.step.completed"]` + - `"custom"` - - `"thread.run.step.completed"` + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` - - `class ThreadRunStepFailed: …` + - `type: Literal["programmatic_tool_calling"]` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. + The tool to call. Always `programmatic_tool_calling`. - - `data: RunStep` + - `"programmatic_tool_calling"` - Represents a step in execution of a run. + - `class BetaToolChoiceApplyPatch: …` - - `event: Literal["thread.run.step.failed"]` + Forces the model to call the apply_patch tool when executing a tool call. - - `"thread.run.step.failed"` + - `type: Literal["apply_patch"]` - - `class ThreadRunStepCancelled: …` + The tool to call. Always `apply_patch`. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. + - `"apply_patch"` - - `data: RunStep` + - `class BetaToolChoiceShell: …` - Represents a step in execution of a run. + Forces the model to call the shell tool when a tool call is required. - - `event: Literal["thread.run.step.cancelled"]` + - `type: Literal["shell"]` - - `"thread.run.step.cancelled"` + The tool to call. Always `shell`. - - `class ThreadRunStepExpired: …` + - `"shell"` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. +- `tools: Optional[Iterable[BetaToolParam]]` - - `data: RunStep` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - Represents a step in execution of a run. + We support the following categories of tools: - - `event: Literal["thread.run.step.expired"]` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `"thread.run.step.expired"` + - `class BetaFunctionTool: …` - - `class ThreadMessageCreated: …` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + - `class BetaFileSearchTool: …` - - `data: Message` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class BetaComputerTool: …` - - `id: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The identifier, which can be referenced in API endpoints. + - `class BetaComputerUsePreviewTool: …` - - `assistant_id: Optional[str]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `class BetaWebSearchTool: …` - - `attachments: Optional[List[Attachment]]` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - A list of files attached to the message, and the tools they were added to. + - `class Mcp: …` - - `file_id: Optional[str]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The ID of the file to attach to the message. + - `class CodeInterpreter: …` - - `tools: Optional[List[AttachmentTool]]` + A tool that runs Python code to help generate a response to a prompt. - The tools to add this file to. + - `class ProgrammaticToolCalling: …` - - `class CodeInterpreterTool: …` + - `class ImageGeneration: …` - - `type: Literal["code_interpreter"]` + A tool that generates images using the GPT image models. - The type of tool being defined: `code_interpreter` + - `class LocalShell: …` - - `"code_interpreter"` + A tool that allows the model to execute shell commands in a local environment. - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + - `class BetaFunctionShellTool: …` - - `type: Literal["file_search"]` + A tool that allows the model to execute shell commands. - The type of tool being defined: `file_search` + - `class BetaCustomTool: …` - - `"file_search"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `completed_at: Optional[int]` + - `class BetaNamespaceTool: …` - The Unix timestamp (in seconds) for when the message was completed. + Groups function/custom tools under a shared namespace. - - `content: List[object]` + - `class BetaToolSearchTool: …` - The content of the message in array of text and/or images. + Hosted or BYOT tool search configuration for deferred tools. - - `created_at: int` + - `class BetaWebSearchPreviewTool: …` - The Unix timestamp (in seconds) for when the message was created. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `incomplete_at: Optional[int]` + - `class BetaApplyPatchTool: …` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + Allows the assistant to create, delete, or update files using unified diffs. - - `incomplete_details: Optional[IncompleteDetails]` +- `top_logprobs: Optional[int]` - On an incomplete message, details about why the message is incomplete. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` +- `top_p: Optional[float]` - The reason the message is incomplete. + 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. - - `"content_filter"` + We generally recommend altering this or `temperature` but not both. - - `"max_tokens"` +- `truncation: Optional[Literal["auto", "disabled"]]` - - `"run_cancelled"` + The truncation strategy to use for the model response. - - `"run_expired"` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `"run_failed"` + - `"auto"` - - `metadata: Optional[Metadata]` + - `"disabled"` - 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. +- `user: Optional[str]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `object: Literal["thread.message"]` +- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` - The object type, which is always `thread.message`. + - `"responses_multi_agent=v1"` - - `"thread.message"` +### Returns - - `role: Literal["user", "assistant"]` +- `class BetaResponse: …` - The entity that produced the message. One of `user` or `assistant`. + - `id: str` - - `"user"` + Unique identifier for this Response. - - `"assistant"` + - `created_at: float` - - `run_id: Optional[str]` + Unix timestamp (in seconds) of when this Response was created. - 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. + - `error: Optional[BetaResponseError]` - - `status: Literal["in_progress", "incomplete", "completed"]` + An error object returned when the model fails to generate a Response. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` - - `"in_progress"` + The error code for the response. - - `"incomplete"` + - `"server_error"` - - `"completed"` + - `"rate_limit_exceeded"` - - `thread_id: str` + - `"invalid_prompt"` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `"bio_policy"` - - `event: Literal["thread.message.created"]` + - `"vector_store_timeout"` - - `"thread.message.created"` + - `"invalid_image"` - - `class ThreadMessageInProgress: …` + - `"invalid_image_format"` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. + - `"invalid_base64_image"` - - `data: Message` + - `"invalid_image_url"` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"image_too_large"` - - `event: Literal["thread.message.in_progress"]` + - `"image_too_small"` - - `"thread.message.in_progress"` + - `"image_parse_error"` - - `class ThreadMessageDelta: …` + - `"image_content_policy_violation"` - Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. + - `"invalid_image_mode"` - - `data: MessageDeltaEvent` + - `"image_file_too_large"` - Represents a message delta i.e. any changed fields on a message during streaming. + - `"unsupported_image_media_type"` - - `id: str` + - `"empty_image_file"` - The identifier of the message, which can be referenced in API endpoints. + - `"failed_to_download_image"` - - `delta: MessageDelta` + - `"image_file_not_found"` - The delta containing the fields that have changed on the Message. + - `message: str` - - `content: Optional[List[object]]` + A human-readable description of the error. - The content of the message in array of text and/or images. + - `incomplete_details: Optional[IncompleteDetails]` - - `role: Optional[Literal["user", "assistant"]]` + Details about why the response is incomplete. - The entity that produced the message. One of `user` or `assistant`. + - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` - - `"user"` + The reason why the response is incomplete. - - `"assistant"` + - `"max_output_tokens"` - - `object: Literal["thread.message.delta"]` + - `"content_filter"` - The object type, which is always `thread.message.delta`. + - `instructions: Union[str, List[BetaResponseInputItem], null]` - - `"thread.message.delta"` + A system (or developer) message inserted into the model's context. - - `event: Literal["thread.message.delta"]` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `"thread.message.delta"` + - `str` - - `class ThreadMessageCompleted: …` + A text input to the model, equivalent to a text input with the + `developer` role. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. + - `List[BetaResponseInputItem]` - - `data: Message` + A list of one or many input items to the model, containing + different content types. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class BetaEasyInputMessage: …` - - `event: Literal["thread.message.completed"]` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `"thread.message.completed"` + - `content: Union[str, BetaResponseInputMessageContentList]` - - `class ThreadMessageIncomplete: …` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. + - `str` - - `data: Message` + A text input to the model. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `List[BetaResponseInputContent]` - - `event: Literal["thread.message.incomplete"]` + - `class BetaResponseInputText: …` - - `"thread.message.incomplete"` + A text input to the model. - - `class ErrorEvent: …` + - `text: str` - 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. + The text input to the model. - - `data: ErrorObject` + - `type: Literal["input_text"]` - - `code: Optional[str]` + The type of the input item. Always `input_text`. - - `message: str` + - `"input_text"` - - `param: Optional[str]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `type: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `event: Literal["error"]` + - `mode: Literal["explicit"]` - - `"error"` + The breakpoint mode. Always `explicit`. -### Assistant Tool + - `"explicit"` -- `object` + - `class BetaResponseInputImage: …` -### Code Interpreter Tool + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). -- `class CodeInterpreterTool: …` + - `detail: Literal["low", "high", "auto", "original"]` - - `type: Literal["code_interpreter"]` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The type of tool being defined: `code_interpreter` + - `"low"` - - `"code_interpreter"` + - `"high"` -### File Search Tool + - `"auto"` -- `class FileSearchTool: …` + - `"original"` - - `type: Literal["file_search"]` + - `type: Literal["input_image"]` - The type of tool being defined: `file_search` + The type of the input item. Always `input_image`. - - `"file_search"` + - `"input_image"` - - `file_search: Optional[FileSearch]` + - `file_id: Optional[str]` - Overrides for the file search tool. + The ID of the file to be sent to the model. - - `max_num_results: Optional[int]` + - `image_url: Optional[str]` - 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. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - 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. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `ranking_options: Optional[FileSearchRankingOptions]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - 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. + - `mode: Literal["explicit"]` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The breakpoint mode. Always `explicit`. - - `score_threshold: float` + - `"explicit"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `class BetaResponseInputFile: …` - - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` + A file input to the model. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `type: Literal["input_file"]` - - `"auto"` + The type of the input item. Always `input_file`. - - `"default_2024_08_21"` + - `"input_file"` -### Function Tool + - `detail: Optional[Literal["auto", "low", "high"]]` -- `class FunctionTool: …` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `function: FunctionDefinition` + - `"auto"` - - `name: str` + - `"low"` - 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. + - `"high"` - - `description: Optional[str]` + - `file_data: Optional[str]` - A description of what the function does, used by the model to choose when and how to call the function. + The content of the file to be sent to the model. - - `parameters: Optional[FunctionParameters]` + - `file_id: Optional[str]` - 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. + The ID of the file to be sent to the model. - Omitting `parameters` defines a function with an empty parameter list. + - `file_url: Optional[str]` - - `strict: Optional[bool]` + The URL of the file to be sent to the model. - 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). + - `filename: Optional[str]` - - `type: Literal["function"]` + The name of the file to be sent to the model. - The type of tool being defined: `function` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"function"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. -### Message Stream Event + - `mode: Literal["explicit"]` -- `MessageStreamEvent` + The breakpoint mode. Always `explicit`. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + - `"explicit"` - - `class ThreadMessageCreated: …` + - `role: Literal["user", "assistant", "system", "developer"]` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `data: Message` + - `"user"` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"assistant"` - - `id: str` + - `"system"` - The identifier, which can be referenced in API endpoints. + - `"developer"` - - `assistant_id: Optional[str]` + - `phase: Optional[Literal["commentary", "final_answer"]]` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `attachments: Optional[List[Attachment]]` + - `"commentary"` - A list of files attached to the message, and the tools they were added to. + - `"final_answer"` - - `file_id: Optional[str]` + - `type: Optional[Literal["message"]]` - The ID of the file to attach to the message. + The type of the message input. Always `message`. - - `tools: Optional[List[AttachmentTool]]` + - `"message"` - The tools to add this file to. + - `class Message: …` - - `class CodeInterpreterTool: …` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `type: Literal["code_interpreter"]` + - `content: BetaResponseInputMessageContentList` - The type of tool being defined: `code_interpreter` + A list of one or many input items to the model, containing different content + types. - - `"code_interpreter"` + - `class BetaResponseInputText: …` - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + A text input to the model. - - `type: Literal["file_search"]` + - `class BetaResponseInputImage: …` - The type of tool being defined: `file_search` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"file_search"` + - `class BetaResponseInputFile: …` - - `completed_at: Optional[int]` + A file input to the model. - The Unix timestamp (in seconds) for when the message was completed. + - `role: Literal["user", "system", "developer"]` - - `content: List[object]` + The role of the message input. One of `user`, `system`, or `developer`. - The content of the message in array of text and/or images. + - `"user"` - - `created_at: int` + - `"system"` - The Unix timestamp (in seconds) for when the message was created. + - `"developer"` - - `incomplete_at: Optional[int]` + - `agent: Optional[MessageAgent]` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The agent that produced this item. - - `incomplete_details: Optional[IncompleteDetails]` + - `agent_name: str` - On an incomplete message, details about why the message is incomplete. + The canonical name of the agent that produced this item. - - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The reason the message is incomplete. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"content_filter"` + - `"in_progress"` - - `"max_tokens"` + - `"completed"` - - `"run_cancelled"` + - `"incomplete"` - - `"run_expired"` + - `type: Optional[Literal["message"]]` - - `"run_failed"` + The type of the message input. Always set to `message`. - - `metadata: Optional[Metadata]` + - `"message"` - 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. + - `class BetaResponseOutputMessage: …` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + An output message from the model. - - `object: Literal["thread.message"]` + - `id: str` - The object type, which is always `thread.message`. + The unique ID of the output message. - - `"thread.message"` + - `content: List[Content]` - - `role: Literal["user", "assistant"]` + The content of the output message. - The entity that produced the message. One of `user` or `assistant`. + - `class BetaResponseOutputText: …` - - `"user"` + A text output from the model. - - `"assistant"` + - `annotations: List[Annotation]` - - `run_id: Optional[str]` + The annotations of the text output. - 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. + - `class AnnotationFileCitation: …` - - `status: Literal["in_progress", "incomplete", "completed"]` + A citation to a file. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `file_id: str` - - `"in_progress"` + The ID of the file. - - `"incomplete"` + - `filename: str` - - `"completed"` + The filename of the file cited. - - `thread_id: str` + - `index: int` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + The index of the file in the list of files. - - `event: Literal["thread.message.created"]` + - `type: Literal["file_citation"]` - - `"thread.message.created"` + The type of the file citation. Always `file_citation`. - - `class ThreadMessageInProgress: …` + - `"file_citation"` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. + - `class AnnotationURLCitation: …` - - `data: Message` + A citation for a web resource used to generate a model response. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `end_index: int` - - `event: Literal["thread.message.in_progress"]` + The index of the last character of the URL citation in the message. - - `"thread.message.in_progress"` + - `start_index: int` - - `class ThreadMessageDelta: …` + The index of the first character of the URL citation in the message. - Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. + - `title: str` - - `data: MessageDeltaEvent` + The title of the web resource. - Represents a message delta i.e. any changed fields on a message during streaming. + - `type: Literal["url_citation"]` - - `id: str` + The type of the URL citation. Always `url_citation`. - The identifier of the message, which can be referenced in API endpoints. + - `"url_citation"` - - `delta: MessageDelta` + - `url: str` - The delta containing the fields that have changed on the Message. + The URL of the web resource. - - `content: Optional[List[object]]` + - `class AnnotationContainerFileCitation: …` - The content of the message in array of text and/or images. + A citation for a container file used to generate a model response. - - `role: Optional[Literal["user", "assistant"]]` + - `container_id: str` - The entity that produced the message. One of `user` or `assistant`. + The ID of the container file. - - `"user"` + - `end_index: int` - - `"assistant"` + The index of the last character of the container file citation in the message. - - `object: Literal["thread.message.delta"]` + - `file_id: str` - The object type, which is always `thread.message.delta`. + The ID of the file. - - `"thread.message.delta"` + - `filename: str` - - `event: Literal["thread.message.delta"]` + The filename of the container file cited. - - `"thread.message.delta"` + - `start_index: int` - - `class ThreadMessageCompleted: …` + The index of the first character of the container file citation in the message. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. + - `type: Literal["container_file_citation"]` - - `data: Message` + The type of the container file citation. Always `container_file_citation`. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"container_file_citation"` - - `event: Literal["thread.message.completed"]` + - `class AnnotationFilePath: …` - - `"thread.message.completed"` + A path to a file. - - `class ThreadMessageIncomplete: …` + - `file_id: str` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. + The ID of the file. - - `data: Message` + - `index: int` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + The index of the file in the list of files. - - `event: Literal["thread.message.incomplete"]` + - `type: Literal["file_path"]` - - `"thread.message.incomplete"` + The type of the file path. Always `file_path`. -### Run Step Stream Event + - `"file_path"` -- `RunStepStreamEvent` + - `text: str` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. + The text output from the model. - - `class ThreadRunStepCreated: …` + - `type: Literal["output_text"]` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. + The type of the output text. Always `output_text`. - - `data: RunStep` + - `"output_text"` - Represents a step in execution of a run. + - `logprobs: Optional[List[Logprob]]` - - `id: str` + - `token: str` - The identifier of the run step, which can be referenced in API endpoints. + - `bytes: List[int]` - - `assistant_id: str` + - `logprob: float` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `top_logprobs: List[LogprobTopLogprob]` - - `cancelled_at: Optional[int]` + - `token: str` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `bytes: List[int]` - - `completed_at: Optional[int]` + - `logprob: float` - The Unix timestamp (in seconds) for when the run step completed. + - `class BetaResponseOutputRefusal: …` - - `created_at: int` + A refusal from the model. - The Unix timestamp (in seconds) for when the run step was created. + - `refusal: str` - - `expired_at: Optional[int]` + The refusal explanation from the model. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `type: Literal["refusal"]` - - `failed_at: Optional[int]` + The type of the refusal. Always `refusal`. - The Unix timestamp (in seconds) for when the run step failed. + - `"refusal"` - - `last_error: Optional[LastError]` + - `role: Literal["assistant"]` - The last error associated with this run step. Will be `null` if there are no errors. + The role of the output message. Always `assistant`. - - `code: Literal["server_error", "rate_limit_exceeded"]` + - `"assistant"` - One of `server_error` or `rate_limit_exceeded`. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"server_error"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"rate_limit_exceeded"` + - `"in_progress"` - - `message: str` + - `"completed"` - A human-readable description of the error. + - `"incomplete"` - - `metadata: Optional[Metadata]` + - `type: Literal["message"]` - 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. + The type of the output message. Always `message`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"message"` - - `object: Literal["thread.run.step"]` + - `agent: Optional[Agent]` - The object type, which is always `thread.run.step`. + The agent that produced this item. - - `"thread.run.step"` + - `agent_name: str` - - `run_id: str` + The canonical name of the agent that produced this item. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `status: Literal["in_progress", "cancelled", "failed", 2 more]` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `"commentary"` - - `"in_progress"` + - `"final_answer"` - - `"cancelled"` + - `class BetaResponseFileSearchToolCall: …` - - `"failed"` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `"completed"` + - `id: str` - - `"expired"` + The unique ID of the file search tool call. - - `step_details: StepDetails` - - The details of the run step. + - `queries: List[str]` - - `class MessageCreationStepDetails: …` + The queries used to search for files. - Details of the message creation by the run step. + - `status: Literal["in_progress", "searching", "completed", 2 more]` - - `message_creation: MessageCreation` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `message_id: str` + - `"in_progress"` - The ID of the message that was created by this run step. + - `"searching"` - - `type: Literal["message_creation"]` + - `"completed"` - Always `message_creation`. + - `"incomplete"` - - `"message_creation"` + - `"failed"` - - `class ToolCallsStepDetails: …` + - `type: Literal["file_search_call"]` - Details of the tool call. + The type of the file search tool call. Always `file_search_call`. - - `tool_calls: List[object]` + - `"file_search_call"` - 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`. + - `agent: Optional[Agent]` - - `type: Literal["tool_calls"]` + The agent that produced this item. - Always `tool_calls`. + - `agent_name: str` - - `"tool_calls"` + The canonical name of the agent that produced this item. - - `thread_id: str` + - `results: Optional[List[Result]]` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + The results of the file search tool call. - - `type: Literal["message_creation", "tool_calls"]` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - The type of run step, which can be either `message_creation` or `tool_calls`. + 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, booleans, or numbers. - - `"message_creation"` + - `str` - - `"tool_calls"` + - `float` - - `usage: Optional[Usage]` + - `bool` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `file_id: Optional[str]` - - `completion_tokens: int` + The unique ID of the file. - Number of completion tokens used over the course of the run step. + - `filename: Optional[str]` - - `prompt_tokens: int` + The name of the file. - Number of prompt tokens used over the course of the run step. + - `score: Optional[float]` - - `total_tokens: int` + The relevance score of the file - a value between 0 and 1. - Total number of tokens used (prompt + completion). + - `text: Optional[str]` - - `event: Literal["thread.run.step.created"]` + The text that was retrieved from the file. - - `"thread.run.step.created"` + - `class BetaResponseComputerToolCall: …` - - `class ThreadRunStepInProgress: …` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. + - `id: str` - - `data: RunStep` + The unique ID of the computer call. - Represents a step in execution of a run. + - `call_id: str` - - `event: Literal["thread.run.step.in_progress"]` + An identifier used when responding to the tool call with output. - - `"thread.run.step.in_progress"` + - `pending_safety_checks: List[PendingSafetyCheck]` - - `class ThreadRunStepDelta: …` + The pending safety checks for the computer call. - Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. + - `id: str` - - `data: RunStepDeltaEvent` + The ID of the pending safety check. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `code: Optional[str]` - - `id: str` + The type of the pending safety check. - The identifier of the run step, which can be referenced in API endpoints. + - `message: Optional[str]` - - `delta: object` + Details about the pending safety check. - - `object: Literal["thread.run.step.delta"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The object type, which is always `thread.run.step.delta`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"thread.run.step.delta"` + - `"in_progress"` - - `event: Literal["thread.run.step.delta"]` + - `"completed"` - - `"thread.run.step.delta"` + - `"incomplete"` - - `class ThreadRunStepCompleted: …` + - `type: Literal["computer_call"]` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. + The type of the computer call. Always `computer_call`. - - `data: RunStep` + - `"computer_call"` - Represents a step in execution of a run. + - `action: Optional[BetaComputerAction]` - - `event: Literal["thread.run.step.completed"]` + A click action. - - `"thread.run.step.completed"` + - `class Click: …` - - `class ThreadRunStepFailed: …` + A click action. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. + - `button: Literal["left", "right", "wheel", 2 more]` - - `data: RunStep` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - Represents a step in execution of a run. + - `"left"` - - `event: Literal["thread.run.step.failed"]` + - `"right"` - - `"thread.run.step.failed"` + - `"wheel"` - - `class ThreadRunStepCancelled: …` + - `"back"` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. + - `"forward"` - - `data: RunStep` + - `type: Literal["click"]` - Represents a step in execution of a run. + Specifies the event type. For a click action, this property is always `click`. - - `event: Literal["thread.run.step.cancelled"]` + - `"click"` - - `"thread.run.step.cancelled"` + - `x: int` - - `class ThreadRunStepExpired: …` + The x-coordinate where the click occurred. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. + - `y: int` - - `data: RunStep` + The y-coordinate where the click occurred. - Represents a step in execution of a run. + - `keys: Optional[List[str]]` - - `event: Literal["thread.run.step.expired"]` + The keys being held while clicking. - - `"thread.run.step.expired"` + - `class DoubleClick: …` -### Run Stream Event + A double click action. -- `RunStreamEvent` + - `keys: Optional[List[str]]` - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + The keys being held while double-clicking. - - `class ThreadRunCreated: …` + - `type: Literal["double_click"]` - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `data: Run` + - `"double_click"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `x: int` - - `id: str` + The x-coordinate where the double click occurred. - The identifier, which can be referenced in API endpoints. + - `y: int` - - `assistant_id: str` + The y-coordinate where the double click occurred. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `class Drag: …` - - `cancelled_at: Optional[int]` + A drag action. - The Unix timestamp (in seconds) for when the run was cancelled. + - `path: List[DragPath]` - - `completed_at: Optional[int]` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The Unix timestamp (in seconds) for when the run was completed. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `created_at: int` + - `x: int` - The Unix timestamp (in seconds) for when the run was created. + The x-coordinate. - - `expires_at: Optional[int]` + - `y: int` - The Unix timestamp (in seconds) for when the run will expire. + The y-coordinate. - - `failed_at: Optional[int]` + - `type: Literal["drag"]` - The Unix timestamp (in seconds) for when the run failed. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `incomplete_details: Optional[IncompleteDetails]` + - `"drag"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `keys: Optional[List[str]]` - - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` + The keys being held while dragging the mouse. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `class Keypress: …` - - `"max_completion_tokens"` + A collection of keypresses the model would like to perform. - - `"max_prompt_tokens"` + - `keys: List[str]` - - `instructions: str` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `type: Literal["keypress"]` - - `last_error: Optional[LastError]` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The last error associated with this run. Will be `null` if there are no errors. + - `"keypress"` - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` + - `class Move: …` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + A mouse move action. - - `"server_error"` + - `type: Literal["move"]` - - `"rate_limit_exceeded"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"invalid_prompt"` + - `"move"` - - `message: str` + - `x: int` - A human-readable description of the error. + The x-coordinate to move to. - - `max_completion_tokens: Optional[int]` + - `y: int` - The maximum number of completion tokens specified to have been used over the course of the run. + The y-coordinate to move to. - - `max_prompt_tokens: Optional[int]` + - `keys: Optional[List[str]]` - The maximum number of prompt tokens specified to have been used over the course of the run. + The keys being held while moving the mouse. - - `metadata: Optional[Metadata]` + - `class Screenshot: …` - 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. + A screenshot action. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: Literal["screenshot"]` - - `model: str` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"screenshot"` - - `object: Literal["thread.run"]` + - `class Scroll: …` - The object type, which is always `thread.run`. + A scroll action. - - `"thread.run"` + - `scroll_x: int` - - `parallel_tool_calls: bool` + The horizontal scroll distance. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `scroll_y: int` - - `required_action: Optional[RequiredAction]` + The vertical scroll distance. - Details on the action required to continue the run. Will be `null` if no action is required. + - `type: Literal["scroll"]` - - `submit_tool_outputs: RequiredActionSubmitToolOutputs` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - Details on the tool outputs needed for this run to continue. + - `"scroll"` - - `tool_calls: List[RequiredActionFunctionToolCall]` + - `x: int` - A list of the relevant tool calls. + The x-coordinate where the scroll occurred. - - `id: str` + - `y: int` - 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. + The y-coordinate where the scroll occurred. - - `function: Function` + - `keys: Optional[List[str]]` - The function definition. + The keys being held while scrolling. - - `arguments: str` + - `class Type: …` - The arguments that the model expects you to pass to the function. + An action to type in text. - - `name: str` + - `text: str` - The name of the function. + The text to type. - - `type: Literal["function"]` + - `type: Literal["type"]` - The type of tool call the output is required for. For now, this is always `function`. + Specifies the event type. For a type action, this property is always set to `type`. - - `"function"` + - `"type"` - - `type: Literal["submit_tool_outputs"]` + - `class Wait: …` - For now, this is always `submit_tool_outputs`. + A wait action. - - `"submit_tool_outputs"` + - `type: Literal["wait"]` - - `response_format: Optional[AssistantResponseFormatOption]` + Specifies the event type. For a wait action, this property is always set to `wait`. - 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`. + - `"wait"` - 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). + - `actions: Optional[BetaComputerActionList]` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - **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. + - `class Click: …` - - `Literal["auto"]` + A click action. - `auto` is the default value + - `class DoubleClick: …` - - `"auto"` + A double click action. - - `class ResponseFormatText: …` + - `class Drag: …` - Default response format. Used to generate text responses. + A drag action. - - `type: Literal["text"]` + - `class Keypress: …` - The type of response format being defined. Always `text`. + A collection of keypresses the model would like to perform. - - `"text"` + - `class Move: …` - - `class ResponseFormatJSONObject: …` + A mouse move action. - 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. + - `class Screenshot: …` - - `type: Literal["json_object"]` + A screenshot action. - The type of response format being defined. Always `json_object`. + - `class Scroll: …` - - `"json_object"` + A scroll action. - - `class ResponseFormatJSONSchema: …` + - `class Type: …` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + An action to type in text. - - `json_schema: JSONSchema` + - `class Wait: …` - Structured Outputs configuration options, including a JSON Schema. + A wait action. - - `name: str` + - `agent: Optional[Agent]` - 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. + The agent that produced this item. - - `description: Optional[str]` + - `agent_name: str` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The canonical name of the agent that produced this item. - - `schema: Optional[Dict[str, object]]` + - `class ComputerCallOutput: …` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The output of a computer tool call. - - `strict: Optional[bool]` + - `call_id: str` - 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). + The ID of the computer tool call that produced the output. - - `type: Literal["json_schema"]` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The type of response format being defined. Always `json_schema`. + A computer screenshot image used with the computer use tool. - - `"json_schema"` + - `type: Literal["computer_screenshot"]` - - `started_at: Optional[int]` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The Unix timestamp (in seconds) for when the run was started. + - `"computer_screenshot"` - - `status: object` + - `file_id: Optional[str]` - - `thread_id: str` + The identifier of an uploaded file that contains the screenshot. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `image_url: Optional[str]` - - `tool_choice: Optional[AssistantToolChoiceOption]` + The URL of the screenshot image. - 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. + - `type: Literal["computer_call_output"]` - - `Literal["none", "auto", "required"]` + The type of the computer tool call output. Always `computer_call_output`. - `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. + - `"computer_call_output"` - - `"none"` + - `id: Optional[str]` - - `"auto"` + The ID of the computer tool call output. - - `"required"` + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - - `class AssistantToolChoice: …` + The safety checks reported by the API that have been acknowledged by the developer. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `id: str` - - `type: Literal["function", "code_interpreter", "file_search"]` + The ID of the pending safety check. - The type of the tool. If type is `function`, the function name must be set + - `code: Optional[str]` - - `"function"` + The type of the pending safety check. - - `"code_interpreter"` + - `message: Optional[str]` - - `"file_search"` + Details about the pending safety check. - - `function: Optional[AssistantToolChoiceFunction]` + - `agent: Optional[ComputerCallOutputAgent]` - - `name: str` + The agent that produced this item. - The name of the function to call. + - `agent_name: str` - - `tools: List[object]` + The canonical name of the agent that produced this item. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `truncation_strategy: Optional[TruncationStrategy]` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"in_progress"` - - `type: Literal["auto", "last_messages"]` + - `"completed"` - 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`. + - `"incomplete"` - - `"auto"` + - `class BetaResponseFunctionWebSearch: …` - - `"last_messages"` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `last_messages: Optional[int]` + - `id: str` - The number of most recent messages from the thread when constructing the context for the run. + The unique ID of the web search tool call. - - `usage: Optional[Usage]` + - `action: Action` - 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.). + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `completion_tokens: int` + - `class ActionSearch: …` - Number of completion tokens used over the course of the run. + Action type "search" - Performs a web search query. - - `prompt_tokens: int` + - `type: Literal["search"]` - Number of prompt tokens used over the course of the run. + The action type. - - `total_tokens: int` + - `"search"` - Total number of tokens used (prompt + completion). + - `queries: Optional[List[str]]` - - `temperature: Optional[float]` + The search queries. - The sampling temperature used for this run. If not set, defaults to 1. + - `query: Optional[str]` - - `top_p: Optional[float]` + The search query. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `sources: Optional[List[ActionSearchSource]]` - - `event: Literal["thread.run.created"]` + The sources used in the search. - - `"thread.run.created"` + - `type: Literal["url"]` - - `class ThreadRunQueued: …` + The type of source. Always `url`. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. + - `"url"` - - `data: Run` + - `url: str` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The URL of the source. - - `event: Literal["thread.run.queued"]` + - `class ActionOpenPage: …` - - `"thread.run.queued"` + Action type "open_page" - Opens a specific URL from search results. - - `class ThreadRunInProgress: …` + - `type: Literal["open_page"]` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. + The action type. - - `data: Run` + - `"open_page"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `url: Optional[str]` - - `event: Literal["thread.run.in_progress"]` + The URL opened by the model. - - `"thread.run.in_progress"` + - `class ActionFindInPage: …` - - `class ThreadRunRequiresAction: …` + Action type "find_in_page": Searches for a pattern within a loaded page. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. + - `pattern: str` - - `data: Run` + The pattern or text to search for within the page. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `type: Literal["find_in_page"]` - - `event: Literal["thread.run.requires_action"]` + The action type. - - `"thread.run.requires_action"` + - `"find_in_page"` - - `class ThreadRunCompleted: …` + - `url: str` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. + The URL of the page searched for the pattern. - - `data: Run` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The status of the web search tool call. - - `event: Literal["thread.run.completed"]` + - `"in_progress"` - - `"thread.run.completed"` + - `"searching"` - - `class ThreadRunIncomplete: …` + - `"completed"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. + - `"failed"` - - `data: Run` + - `type: Literal["web_search_call"]` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The type of the web search tool call. Always `web_search_call`. - - `event: Literal["thread.run.incomplete"]` + - `"web_search_call"` - - `"thread.run.incomplete"` + - `agent: Optional[Agent]` - - `class ThreadRunFailed: …` + The agent that produced this item. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. + - `agent_name: str` - - `data: Run` + The canonical name of the agent that produced this item. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class BetaResponseFunctionToolCall: …` - - `event: Literal["thread.run.failed"]` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `"thread.run.failed"` + - `arguments: str` - - `class ThreadRunCancelling: …` + A JSON string of the arguments to pass to the function. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. + - `call_id: str` - - `data: Run` + The unique ID of the function tool call generated by the model. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `name: str` - - `event: Literal["thread.run.cancelling"]` + The name of the function to run. - - `"thread.run.cancelling"` + - `type: Literal["function_call"]` - - `class ThreadRunCancelled: …` + The type of the function tool call. Always `function_call`. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. + - `"function_call"` - - `data: Run` + - `id: Optional[str]` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The unique ID of the function tool call. - - `event: Literal["thread.run.cancelled"]` + - `agent: Optional[Agent]` - - `"thread.run.cancelled"` + The agent that produced this item. - - `class ThreadRunExpired: …` + - `agent_name: str` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. + The canonical name of the agent that produced this item. - - `data: Run` + - `caller: Optional[Caller]` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The execution context that produced this tool call. - - `event: Literal["thread.run.expired"]` + - `class CallerDirect: …` - - `"thread.run.expired"` + - `type: Literal["direct"]` -### Thread Stream Event + - `"direct"` -- `class ThreadStreamEvent: …` + - `class CallerProgram: …` - Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. + - `caller_id: str` - - `data: Thread` + The call ID of the program item that produced this tool call. - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `type: Literal["program"]` - - `id: str` + - `"program"` - The identifier, which can be referenced in API endpoints. + - `namespace: Optional[str]` - - `created_at: int` + The namespace of the function to run. - The Unix timestamp (in seconds) for when the thread was created. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `metadata: Optional[Metadata]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - 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. + - `"in_progress"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"completed"` - - `object: Literal["thread"]` + - `"incomplete"` - The object type, which is always `thread`. + - `class FunctionCallOutput: …` - - `"thread"` + The output of a function tool call. - - `tool_resources: Optional[ToolResources]` + - `call_id: str` - 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. + The unique ID of the function tool call generated by the model. - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - - `file_ids: Optional[List[str]]` + Text, image, or file output of the function tool call. - 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. + - `str` - - `file_search: Optional[ToolResourcesFileSearch]` + A JSON string of the output of the function tool call. - - `vector_store_ids: Optional[List[str]]` + - `List[BetaResponseFunctionCallOutputItem]` - 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. + - `class BetaResponseInputTextContent: …` - - `event: Literal["thread.created"]` + A text input to the model. - - `"thread.created"` + - `text: str` - - `enabled: Optional[bool]` + The text input to the model. - Whether to enable input audio transcription. + - `type: Literal["input_text"]` -# Threads + The type of the input item. Always `input_text`. -## Create thread + - `"input_text"` -`beta.threads.create(ThreadCreateParams**kwargs) -> Thread` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` -**post** `/threads` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. -Create thread + - `mode: Literal["explicit"]` -### Parameters + The breakpoint mode. Always `explicit`. -- `messages: Optional[Iterable[Message]]` + - `"explicit"` - A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. + - `class BetaResponseInputImageContent: …` - - `content: Union[str, Iterable[MessageContentPartParam]]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The text contents of the message. + - `type: Literal["input_image"]` - - `str` + The type of the input item. Always `input_image`. - The text contents of the message. + - `"input_image"` - - `Iterable[MessageContentPartParam]` + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](https://platform.openai.com/docs/models). + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `class ImageFileContentBlock: …` + - `"low"` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `"high"` - - `image_file: ImageFileParam` + - `"auto"` - - `file_id: str` + - `"original"` - 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. + - `file_id: Optional[str]` - - `detail: Optional[Literal["auto", "low", "high"]]` + The ID of the file to be sent to the model. - 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`. + - `image_url: Optional[str]` - - `"auto"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"low"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"high"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `type: Literal["image_file"]` + - `mode: Literal["explicit"]` - Always `image_file`. + The breakpoint mode. Always `explicit`. - - `"image_file"` + - `"explicit"` - - `class ImageURLContentBlock: …` + - `class BetaResponseInputFileContent: …` - References an image URL in the content of a message. + A file input to the model. - - `image_url: ImageURLParam` + - `type: Literal["input_file"]` - - `url: str` + The type of the input item. Always `input_file`. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"input_file"` - `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` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - `"auto"` @@ -6646,6389 +6031,16916 @@ Create thread - `"high"` - - `type: Literal["image_url"]` + - `file_data: Optional[str]` - The type of the content part. + The base64-encoded data of the file to be sent to the model. - - `"image_url"` + - `file_id: Optional[str]` - - `class TextContentBlockParam: …` + The ID of the file to be sent to the model. - The text content that is part of a message. + - `file_url: Optional[str]` - - `text: str` + The URL of the file to be sent to the model. - Text content to be sent to the model + - `filename: Optional[str]` - - `type: Literal["text"]` + The name of the file to be sent to the model. - Always `text`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"text"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `role: Literal["user", "assistant"]` + - `mode: Literal["explicit"]` - The role of the entity that is creating the message. Allowed values include: + The breakpoint mode. Always `explicit`. - - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + - `"explicit"` - - `"user"` + - `type: Literal["function_call_output"]` - - `"assistant"` + The type of the function tool call output. Always `function_call_output`. - - `attachments: Optional[Iterable[MessageAttachment]]` + - `"function_call_output"` - A list of files attached to the message, and the tools they should be added to. + - `id: Optional[str]` - - `file_id: Optional[str]` + The unique ID of the function tool call output. Populated when this item is returned via API. - The ID of the file to attach to the message. + - `agent: Optional[FunctionCallOutputAgent]` - - `tools: Optional[Iterable[MessageAttachmentTool]]` + The agent that produced this item. - The tools to add this file to. + - `agent_name: str` - - `class CodeInterpreterTool: …` + The canonical name of the agent that produced this item. - - `type: Literal["code_interpreter"]` + - `caller: Optional[FunctionCallOutputCaller]` - The type of tool being defined: `code_interpreter` + The execution context that produced this tool call. - - `"code_interpreter"` + - `class FunctionCallOutputCallerDirect: …` - - `class MessageAttachmentToolFileSearch: …` + - `type: Literal["direct"]` - - `type: Literal["file_search"]` + The caller type. Always `direct`. - The type of tool being defined: `file_search` + - `"direct"` - - `"file_search"` + - `class FunctionCallOutputCallerProgram: …` - - `metadata: Optional[Metadata]` + - `caller_id: str` - 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. + The call ID of the program item that produced this tool call. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: Literal["program"]` -- `metadata: Optional[Metadata]` + The caller type. Always `program`. - 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. + - `"program"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` -- `tool_resources: Optional[ToolResources]` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - 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. + - `"in_progress"` - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + - `"completed"` - - `file_ids: Optional[Sequence[str]]` + - `"incomplete"` - 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. + - `class AgentMessage: …` - - `file_search: Optional[ToolResourcesFileSearch]` + A message routed between agents. - - `vector_store_ids: Optional[Sequence[str]]` + - `author: 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. + The sending agent identity. - - `vector_stores: Optional[Iterable[ToolResourcesFileSearchVectorStore]]` + - `content: List[AgentMessageContent]` - 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 thread. There can be a maximum of 1 vector store attached to the thread. + Plaintext, image, or encrypted content sent between agents. - - `chunking_strategy: Optional[ToolResourcesFileSearchVectorStoreChunkingStrategy]` + - `class BetaResponseInputTextContent: …` - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + A text input to the model. - - `class ToolResourcesFileSearchVectorStoreChunkingStrategyAuto: …` + - `class BetaResponseInputImageContent: …` - The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `type: Literal["auto"]` + - `class AgentMessageContentEncryptedContent: …` - Always `auto`. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"auto"` + - `encrypted_content: str` - - `class ToolResourcesFileSearchVectorStoreChunkingStrategyStatic: …` + Opaque encrypted content. - - `static: ToolResourcesFileSearchVectorStoreChunkingStrategyStaticStatic` + - `type: Literal["encrypted_content"]` - - `chunk_overlap_tokens: int` + The type of the input item. Always `encrypted_content`. - The number of tokens that overlap between chunks. The default value is `400`. + - `"encrypted_content"` - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + - `recipient: str` - - `max_chunk_size_tokens: int` + The destination agent identity. - 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["agent_message"]` - - `type: Literal["static"]` + The item type. Always `agent_message`. - Always `static`. + - `"agent_message"` - - `"static"` + - `id: Optional[str]` - - `file_ids: Optional[Sequence[str]]` + The unique ID of this agent message item. - 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. + - `agent: Optional[AgentMessageAgent]` - - `metadata: Optional[Metadata]` + The agent that produced this item. - 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. + - `agent_name: str` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The canonical name of the agent that produced this item. -### Returns + - `class MultiAgentCall: …` -- `class Thread: …` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + The multi-agent action that was executed. - - `id: str` + - `"spawn_agent"` - The identifier, which can be referenced in API endpoints. + - `"interrupt_agent"` - - `created_at: int` + - `"list_agents"` - The Unix timestamp (in seconds) for when the thread was created. + - `"send_message"` - - `metadata: Optional[Metadata]` + - `"followup_task"` - 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. + - `"wait_agent"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `arguments: str` - - `object: Literal["thread"]` + The action arguments as a JSON string. - The object type, which is always `thread`. + - `call_id: str` - - `"thread"` + The unique ID linking this call to its output. - - `tool_resources: Optional[ToolResources]` + - `type: Literal["multi_agent_call"]` - 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. + The item type. Always `multi_agent_call`. - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + - `"multi_agent_call"` - - `file_ids: Optional[List[str]]` + - `id: Optional[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. + The unique ID of this multi-agent call. - - `file_search: Optional[ToolResourcesFileSearch]` + - `agent: Optional[MultiAgentCallAgent]` - - `vector_store_ids: Optional[List[str]]` + The agent that produced this item. - 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. + - `agent_name: str` -### Example + The canonical name of the agent that produced this item. -```python -import os -from openai import OpenAI + - `class MultiAgentCallOutput: …` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -thread = client.beta.threads.create() -print(thread.id) -``` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` -#### Response + The multi-agent action that produced this result. -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + - `"spawn_agent"` -### Empty + - `"interrupt_agent"` -```python -from openai import OpenAI -client = OpenAI() + - `"list_agents"` -empty_thread = client.beta.threads.create() -print(empty_thread) -``` + - `"send_message"` -#### Response + - `"followup_task"` -```json -{ - "id": "thread_abc123", - "object": "thread", - "created_at": 1699012949, - "metadata": {}, - "tool_resources": {} -} -``` + - `"wait_agent"` -### Messages + - `call_id: str` -```python -from openai import OpenAI -client = OpenAI() + The unique ID of the multi-agent call. -message_thread = client.beta.threads.create( - messages=[ - { - "role": "user", - "content": "Hello, what is AI?" - }, - { - "role": "user", - "content": "How does AI work? Explain it in simple terms." - }, - ] -) + - `output: List[MultiAgentCallOutputOutput]` -print(message_thread) -``` + Text output returned by the multi-agent action. -#### Response + - `text: str` -```json -{ - "id": "thread_abc123", - "object": "thread", - "created_at": 1699014083, - "metadata": {}, - "tool_resources": {} -} -``` + The text content. -## Create thread and run + - `type: Literal["output_text"]` -`beta.threads.create_and_run(ThreadCreateAndRunParams**kwargs) -> Run` + The content type. Always `output_text`. -**post** `/threads/runs` + - `"output_text"` -Create thread and run + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` -### Parameters + Citations associated with the text content. -- `assistant_id: str` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. + - `file_id: str` -- `instructions: Optional[str]` + The ID of the file. - Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis. + - `filename: str` -- `max_completion_tokens: Optional[int]` + The filename of the file cited. - The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + - `index: int` -- `max_prompt_tokens: Optional[int]` + The index of the file in the list of files. - The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + - `type: Literal["file_citation"]` -- `metadata: Optional[Metadata]` + The citation type. Always `file_citation`. - 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. + - `"file_citation"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` -- `model: Optional[Union[str, ChatModel, null]]` + - `end_index: int` - The ID of the [Model](https://platform.openai.com/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. + The index of the last character of the citation in the message. - - `str` + - `start_index: int` - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 78 more]` + The index of the first character of the citation in the message. - - `"gpt-5.6-sol"` + - `title: str` - - `"gpt-5.6-terra"` + The title of the cited resource. - - `"gpt-5.6-luna"` + - `type: Literal["url_citation"]` - - `"gpt-5.4"` + The citation type. Always `url_citation`. - - `"gpt-5.4-mini"` + - `"url_citation"` - - `"gpt-5.4-nano"` + - `url: str` - - `"gpt-5.4-mini-2026-03-17"` + The URL of the cited resource. - - `"gpt-5.4-nano-2026-03-17"` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` - - `"gpt-5.3-chat-latest"` + - `container_id: str` - - `"gpt-5.2"` + The ID of the container. - - `"gpt-5.2-2025-12-11"` + - `end_index: int` - - `"gpt-5.2-chat-latest"` + The index of the last character of the citation in the message. - - `"gpt-5.2-pro"` + - `file_id: str` - - `"gpt-5.2-pro-2025-12-11"` + The ID of the container file. - - `"gpt-5.1"` + - `filename: str` - - `"gpt-5.1-2025-11-13"` + The filename of the container file cited. - - `"gpt-5.1-codex"` + - `start_index: int` - - `"gpt-5.1-mini"` + The index of the first character of the citation in the message. - - `"gpt-5.1-chat-latest"` + - `type: Literal["container_file_citation"]` - - `"gpt-5"` + The citation type. Always `container_file_citation`. - - `"gpt-5-mini"` + - `"container_file_citation"` - - `"gpt-5-nano"` + - `type: Literal["multi_agent_call_output"]` - - `"gpt-5-2025-08-07"` + The item type. Always `multi_agent_call_output`. - - `"gpt-5-mini-2025-08-07"` + - `"multi_agent_call_output"` - - `"gpt-5-nano-2025-08-07"` + - `id: Optional[str]` - - `"gpt-5-chat-latest"` + The unique ID of this multi-agent call output. - - `"gpt-4.1"` + - `agent: Optional[MultiAgentCallOutputAgent]` - - `"gpt-4.1-mini"` + The agent that produced this item. - - `"gpt-4.1-nano"` + - `agent_name: str` - - `"gpt-4.1-2025-04-14"` + The canonical name of the agent that produced this item. - - `"gpt-4.1-mini-2025-04-14"` + - `class ToolSearchCall: …` - - `"gpt-4.1-nano-2025-04-14"` + - `arguments: object` - - `"o4-mini"` + The arguments supplied to the tool search call. - - `"o4-mini-2025-04-16"` + - `type: Literal["tool_search_call"]` - - `"o3"` + The item type. Always `tool_search_call`. - - `"o3-2025-04-16"` + - `"tool_search_call"` - - `"o3-mini"` + - `id: Optional[str]` - - `"o3-mini-2025-01-31"` + The unique ID of this tool search call. - - `"o1"` + - `agent: Optional[ToolSearchCallAgent]` - - `"o1-2024-12-17"` + The agent that produced this item. - - `"o1-preview"` + - `agent_name: str` - - `"o1-preview-2024-09-12"` + The canonical name of the agent that produced this item. - - `"o1-mini"` + - `call_id: Optional[str]` - - `"o1-mini-2024-09-12"` + The unique ID of the tool search call generated by the model. - - `"gpt-4o"` + - `execution: Optional[Literal["server", "client"]]` - - `"gpt-4o-2024-11-20"` + Whether tool search was executed by the server or by the client. - - `"gpt-4o-2024-08-06"` + - `"server"` - - `"gpt-4o-2024-05-13"` + - `"client"` - - `"gpt-4o-audio-preview"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"gpt-4o-audio-preview-2024-10-01"` + The status of the tool search call. - - `"gpt-4o-audio-preview-2024-12-17"` + - `"in_progress"` - - `"gpt-4o-audio-preview-2025-06-03"` + - `"completed"` - - `"gpt-4o-mini-audio-preview"` + - `"incomplete"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `class BetaResponseToolSearchOutputItemParam: …` - - `"gpt-4o-search-preview"` + - `tools: List[BetaTool]` - - `"gpt-4o-mini-search-preview"` + The loaded tool definitions returned by the tool search output. - - `"gpt-4o-search-preview-2025-03-11"` + - `class BetaFunctionTool: …` - - `"gpt-4o-mini-search-preview-2025-03-11"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"chatgpt-4o-latest"` + - `name: str` - - `"codex-mini-latest"` + The name of the function to call. - - `"gpt-4o-mini"` + - `parameters: Optional[Dict[str, object]]` - - `"gpt-4o-mini-2024-07-18"` + A JSON schema object describing the parameters of the function. - - `"gpt-4-turbo"` + - `strict: Optional[bool]` - - `"gpt-4-turbo-2024-04-09"` + Whether strict parameter validation is enforced for this function tool. - - `"gpt-4-0125-preview"` + - `type: Literal["function"]` - - `"gpt-4-turbo-preview"` + The type of the function tool. Always `function`. - - `"gpt-4-1106-preview"` + - `"function"` - - `"gpt-4-vision-preview"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"gpt-4"` + The tool invocation context(s). - - `"gpt-4-0314"` + - `"direct"` - - `"gpt-4-0613"` + - `"programmatic"` - - `"gpt-4-32k"` + - `defer_loading: Optional[bool]` - - `"gpt-4-32k-0314"` + Whether this function is deferred and loaded via tool search. - - `"gpt-4-32k-0613"` + - `description: Optional[str]` - - `"gpt-3.5-turbo"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"gpt-3.5-turbo-16k"` + - `output_schema: Optional[Dict[str, object]]` - - `"gpt-3.5-turbo-0301"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"gpt-3.5-turbo-0613"` + - `class BetaFileSearchTool: …` - - `"gpt-3.5-turbo-1106"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `"gpt-3.5-turbo-0125"` + - `type: Literal["file_search"]` - - `"gpt-3.5-turbo-16k-0613"` + The type of the file search tool. Always `file_search`. -- `parallel_tool_calls: Optional[bool]` + - `"file_search"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `vector_store_ids: List[str]` -- `response_format: Optional[AssistantResponseFormatOptionParam]` + The IDs of the vector stores to search. - 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`. + - `filters: Optional[Filters]` - 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). + A filter to apply. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `class FiltersComparisonFilter: …` - **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. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `Literal["auto"]` + - `key: str` - `auto` is the default value + The key to compare against the value. - - `"auto"` + - `type: Literal["eq", "ne", "gt", 5 more]` - - `class ResponseFormatText: …` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Default response format. Used to generate text responses. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `type: Literal["text"]` + - `"eq"` - The type of response format being defined. Always `text`. + - `"ne"` - - `"text"` + - `"gt"` - - `class ResponseFormatJSONObject: …` + - `"gte"` - 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. + - `"lt"` - - `type: Literal["json_object"]` + - `"lte"` - The type of response format being defined. Always `json_object`. + - `"in"` - - `"json_object"` + - `"nin"` - - `class ResponseFormatJSONSchema: …` + - `value: Union[str, float, bool, List[Union[str, float]]]` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The value to compare against the attribute key; supports string, number, or boolean types. - - `json_schema: JSONSchema` + - `str` - Structured Outputs configuration options, including a JSON Schema. + - `float` - - `name: str` + - `bool` - 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. + - `List[Union[str, float]]` - - `description: Optional[str]` + - `str` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `float` - - `schema: Optional[Dict[str, object]]` + - `class FiltersCompoundFilter: …` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Combine multiple filters using `and` or `or`. - - `strict: Optional[bool]` + - `filters: List[FiltersCompoundFilterFilter]` - 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). + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `type: Literal["json_schema"]` + - `class FiltersCompoundFilterFilterComparisonFilter: …` - The type of response format being defined. Always `json_schema`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"json_schema"` + - `key: str` -- `stream: Optional[Literal[false]]` + The key to compare against the value. - If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `false` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. -- `temperature: Optional[float]` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - 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. + - `"eq"` -- `thread: Optional[Thread]` + - `"ne"` - Options to create a new thread. If no thread is provided when running a - request, an empty thread will be created. + - `"gt"` - - `messages: Optional[Iterable[ThreadMessage]]` + - `"gte"` - A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. + - `"lt"` - - `content: Union[str, Iterable[MessageContentPartParam]]` + - `"lte"` - The text contents of the message. + - `"in"` - - `str` + - `"nin"` - The text contents of the message. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `Iterable[MessageContentPartParam]` + The value to compare against the attribute key; supports string, number, or boolean types. - An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](https://platform.openai.com/docs/models). + - `str` - - `class ImageFileContentBlock: …` + - `float` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `bool` - - `image_file: ImageFileParam` + - `List[Union[str, float]]` - - `file_id: str` + - `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. + - `float` - - `detail: Optional[Literal["auto", "low", "high"]]` + - `object` - 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`. + - `type: Literal["and", "or"]` - - `"auto"` + Type of operation: `and` or `or`. - - `"low"` + - `"and"` - - `"high"` + - `"or"` - - `type: Literal["image_file"]` + - `max_num_results: Optional[int]` - Always `image_file`. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"image_file"` + - `ranking_options: Optional[RankingOptions]` - - `class ImageURLContentBlock: …` + Ranking options for search. - References an image URL in the content of a message. + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - `image_url: ImageURLParam` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `url: str` + - `embedding_weight: float` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The weight of the embedding in the reciprocal ranking fusion. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `text_weight: float` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + The weight of the text in the reciprocal ranking fusion. + + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + + The ranker to use for the file search. - `"auto"` - - `"low"` + - `"default-2024-11-15"` - - `"high"` + - `score_threshold: Optional[float]` - - `type: Literal["image_url"]` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The type of the content part. + - `class BetaComputerTool: …` - - `"image_url"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class TextContentBlockParam: …` + - `type: Literal["computer"]` - The text content that is part of a message. + The type of the computer tool. Always `computer`. - - `text: str` + - `"computer"` - Text content to be sent to the model + - `class BetaComputerUsePreviewTool: …` - - `type: Literal["text"]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Always `text`. + - `display_height: int` - - `"text"` + The height of the computer display. - - `role: Literal["user", "assistant"]` + - `display_width: int` - The role of the entity that is creating the message. Allowed values include: + The width of the computer display. - - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + - `environment: Literal["windows", "mac", "linux", 2 more]` - - `"user"` + The type of computer environment to control. - - `"assistant"` + - `"windows"` - - `attachments: Optional[Iterable[ThreadMessageAttachment]]` + - `"mac"` - A list of files attached to the message, and the tools they should be added to. + - `"linux"` - - `file_id: Optional[str]` + - `"ubuntu"` - The ID of the file to attach to the message. + - `"browser"` - - `tools: Optional[Iterable[ThreadMessageAttachmentTool]]` + - `type: Literal["computer_use_preview"]` - The tools to add this file to. + The type of the computer use tool. Always `computer_use_preview`. - - `class CodeInterpreterTool: …` + - `"computer_use_preview"` - - `type: Literal["code_interpreter"]` + - `class BetaWebSearchTool: …` - The type of tool being defined: `code_interpreter` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"code_interpreter"` + - `type: Literal["web_search", "web_search_2025_08_26"]` - - `class ThreadMessageAttachmentToolFileSearch: …` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `type: Literal["file_search"]` + - `"web_search"` - The type of tool being defined: `file_search` + - `"web_search_2025_08_26"` - - `"file_search"` + - `filters: Optional[Filters]` - - `metadata: Optional[Metadata]` + Filters for the search. - 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. + - `allowed_domains: Optional[List[str]]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `metadata: Optional[Metadata]` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - 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. + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `tool_resources: Optional[ThreadToolResources]` + - `"low"` - 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. + - `"medium"` - - `code_interpreter: Optional[ThreadToolResourcesCodeInterpreter]` + - `"high"` - - `file_ids: Optional[Sequence[str]]` + - `user_location: Optional[UserLocation]` - 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. + The approximate location of the user. - - `file_search: Optional[ThreadToolResourcesFileSearch]` + - `city: Optional[str]` - - `vector_store_ids: Optional[Sequence[str]]` + Free text input for the city of the user, e.g. `San Francisco`. - 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. + - `country: Optional[str]` - - `vector_stores: Optional[Iterable[ThreadToolResourcesFileSearchVectorStore]]` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - 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 thread. There can be a maximum of 1 vector store attached to the thread. + - `region: Optional[str]` - - `chunking_strategy: Optional[ThreadToolResourcesFileSearchVectorStoreChunkingStrategy]` + Free text input for the region of the user, e.g. `California`. - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + - `timezone: Optional[str]` - - `class ThreadToolResourcesFileSearchVectorStoreChunkingStrategyAuto: …` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. + - `type: Optional[Literal["approximate"]]` - - `type: Literal["auto"]` + The type of location approximation. Always `approximate`. - Always `auto`. + - `"approximate"` - - `"auto"` + - `class Mcp: …` - - `class ThreadToolResourcesFileSearchVectorStoreChunkingStrategyStatic: …` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `static: ThreadToolResourcesFileSearchVectorStoreChunkingStrategyStaticStatic` + - `server_label: str` - - `chunk_overlap_tokens: int` + A label for this MCP server, used to identify it in tool calls. - The number of tokens that overlap between chunks. The default value is `400`. + - `type: Literal["mcp"]` - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + The type of the MCP tool. Always `mcp`. - - `max_chunk_size_tokens: int` + - `"mcp"` - The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `type: Literal["static"]` + The tool invocation context(s). - Always `static`. + - `"direct"` - - `"static"` + - `"programmatic"` - - `file_ids: Optional[Sequence[str]]` + - `allowed_tools: Optional[McpAllowedTools]` - 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. + List of allowed tool names or a filter object. - - `metadata: Optional[Metadata]` + - `List[str]` - 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. + A string array of allowed tool names - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `class McpAllowedToolsMcpToolFilter: …` -- `tool_choice: Optional[AssistantToolChoiceOptionParam]` + A filter object to specify which tools are allowed. - 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. + - `read_only: Optional[bool]` - - `Literal["none", "auto", "required"]` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - `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. + - `tool_names: Optional[List[str]]` - - `"none"` + List of allowed tool names. - - `"auto"` + - `authorization: Optional[str]` - - `"required"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `class AssistantToolChoice: …` + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - Specifies a tool the model should use. Use to force the model to call a specific tool. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `type: Literal["function", "code_interpreter", "file_search"]` + Currently supported `connector_id` values are: - The type of the tool. If type is `function`, the function name must be set + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `"function"` + - `"connector_dropbox"` - - `"code_interpreter"` + - `"connector_gmail"` - - `"file_search"` + - `"connector_googlecalendar"` - - `function: Optional[AssistantToolChoiceFunction]` + - `"connector_googledrive"` - - `name: str` + - `"connector_microsoftteams"` - The name of the function to call. + - `"connector_outlookcalendar"` -- `tool_resources: Optional[ToolResources]` + - `"connector_outlookemail"` - 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. + - `"connector_sharepoint"` - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + - `defer_loading: Optional[bool]` - - `file_ids: Optional[Sequence[str]]` + Whether this MCP tool is deferred and discovered via tool search. - 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. + - `headers: Optional[Dict[str, str]]` - - `file_search: Optional[ToolResourcesFileSearch]` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `vector_store_ids: Optional[Sequence[str]]` + - `require_approval: Optional[McpRequireApproval]` - 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. + Specify which of the MCP server's tools require approval. -- `tools: Optional[Iterable[object]]` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. -- `top_p: Optional[float]` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - 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. + A filter object to specify which tools are allowed. - We generally recommend altering this or temperature but not both. + - `read_only: Optional[bool]` -- `truncation_strategy: Optional[TruncationStrategy]` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `tool_names: Optional[List[str]]` - - `type: Literal["auto", "last_messages"]` + List of allowed tool names. - 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`. + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - - `"auto"` + A filter object to specify which tools are allowed. - - `"last_messages"` + - `read_only: Optional[bool]` - - `last_messages: Optional[int]` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The number of most recent messages from the thread when constructing the context for the run. + - `tool_names: Optional[List[str]]` -### Returns + List of allowed tool names. -- `class Run: …` + - `Literal["always", "never"]` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `id: str` + - `"always"` - The identifier, which can be referenced in API endpoints. + - `"never"` - - `assistant_id: str` + - `server_description: Optional[str]` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + Optional description of the MCP server, used to provide more context. - - `cancelled_at: Optional[int]` + - `server_url: Optional[str]` - The Unix timestamp (in seconds) for when the run was cancelled. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `completed_at: Optional[int]` + - `tunnel_id: Optional[str]` - The Unix timestamp (in seconds) for when the run was completed. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `created_at: int` + - `class CodeInterpreter: …` - The Unix timestamp (in seconds) for when the run was created. + A tool that runs Python code to help generate a response to a prompt. - - `expires_at: Optional[int]` + - `container: CodeInterpreterContainer` - The Unix timestamp (in seconds) for when the run will expire. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `failed_at: Optional[int]` + - `str` - The Unix timestamp (in seconds) for when the run failed. + The container ID. - - `incomplete_details: Optional[IncompleteDetails]` + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` + - `type: Literal["auto"]` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + Always `auto`. - - `"max_completion_tokens"` + - `"auto"` - - `"max_prompt_tokens"` + - `file_ids: Optional[List[str]]` - - `instructions: str` + An optional list of uploaded files to make available to your code. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `last_error: Optional[LastError]` + The memory limit for the code interpreter container. - The last error associated with this run. Will be `null` if there are no errors. + - `"1g"` - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` + - `"4g"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"16g"` - - `"server_error"` + - `"64g"` - - `"rate_limit_exceeded"` + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - - `"invalid_prompt"` + Network access policy for the container. - - `message: str` + - `class BetaContainerNetworkPolicyDisabled: …` - A human-readable description of the error. + - `type: Literal["disabled"]` - - `max_completion_tokens: Optional[int]` + Disable outbound network access. Always `disabled`. - The maximum number of completion tokens specified to have been used over the course of the run. + - `"disabled"` - - `max_prompt_tokens: Optional[int]` + - `class BetaContainerNetworkPolicyAllowlist: …` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `allowed_domains: List[str]` - - `metadata: Optional[Metadata]` + A list of allowed domains when type is `allowlist`. - 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. + - `type: Literal["allowlist"]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Allow outbound network access only to specified domains. Always `allowlist`. - - `model: str` + - `"allowlist"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `object: Literal["thread.run"]` + Optional domain-scoped secrets for allowlisted domains. - The object type, which is always `thread.run`. + - `domain: str` - - `"thread.run"` + The domain associated with the secret. - - `parallel_tool_calls: bool` + - `name: str` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The name of the secret to inject for the domain. - - `required_action: Optional[RequiredAction]` + - `value: str` - Details on the action required to continue the run. Will be `null` if no action is required. + The secret value to inject for the domain. - - `submit_tool_outputs: RequiredActionSubmitToolOutputs` + - `type: Literal["code_interpreter"]` - Details on the tool outputs needed for this run to continue. + The type of the code interpreter tool. Always `code_interpreter`. - - `tool_calls: List[RequiredActionFunctionToolCall]` + - `"code_interpreter"` - A list of the relevant tool calls. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `id: str` + The tool invocation context(s). - 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. + - `"direct"` - - `function: Function` + - `"programmatic"` - The function definition. + - `class ProgrammaticToolCalling: …` - - `arguments: str` + - `type: Literal["programmatic_tool_calling"]` - The arguments that the model expects you to pass to the function. + The type of the tool. Always `programmatic_tool_calling`. - - `name: str` + - `"programmatic_tool_calling"` - The name of the function. + - `class ImageGeneration: …` - - `type: Literal["function"]` + A tool that generates images using the GPT image models. - The type of tool call the output is required for. For now, this is always `function`. + - `type: Literal["image_generation"]` - - `"function"` + The type of the image generation tool. Always `image_generation`. - - `type: Literal["submit_tool_outputs"]` + - `"image_generation"` - For now, this is always `submit_tool_outputs`. + - `action: Optional[Literal["generate", "edit", "auto"]]` - - `"submit_tool_outputs"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `response_format: Optional[AssistantResponseFormatOption]` + - `"generate"` - 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`. + - `"edit"` - 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). + - `"auto"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - **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. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `Literal["auto"]` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - `auto` is the default value + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. + + - `"transparent"` + + - `"opaque"` - `"auto"` - - `class ResponseFormatText: …` + - `input_fidelity: Optional[Literal["high", "low"]]` - Default response format. Used to generate text responses. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `type: Literal["text"]` + - `"high"` - The type of response format being defined. Always `text`. + - `"low"` - - `"text"` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - - `class ResponseFormatJSONObject: …` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - 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. + - `file_id: Optional[str]` - - `type: Literal["json_object"]` + File ID for the mask image. - The type of response format being defined. Always `json_object`. + - `image_url: Optional[str]` - - `"json_object"` + Base64-encoded mask image. - - `class ResponseFormatJSONSchema: …` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The image generation model to use. Default: `gpt-image-1`. - - `json_schema: JSONSchema` + - `str` - Structured Outputs configuration options, including a JSON Schema. + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `name: str` + The image generation model to use. Default: `gpt-image-1`. - 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. + - `"gpt-image-1"` - - `description: Optional[str]` + - `"gpt-image-1-mini"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"gpt-image-2"` - - `schema: Optional[Dict[str, object]]` + - `"gpt-image-2-2026-04-21"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"gpt-image-1.5"` - - `strict: Optional[bool]` + - `"chatgpt-image-latest"` - 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). + - `moderation: Optional[Literal["auto", "low"]]` - - `type: Literal["json_schema"]` + Moderation level for the generated image. Default: `auto`. - The type of response format being defined. Always `json_schema`. + - `"auto"` - - `"json_schema"` + - `"low"` - - `started_at: Optional[int]` + - `output_compression: Optional[int]` - The Unix timestamp (in seconds) for when the run was started. + Compression level for the output image. Default: 100. - - `status: object` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `thread_id: str` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `"png"` - - `tool_choice: Optional[AssistantToolChoiceOption]` + - `"webp"` - 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. + - `"jpeg"` - - `Literal["none", "auto", "required"]` + - `partial_images: Optional[int]` - `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. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"none"` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` - `"auto"` - - `"required"` + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - - `class AssistantToolChoice: …` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `str` - - `type: Literal["function", "code_interpreter", "file_search"]` + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - The type of the tool. If type is `function`, the function name must be set + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `"function"` + - `"1024x1024"` - - `"code_interpreter"` + - `"1024x1536"` - - `"file_search"` + - `"1536x1024"` - - `function: Optional[AssistantToolChoiceFunction]` + - `"auto"` - - `name: str` + - `class LocalShell: …` - The name of the function to call. + A tool that allows the model to execute shell commands in a local environment. - - `tools: List[object]` + - `type: Literal["local_shell"]` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The type of the local shell tool. Always `local_shell`. - - `truncation_strategy: Optional[TruncationStrategy]` + - `"local_shell"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `class BetaFunctionShellTool: …` - - `type: Literal["auto", "last_messages"]` + A tool that allows the model to execute shell commands. - 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`. + - `type: Literal["shell"]` - - `"auto"` + The type of the shell tool. Always `shell`. - - `"last_messages"` + - `"shell"` - - `last_messages: Optional[int]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The number of most recent messages from the thread when constructing the context for the run. + The tool invocation context(s). - - `usage: Optional[Usage]` + - `"direct"` - 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.). + - `"programmatic"` - - `completion_tokens: int` + - `environment: Optional[Environment]` - Number of completion tokens used over the course of the run. + - `class BetaContainerAuto: …` - - `prompt_tokens: int` + - `type: Literal["container_auto"]` - Number of prompt tokens used over the course of the run. + Automatically creates a container for this request - - `total_tokens: int` + - `"container_auto"` - Total number of tokens used (prompt + completion). + - `file_ids: Optional[List[str]]` - - `temperature: Optional[float]` + An optional list of uploaded files to make available to your code. - The sampling temperature used for this run. If not set, defaults to 1. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `top_p: Optional[float]` + The memory limit for the container. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"1g"` -### Example + - `"4g"` -```python -import os -from openai import OpenAI + - `"16g"` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -for thread in client.beta.threads.create_and_run( - assistant_id="assistant_id", -): - print(thread) -``` + - `"64g"` -#### Response + - `network_policy: Optional[NetworkPolicy]` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + Network access policy for the container. -### Example + - `class BetaContainerNetworkPolicyDisabled: …` -```python -from openai import OpenAI -client = OpenAI() + - `class BetaContainerNetworkPolicyAllowlist: …` -run = client.beta.threads.create_and_run( - assistant_id="asst_abc123", - thread={ - "messages": [ - {"role": "user", "content": "Explain deep learning to a 5 year old."} - ] - } -) + - `skills: Optional[List[Skill]]` -print(run) -``` + An optional list of skills referenced by id or inline data. -#### Response + - `class BetaSkillReference: …` -```json -{ - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699076792, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "queued", - "started_at": null, - "expires_at": 1699077392, - "cancelled_at": null, - "failed_at": null, - "completed_at": null, - "required_action": null, - "last_error": null, - "model": "gpt-4o", - "instructions": "You are a helpful assistant.", - "tools": [], - "tool_resources": {}, - "metadata": {}, - "temperature": 1.0, - "top_p": 1.0, - "max_completion_tokens": null, - "max_prompt_tokens": null, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "incomplete_details": null, - "usage": null, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` + - `skill_id: str` -### Streaming + The ID of the referenced skill. -```python -from openai import OpenAI -client = OpenAI() + - `type: Literal["skill_reference"]` -stream = client.beta.threads.create_and_run( - assistant_id="asst_123", - thread={ - "messages": [ - {"role": "user", "content": "Hello"} - ] - }, - stream=True -) + References a skill created with the /v1/skills endpoint. -for event in stream: - print(event) -``` + - `"skill_reference"` -#### Response + - `version: Optional[str]` -```json -event: thread.created -data: {"id":"thread_123","object":"thread","created_at":1710348075,"metadata":{}} + Optional skill version. Use a positive integer or 'latest'. Omit for default. -event: thread.run.created -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} + - `class BetaInlineSkill: …` -event: thread.run.queued -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} + - `description: str` -event: thread.run.in_progress -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} + The description of the skill. -event: thread.run.step.created -data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + - `name: str` -event: thread.run.step.in_progress -data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + The name of the skill. -event: thread.message.created -data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[], "metadata":{}} + - `source: BetaInlineSkillSource` -event: thread.message.in_progress -data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[], "metadata":{}} + Inline skill payload -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + - `data: str` -... + Base64-encoded skill zip bundle. -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + - `media_type: Literal["application/zip"]` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + The media type of the inline skill payload. Must be `application/zip`. -event: thread.message.completed -data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}], "metadata":{}} + - `"application/zip"` -event: thread.run.step.completed -data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + - `type: Literal["base64"]` -event: thread.run.completed -{"id":"run_123","object":"thread.run","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1713226836,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1713226837,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} + The type of the inline skill source. Must be `base64`. -event: done -data: [DONE] -``` + - `"base64"` -### Streaming with Functions + - `type: Literal["inline"]` -```python -from openai import OpenAI -client = OpenAI() + Defines an inline skill for this request. -tools = [ - { - "type": "function", - "function": { - "name": "get_current_weather", - "description": "Get the current weather in a given location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA", - }, - "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, - }, - "required": ["location"], - }, - } - } -] + - `"inline"` -stream = client.beta.threads.create_and_run( - thread={ - "messages": [ - {"role": "user", "content": "What is the weather like in San Francisco?"} - ] - }, - assistant_id="asst_abc123", - tools=tools, - stream=True -) + - `class BetaLocalEnvironment: …` -for event in stream: - print(event) -``` + - `type: Literal["local"]` -#### Response + Use a local computer environment. -```json -event: thread.created -data: {"id":"thread_123","object":"thread","created_at":1710351818,"metadata":{}} + - `"local"` -event: thread.run.created -data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `skills: Optional[List[BetaLocalSkill]]` -event: thread.run.queued -data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + An optional list of skills. -event: thread.run.in_progress -data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `description: str` -event: thread.run.step.created -data: {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} + The description of the skill. -event: thread.run.step.in_progress -data: {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} + - `name: str` -event: thread.run.step.delta -data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"","output":null}}]}}} + The name of the skill. -event: thread.run.step.delta -data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"{\""}}]}}} + - `path: str` -event: thread.run.step.delta -data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"location"}}]}}} + The path to the directory containing the skill. -... + - `class BetaContainerReference: …` -event: thread.run.step.delta -data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"ahrenheit"}}]}}} + - `container_id: str` -event: thread.run.step.delta -data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"\"}"}}]}}} + The ID of the referenced container. -event: thread.run.requires_action -data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"requires_action","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":{"type":"submit_tool_outputs","submit_tool_outputs":{"tool_calls":[{"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}"}}]}},"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `type: Literal["container_reference"]` -event: done -data: [DONE] -``` + References a container created with the /v1/containers endpoint -## Retrieve thread + - `"container_reference"` -`beta.threads.retrieve(strthread_id) -> Thread` + - `class BetaCustomTool: …` -**get** `/threads/{thread_id}` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) -Retrieve thread + - `name: str` -### Parameters + The name of the custom tool, used to identify it in tool calls. -- `thread_id: str` + - `type: Literal["custom"]` -### Returns + The type of the custom tool. Always `custom`. -- `class Thread: …` + - `"custom"` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `id: str` + The tool invocation context(s). - The identifier, which can be referenced in API endpoints. + - `"direct"` - - `created_at: int` + - `"programmatic"` - The Unix timestamp (in seconds) for when the thread was created. + - `defer_loading: Optional[bool]` - - `metadata: Optional[Metadata]` + Whether this tool should be deferred and discovered via tool search. - 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. + - `description: Optional[str]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Optional description of the custom tool, used to provide more context. - - `object: Literal["thread"]` + - `format: Optional[Format]` - The object type, which is always `thread`. + The input format for the custom tool. Default is unconstrained text. - - `"thread"` + - `class FormatText: …` - - `tool_resources: Optional[ToolResources]` + Unconstrained free-form text. - 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. + - `type: Literal["text"]` - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + Unconstrained text format. Always `text`. - - `file_ids: Optional[List[str]]` + - `"text"` - 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. + - `class FormatGrammar: …` - - `file_search: Optional[ToolResourcesFileSearch]` + A grammar defined by the user. - - `vector_store_ids: Optional[List[str]]` + - `definition: 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. + The grammar definition. -### Example + - `syntax: Literal["lark", "regex"]` -```python -import os -from openai import OpenAI + The syntax of the grammar definition. One of `lark` or `regex`. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -thread = client.beta.threads.retrieve( - "thread_id", -) -print(thread.id) -``` + - `"lark"` -#### Response + - `"regex"` -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + - `type: Literal["grammar"]` -### Example + Grammar format. Always `grammar`. -```python -from openai import OpenAI -client = OpenAI() + - `"grammar"` -my_thread = client.beta.threads.retrieve("thread_abc123") -print(my_thread) -``` + - `class BetaNamespaceTool: …` -#### Response + Groups function/custom tools under a shared namespace. -```json -{ - "id": "thread_abc123", - "object": "thread", - "created_at": 1699014083, - "metadata": {}, - "tool_resources": { - "code_interpreter": { - "file_ids": [] - } - } -} -``` + - `description: str` -## Modify thread + A description of the namespace shown to the model. -`beta.threads.update(strthread_id, ThreadUpdateParams**kwargs) -> Thread` + - `name: str` -**post** `/threads/{thread_id}` + The namespace name used in tool calls (for example, `crm`). -Modify thread + - `tools: List[Tool]` -### Parameters + The function/custom tools available inside this namespace. -- `thread_id: str` + - `class ToolFunction: …` -- `metadata: Optional[Metadata]` + - `name: str` - 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. + - `type: Literal["function"]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"function"` -- `tool_resources: Optional[ToolResources]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - 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. + The tool invocation context(s). - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + - `"direct"` - - `file_ids: Optional[Sequence[str]]` + - `"programmatic"` - 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. + - `defer_loading: Optional[bool]` - - `file_search: Optional[ToolResourcesFileSearch]` + Whether this function should be deferred and discovered via tool search. - - `vector_store_ids: Optional[Sequence[str]]` + - `description: Optional[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. + - `output_schema: Optional[Dict[str, object]]` -### Returns + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. -- `class Thread: …` + - `parameters: Optional[object]` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `strict: Optional[bool]` - - `id: str` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - The identifier, which can be referenced in API endpoints. + - `class BetaCustomTool: …` - - `created_at: int` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The Unix timestamp (in seconds) for when the thread was created. + - `type: Literal["namespace"]` - - `metadata: Optional[Metadata]` + The type of the tool. Always `namespace`. - 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. + - `"namespace"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `class BetaToolSearchTool: …` - - `object: Literal["thread"]` + Hosted or BYOT tool search configuration for deferred tools. - The object type, which is always `thread`. + - `type: Literal["tool_search"]` - - `"thread"` + The type of the tool. Always `tool_search`. - - `tool_resources: Optional[ToolResources]` + - `"tool_search"` - 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. + - `description: Optional[str]` - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + Description shown to the model for a client-executed tool search tool. - - `file_ids: Optional[List[str]]` + - `execution: Optional[Literal["server", "client"]]` - 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. + Whether tool search is executed by the server or by the client. - - `file_search: Optional[ToolResourcesFileSearch]` + - `"server"` - - `vector_store_ids: Optional[List[str]]` + - `"client"` - 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. + - `parameters: Optional[object]` -### Example + Parameter schema for a client-executed tool search tool. -```python -import os -from openai import OpenAI + - `class BetaWebSearchPreviewTool: …` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -thread = client.beta.threads.update( - thread_id="thread_id", -) -print(thread.id) -``` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). -#### Response + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. -### Example + - `"web_search_preview"` -```python -from openai import OpenAI -client = OpenAI() + - `"web_search_preview_2025_03_11"` -my_updated_thread = client.beta.threads.update( - "thread_abc123", - metadata={ - "modified": "true", - "user": "abc123" - } -) -print(my_updated_thread) -``` + - `search_content_types: Optional[List[Literal["text", "image"]]]` -#### Response + - `"text"` -```json -{ - "id": "thread_abc123", - "object": "thread", - "created_at": 1699014083, - "metadata": { - "modified": "true", - "user": "abc123" - }, - "tool_resources": {} -} -``` + - `"image"` -## Delete thread + - `search_context_size: Optional[Literal["low", "medium", "high"]]` -`beta.threads.delete(strthread_id) -> ThreadDeleted` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. -**delete** `/threads/{thread_id}` + - `"low"` -Delete thread + - `"medium"` -### Parameters + - `"high"` -- `thread_id: str` + - `user_location: Optional[UserLocation]` -### Returns + The user's location. -- `class ThreadDeleted: …` + - `type: Literal["approximate"]` - - `id: str` + The type of location approximation. Always `approximate`. - - `deleted: bool` + - `"approximate"` - - `object: Literal["thread.deleted"]` + - `city: Optional[str]` - - `"thread.deleted"` + Free text input for the city of the user, e.g. `San Francisco`. -### Example + - `country: Optional[str]` -```python -import os -from openai import OpenAI + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -thread_deleted = client.beta.threads.delete( - "thread_id", -) -print(thread_deleted.id) -``` + - `region: Optional[str]` -#### Response + Free text input for the region of the user, e.g. `California`. -```json -{ - "id": "id", - "deleted": true, - "object": "thread.deleted" -} -``` + - `timezone: Optional[str]` -### Example + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. -```python -from openai import OpenAI -client = OpenAI() + - `class BetaApplyPatchTool: …` -response = client.beta.threads.delete("thread_abc123") -print(response) -``` + Allows the assistant to create, delete, or update files using unified diffs. -#### Response + - `type: Literal["apply_patch"]` -```json -{ - "id": "thread_abc123", - "object": "thread.deleted", - "deleted": true -} -``` + The type of the tool. Always `apply_patch`. -## Domain Types + - `"apply_patch"` -### Assistant Response Format Option + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` -- `AssistantResponseFormatOption` + The tool invocation context(s). - 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`. + - `"direct"` - 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). + - `"programmatic"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `type: Literal["tool_search_output"]` - **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. + The item type. Always `tool_search_output`. - - `Literal["auto"]` + - `"tool_search_output"` - `auto` is the default value + - `id: Optional[str]` - - `"auto"` + The unique ID of this tool search output. - - `class ResponseFormatText: …` + - `agent: Optional[Agent]` - Default response format. Used to generate text responses. + The agent that produced this item. - - `type: Literal["text"]` + - `agent_name: str` - The type of response format being defined. Always `text`. + The canonical name of the agent that produced this item. - - `"text"` + - `call_id: Optional[str]` - - `class ResponseFormatJSONObject: …` + The unique ID of the tool search call generated by the model. - 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. + - `execution: Optional[Literal["server", "client"]]` - - `type: Literal["json_object"]` + Whether tool search was executed by the server or by the client. - The type of response format being defined. Always `json_object`. + - `"server"` - - `"json_object"` + - `"client"` - - `class ResponseFormatJSONSchema: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The status of the tool search output. - - `json_schema: JSONSchema` + - `"in_progress"` - Structured Outputs configuration options, including a JSON Schema. + - `"completed"` - - `name: str` + - `"incomplete"` - 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. + - `class AdditionalTools: …` - - `description: Optional[str]` + - `role: Literal["developer"]` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The role that provided the additional tools. Only `developer` is supported. - - `schema: Optional[Dict[str, object]]` + - `"developer"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `tools: List[BetaTool]` - - `strict: Optional[bool]` + A list of additional tools made available at this item. - 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). + - `class BetaFunctionTool: …` - - `type: Literal["json_schema"]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The type of response format being defined. Always `json_schema`. + - `class BetaFileSearchTool: …` - - `"json_schema"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). -### Assistant Tool Choice + - `class BetaComputerTool: …` -- `class AssistantToolChoice: …` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `class BetaComputerUsePreviewTool: …` - - `type: Literal["function", "code_interpreter", "file_search"]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the tool. If type is `function`, the function name must be set + - `class BetaWebSearchTool: …` - - `"function"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"code_interpreter"` + - `class Mcp: …` - - `"file_search"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `function: Optional[AssistantToolChoiceFunction]` + - `class CodeInterpreter: …` - - `name: str` + A tool that runs Python code to help generate a response to a prompt. - The name of the function to call. + - `class ProgrammaticToolCalling: …` -### Assistant Tool Choice Function + - `class ImageGeneration: …` -- `class AssistantToolChoiceFunction: …` + A tool that generates images using the GPT image models. - - `name: str` + - `class LocalShell: …` - The name of the function to call. + A tool that allows the model to execute shell commands in a local environment. -### Assistant Tool Choice Option + - `class BetaFunctionShellTool: …` -- `AssistantToolChoiceOption` + A tool that allows the model to execute shell commands. - 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. + - `class BetaCustomTool: …` - - `Literal["none", "auto", "required"]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `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. + - `class BetaNamespaceTool: …` - - `"none"` + Groups function/custom tools under a shared namespace. - - `"auto"` + - `class BetaToolSearchTool: …` - - `"required"` + Hosted or BYOT tool search configuration for deferred tools. - - `class AssistantToolChoice: …` + - `class BetaWebSearchPreviewTool: …` - Specifies a tool the model should use. Use to force the model to call a specific tool. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `type: Literal["function", "code_interpreter", "file_search"]` + - `class BetaApplyPatchTool: …` - The type of the tool. If type is `function`, the function name must be set + Allows the assistant to create, delete, or update files using unified diffs. - - `"function"` + - `type: Literal["additional_tools"]` - - `"code_interpreter"` + The item type. Always `additional_tools`. - - `"file_search"` + - `"additional_tools"` - - `function: Optional[AssistantToolChoiceFunction]` + - `id: Optional[str]` - - `name: str` + The unique ID of this additional tools item. - The name of the function to call. + - `agent: Optional[AdditionalToolsAgent]` -### Thread + The agent that produced this item. -- `class Thread: …` + - `agent_name: str` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + The canonical name of the agent that produced this item. + + - `class BetaResponseReasoningItem: …` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: str` - The identifier, which can be referenced in API endpoints. + The unique identifier of the reasoning content. - - `created_at: int` + - `summary: List[Summary]` - The Unix timestamp (in seconds) for when the thread was created. + Reasoning summary content. - - `metadata: Optional[Metadata]` + - `text: str` - 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. + A summary of the reasoning output from the model so far. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: Literal["summary_text"]` - - `object: Literal["thread"]` + The type of the object. Always `summary_text`. - The object type, which is always `thread`. + - `"summary_text"` - - `"thread"` + - `type: Literal["reasoning"]` - - `tool_resources: Optional[ToolResources]` + The type of the object. Always `reasoning`. - 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. + - `"reasoning"` - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` + - `agent: Optional[Agent]` - - `file_ids: Optional[List[str]]` + The agent that produced this item. - 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. + - `agent_name: str` - - `file_search: Optional[ToolResourcesFileSearch]` + The canonical name of the agent that produced this item. - - `vector_store_ids: Optional[List[str]]` + - `content: Optional[List[Content]]` - 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. + Reasoning text content. -### Thread Deleted + - `text: str` -- `class ThreadDeleted: …` + The reasoning text from the model. - - `id: str` + - `type: Literal["reasoning_text"]` - - `deleted: bool` + The type of the reasoning text. Always `reasoning_text`. - - `object: Literal["thread.deleted"]` + - `"reasoning_text"` - - `"thread.deleted"` + - `encrypted_content: Optional[str]` -# Runs + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. -## List runs + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` -`beta.threads.runs.list(strthread_id, RunListParams**kwargs) -> SyncCursorPage[Run]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -**get** `/threads/{thread_id}/runs` + - `"in_progress"` -List runs + - `"completed"` -### Parameters + - `"incomplete"` -- `thread_id: str` + - `class BetaResponseCompactionItemParam: …` -- `after: Optional[str]` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - 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. + - `encrypted_content: str` -- `before: Optional[str]` + The encrypted content of the compaction summary. - 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. + - `type: Literal["compaction"]` -- `limit: Optional[int]` + The type of the item. Always `compaction`. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `"compaction"` -- `order: Optional[Literal["asc", "desc"]]` + - `id: Optional[str]` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + The ID of the compaction item. - - `"asc"` + - `agent: Optional[Agent]` - - `"desc"` + The agent that produced this item. -### Returns + - `agent_name: str` -- `class Run: …` + The canonical name of the agent that produced this item. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class ImageGenerationCall: …` + + An image generation request made by the model. - `id: str` - The identifier, which can be referenced in API endpoints. + The unique ID of the image generation call. - - `assistant_id: str` + - `result: Optional[str]` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The generated image encoded in base64. - - `cancelled_at: Optional[int]` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - The Unix timestamp (in seconds) for when the run was cancelled. + The status of the image generation call. - - `completed_at: Optional[int]` + - `"in_progress"` - The Unix timestamp (in seconds) for when the run was completed. + - `"completed"` - - `created_at: int` + - `"generating"` - The Unix timestamp (in seconds) for when the run was created. + - `"failed"` - - `expires_at: Optional[int]` + - `type: Literal["image_generation_call"]` - The Unix timestamp (in seconds) for when the run will expire. + The type of the image generation call. Always `image_generation_call`. - - `failed_at: Optional[int]` + - `"image_generation_call"` - The Unix timestamp (in seconds) for when the run failed. + - `agent: Optional[ImageGenerationCallAgent]` - - `incomplete_details: Optional[IncompleteDetails]` + The agent that produced this item. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `agent_name: str` - - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` + The canonical name of the agent that produced this item. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `class BetaResponseCodeInterpreterToolCall: …` - - `"max_completion_tokens"` + A tool call to run code. - - `"max_prompt_tokens"` + - `id: str` - - `instructions: str` + The unique ID of the code interpreter tool call. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `code: Optional[str]` - - `last_error: Optional[LastError]` + The code to run, or null if not available. - The last error associated with this run. Will be `null` if there are no errors. + - `container_id: str` - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` + The ID of the container used to run the code. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `outputs: Optional[List[Output]]` - - `"server_error"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"rate_limit_exceeded"` + - `class OutputLogs: …` - - `"invalid_prompt"` + The logs output from the code interpreter. - - `message: str` + - `logs: str` - A human-readable description of the error. + The logs output from the code interpreter. - - `max_completion_tokens: Optional[int]` + - `type: Literal["logs"]` - The maximum number of completion tokens specified to have been used over the course of the run. + The type of the output. Always `logs`. - - `max_prompt_tokens: Optional[int]` + - `"logs"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `class OutputImage: …` - - `metadata: Optional[Metadata]` + The image output from the code interpreter. - 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. + - `type: Literal["image"]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The type of the output. Always `image`. - - `model: str` + - `"image"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `url: str` - - `object: Literal["thread.run"]` + The URL of the image output from the code interpreter. - The object type, which is always `thread.run`. + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - - `"thread.run"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `parallel_tool_calls: bool` + - `"in_progress"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `"completed"` - - `required_action: Optional[RequiredAction]` + - `"incomplete"` - Details on the action required to continue the run. Will be `null` if no action is required. + - `"interpreting"` - - `submit_tool_outputs: RequiredActionSubmitToolOutputs` + - `"failed"` - Details on the tool outputs needed for this run to continue. + - `type: Literal["code_interpreter_call"]` - - `tool_calls: List[RequiredActionFunctionToolCall]` + The type of the code interpreter tool call. Always `code_interpreter_call`. - A list of the relevant tool calls. + - `"code_interpreter_call"` - - `id: str` + - `agent: Optional[Agent]` - 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. + The agent that produced this item. - - `function: Function` + - `agent_name: str` - The function definition. + The canonical name of the agent that produced this item. - - `arguments: str` + - `class LocalShellCall: …` - The arguments that the model expects you to pass to the function. + A tool call to run a command on the local shell. - - `name: str` + - `id: str` - The name of the function. + The unique ID of the local shell call. - - `type: Literal["function"]` + - `action: LocalShellCallAction` - The type of tool call the output is required for. For now, this is always `function`. + Execute a shell command on the server. - - `"function"` + - `command: List[str]` - - `type: Literal["submit_tool_outputs"]` + The command to run. - For now, this is always `submit_tool_outputs`. + - `env: Dict[str, str]` - - `"submit_tool_outputs"` + Environment variables to set for the command. - - `response_format: Optional[AssistantResponseFormatOption]` + - `type: Literal["exec"]` - 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`. + The type of the local shell action. Always `exec`. - 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). + - `"exec"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `timeout_ms: Optional[int]` - **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. + Optional timeout in milliseconds for the command. - - `Literal["auto"]` + - `user: Optional[str]` - `auto` is the default value + Optional user to run the command as. - - `"auto"` + - `working_directory: Optional[str]` - - `class ResponseFormatText: …` + Optional working directory to run the command in. - Default response format. Used to generate text responses. + - `call_id: str` - - `type: Literal["text"]` + The unique ID of the local shell tool call generated by the model. - The type of response format being defined. Always `text`. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"text"` + The status of the local shell call. - - `class ResponseFormatJSONObject: …` + - `"in_progress"` - 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. + - `"completed"` - - `type: Literal["json_object"]` + - `"incomplete"` - The type of response format being defined. Always `json_object`. + - `type: Literal["local_shell_call"]` - - `"json_object"` + The type of the local shell call. Always `local_shell_call`. - - `class ResponseFormatJSONSchema: …` + - `"local_shell_call"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `agent: Optional[LocalShellCallAgent]` - - `json_schema: JSONSchema` + The agent that produced this item. - Structured Outputs configuration options, including a JSON Schema. + - `agent_name: str` - - `name: str` + The canonical name of the agent that produced this item. - 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. + - `class LocalShellCallOutput: …` - - `description: Optional[str]` + The output of a local shell tool call. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `id: str` - - `schema: Optional[Dict[str, object]]` + The unique ID of the local shell tool call generated by the model. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `output: str` - - `strict: Optional[bool]` + A JSON string of the output of the local shell tool call. - 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["local_shell_call_output"]` - - `type: Literal["json_schema"]` + The type of the local shell tool call output. Always `local_shell_call_output`. - The type of response format being defined. Always `json_schema`. + - `"local_shell_call_output"` - - `"json_schema"` + - `agent: Optional[LocalShellCallOutputAgent]` - - `started_at: Optional[int]` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run was started. + - `agent_name: str` - - `status: object` + The canonical name of the agent that produced this item. - - `thread_id: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `tool_choice: Optional[AssistantToolChoiceOption]` + - `"in_progress"` - 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. + - `"completed"` - - `Literal["none", "auto", "required"]` + - `"incomplete"` - `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. + - `class ShellCall: …` - - `"none"` + A tool representing a request to execute one or more shell commands. - - `"auto"` + - `action: ShellCallAction` - - `"required"` + The shell commands and limits that describe how to run the tool call. - - `class AssistantToolChoice: …` + - `commands: List[str]` - Specifies a tool the model should use. Use to force the model to call a specific tool. + Ordered shell commands for the execution environment to run. - - `type: Literal["function", "code_interpreter", "file_search"]` + - `max_output_length: Optional[int]` - The type of the tool. If type is `function`, the function name must be set + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `"function"` + - `timeout_ms: Optional[int]` - - `"code_interpreter"` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `"file_search"` + - `call_id: str` - - `function: Optional[AssistantToolChoiceFunction]` + The unique ID of the shell tool call generated by the model. - - `name: str` + - `type: Literal["shell_call"]` - The name of the function to call. + The type of the item. Always `shell_call`. - - `tools: List[object]` + - `"shell_call"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `id: Optional[str]` - - `truncation_strategy: Optional[TruncationStrategy]` + The unique ID of the shell tool call. Populated when this item is returned via API. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `agent: Optional[ShellCallAgent]` - - `type: Literal["auto", "last_messages"]` + The agent that produced this item. - 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`. + - `agent_name: str` - - `"auto"` + The canonical name of the agent that produced this item. - - `"last_messages"` + - `caller: Optional[ShellCallCaller]` - - `last_messages: Optional[int]` + The execution context that produced this tool call. - The number of most recent messages from the thread when constructing the context for the run. + - `class ShellCallCallerDirect: …` - - `usage: Optional[Usage]` + - `type: Literal["direct"]` - 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.). + The caller type. Always `direct`. - - `completion_tokens: int` + - `"direct"` - Number of completion tokens used over the course of the run. + - `class ShellCallCallerProgram: …` - - `prompt_tokens: int` + - `caller_id: str` - Number of prompt tokens used over the course of the run. + The call ID of the program item that produced this tool call. - - `total_tokens: int` + - `type: Literal["program"]` - Total number of tokens used (prompt + completion). + The caller type. Always `program`. - - `temperature: Optional[float]` + - `"program"` - The sampling temperature used for this run. If not set, defaults to 1. + - `environment: Optional[ShellCallEnvironment]` - - `top_p: Optional[float]` + The environment to execute the shell commands in. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `class BetaLocalEnvironment: …` -### Example + - `class BetaContainerReference: …` -```python -import os -from openai import OpenAI + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -page = client.beta.threads.runs.list( - thread_id="thread_id", -) -page = page.data[0] -print(page.id) -``` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. -#### Response + - `"in_progress"` -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 - } - ], - "first_id": "run_abc123", - "has_more": false, - "last_id": "run_abc456", - "object": "list" -} -``` + - `"completed"` -### Example + - `"incomplete"` -```python -from openai import OpenAI -client = OpenAI() + - `class ShellCallOutput: …` -runs = client.beta.threads.runs.list( - "thread_abc123" -) + The streamed output items emitted by a shell tool call. -print(runs) -``` + - `call_id: str` -#### Response + The unique ID of the shell tool call generated by the model. -```json -{ - "object": "list", - "data": [ - { - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699075072, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699075072, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699075073, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "file-abc123", - "file-abc456" - ] - } - }, - "metadata": {}, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true - }, - { - "id": "run_abc456", - "object": "thread.run", - "created_at": 1699063290, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699063290, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699063291, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "file-abc123", - "file-abc456" - ] - } - }, - "metadata": {}, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true - } - ], - "first_id": "run_abc123", - "last_id": "run_abc456", - "has_more": false -} -``` + - `output: List[BetaResponseFunctionShellCallOutputContent]` -## Create run + Captured chunks of stdout and stderr output, along with their associated outcomes. -`beta.threads.runs.create(strthread_id, RunCreateParams**kwargs) -> Run` + - `outcome: Outcome` -**post** `/threads/{thread_id}/runs` + The exit or timeout outcome associated with this shell call. -Create run + - `class OutcomeTimeout: …` -### Parameters + Indicates that the shell call exceeded its configured time limit. -- `thread_id: str` + - `type: Literal["timeout"]` -- `assistant_id: str` + The outcome type. Always `timeout`. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. + - `"timeout"` -- `include: Optional[List[RunStepInclude]]` + - `class OutcomeExit: …` - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + Indicates that the shell commands finished and returned an exit code. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `exit_code: int` - - `"step_details.tool_calls[*].file_search.results[*].content"` + The exit code returned by the shell process. -- `additional_instructions: Optional[str]` + - `type: Literal["exit"]` - Appends additional instructions at the end of the instructions for the run. This is useful for modifying the behavior on a per-run basis without overriding other instructions. + The outcome type. Always `exit`. -- `additional_messages: Optional[Iterable[AdditionalMessage]]` + - `"exit"` - Adds additional messages to the thread before creating the run. + - `stderr: str` - - `content: Union[str, Iterable[MessageContentPartParam]]` + Captured stderr output for the shell call. - The text contents of the message. + - `stdout: str` - - `str` + Captured stdout output for the shell call. - The text contents of the message. + - `type: Literal["shell_call_output"]` - - `Iterable[MessageContentPartParam]` + The type of the item. Always `shell_call_output`. - An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](https://platform.openai.com/docs/models). + - `"shell_call_output"` - - `class ImageFileContentBlock: …` + - `id: Optional[str]` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `image_file: ImageFileParam` + - `agent: Optional[ShellCallOutputAgent]` - - `file_id: str` + The agent that produced this item. - 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. + - `agent_name: str` - - `detail: Optional[Literal["auto", "low", "high"]]` + The canonical name of the agent that produced this item. - 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`. + - `caller: Optional[ShellCallOutputCaller]` - - `"auto"` + The execution context that produced this tool call. - - `"low"` + - `class ShellCallOutputCallerDirect: …` - - `"high"` + - `type: Literal["direct"]` - - `type: Literal["image_file"]` + The caller type. Always `direct`. - Always `image_file`. + - `"direct"` - - `"image_file"` + - `class ShellCallOutputCallerProgram: …` - - `class ImageURLContentBlock: …` + - `caller_id: str` - References an image URL in the content of a message. + The call ID of the program item that produced this tool call. - - `image_url: ImageURLParam` + - `type: Literal["program"]` - - `url: str` + The caller type. Always `program`. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"program"` - - `detail: Optional[Literal["auto", "low", "high"]]` + - `max_output_length: Optional[int]` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `"auto"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"low"` + The status of the shell call output. - - `"high"` + - `"in_progress"` - - `type: Literal["image_url"]` + - `"completed"` - The type of the content part. + - `"incomplete"` - - `"image_url"` + - `class ApplyPatchCall: …` - - `class TextContentBlockParam: …` + A tool call representing a request to create, delete, or update files using diff patches. - The text content that is part of a message. + - `call_id: str` - - `text: str` + The unique ID of the apply patch tool call generated by the model. - Text content to be sent to the model + - `operation: ApplyPatchCallOperation` - - `type: Literal["text"]` + The specific create, delete, or update instruction for the apply_patch tool call. - Always `text`. + - `class ApplyPatchCallOperationCreateFile: …` - - `"text"` + Instruction for creating a new file via the apply_patch tool. - - `role: Literal["user", "assistant"]` + - `diff: str` - The role of the entity that is creating the message. Allowed values include: + Unified diff content to apply when creating the file. - - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + - `path: str` - - `"user"` + Path of the file to create relative to the workspace root. - - `"assistant"` + - `type: Literal["create_file"]` - - `attachments: Optional[Iterable[AdditionalMessageAttachment]]` + The operation type. Always `create_file`. - A list of files attached to the message, and the tools they should be added to. + - `"create_file"` - - `file_id: Optional[str]` + - `class ApplyPatchCallOperationDeleteFile: …` - The ID of the file to attach to the message. + Instruction for deleting an existing file via the apply_patch tool. - - `tools: Optional[Iterable[AdditionalMessageAttachmentTool]]` + - `path: str` - The tools to add this file to. + Path of the file to delete relative to the workspace root. - - `class CodeInterpreterTool: …` + - `type: Literal["delete_file"]` - - `type: Literal["code_interpreter"]` + The operation type. Always `delete_file`. - The type of tool being defined: `code_interpreter` + - `"delete_file"` - - `"code_interpreter"` + - `class ApplyPatchCallOperationUpdateFile: …` - - `class AdditionalMessageAttachmentToolFileSearch: …` + Instruction for updating an existing file via the apply_patch tool. - - `type: Literal["file_search"]` + - `diff: str` - The type of tool being defined: `file_search` + Unified diff content to apply to the existing file. - - `"file_search"` + - `path: str` - - `metadata: Optional[Metadata]` + Path of the file to update relative to the workspace root. - 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. + - `type: Literal["update_file"]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The operation type. Always `update_file`. -- `instructions: Optional[str]` + - `"update_file"` - Overrides the [instructions](https://platform.openai.com/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis. + - `status: Literal["in_progress", "completed"]` -- `max_completion_tokens: Optional[int]` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + - `"in_progress"` -- `max_prompt_tokens: Optional[int]` + - `"completed"` - The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + - `type: Literal["apply_patch_call"]` -- `metadata: Optional[Metadata]` + The type of the item. Always `apply_patch_call`. - 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. + - `"apply_patch_call"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `id: Optional[str]` -- `model: Optional[Union[str, ChatModel, null]]` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The ID of the [Model](https://platform.openai.com/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. + - `agent: Optional[ApplyPatchCallAgent]` - - `str` + The agent that produced this item. - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 78 more]` + - `agent_name: str` - - `"gpt-5.6-sol"` + The canonical name of the agent that produced this item. - - `"gpt-5.6-terra"` + - `caller: Optional[ApplyPatchCallCaller]` - - `"gpt-5.6-luna"` + The execution context that produced this tool call. - - `"gpt-5.4"` + - `class ApplyPatchCallCallerDirect: …` - - `"gpt-5.4-mini"` + - `type: Literal["direct"]` - - `"gpt-5.4-nano"` + The caller type. Always `direct`. - - `"gpt-5.4-mini-2026-03-17"` + - `"direct"` - - `"gpt-5.4-nano-2026-03-17"` + - `class ApplyPatchCallCallerProgram: …` - - `"gpt-5.3-chat-latest"` + - `caller_id: str` - - `"gpt-5.2"` + The call ID of the program item that produced this tool call. - - `"gpt-5.2-2025-12-11"` + - `type: Literal["program"]` - - `"gpt-5.2-chat-latest"` + The caller type. Always `program`. - - `"gpt-5.2-pro"` + - `"program"` - - `"gpt-5.2-pro-2025-12-11"` + - `class ApplyPatchCallOutput: …` - - `"gpt-5.1"` + The streamed output emitted by an apply patch tool call. - - `"gpt-5.1-2025-11-13"` + - `call_id: str` - - `"gpt-5.1-codex"` + The unique ID of the apply patch tool call generated by the model. - - `"gpt-5.1-mini"` + - `status: Literal["completed", "failed"]` - - `"gpt-5.1-chat-latest"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"gpt-5"` + - `"completed"` - - `"gpt-5-mini"` + - `"failed"` - - `"gpt-5-nano"` + - `type: Literal["apply_patch_call_output"]` - - `"gpt-5-2025-08-07"` + The type of the item. Always `apply_patch_call_output`. - - `"gpt-5-mini-2025-08-07"` + - `"apply_patch_call_output"` - - `"gpt-5-nano-2025-08-07"` + - `id: Optional[str]` - - `"gpt-5-chat-latest"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"gpt-4.1"` + - `agent: Optional[ApplyPatchCallOutputAgent]` - - `"gpt-4.1-mini"` + The agent that produced this item. - - `"gpt-4.1-nano"` + - `agent_name: str` - - `"gpt-4.1-2025-04-14"` + The canonical name of the agent that produced this item. - - `"gpt-4.1-mini-2025-04-14"` + - `caller: Optional[ApplyPatchCallOutputCaller]` - - `"gpt-4.1-nano-2025-04-14"` + The execution context that produced this tool call. - - `"o4-mini"` + - `class ApplyPatchCallOutputCallerDirect: …` - - `"o4-mini-2025-04-16"` + - `type: Literal["direct"]` - - `"o3"` + The caller type. Always `direct`. - - `"o3-2025-04-16"` + - `"direct"` - - `"o3-mini"` + - `class ApplyPatchCallOutputCallerProgram: …` - - `"o3-mini-2025-01-31"` + - `caller_id: str` - - `"o1"` + The call ID of the program item that produced this tool call. - - `"o1-2024-12-17"` + - `type: Literal["program"]` - - `"o1-preview"` + The caller type. Always `program`. - - `"o1-preview-2024-09-12"` + - `"program"` - - `"o1-mini"` + - `output: Optional[str]` - - `"o1-mini-2024-09-12"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `"gpt-4o"` + - `class McpListTools: …` - - `"gpt-4o-2024-11-20"` + A list of tools available on an MCP server. - - `"gpt-4o-2024-08-06"` + - `id: str` - - `"gpt-4o-2024-05-13"` + The unique ID of the list. - - `"gpt-4o-audio-preview"` + - `server_label: str` - - `"gpt-4o-audio-preview-2024-10-01"` + The label of the MCP server. - - `"gpt-4o-audio-preview-2024-12-17"` + - `tools: List[McpListToolsTool]` - - `"gpt-4o-audio-preview-2025-06-03"` + The tools available on the server. - - `"gpt-4o-mini-audio-preview"` + - `input_schema: object` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The JSON schema describing the tool's input. - - `"gpt-4o-search-preview"` + - `name: str` - - `"gpt-4o-mini-search-preview"` + The name of the tool. - - `"gpt-4o-search-preview-2025-03-11"` + - `annotations: Optional[object]` - - `"gpt-4o-mini-search-preview-2025-03-11"` + Additional annotations about the tool. - - `"chatgpt-4o-latest"` + - `description: Optional[str]` - - `"codex-mini-latest"` + The description of the tool. - - `"gpt-4o-mini"` + - `type: Literal["mcp_list_tools"]` - - `"gpt-4o-mini-2024-07-18"` + The type of the item. Always `mcp_list_tools`. - - `"gpt-4-turbo"` + - `"mcp_list_tools"` - - `"gpt-4-turbo-2024-04-09"` + - `agent: Optional[McpListToolsAgent]` - - `"gpt-4-0125-preview"` + The agent that produced this item. - - `"gpt-4-turbo-preview"` + - `agent_name: str` - - `"gpt-4-1106-preview"` + The canonical name of the agent that produced this item. - - `"gpt-4-vision-preview"` + - `error: Optional[str]` - - `"gpt-4"` + Error message if the server could not list tools. - - `"gpt-4-0314"` + - `class McpApprovalRequest: …` - - `"gpt-4-0613"` + A request for human approval of a tool invocation. - - `"gpt-4-32k"` + - `id: str` - - `"gpt-4-32k-0314"` + The unique ID of the approval request. - - `"gpt-4-32k-0613"` + - `arguments: str` - - `"gpt-3.5-turbo"` + A JSON string of arguments for the tool. - - `"gpt-3.5-turbo-16k"` + - `name: str` - - `"gpt-3.5-turbo-0301"` + The name of the tool to run. - - `"gpt-3.5-turbo-0613"` + - `server_label: str` - - `"gpt-3.5-turbo-1106"` + The label of the MCP server making the request. - - `"gpt-3.5-turbo-0125"` + - `type: Literal["mcp_approval_request"]` - - `"gpt-3.5-turbo-16k-0613"` + The type of the item. Always `mcp_approval_request`. -- `parallel_tool_calls: Optional[bool]` + - `"mcp_approval_request"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `agent: Optional[McpApprovalRequestAgent]` -- `reasoning_effort: Optional[ReasoningEffort]` + The agent that produced this item. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `agent_name: str` - - `"none"` + The canonical name of the agent that produced this item. - - `"minimal"` + - `class McpApprovalResponse: …` - - `"low"` + A response to an MCP approval request. - - `"medium"` + - `approval_request_id: str` - - `"high"` + The ID of the approval request being answered. - - `"xhigh"` + - `approve: bool` - - `"max"` + Whether the request was approved. -- `response_format: Optional[AssistantResponseFormatOptionParam]` + - `type: Literal["mcp_approval_response"]` - 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`. + The type of the item. Always `mcp_approval_response`. - 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). + - `"mcp_approval_response"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `id: Optional[str]` - **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. + The unique ID of the approval response - - `Literal["auto"]` + - `agent: Optional[McpApprovalResponseAgent]` - `auto` is the default value + The agent that produced this item. - - `"auto"` + - `agent_name: str` - - `class ResponseFormatText: …` + The canonical name of the agent that produced this item. - Default response format. Used to generate text responses. + - `reason: Optional[str]` - - `type: Literal["text"]` + Optional reason for the decision. - The type of response format being defined. Always `text`. + - `class McpCall: …` - - `"text"` + An invocation of a tool on an MCP server. - - `class ResponseFormatJSONObject: …` + - `id: str` - 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. + The unique ID of the tool call. - - `type: Literal["json_object"]` + - `arguments: str` - The type of response format being defined. Always `json_object`. + A JSON string of the arguments passed to the tool. - - `"json_object"` + - `name: str` - - `class ResponseFormatJSONSchema: …` + The name of the tool that was run. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `server_label: str` - - `json_schema: JSONSchema` + The label of the MCP server running the tool. - Structured Outputs configuration options, including a JSON Schema. + - `type: Literal["mcp_call"]` - - `name: str` + The type of the item. Always `mcp_call`. - 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. + - `"mcp_call"` - - `description: Optional[str]` + - `agent: Optional[McpCallAgent]` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The agent that produced this item. - - `schema: Optional[Dict[str, object]]` + - `agent_name: str` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The canonical name of the agent that produced this item. - - `strict: Optional[bool]` + - `approval_request_id: Optional[str]` - 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). + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `type: Literal["json_schema"]` + - `error: Optional[str]` - The type of response format being defined. Always `json_schema`. + The error from the tool call, if any. - - `"json_schema"` + - `output: Optional[str]` -- `stream: Optional[Literal[false]]` + The output from the tool call. - If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - `false` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. -- `temperature: Optional[float]` + - `"in_progress"` - 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. + - `"completed"` -- `tool_choice: Optional[AssistantToolChoiceOptionParam]` + - `"incomplete"` - 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. + - `"calling"` - - `Literal["none", "auto", "required"]` + - `"failed"` - `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. + - `class BetaResponseCustomToolCallOutput: …` - - `"none"` + The output of a custom tool call from your code, being sent back to the model. - - `"auto"` + - `call_id: str` - - `"required"` + The call ID, used to map this custom tool call output to a custom tool call. - - `class AssistantToolChoice: …` + - `output: Union[str, List[OutputOutputContentList]]` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `type: Literal["function", "code_interpreter", "file_search"]` + - `str` - The type of the tool. If type is `function`, the function name must be set + A string of the output of the custom tool call. - - `"function"` + - `List[OutputOutputContentList]` - - `"code_interpreter"` + Text, image, or file output of the custom tool call. - - `"file_search"` + - `class BetaResponseInputText: …` - - `function: Optional[AssistantToolChoiceFunction]` + A text input to the model. - - `name: str` + - `class BetaResponseInputImage: …` - The name of the function to call. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). -- `tools: Optional[Iterable[object]]` + - `class BetaResponseInputFile: …` - Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + A file input to the model. -- `top_p: Optional[float]` + - `type: Literal["custom_tool_call_output"]` - 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. + The type of the custom tool call output. Always `custom_tool_call_output`. - We generally recommend altering this or temperature but not both. + - `"custom_tool_call_output"` -- `truncation_strategy: Optional[TruncationStrategy]` + - `id: Optional[str]` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The unique ID of the custom tool call output in the OpenAI platform. - - `type: Literal["auto", "last_messages"]` + - `agent: Optional[Agent]` - 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`. + The agent that produced this item. - - `"auto"` + - `agent_name: str` - - `"last_messages"` + The canonical name of the agent that produced this item. - - `last_messages: Optional[int]` + - `caller: Optional[Caller]` - The number of most recent messages from the thread when constructing the context for the run. + The execution context that produced this tool call. -### Returns + - `class CallerDirect: …` -- `class Run: …` + - `type: Literal["direct"]` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The caller type. Always `direct`. - - `id: str` + - `"direct"` - The identifier, which can be referenced in API endpoints. + - `class CallerProgram: …` - - `assistant_id: str` + - `caller_id: str` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The call ID of the program item that produced this tool call. - - `cancelled_at: Optional[int]` + - `type: Literal["program"]` - The Unix timestamp (in seconds) for when the run was cancelled. + The caller type. Always `program`. - - `completed_at: Optional[int]` + - `"program"` - The Unix timestamp (in seconds) for when the run was completed. + - `class BetaResponseCustomToolCall: …` - - `created_at: int` + A call to a custom tool created by the model. - The Unix timestamp (in seconds) for when the run was created. + - `call_id: str` - - `expires_at: Optional[int]` + An identifier used to map this custom tool call to a tool call output. - The Unix timestamp (in seconds) for when the run will expire. + - `input: str` - - `failed_at: Optional[int]` + The input for the custom tool call generated by the model. - The Unix timestamp (in seconds) for when the run failed. + - `name: str` - - `incomplete_details: Optional[IncompleteDetails]` + The name of the custom tool being called. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `type: Literal["custom_tool_call"]` - - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` + The type of the custom tool call. Always `custom_tool_call`. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `"custom_tool_call"` - - `"max_completion_tokens"` + - `id: Optional[str]` - - `"max_prompt_tokens"` + The unique ID of the custom tool call in the OpenAI platform. - - `instructions: str` + - `agent: Optional[Agent]` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The agent that produced this item. - - `last_error: Optional[LastError]` + - `agent_name: str` - The last error associated with this run. Will be `null` if there are no errors. + The canonical name of the agent that produced this item. - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` + - `caller: Optional[Caller]` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The execution context that produced this tool call. - - `"server_error"` + - `class CallerDirect: …` - - `"rate_limit_exceeded"` + - `type: Literal["direct"]` - - `"invalid_prompt"` + - `"direct"` - - `message: str` + - `class CallerProgram: …` - A human-readable description of the error. + - `caller_id: str` - - `max_completion_tokens: Optional[int]` + The call ID of the program item that produced this tool call. - The maximum number of completion tokens specified to have been used over the course of the run. + - `type: Literal["program"]` - - `max_prompt_tokens: Optional[int]` + - `"program"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `namespace: Optional[str]` - - `metadata: Optional[Metadata]` + The namespace of the custom tool being called. - 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. + - `class CompactionTrigger: …` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Compacts the current context. Must be the final input item. - - `model: str` + - `type: Literal["compaction_trigger"]` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The type of the item. Always `compaction_trigger`. - - `object: Literal["thread.run"]` + - `"compaction_trigger"` - The object type, which is always `thread.run`. + - `agent: Optional[CompactionTriggerAgent]` - - `"thread.run"` + The agent that produced this item. - - `parallel_tool_calls: bool` + - `agent_name: str` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The canonical name of the agent that produced this item. - - `required_action: Optional[RequiredAction]` + - `class ItemReference: …` - Details on the action required to continue the run. Will be `null` if no action is required. + An internal identifier for an item to reference. - - `submit_tool_outputs: RequiredActionSubmitToolOutputs` + - `id: str` - Details on the tool outputs needed for this run to continue. + The ID of the item to reference. - - `tool_calls: List[RequiredActionFunctionToolCall]` + - `agent: Optional[ItemReferenceAgent]` - A list of the relevant tool calls. + The agent that produced this item. - - `id: str` + - `agent_name: 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. + The canonical name of the agent that produced this item. - - `function: Function` + - `type: Optional[Literal["item_reference"]]` - The function definition. + The type of item to reference. Always `item_reference`. - - `arguments: str` + - `"item_reference"` - The arguments that the model expects you to pass to the function. + - `class Program: …` - - `name: str` + - `id: str` - The name of the function. + The unique ID of this program item. - - `type: Literal["function"]` + - `call_id: str` - The type of tool call the output is required for. For now, this is always `function`. + The stable call ID of the program item. - - `"function"` + - `code: str` - - `type: Literal["submit_tool_outputs"]` + The JavaScript source executed by programmatic tool calling. - For now, this is always `submit_tool_outputs`. + - `fingerprint: str` - - `"submit_tool_outputs"` + Opaque program replay fingerprint that must be round-tripped. - - `response_format: Optional[AssistantResponseFormatOption]` + - `type: Literal["program"]` - 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`. + The item type. Always `program`. - 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). + - `"program"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `agent: Optional[ProgramAgent]` - **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. + The agent that produced this item. - - `Literal["auto"]` + - `agent_name: str` - `auto` is the default value + The canonical name of the agent that produced this item. - - `"auto"` + - `class ProgramOutput: …` - - `class ResponseFormatText: …` + - `id: str` - Default response format. Used to generate text responses. + The unique ID of this program output item. - - `type: Literal["text"]` + - `call_id: str` - The type of response format being defined. Always `text`. + The call ID of the program item. - - `"text"` + - `result: str` - - `class ResponseFormatJSONObject: …` + The result produced by the program item. - 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. + - `status: Literal["completed", "incomplete"]` - - `type: Literal["json_object"]` + The terminal status of the program output. - The type of response format being defined. Always `json_object`. + - `"completed"` - - `"json_object"` + - `"incomplete"` - - `class ResponseFormatJSONSchema: …` + - `type: Literal["program_output"]` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The item type. Always `program_output`. - - `json_schema: JSONSchema` + - `"program_output"` - Structured Outputs configuration options, including a JSON Schema. + - `agent: Optional[ProgramOutputAgent]` - - `name: str` + The agent that produced this item. - 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. + - `agent_name: str` - - `description: Optional[str]` + The canonical name of the agent that produced this item. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `metadata: Optional[Dict[str, str]]` - - `schema: Optional[Dict[str, object]]` + 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. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `strict: Optional[bool]` + - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` - 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). + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `type: Literal["json_schema"]` + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` - The type of response format being defined. Always `json_schema`. + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `"json_schema"` + - `"gpt-5.6-sol"` - - `started_at: Optional[int]` + - `"gpt-5.6-terra"` - The Unix timestamp (in seconds) for when the run was started. + - `"gpt-5.6-luna"` - - `status: object` + - `"gpt-5.4"` - - `thread_id: str` + - `"gpt-5.4-mini"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `"gpt-5.4-nano"` - - `tool_choice: Optional[AssistantToolChoiceOption]` + - `"gpt-5.4-mini-2026-03-17"` - 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. + - `"gpt-5.4-nano-2026-03-17"` - - `Literal["none", "auto", "required"]` + - `"gpt-5.3-chat-latest"` - `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. + - `"gpt-5.2"` - - `"none"` + - `"gpt-5.2-2025-12-11"` - - `"auto"` + - `"gpt-5.2-chat-latest"` - - `"required"` + - `"gpt-5.2-pro"` - - `class AssistantToolChoice: …` + - `"gpt-5.2-pro-2025-12-11"` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `"gpt-5.1"` - - `type: Literal["function", "code_interpreter", "file_search"]` + - `"gpt-5.1-2025-11-13"` - The type of the tool. If type is `function`, the function name must be set + - `"gpt-5.1-codex"` - - `"function"` + - `"gpt-5.1-mini"` - - `"code_interpreter"` + - `"gpt-5.1-chat-latest"` - - `"file_search"` + - `"gpt-5"` - - `function: Optional[AssistantToolChoiceFunction]` + - `"gpt-5-mini"` - - `name: str` + - `"gpt-5-nano"` - The name of the function to call. + - `"gpt-5-2025-08-07"` - - `tools: List[object]` + - `"gpt-5-mini-2025-08-07"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"gpt-5-nano-2025-08-07"` - - `truncation_strategy: Optional[TruncationStrategy]` + - `"gpt-5-chat-latest"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"gpt-4.1"` - - `type: Literal["auto", "last_messages"]` + - `"gpt-4.1-mini"` - 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`. + - `"gpt-4.1-nano"` - - `"auto"` + - `"gpt-4.1-2025-04-14"` - - `"last_messages"` + - `"gpt-4.1-mini-2025-04-14"` - - `last_messages: Optional[int]` + - `"gpt-4.1-nano-2025-04-14"` - The number of most recent messages from the thread when constructing the context for the run. + - `"o4-mini"` - - `usage: Optional[Usage]` + - `"o4-mini-2025-04-16"` - 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.). + - `"o3"` - - `completion_tokens: int` + - `"o3-2025-04-16"` - Number of completion tokens used over the course of the run. + - `"o3-mini"` - - `prompt_tokens: int` + - `"o3-mini-2025-01-31"` - Number of prompt tokens used over the course of the run. + - `"o1"` - - `total_tokens: int` + - `"o1-2024-12-17"` - Total number of tokens used (prompt + completion). + - `"o1-preview"` - - `temperature: Optional[float]` + - `"o1-preview-2024-09-12"` - The sampling temperature used for this run. If not set, defaults to 1. + - `"o1-mini"` - - `top_p: Optional[float]` + - `"o1-mini-2024-09-12"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"gpt-4o"` -### Example + - `"gpt-4o-2024-11-20"` -```python -import os -from openai import OpenAI + - `"gpt-4o-2024-08-06"` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -for run in client.beta.threads.runs.create( - thread_id="thread_id", - assistant_id="assistant_id", -): - print(run) -``` + - `"gpt-4o-2024-05-13"` -#### Response + - `"gpt-4o-audio-preview"` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `"gpt-4o-audio-preview-2024-10-01"` -### Example + - `"gpt-4o-audio-preview-2024-12-17"` -```python -from openai import OpenAI -client = OpenAI() + - `"gpt-4o-audio-preview-2025-06-03"` -run = client.beta.threads.runs.create( - thread_id="thread_abc123", - assistant_id="asst_abc123" -) + - `"gpt-4o-mini-audio-preview"` -print(run) -``` + - `"gpt-4o-mini-audio-preview-2024-12-17"` -#### Response + - `"gpt-4o-search-preview"` -```json -{ - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699063290, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "queued", - "started_at": 1699063290, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699063291, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "metadata": {}, - "usage": null, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` + - `"gpt-4o-mini-search-preview"` -### Streaming + - `"gpt-4o-search-preview-2025-03-11"` -```python -from openai import OpenAI -client = OpenAI() + - `"gpt-4o-mini-search-preview-2025-03-11"` -stream = client.beta.threads.runs.create( - thread_id="thread_123", - assistant_id="asst_123", - stream=True -) + - `"chatgpt-4o-latest"` -for event in stream: - print(event) -``` + - `"codex-mini-latest"` -#### Response + - `"gpt-4o-mini"` -```json -event: thread.run.created -data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `"gpt-4o-mini-2024-07-18"` -event: thread.run.queued -data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `"gpt-4-turbo"` -event: thread.run.in_progress -data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710330641,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `"gpt-4-turbo-2024-04-09"` -event: thread.run.step.created -data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + - `"gpt-4-0125-preview"` -event: thread.run.step.in_progress -data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + - `"gpt-4-turbo-preview"` -event: thread.message.created -data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `"gpt-4-1106-preview"` -event: thread.message.in_progress -data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `"gpt-4-vision-preview"` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + - `"gpt-4"` -... + - `"gpt-4-0314"` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + - `"gpt-4-0613"` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + - `"gpt-4-32k"` -event: thread.message.completed -data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710330642,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} + - `"gpt-4-32k-0314"` -event: thread.run.step.completed -data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710330642,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + - `"gpt-4-32k-0613"` -event: thread.run.completed -data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710330641,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710330642,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `"gpt-3.5-turbo"` -event: done -data: [DONE] -``` + - `"gpt-3.5-turbo-16k"` -### Streaming with Functions + - `"gpt-3.5-turbo-0301"` -```python -from openai import OpenAI -client = OpenAI() + - `"gpt-3.5-turbo-0613"` -tools = [ - { - "type": "function", - "function": { - "name": "get_current_weather", - "description": "Get the current weather in a given location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA", - }, - "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, - }, - "required": ["location"], - }, - } - } -] + - `"gpt-3.5-turbo-1106"` -stream = client.beta.threads.runs.create( - thread_id="thread_abc123", - assistant_id="asst_abc123", - tools=tools, - stream=True -) + - `"gpt-3.5-turbo-0125"` -for event in stream: - print(event) -``` + - `"gpt-3.5-turbo-16k-0613"` -#### Response + - `"o1-pro"` -```json -event: thread.run.created -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `"o1-pro-2025-03-19"` -event: thread.run.queued -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `"o3-pro"` -event: thread.run.in_progress -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710348075,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `"o3-pro-2025-06-10"` -event: thread.run.step.created -data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + - `"o3-deep-research"` -event: thread.run.step.in_progress -data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + - `"o3-deep-research-2025-06-26"` -event: thread.message.created -data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `"o4-mini-deep-research"` -event: thread.message.in_progress -data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `"o4-mini-deep-research-2025-06-26"` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + - `"computer-use-preview"` -... + - `"computer-use-preview-2025-03-11"` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + - `"gpt-5-codex"` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + - `"gpt-5-pro"` -event: thread.message.completed -data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} + - `"gpt-5-pro-2025-10-06"` -event: thread.run.step.completed -data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + - `"gpt-5.1-codex-max"` -event: thread.run.completed -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710348075,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710348077,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `str` -event: done -data: [DONE] -``` + - `object: Literal["response"]` -## Retrieve run + The object type of this resource - always set to `response`. -`beta.threads.runs.retrieve(strrun_id, RunRetrieveParams**kwargs) -> Run` + - `"response"` -**get** `/threads/{thread_id}/runs/{run_id}` + - `output: List[BetaResponseOutputItem]` -Retrieve run + An array of content items generated by the model. -### Parameters + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. -- `thread_id: str` + - `class BetaResponseOutputMessage: …` -- `run_id: str` + An output message from the model. -### Returns + - `class BetaResponseFileSearchToolCall: …` -- `class Run: …` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class BetaResponseFunctionToolCall: …` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `class BetaResponseFunctionToolCallOutputItem: …` - `id: str` - The identifier, which can be referenced in API endpoints. + The unique ID of the function call tool output. - - `assistant_id: str` + - `call_id: str` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The unique ID of the function tool call generated by the model. - - `cancelled_at: Optional[int]` + - `output: Union[str, List[OutputOutputContentList]]` - The Unix timestamp (in seconds) for when the run was cancelled. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `completed_at: Optional[int]` + - `str` - The Unix timestamp (in seconds) for when the run was completed. + A string of the output of the function call. - - `created_at: int` + - `List[OutputOutputContentList]` - The Unix timestamp (in seconds) for when the run was created. + Text, image, or file output of the function call. - - `expires_at: Optional[int]` + - `class BetaResponseInputText: …` - The Unix timestamp (in seconds) for when the run will expire. + A text input to the model. - - `failed_at: Optional[int]` + - `class BetaResponseInputImage: …` - The Unix timestamp (in seconds) for when the run failed. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `incomplete_details: Optional[IncompleteDetails]` + - `class BetaResponseInputFile: …` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + A file input to the model. - - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"max_completion_tokens"` + - `"in_progress"` - - `"max_prompt_tokens"` + - `"completed"` - - `instructions: str` + - `"incomplete"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `type: Literal["function_call_output"]` - - `last_error: Optional[LastError]` + The type of the function tool call output. Always `function_call_output`. - The last error associated with this run. Will be `null` if there are no errors. + - `"function_call_output"` - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` + - `agent: Optional[Agent]` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The agent that produced this item. - - `"server_error"` + - `agent_name: str` - - `"rate_limit_exceeded"` + The canonical name of the agent that produced this item. - - `"invalid_prompt"` + - `caller: Optional[Caller]` - - `message: str` + The execution context that produced this tool call. - A human-readable description of the error. + - `class CallerDirect: …` - - `max_completion_tokens: Optional[int]` + - `type: Literal["direct"]` - The maximum number of completion tokens specified to have been used over the course of the run. + The caller type. Always `direct`. - - `max_prompt_tokens: Optional[int]` + - `"direct"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `class CallerProgram: …` - - `metadata: Optional[Metadata]` + - `caller_id: str` - 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. + The call ID of the program item that produced this tool call. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: Literal["program"]` - - `model: str` + The caller type. Always `program`. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"program"` - - `object: Literal["thread.run"]` + - `created_by: Optional[str]` - The object type, which is always `thread.run`. + The identifier of the actor that created the item. - - `"thread.run"` + - `class AgentMessage: …` - - `parallel_tool_calls: bool` + - `id: str` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The unique ID of the agent message. - - `required_action: Optional[RequiredAction]` + - `author: str` - Details on the action required to continue the run. Will be `null` if no action is required. + The sending agent identity. - - `submit_tool_outputs: RequiredActionSubmitToolOutputs` + - `content: List[AgentMessageContent]` - Details on the tool outputs needed for this run to continue. + Encrypted content sent between agents. - - `tool_calls: List[RequiredActionFunctionToolCall]` + - `class BetaResponseInputText: …` - A list of the relevant tool calls. + A text input to the model. - - `id: str` + - `class BetaResponseOutputText: …` - 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. + A text output from the model. - - `function: Function` + - `class AgentMessageContentText: …` - The function definition. + A text content. - - `arguments: str` + - `text: str` - The arguments that the model expects you to pass to the function. + - `type: Literal["text"]` - - `name: str` + - `"text"` - The name of the function. + - `class AgentMessageContentSummaryText: …` - - `type: Literal["function"]` + A summary text from the model. - The type of tool call the output is required for. For now, this is always `function`. + - `text: str` - - `"function"` + A summary of the reasoning output from the model so far. - - `type: Literal["submit_tool_outputs"]` + - `type: Literal["summary_text"]` - For now, this is always `submit_tool_outputs`. + The type of the object. Always `summary_text`. - - `"submit_tool_outputs"` + - `"summary_text"` - - `response_format: Optional[AssistantResponseFormatOption]` + - `class AgentMessageContentReasoningText: …` - 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`. + Reasoning text from the model. - 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). + - `text: str` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The reasoning text from the model. - **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. + - `type: Literal["reasoning_text"]` - - `Literal["auto"]` + The type of the reasoning text. Always `reasoning_text`. - `auto` is the default value + - `"reasoning_text"` - - `"auto"` + - `class BetaResponseOutputRefusal: …` - - `class ResponseFormatText: …` + A refusal from the model. - Default response format. Used to generate text responses. + - `class BetaResponseInputImage: …` - - `type: Literal["text"]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The type of response format being defined. Always `text`. + - `class AgentMessageContentComputerScreenshot: …` - - `"text"` + A screenshot of a computer. - - `class ResponseFormatJSONObject: …` + - `detail: Literal["low", "high", "auto", "original"]` - 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. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: Literal["json_object"]` + - `"low"` - The type of response format being defined. Always `json_object`. + - `"high"` - - `"json_object"` + - `"auto"` - - `class ResponseFormatJSONSchema: …` + - `"original"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `file_id: Optional[str]` - - `json_schema: JSONSchema` + The identifier of an uploaded file that contains the screenshot. - Structured Outputs configuration options, including a JSON Schema. + - `image_url: Optional[str]` - - `name: str` + The URL of the screenshot image. - 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. + - `type: Literal["computer_screenshot"]` - - `description: Optional[str]` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"computer_screenshot"` - - `schema: Optional[Dict[str, object]]` + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `strict: Optional[bool]` + - `mode: Literal["explicit"]` - 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). + The breakpoint mode. Always `explicit`. - - `type: Literal["json_schema"]` + - `"explicit"` - The type of response format being defined. Always `json_schema`. + - `class BetaResponseInputFile: …` - - `"json_schema"` + A file input to the model. - - `started_at: Optional[int]` + - `class AgentMessageContentEncryptedContent: …` - The Unix timestamp (in seconds) for when the run was started. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `status: object` + - `encrypted_content: str` - - `thread_id: str` + Opaque encrypted content. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `type: Literal["encrypted_content"]` - - `tool_choice: Optional[AssistantToolChoiceOption]` + The type of the input item. Always `encrypted_content`. - 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. + - `"encrypted_content"` - - `Literal["none", "auto", "required"]` + - `recipient: str` - `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. + The destination agent identity. - - `"none"` + - `type: Literal["agent_message"]` - - `"auto"` + The type of the item. Always `agent_message`. - - `"required"` + - `"agent_message"` - - `class AssistantToolChoice: …` + - `agent: Optional[AgentMessageAgent]` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The agent that produced this item. - - `type: Literal["function", "code_interpreter", "file_search"]` + - `agent_name: str` - The type of the tool. If type is `function`, the function name must be set + The canonical name of the agent that produced this item. - - `"function"` + - `class MultiAgentCall: …` - - `"code_interpreter"` + - `id: str` - - `"file_search"` + The unique ID of the multi-agent call item. - - `function: Optional[AssistantToolChoiceFunction]` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `name: str` + The multi-agent action to execute. - The name of the function to call. + - `"spawn_agent"` - - `tools: List[object]` + - `"interrupt_agent"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"list_agents"` - - `truncation_strategy: Optional[TruncationStrategy]` + - `"send_message"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"followup_task"` - - `type: Literal["auto", "last_messages"]` + - `"wait_agent"` - 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`. + - `arguments: str` - - `"auto"` + The JSON string of arguments generated for the action. - - `"last_messages"` + - `call_id: str` - - `last_messages: Optional[int]` + The unique ID linking this call to its output. - The number of most recent messages from the thread when constructing the context for the run. + - `type: Literal["multi_agent_call"]` - - `usage: Optional[Usage]` + The type of the multi-agent call. Always `multi_agent_call`. - 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.). + - `"multi_agent_call"` - - `completion_tokens: int` + - `agent: Optional[MultiAgentCallAgent]` - Number of completion tokens used over the course of the run. + The agent that produced this item. - - `prompt_tokens: int` + - `agent_name: str` - Number of prompt tokens used over the course of the run. + The canonical name of the agent that produced this item. - - `total_tokens: int` + - `class MultiAgentCallOutput: …` - Total number of tokens used (prompt + completion). + - `id: str` - - `temperature: Optional[float]` + The unique ID of the multi-agent call output item. - The sampling temperature used for this run. If not set, defaults to 1. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `top_p: Optional[float]` + The multi-agent action that produced this result. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"spawn_agent"` -### Example + - `"interrupt_agent"` -```python -import os -from openai import OpenAI + - `"list_agents"` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -run = client.beta.threads.runs.retrieve( - run_id="run_id", - thread_id="thread_id", -) -print(run.id) -``` + - `"send_message"` -#### Response + - `"followup_task"` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `"wait_agent"` -### Example + - `call_id: str` -```python -from openai import OpenAI -client = OpenAI() + The unique ID of the multi-agent call. -run = client.beta.threads.runs.retrieve( - thread_id="thread_abc123", - run_id="run_abc123" -) + - `output: List[BetaResponseOutputText]` -print(run) -``` + Text output returned by the multi-agent action. -#### Response + - `annotations: List[Annotation]` -```json -{ - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699075072, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699075072, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699075073, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "metadata": {}, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` + The annotations of the text output. -## Modify run + - `text: str` -`beta.threads.runs.update(strrun_id, RunUpdateParams**kwargs) -> Run` + The text output from the model. -**post** `/threads/{thread_id}/runs/{run_id}` + - `type: Literal["output_text"]` -Modify run + The type of the output text. Always `output_text`. -### Parameters + - `logprobs: Optional[List[Logprob]]` -- `thread_id: str` + - `type: Literal["multi_agent_call_output"]` -- `run_id: str` + The type of the multi-agent result. Always `multi_agent_call_output`. -- `metadata: Optional[Metadata]` + - `"multi_agent_call_output"` - 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. + - `agent: Optional[MultiAgentCallOutputAgent]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The agent that produced this item. -### Returns + - `agent_name: str` -- `class Run: …` + The canonical name of the agent that produced this item. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class BetaResponseFunctionWebSearch: …` - - `id: str` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The identifier, which can be referenced in API endpoints. + - `class BetaResponseComputerToolCall: …` - - `assistant_id: str` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `class BetaResponseComputerToolCallOutputItem: …` - - `cancelled_at: Optional[int]` + - `id: str` - The Unix timestamp (in seconds) for when the run was cancelled. + The unique ID of the computer call tool output. - - `completed_at: Optional[int]` + - `call_id: str` - The Unix timestamp (in seconds) for when the run was completed. + The ID of the computer tool call that produced the output. - - `created_at: int` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The Unix timestamp (in seconds) for when the run was created. + A computer screenshot image used with the computer use tool. - - `expires_at: Optional[int]` + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - The Unix timestamp (in seconds) for when the run will expire. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `failed_at: Optional[int]` + - `"completed"` - The Unix timestamp (in seconds) for when the run failed. + - `"incomplete"` - - `incomplete_details: Optional[IncompleteDetails]` + - `"failed"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"in_progress"` - - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` + - `type: Literal["computer_call_output"]` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + The type of the computer tool call output. Always `computer_call_output`. - - `"max_completion_tokens"` + - `"computer_call_output"` - - `"max_prompt_tokens"` + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - - `instructions: str` + The safety checks reported by the API that have been acknowledged by the + developer. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `id: str` - - `last_error: Optional[LastError]` + The ID of the pending safety check. - The last error associated with this run. Will be `null` if there are no errors. + - `code: Optional[str]` - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` + The type of the pending safety check. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `message: Optional[str]` - - `"server_error"` + Details about the pending safety check. - - `"rate_limit_exceeded"` + - `agent: Optional[Agent]` - - `"invalid_prompt"` + The agent that produced this item. - - `message: str` + - `agent_name: str` - A human-readable description of the error. + The canonical name of the agent that produced this item. - - `max_completion_tokens: Optional[int]` + - `created_by: Optional[str]` - The maximum number of completion tokens specified to have been used over the course of the run. + The identifier of the actor that created the item. - - `max_prompt_tokens: Optional[int]` + - `class BetaResponseReasoningItem: …` - The maximum number of prompt tokens specified to have been used over the course of the run. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `metadata: Optional[Metadata]` + - `class Program: …` - 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. + - `id: str` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The unique ID of the program item. - - `model: str` + - `call_id: str` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The stable call ID of the program item. - - `object: Literal["thread.run"]` + - `code: str` - The object type, which is always `thread.run`. + The JavaScript source executed by programmatic tool calling. - - `"thread.run"` + - `fingerprint: str` - - `parallel_tool_calls: bool` + Opaque program replay fingerprint that must be round-tripped. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `type: Literal["program"]` - - `required_action: Optional[RequiredAction]` + The type of the item. Always `program`. - Details on the action required to continue the run. Will be `null` if no action is required. + - `"program"` - - `submit_tool_outputs: RequiredActionSubmitToolOutputs` + - `agent: Optional[ProgramAgent]` - Details on the tool outputs needed for this run to continue. + The agent that produced this item. - - `tool_calls: List[RequiredActionFunctionToolCall]` + - `agent_name: str` - A list of the relevant tool calls. + The canonical name of the agent that produced this item. + + - `class ProgramOutput: …` - `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. + The unique ID of the program output item. - - `function: Function` + - `call_id: str` - The function definition. + The call ID of the program item. - - `arguments: str` + - `result: str` - The arguments that the model expects you to pass to the function. + The result produced by the program item. - - `name: str` + - `status: Literal["completed", "incomplete"]` - The name of the function. + The terminal status of the program output item. - - `type: Literal["function"]` + - `"completed"` - The type of tool call the output is required for. For now, this is always `function`. + - `"incomplete"` - - `"function"` + - `type: Literal["program_output"]` - - `type: Literal["submit_tool_outputs"]` + The type of the item. Always `program_output`. - For now, this is always `submit_tool_outputs`. + - `"program_output"` - - `"submit_tool_outputs"` + - `agent: Optional[ProgramOutputAgent]` - - `response_format: Optional[AssistantResponseFormatOption]` + The agent that produced this item. - 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`. + - `agent_name: str` - 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). + The canonical name of the agent that produced this item. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `class BetaResponseToolSearchCall: …` - **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. + - `id: str` - - `Literal["auto"]` + The unique ID of the tool search call item. - `auto` is the default value + - `arguments: object` - - `"auto"` + Arguments used for the tool search call. - - `class ResponseFormatText: …` + - `call_id: Optional[str]` - Default response format. Used to generate text responses. + The unique ID of the tool search call generated by the model. - - `type: Literal["text"]` + - `execution: Literal["server", "client"]` - The type of response format being defined. Always `text`. + Whether tool search was executed by the server or by the client. - - `"text"` + - `"server"` - - `class ResponseFormatJSONObject: …` + - `"client"` - 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. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["json_object"]` + The status of the tool search call item that was recorded. - The type of response format being defined. Always `json_object`. + - `"in_progress"` - - `"json_object"` + - `"completed"` - - `class ResponseFormatJSONSchema: …` + - `"incomplete"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `type: Literal["tool_search_call"]` - - `json_schema: JSONSchema` + The type of the item. Always `tool_search_call`. - Structured Outputs configuration options, including a JSON Schema. + - `"tool_search_call"` - - `name: str` + - `agent: Optional[Agent]` - 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. + The agent that produced this item. - - `description: Optional[str]` + - `agent_name: str` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The canonical name of the agent that produced this item. - - `schema: Optional[Dict[str, object]]` + - `created_by: Optional[str]` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The identifier of the actor that created the item. - - `strict: Optional[bool]` + - `class BetaResponseToolSearchOutputItem: …` - 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). + - `id: str` - - `type: Literal["json_schema"]` + The unique ID of the tool search output item. - The type of response format being defined. Always `json_schema`. + - `call_id: Optional[str]` - - `"json_schema"` + The unique ID of the tool search call generated by the model. - - `started_at: Optional[int]` + - `execution: Literal["server", "client"]` - The Unix timestamp (in seconds) for when the run was started. + Whether tool search was executed by the server or by the client. - - `status: object` + - `"server"` - - `thread_id: str` + - `"client"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `tool_choice: Optional[AssistantToolChoiceOption]` + The status of the tool search output item that was recorded. - 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. + - `"in_progress"` - - `Literal["none", "auto", "required"]` + - `"completed"` - `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. + - `"incomplete"` - - `"none"` + - `tools: List[BetaTool]` - - `"auto"` + The loaded tool definitions returned by tool search. - - `"required"` + - `class BetaFunctionTool: …` - - `class AssistantToolChoice: …` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `class BetaFileSearchTool: …` - - `type: Literal["function", "code_interpreter", "file_search"]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The type of the tool. If type is `function`, the function name must be set + - `class BetaComputerTool: …` - - `"function"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"code_interpreter"` + - `class BetaComputerUsePreviewTool: …` - - `"file_search"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `function: Optional[AssistantToolChoiceFunction]` + - `class BetaWebSearchTool: …` - - `name: str` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The name of the function to call. + - `class Mcp: …` - - `tools: List[object]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `class CodeInterpreter: …` - - `truncation_strategy: Optional[TruncationStrategy]` + A tool that runs Python code to help generate a response to a prompt. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `class ProgrammaticToolCalling: …` - - `type: Literal["auto", "last_messages"]` + - `class ImageGeneration: …` - 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`. + A tool that generates images using the GPT image models. - - `"auto"` + - `class LocalShell: …` - - `"last_messages"` + A tool that allows the model to execute shell commands in a local environment. - - `last_messages: Optional[int]` + - `class BetaFunctionShellTool: …` - The number of most recent messages from the thread when constructing the context for the run. + A tool that allows the model to execute shell commands. - - `usage: Optional[Usage]` + - `class BetaCustomTool: …` - 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.). + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `completion_tokens: int` + - `class BetaNamespaceTool: …` - Number of completion tokens used over the course of the run. + Groups function/custom tools under a shared namespace. - - `prompt_tokens: int` + - `class BetaToolSearchTool: …` - Number of prompt tokens used over the course of the run. + Hosted or BYOT tool search configuration for deferred tools. - - `total_tokens: int` + - `class BetaWebSearchPreviewTool: …` - Total number of tokens used (prompt + completion). + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `temperature: Optional[float]` + - `class BetaApplyPatchTool: …` - The sampling temperature used for this run. If not set, defaults to 1. + Allows the assistant to create, delete, or update files using unified diffs. - - `top_p: Optional[float]` + - `type: Literal["tool_search_output"]` - The nucleus sampling value used for this run. If not set, defaults to 1. + The type of the item. Always `tool_search_output`. -### Example + - `"tool_search_output"` -```python -import os -from openai import OpenAI + - `agent: Optional[Agent]` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -run = client.beta.threads.runs.update( - run_id="run_id", - thread_id="thread_id", -) -print(run.id) -``` + The agent that produced this item. -#### Response + - `agent_name: str` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + The canonical name of the agent that produced this item. -### Example + - `created_by: Optional[str]` -```python -from openai import OpenAI -client = OpenAI() + The identifier of the actor that created the item. -run = client.beta.threads.runs.update( - thread_id="thread_abc123", - run_id="run_abc123", - metadata={"user_id": "user_abc123"}, -) + - `class AdditionalTools: …` -print(run) -``` + - `id: str` -#### Response + The unique ID of the additional tools item. -```json -{ - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699075072, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699075072, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699075073, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "file-abc123", - "file-abc456" - ] - } - }, - "metadata": { - "user_id": "user_abc123" - }, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` + - `role: Literal["unknown", "user", "assistant", 5 more]` -## Submit tool outputs to run + The role that provided the additional tools. -`beta.threads.runs.submit_tool_outputs(strrun_id, RunSubmitToolOutputsParams**kwargs) -> Run` + - `"unknown"` -**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` + - `"user"` -Submit tool outputs to run + - `"assistant"` -### Parameters + - `"system"` -- `thread_id: str` + - `"critic"` -- `run_id: str` + - `"discriminator"` -- `tool_outputs: Iterable[ToolOutput]` + - `"developer"` - A list of tools for which the outputs are being submitted. + - `"tool"` - - `output: Optional[str]` + - `tools: List[BetaTool]` - The output of the tool call to be submitted to continue the run. + The additional tool definitions made available at this item. - - `tool_call_id: Optional[str]` + - `class BetaFunctionTool: …` - The ID of the tool call in the `required_action` object within the run object the output is being submitted for. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). -- `stream: Optional[Literal[false]]` + - `class BetaFileSearchTool: …` - If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `false` + - `class BetaComputerTool: …` -### Returns + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). -- `class Run: …` + - `class BetaComputerUsePreviewTool: …` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `id: str` + - `class BetaWebSearchTool: …` - The identifier, which can be referenced in API endpoints. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `assistant_id: str` + - `class Mcp: …` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `cancelled_at: Optional[int]` + - `class CodeInterpreter: …` - The Unix timestamp (in seconds) for when the run was cancelled. + A tool that runs Python code to help generate a response to a prompt. - - `completed_at: Optional[int]` + - `class ProgrammaticToolCalling: …` - The Unix timestamp (in seconds) for when the run was completed. + - `class ImageGeneration: …` - - `created_at: int` + A tool that generates images using the GPT image models. - The Unix timestamp (in seconds) for when the run was created. + - `class LocalShell: …` - - `expires_at: Optional[int]` + A tool that allows the model to execute shell commands in a local environment. - The Unix timestamp (in seconds) for when the run will expire. + - `class BetaFunctionShellTool: …` - - `failed_at: Optional[int]` + A tool that allows the model to execute shell commands. - The Unix timestamp (in seconds) for when the run failed. + - `class BetaCustomTool: …` - - `incomplete_details: Optional[IncompleteDetails]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `class BetaNamespaceTool: …` - - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` + Groups function/custom tools under a shared namespace. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `class BetaToolSearchTool: …` - - `"max_completion_tokens"` + Hosted or BYOT tool search configuration for deferred tools. - - `"max_prompt_tokens"` + - `class BetaWebSearchPreviewTool: …` - - `instructions: str` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `class BetaApplyPatchTool: …` - - `last_error: Optional[LastError]` + Allows the assistant to create, delete, or update files using unified diffs. - The last error associated with this run. Will be `null` if there are no errors. + - `type: Literal["additional_tools"]` - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` + The type of the item. Always `additional_tools`. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"additional_tools"` - - `"server_error"` + - `agent: Optional[AdditionalToolsAgent]` - - `"rate_limit_exceeded"` + The agent that produced this item. - - `"invalid_prompt"` + - `agent_name: str` - - `message: str` + The canonical name of the agent that produced this item. - A human-readable description of the error. + - `class BetaResponseCompactionItem: …` - - `max_completion_tokens: Optional[int]` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The maximum number of completion tokens specified to have been used over the course of the run. + - `id: str` - - `max_prompt_tokens: Optional[int]` + The unique ID of the compaction item. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `encrypted_content: str` - - `metadata: Optional[Metadata]` + The encrypted content that was produced by compaction. - 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. + - `type: Literal["compaction"]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The type of the item. Always `compaction`. - - `model: str` + - `"compaction"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `agent: Optional[Agent]` - - `object: Literal["thread.run"]` + The agent that produced this item. - The object type, which is always `thread.run`. + - `agent_name: str` - - `"thread.run"` + The canonical name of the agent that produced this item. - - `parallel_tool_calls: bool` + - `created_by: Optional[str]` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The identifier of the actor that created the item. - - `required_action: Optional[RequiredAction]` + - `class ImageGenerationCall: …` - Details on the action required to continue the run. Will be `null` if no action is required. + An image generation request made by the model. - - `submit_tool_outputs: RequiredActionSubmitToolOutputs` + - `id: str` - Details on the tool outputs needed for this run to continue. + The unique ID of the image generation call. - - `tool_calls: List[RequiredActionFunctionToolCall]` + - `result: Optional[str]` - A list of the relevant tool calls. + The generated image encoded in base64. - - `id: str` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - 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. + The status of the image generation call. - - `function: Function` + - `"in_progress"` - The function definition. + - `"completed"` - - `arguments: str` + - `"generating"` - The arguments that the model expects you to pass to the function. + - `"failed"` - - `name: str` + - `type: Literal["image_generation_call"]` - The name of the function. + The type of the image generation call. Always `image_generation_call`. - - `type: Literal["function"]` + - `"image_generation_call"` - The type of tool call the output is required for. For now, this is always `function`. + - `agent: Optional[ImageGenerationCallAgent]` - - `"function"` + The agent that produced this item. - - `type: Literal["submit_tool_outputs"]` + - `agent_name: str` - For now, this is always `submit_tool_outputs`. + The canonical name of the agent that produced this item. - - `"submit_tool_outputs"` + - `class BetaResponseCodeInterpreterToolCall: …` - - `response_format: Optional[AssistantResponseFormatOption]` + A tool call to run code. - 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`. + - `class LocalShellCall: …` - 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). + A tool call to run a command on the local shell. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `id: str` - **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. + The unique ID of the local shell call. - - `Literal["auto"]` + - `action: LocalShellCallAction` - `auto` is the default value + Execute a shell command on the server. - - `"auto"` + - `command: List[str]` - - `class ResponseFormatText: …` + The command to run. - Default response format. Used to generate text responses. + - `env: Dict[str, str]` - - `type: Literal["text"]` + Environment variables to set for the command. - The type of response format being defined. Always `text`. + - `type: Literal["exec"]` - - `"text"` + The type of the local shell action. Always `exec`. - - `class ResponseFormatJSONObject: …` + - `"exec"` - 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. + - `timeout_ms: Optional[int]` - - `type: Literal["json_object"]` + Optional timeout in milliseconds for the command. - The type of response format being defined. Always `json_object`. + - `user: Optional[str]` - - `"json_object"` + Optional user to run the command as. - - `class ResponseFormatJSONSchema: …` + - `working_directory: Optional[str]` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + Optional working directory to run the command in. - - `json_schema: JSONSchema` + - `call_id: str` - Structured Outputs configuration options, including a JSON Schema. + The unique ID of the local shell tool call generated by the model. - - `name: str` + - `status: Literal["in_progress", "completed", "incomplete"]` - 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. + The status of the local shell call. - - `description: Optional[str]` + - `"in_progress"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"completed"` - - `schema: Optional[Dict[str, object]]` + - `"incomplete"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `type: Literal["local_shell_call"]` - - `strict: Optional[bool]` + The type of the local shell call. Always `local_shell_call`. - 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). + - `"local_shell_call"` - - `type: Literal["json_schema"]` + - `agent: Optional[LocalShellCallAgent]` - The type of response format being defined. Always `json_schema`. + The agent that produced this item. - - `"json_schema"` + - `agent_name: str` - - `started_at: Optional[int]` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run was started. + - `class LocalShellCallOutput: …` - - `status: object` + The output of a local shell tool call. - - `thread_id: str` + - `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. + The unique ID of the local shell tool call generated by the model. - - `tool_choice: Optional[AssistantToolChoiceOption]` + - `output: str` - 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. + A JSON string of the output of the local shell tool call. - - `Literal["none", "auto", "required"]` + - `type: Literal["local_shell_call_output"]` - `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. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"none"` + - `"local_shell_call_output"` - - `"auto"` + - `agent: Optional[LocalShellCallOutputAgent]` - - `"required"` + The agent that produced this item. - - `class AssistantToolChoice: …` + - `agent_name: str` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The canonical name of the agent that produced this item. - - `type: Literal["function", "code_interpreter", "file_search"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The type of the tool. If type is `function`, the function name must be set + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"function"` + - `"in_progress"` - - `"code_interpreter"` + - `"completed"` - - `"file_search"` + - `"incomplete"` - - `function: Optional[AssistantToolChoiceFunction]` + - `class BetaResponseFunctionShellToolCall: …` - - `name: str` + A tool call that executes one or more shell commands in a managed environment. - The name of the function to call. + - `id: str` - - `tools: List[object]` + The unique ID of the shell tool call. Populated when this item is returned via API. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `action: Action` - - `truncation_strategy: Optional[TruncationStrategy]` + The shell commands and limits that describe how to run the tool call. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `commands: List[str]` - - `type: Literal["auto", "last_messages"]` + - `max_output_length: Optional[int]` - 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`. + Optional maximum number of characters to return from each command. - - `"auto"` + - `timeout_ms: Optional[int]` - - `"last_messages"` + Optional timeout in milliseconds for the commands. - - `last_messages: Optional[int]` + - `call_id: str` - The number of most recent messages from the thread when constructing the context for the run. + The unique ID of the shell tool call generated by the model. - - `usage: Optional[Usage]` + - `environment: Optional[Environment]` - 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.). + Represents the use of a local environment to perform shell actions. - - `completion_tokens: int` + - `class BetaResponseLocalEnvironment: …` - Number of completion tokens used over the course of the run. + Represents the use of a local environment to perform shell actions. - - `prompt_tokens: int` + - `type: Literal["local"]` - Number of prompt tokens used over the course of the run. + The environment type. Always `local`. - - `total_tokens: int` + - `"local"` - Total number of tokens used (prompt + completion). + - `class BetaResponseContainerReference: …` - - `temperature: Optional[float]` + Represents a container created with /v1/containers. - The sampling temperature used for this run. If not set, defaults to 1. + - `container_id: str` - - `top_p: Optional[float]` + - `type: Literal["container_reference"]` - The nucleus sampling value used for this run. If not set, defaults to 1. + The environment type. Always `container_reference`. -### Example + - `"container_reference"` -```python -import os -from openai import OpenAI + - `status: Literal["in_progress", "completed", "incomplete"]` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -for run in client.beta.threads.runs.submit_tool_outputs( - run_id="run_id", - thread_id="thread_id", - tool_outputs=[{}], -): - print(run) -``` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. -#### Response + - `"in_progress"` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `"completed"` -### Example + - `"incomplete"` -```python -from openai import OpenAI -client = OpenAI() + - `type: Literal["shell_call"]` -run = client.beta.threads.runs.submit_tool_outputs( - thread_id="thread_123", - run_id="run_123", - tool_outputs=[ - { - "tool_call_id": "call_001", - "output": "70 degrees and sunny." - } - ] -) + The type of the item. Always `shell_call`. -print(run) -``` + - `"shell_call"` -#### Response + - `agent: Optional[Agent]` -```json -{ - "id": "run_123", - "object": "thread.run", - "created_at": 1699075592, - "assistant_id": "asst_123", - "thread_id": "thread_123", - "status": "queued", - "started_at": 1699075592, - "expires_at": 1699076192, - "cancelled_at": null, - "failed_at": null, - "completed_at": null, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "tools": [ - { - "type": "function", - "function": { - "name": "get_current_weather", - "description": "Get the current weather in a given location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA" - }, - "unit": { - "type": "string", - "enum": ["celsius", "fahrenheit"] - } - }, - "required": ["location"] - } - } - } - ], - "metadata": {}, - "usage": null, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` + The agent that produced this item. -### Streaming + - `agent_name: str` -```python -from openai import OpenAI -client = OpenAI() + The canonical name of the agent that produced this item. -stream = client.beta.threads.runs.submit_tool_outputs( - thread_id="thread_123", - run_id="run_123", - tool_outputs=[ - { - "tool_call_id": "call_001", - "output": "70 degrees and sunny." - } - ], - stream=True -) + - `caller: Optional[Caller]` -for event in stream: - print(event) -``` + The execution context that produced this tool call. -#### Response + - `class CallerDirect: …` -```json -event: thread.run.step.completed -data: {"id":"step_001","object":"thread.run.step","created_at":1710352449,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"completed","cancelled_at":null,"completed_at":1710352475,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[{"id":"call_iWr0kQ2EaYMaxNdl0v3KYkx7","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}","output":"70 degrees and sunny."}}]},"usage":{"prompt_tokens":291,"completion_tokens":24,"total_tokens":315}} + - `type: Literal["direct"]` -event: thread.run.queued -data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":1710352448,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `"direct"` -event: thread.run.in_progress -data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710352475,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `class CallerProgram: …` -event: thread.run.step.created -data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} + - `caller_id: str` -event: thread.run.step.in_progress -data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} + The call ID of the program item that produced this tool call. -event: thread.message.created -data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `type: Literal["program"]` -event: thread.message.in_progress -data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `"program"` -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"The","annotations":[]}}]}} + - `created_by: Optional[str]` -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" current"}}]}} + The ID of the entity that created this tool call. -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" weather"}}]}} + - `class BetaResponseFunctionShellToolCallOutput: …` -... + The output of a shell tool call that was emitted. -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" sunny"}}]}} + - `id: str` -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"."}}]}} + The unique ID of the shell call output. Populated when this item is returned via API. -event: thread.message.completed -data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710352477,"role":"assistant","content":[{"type":"text","text":{"value":"The current weather in San Francisco, CA is 70 degrees Fahrenheit and sunny.","annotations":[]}}],"metadata":{}} + - `call_id: str` -event: thread.run.step.completed -data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710352477,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":{"prompt_tokens":329,"completion_tokens":18,"total_tokens":347}} + The unique ID of the shell tool call generated by the model. -event: thread.run.completed -data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710352475,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710352477,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `max_output_length: Optional[int]` -event: done -data: [DONE] -``` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. -## Cancel a run + - `output: List[Output]` -`beta.threads.runs.cancel(strrun_id, RunCancelParams**kwargs) -> Run` + An array of shell call output contents -**post** `/threads/{thread_id}/runs/{run_id}/cancel` + - `outcome: OutputOutcome` -Cancel a run + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. -### Parameters + - `class OutputOutcomeTimeout: …` -- `thread_id: str` + Indicates that the shell call exceeded its configured time limit. -- `run_id: str` + - `type: Literal["timeout"]` -### Returns + The outcome type. Always `timeout`. -- `class Run: …` + - `"timeout"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class OutputOutcomeExit: …` - - `id: str` + Indicates that the shell commands finished and returned an exit code. - The identifier, which can be referenced in API endpoints. + - `exit_code: int` - - `assistant_id: str` + Exit code from the shell process. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `type: Literal["exit"]` - - `cancelled_at: Optional[int]` + The outcome type. Always `exit`. - The Unix timestamp (in seconds) for when the run was cancelled. + - `"exit"` - - `completed_at: Optional[int]` + - `stderr: str` - The Unix timestamp (in seconds) for when the run was completed. + The standard error output that was captured. - - `created_at: int` + - `stdout: str` - The Unix timestamp (in seconds) for when the run was created. + The standard output that was captured. - - `expires_at: Optional[int]` + - `created_by: Optional[str]` - The Unix timestamp (in seconds) for when the run will expire. + The identifier of the actor that created the item. - - `failed_at: Optional[int]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The Unix timestamp (in seconds) for when the run failed. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `incomplete_details: Optional[IncompleteDetails]` + - `"in_progress"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"completed"` - - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` + - `"incomplete"` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `type: Literal["shell_call_output"]` - - `"max_completion_tokens"` + The type of the shell call output. Always `shell_call_output`. - - `"max_prompt_tokens"` + - `"shell_call_output"` - - `instructions: str` + - `agent: Optional[Agent]` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The agent that produced this item. - - `last_error: Optional[LastError]` + - `agent_name: str` - The last error associated with this run. Will be `null` if there are no errors. + The canonical name of the agent that produced this item. - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` + - `caller: Optional[Caller]` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The execution context that produced this tool call. - - `"server_error"` + - `class CallerDirect: …` - - `"rate_limit_exceeded"` + - `type: Literal["direct"]` - - `"invalid_prompt"` + - `"direct"` - - `message: str` + - `class CallerProgram: …` - A human-readable description of the error. + - `caller_id: str` - - `max_completion_tokens: Optional[int]` + The call ID of the program item that produced this tool call. - The maximum number of completion tokens specified to have been used over the course of the run. + - `type: Literal["program"]` - - `max_prompt_tokens: Optional[int]` + - `"program"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `created_by: Optional[str]` - - `metadata: Optional[Metadata]` + The identifier of the actor that created the item. - 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. + - `class BetaResponseApplyPatchToolCall: …` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A tool call that applies file diffs by creating, deleting, or updating files. - - `model: str` + - `id: str` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `object: Literal["thread.run"]` + - `call_id: str` - The object type, which is always `thread.run`. + The unique ID of the apply patch tool call generated by the model. - - `"thread.run"` + - `operation: Operation` - - `parallel_tool_calls: bool` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `class OperationCreateFile: …` - - `required_action: Optional[RequiredAction]` + Instruction describing how to create a file via the apply_patch tool. - Details on the action required to continue the run. Will be `null` if no action is required. + - `diff: str` - - `submit_tool_outputs: RequiredActionSubmitToolOutputs` + Diff to apply. - Details on the tool outputs needed for this run to continue. + - `path: str` - - `tool_calls: List[RequiredActionFunctionToolCall]` + Path of the file to create. - A list of the relevant tool calls. + - `type: Literal["create_file"]` - - `id: str` + Create a new file with the provided diff. - 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. + - `"create_file"` - - `function: Function` + - `class OperationDeleteFile: …` - The function definition. + Instruction describing how to delete a file via the apply_patch tool. - - `arguments: str` + - `path: str` - The arguments that the model expects you to pass to the function. + Path of the file to delete. - - `name: str` + - `type: Literal["delete_file"]` - The name of the function. + Delete the specified file. - - `type: Literal["function"]` + - `"delete_file"` - The type of tool call the output is required for. For now, this is always `function`. + - `class OperationUpdateFile: …` - - `"function"` + Instruction describing how to update a file via the apply_patch tool. - - `type: Literal["submit_tool_outputs"]` + - `diff: str` - For now, this is always `submit_tool_outputs`. + Diff to apply. - - `"submit_tool_outputs"` + - `path: str` - - `response_format: Optional[AssistantResponseFormatOption]` + Path of the file to update. - 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`. + - `type: Literal["update_file"]` - 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). + Update an existing file with the provided diff. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"update_file"` - **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 + - `status: Literal["in_progress", "completed"]` - - `"auto"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `class ResponseFormatText: …` + - `"in_progress"` - Default response format. Used to generate text responses. + - `"completed"` - - `type: Literal["text"]` + - `type: Literal["apply_patch_call"]` - The type of response format being defined. Always `text`. + The type of the item. Always `apply_patch_call`. - - `"text"` + - `"apply_patch_call"` - - `class ResponseFormatJSONObject: …` + - `agent: Optional[Agent]` - 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. + The agent that produced this item. - - `type: Literal["json_object"]` + - `agent_name: str` - The type of response format being defined. Always `json_object`. + The canonical name of the agent that produced this item. - - `"json_object"` + - `caller: Optional[Caller]` - - `class ResponseFormatJSONSchema: …` + The execution context that produced this tool call. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `class CallerDirect: …` - - `json_schema: JSONSchema` + - `type: Literal["direct"]` - Structured Outputs configuration options, including a JSON Schema. + - `"direct"` - - `name: str` + - `class CallerProgram: …` - 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. + - `caller_id: str` - - `description: Optional[str]` + The call ID of the program item that produced this tool call. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `type: Literal["program"]` - - `schema: Optional[Dict[str, object]]` + - `"program"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `created_by: Optional[str]` - - `strict: Optional[bool]` + The ID of the entity that created this tool call. - 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). + - `class BetaResponseApplyPatchToolCallOutput: …` - - `type: Literal["json_schema"]` + The output emitted by an apply patch tool call. - The type of response format being defined. Always `json_schema`. + - `id: str` - - `"json_schema"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `started_at: Optional[int]` + - `call_id: str` - The Unix timestamp (in seconds) for when the run was started. + The unique ID of the apply patch tool call generated by the model. - - `status: object` + - `status: Literal["completed", "failed"]` - - `thread_id: str` + The status of the apply patch tool call output. One of `completed` or `failed`. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `"completed"` - - `tool_choice: Optional[AssistantToolChoiceOption]` + - `"failed"` - 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. + - `type: Literal["apply_patch_call_output"]` - - `Literal["none", "auto", "required"]` + The type of the item. Always `apply_patch_call_output`. - `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. + - `"apply_patch_call_output"` - - `"none"` + - `agent: Optional[Agent]` - - `"auto"` + The agent that produced this item. - - `"required"` + - `agent_name: str` - - `class AssistantToolChoice: …` + The canonical name of the agent that produced this item. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `caller: Optional[Caller]` - - `type: Literal["function", "code_interpreter", "file_search"]` + The execution context that produced this tool call. - The type of the tool. If type is `function`, the function name must be set + - `class CallerDirect: …` - - `"function"` + - `type: Literal["direct"]` - - `"code_interpreter"` + - `"direct"` - - `"file_search"` + - `class CallerProgram: …` - - `function: Optional[AssistantToolChoiceFunction]` + - `caller_id: str` - - `name: str` + The call ID of the program item that produced this tool call. - The name of the function to call. + - `type: Literal["program"]` - - `tools: List[object]` + - `"program"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `created_by: Optional[str]` - - `truncation_strategy: Optional[TruncationStrategy]` + The ID of the entity that created this tool call output. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `output: Optional[str]` - - `type: Literal["auto", "last_messages"]` + Optional textual output returned by the apply patch tool. - 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`. + - `class McpCall: …` - - `"auto"` + An invocation of a tool on an MCP server. - - `"last_messages"` + - `id: str` - - `last_messages: Optional[int]` + The unique ID of the tool call. - The number of most recent messages from the thread when constructing the context for the run. + - `arguments: str` - - `usage: Optional[Usage]` + A JSON string of the arguments passed to the tool. - 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.). + - `name: str` - - `completion_tokens: int` + The name of the tool that was run. - Number of completion tokens used over the course of the run. + - `server_label: str` - - `prompt_tokens: int` + The label of the MCP server running the tool. - Number of prompt tokens used over the course of the run. + - `type: Literal["mcp_call"]` - - `total_tokens: int` + The type of the item. Always `mcp_call`. - Total number of tokens used (prompt + completion). + - `"mcp_call"` - - `temperature: Optional[float]` + - `agent: Optional[McpCallAgent]` - The sampling temperature used for this run. If not set, defaults to 1. + The agent that produced this item. - - `top_p: Optional[float]` + - `agent_name: str` - The nucleus sampling value used for this run. If not set, defaults to 1. + The canonical name of the agent that produced this item. -### Example + - `approval_request_id: Optional[str]` -```python -import os -from openai import OpenAI + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -run = client.beta.threads.runs.cancel( - run_id="run_id", - thread_id="thread_id", -) -print(run.id) -``` + - `error: Optional[str]` -#### Response + The error from the tool call, if any. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `output: Optional[str]` -### Example + The output from the tool call. -```python -from openai import OpenAI -client = OpenAI() + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` -run = client.beta.threads.runs.cancel( - thread_id="thread_abc123", - run_id="run_abc123" -) + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. -print(run) -``` + - `"in_progress"` -#### Response + - `"completed"` -```json -{ - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699076126, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "cancelling", - "started_at": 1699076126, - "expires_at": 1699076726, - "cancelled_at": null, - "failed_at": null, - "completed_at": null, - "last_error": null, - "model": "gpt-4o", - "instructions": "You summarize books.", - "tools": [ - { - "type": "file_search" - } - ], - "tool_resources": { - "file_search": { - "vector_store_ids": ["vs_123"] - } - }, - "metadata": {}, - "usage": null, - "temperature": 1.0, - "top_p": 1.0, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` + - `"incomplete"` -## Domain Types + - `"calling"` -### Required Action Function Tool Call + - `"failed"` -- `class RequiredActionFunctionToolCall: …` + - `class McpListTools: …` - Tool call objects + A list of tools available on an MCP server. - `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. + The unique ID of the list. - - `function: Function` + - `server_label: str` - The function definition. + The label of the MCP server. - - `arguments: str` + - `tools: List[McpListToolsTool]` - The arguments that the model expects you to pass to the function. + The tools available on the server. - - `name: str` + - `input_schema: object` - The name of the function. + The JSON schema describing the tool's input. - - `type: Literal["function"]` + - `name: str` - The type of tool call the output is required for. For now, this is always `function`. + The name of the tool. - - `"function"` + - `annotations: Optional[object]` -### Run + Additional annotations about the tool. -- `class Run: …` + - `description: Optional[str]` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The description of the tool. - - `id: str` + - `type: Literal["mcp_list_tools"]` - The identifier, which can be referenced in API endpoints. + The type of the item. Always `mcp_list_tools`. - - `assistant_id: str` + - `"mcp_list_tools"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `agent: Optional[McpListToolsAgent]` - - `cancelled_at: Optional[int]` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run was cancelled. + - `agent_name: str` - - `completed_at: Optional[int]` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run was completed. + - `error: Optional[str]` - - `created_at: int` + Error message if the server could not list tools. - The Unix timestamp (in seconds) for when the run was created. + - `class McpApprovalRequest: …` - - `expires_at: Optional[int]` + A request for human approval of a tool invocation. - The Unix timestamp (in seconds) for when the run will expire. + - `id: str` - - `failed_at: Optional[int]` + The unique ID of the approval request. - The Unix timestamp (in seconds) for when the run failed. + - `arguments: str` - - `incomplete_details: Optional[IncompleteDetails]` + A JSON string of arguments for the tool. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `name: str` - - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` + The name of the tool to run. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `server_label: str` - - `"max_completion_tokens"` + The label of the MCP server making the request. - - `"max_prompt_tokens"` + - `type: Literal["mcp_approval_request"]` - - `instructions: str` + The type of the item. Always `mcp_approval_request`. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"mcp_approval_request"` - - `last_error: Optional[LastError]` + - `agent: Optional[McpApprovalRequestAgent]` - The last error associated with this run. Will be `null` if there are no errors. + The agent that produced this item. - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` + - `agent_name: str` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The canonical name of the agent that produced this item. - - `"server_error"` + - `class McpApprovalResponse: …` - - `"rate_limit_exceeded"` + A response to an MCP approval request. - - `"invalid_prompt"` + - `id: str` - - `message: str` + The unique ID of the approval response - A human-readable description of the error. + - `approval_request_id: str` - - `max_completion_tokens: Optional[int]` + The ID of the approval request being answered. - The maximum number of completion tokens specified to have been used over the course of the run. + - `approve: bool` - - `max_prompt_tokens: Optional[int]` + Whether the request was approved. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `type: Literal["mcp_approval_response"]` - - `metadata: Optional[Metadata]` + The type of the item. Always `mcp_approval_response`. - 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. + - `"mcp_approval_response"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `agent: Optional[McpApprovalResponseAgent]` - - `model: str` + The agent that produced this item. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `agent_name: str` - - `object: Literal["thread.run"]` + The canonical name of the agent that produced this item. - The object type, which is always `thread.run`. + - `reason: Optional[str]` - - `"thread.run"` + Optional reason for the decision. - - `parallel_tool_calls: bool` + - `class BetaResponseCustomToolCall: …` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + A call to a custom tool created by the model. - - `required_action: Optional[RequiredAction]` + - `class BetaResponseCustomToolCallOutputItem: …` - Details on the action required to continue the run. Will be `null` if no action is required. + The output of a custom tool call from your code, being sent back to the model. - - `submit_tool_outputs: RequiredActionSubmitToolOutputs` + - `id: str` - Details on the tool outputs needed for this run to continue. + The unique ID of the custom tool call output item. - - `tool_calls: List[RequiredActionFunctionToolCall]` + - `status: Literal["in_progress", "completed", "incomplete"]` - A list of the relevant tool calls. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `id: str` + - `"in_progress"` - 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. + - `"completed"` - - `function: Function` + - `"incomplete"` - The function definition. + - `created_by: Optional[str]` - - `arguments: str` + The identifier of the actor that created the item. - The arguments that the model expects you to pass to the function. + - `parallel_tool_calls: bool` - - `name: str` + Whether to allow the model to run tool calls in parallel. - The name of the function. + - `temperature: Optional[float]` - - `type: Literal["function"]` + 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. + We generally recommend altering this or `top_p` but not both. - The type of tool call the output is required for. For now, this is always `function`. + - `tool_choice: ToolChoice` - - `"function"` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `type: Literal["submit_tool_outputs"]` + - `Literal["none", "auto", "required"]` - For now, this is always `submit_tool_outputs`. + - `"none"` - - `"submit_tool_outputs"` + - `"auto"` - - `response_format: Optional[AssistantResponseFormatOption]` + - `"required"` - 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`. + - `class BetaToolChoiceAllowed: …` - 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). + Constrains the tools available to the model to a pre-defined set. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `mode: Literal["auto", "required"]` - **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. + Constrains the tools available to the model to a pre-defined set. - - `Literal["auto"]` + `auto` allows the model to pick from among the allowed tools and generate a + message. - `auto` is the default value + `required` requires the model to call one or more of the allowed tools. - `"auto"` - - `class ResponseFormatText: …` + - `"required"` - Default response format. Used to generate text responses. + - `tools: List[Dict[str, object]]` - - `type: Literal["text"]` + A list of tool definitions that the model should be allowed to call. - The type of response format being defined. Always `text`. + For the Responses API, the list of tool definitions might look like: - - `"text"` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `class ResponseFormatJSONObject: …` + - `type: Literal["allowed_tools"]` - 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. + Allowed tool configuration type. Always `allowed_tools`. - - `type: Literal["json_object"]` + - `"allowed_tools"` - The type of response format being defined. Always `json_object`. + - `class BetaToolChoiceTypes: …` - - `"json_object"` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `class ResponseFormatJSONSchema: …` + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `json_schema: JSONSchema` + Allowed values are: - Structured Outputs configuration options, including a JSON Schema. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `name: str` + - `"file_search"` - 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. + - `"web_search_preview"` - - `description: Optional[str]` + - `"computer"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"computer_use_preview"` - - `schema: Optional[Dict[str, object]]` + - `"computer_use"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"web_search_preview_2025_03_11"` - - `strict: Optional[bool]` + - `"image_generation"` - 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). + - `"code_interpreter"` - - `type: Literal["json_schema"]` + - `class BetaToolChoiceFunction: …` - The type of response format being defined. Always `json_schema`. + Use this option to force the model to call a specific function. - - `"json_schema"` + - `name: str` - - `started_at: Optional[int]` + The name of the function to call. - The Unix timestamp (in seconds) for when the run was started. + - `type: Literal["function"]` - - `status: object` + For function calling, the type is always `function`. - - `thread_id: str` + - `"function"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `class BetaToolChoiceMcp: …` - - `tool_choice: Optional[AssistantToolChoiceOption]` + Use this option to force the model to call a specific tool on a remote MCP server. - 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. + - `server_label: str` - - `Literal["none", "auto", "required"]` + The label of the MCP server to use. - `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. + - `type: Literal["mcp"]` - - `"none"` + For MCP tools, the type is always `mcp`. - - `"auto"` + - `"mcp"` - - `"required"` + - `name: Optional[str]` - - `class AssistantToolChoice: …` + The name of the tool to call on the server. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `class BetaToolChoiceCustom: …` - - `type: Literal["function", "code_interpreter", "file_search"]` + Use this option to force the model to call a specific custom tool. - The type of the tool. If type is `function`, the function name must be set + - `name: str` - - `"function"` + The name of the custom tool to call. - - `"code_interpreter"` + - `type: Literal["custom"]` - - `"file_search"` + For custom tool calling, the type is always `custom`. - - `function: Optional[AssistantToolChoiceFunction]` + - `"custom"` - - `name: str` + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` - The name of the function to call. + - `type: Literal["programmatic_tool_calling"]` - - `tools: List[object]` + The tool to call. Always `programmatic_tool_calling`. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"programmatic_tool_calling"` - - `truncation_strategy: Optional[TruncationStrategy]` + - `class BetaToolChoiceApplyPatch: …` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + Forces the model to call the apply_patch tool when executing a tool call. - - `type: Literal["auto", "last_messages"]` + - `type: Literal["apply_patch"]` - 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`. + The tool to call. Always `apply_patch`. - - `"auto"` + - `"apply_patch"` - - `"last_messages"` + - `class BetaToolChoiceShell: …` - - `last_messages: Optional[int]` + Forces the model to call the shell tool when a tool call is required. - The number of most recent messages from the thread when constructing the context for the run. + - `type: Literal["shell"]` - - `usage: Optional[Usage]` + The tool to call. Always `shell`. - 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.). + - `"shell"` - - `completion_tokens: int` + - `tools: List[BetaTool]` - Number of completion tokens used over the course of the run. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `prompt_tokens: int` + We support the following categories of tools: - Number of prompt tokens used over the course of the run. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `total_tokens: int` + - `class BetaFunctionTool: …` - Total number of tokens used (prompt + completion). + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `temperature: Optional[float]` + - `class BetaFileSearchTool: …` - The sampling temperature used for this run. If not set, defaults to 1. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `top_p: Optional[float]` + - `class BetaComputerTool: …` - The nucleus sampling value used for this run. If not set, defaults to 1. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). -### Run Status + - `class BetaComputerUsePreviewTool: …` -- `object` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). -# Steps + - `class BetaWebSearchTool: …` -## List run steps + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). -`beta.threads.runs.steps.list(strrun_id, StepListParams**kwargs) -> SyncCursorPage[RunStep]` + - `class Mcp: …` -**get** `/threads/{thread_id}/runs/{run_id}/steps` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). -List run steps + - `class CodeInterpreter: …` -### Parameters + A tool that runs Python code to help generate a response to a prompt. -- `thread_id: str` + - `class ProgrammaticToolCalling: …` -- `run_id: str` + - `class ImageGeneration: …` -- `after: Optional[str]` + A tool that generates images using the GPT image models. - 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. + - `class LocalShell: …` -- `before: Optional[str]` + A tool that allows the model to execute shell commands in a local environment. - 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. + - `class BetaFunctionShellTool: …` -- `include: Optional[List[RunStepInclude]]` + A tool that allows the model to execute shell commands. - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + - `class BetaCustomTool: …` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `"step_details.tool_calls[*].file_search.results[*].content"` + - `class BetaNamespaceTool: …` -- `limit: Optional[int]` + Groups function/custom tools under a shared namespace. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `class BetaToolSearchTool: …` -- `order: Optional[Literal["asc", "desc"]]` + Hosted or BYOT tool search configuration for deferred tools. - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `class BetaWebSearchPreviewTool: …` - - `"asc"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"desc"` + - `class BetaApplyPatchTool: …` -### Returns + Allows the assistant to create, delete, or update files using unified diffs. -- `class RunStep: …` + - `top_p: Optional[float]` - Represents a step in execution of a run. + 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. - - `id: str` + We generally recommend altering this or `temperature` but not both. - The identifier of the run step, which can be referenced in API endpoints. + - `background: Optional[bool]` - - `assistant_id: str` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `completed_at: Optional[float]` - - `cancelled_at: Optional[int]` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The Unix timestamp (in seconds) for when the run step was cancelled. + - `conversation: Optional[Conversation]` - - `completed_at: Optional[int]` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The Unix timestamp (in seconds) for when the run step completed. + - `id: str` - - `created_at: int` + The unique ID of the conversation that this response was associated with. - The Unix timestamp (in seconds) for when the run step was created. + - `max_output_tokens: Optional[int]` - - `expired_at: Optional[int]` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `max_tool_calls: Optional[int]` - - `failed_at: Optional[int]` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - The Unix timestamp (in seconds) for when the run step failed. + - `moderation: Optional[Moderation]` - - `last_error: Optional[LastError]` + Moderation results for the response input and output, if moderated completions were requested. - The last error associated with this run step. Will be `null` if there are no errors. + - `input: ModerationInput` - - `code: Literal["server_error", "rate_limit_exceeded"]` + Moderation for the response input. - One of `server_error` or `rate_limit_exceeded`. + - `class ModerationInputModerationResult: …` - - `"server_error"` + A moderation result produced for the response input or output. - - `"rate_limit_exceeded"` + - `categories: Dict[str, bool]` - - `message: str` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - A human-readable description of the error. + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - - `metadata: Optional[Metadata]` + Which modalities of input are reflected by the score for each category. - 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. + - `"text"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"image"` - - `object: Literal["thread.run.step"]` + - `category_scores: Dict[str, float]` - The object type, which is always `thread.run.step`. + A dictionary of moderation categories to scores. - - `"thread.run.step"` + - `flagged: bool` - - `run_id: str` + A boolean indicating whether the content was flagged by any category. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `model: str` - - `status: Literal["in_progress", "cancelled", "failed", 2 more]` + The moderation model that produced this result. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `type: Literal["moderation_result"]` - - `"in_progress"` + The object type, which was always `moderation_result` for successful moderation results. - - `"cancelled"` + - `"moderation_result"` - - `"failed"` + - `class ModerationInputError: …` - - `"completed"` + An error produced while attempting moderation for the response input or output. - - `"expired"` + - `code: str` - - `step_details: StepDetails` + The error code. - The details of the run step. + - `message: str` - - `class MessageCreationStepDetails: …` + The error message. - Details of the message creation by the run step. + - `type: Literal["error"]` - - `message_creation: MessageCreation` + The object type, which was always `error` for moderation failures. - - `message_id: str` + - `"error"` - The ID of the message that was created by this run step. + - `output: ModerationOutput` - - `type: Literal["message_creation"]` + Moderation for the response output. - Always `message_creation`. + - `class ModerationOutputModerationResult: …` - - `"message_creation"` + A moderation result produced for the response input or output. - - `class ToolCallsStepDetails: …` + - `categories: Dict[str, bool]` - Details of the tool call. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `tool_calls: List[object]` + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - 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`. + Which modalities of input are reflected by the score for each category. - - `type: Literal["tool_calls"]` + - `"text"` - Always `tool_calls`. + - `"image"` - - `"tool_calls"` + - `category_scores: Dict[str, float]` - - `thread_id: str` + A dictionary of moderation categories to scores. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `flagged: bool` - - `type: Literal["message_creation", "tool_calls"]` + A boolean indicating whether the content was flagged by any category. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `model: str` - - `"message_creation"` + The moderation model that produced this result. - - `"tool_calls"` + - `type: Literal["moderation_result"]` - - `usage: Optional[Usage]` + The object type, which was always `moderation_result` for successful moderation results. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `"moderation_result"` - - `completion_tokens: int` + - `class ModerationOutputError: …` - Number of completion tokens used over the course of the run step. + An error produced while attempting moderation for the response input or output. - - `prompt_tokens: int` + - `code: str` - Number of prompt tokens used over the course of the run step. + The error code. - - `total_tokens: int` + - `message: str` - Total number of tokens used (prompt + completion). + The error message. -### Example + - `type: Literal["error"]` -```python -import os -from openai import OpenAI + The object type, which was always `error` for moderation failures. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -page = client.beta.threads.runs.steps.list( - run_id="run_id", - thread_id="thread_id", -) -page = page.data[0] -print(page.id) -``` + - `"error"` -#### Response + - `previous_response_id: Optional[str]` -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expired_at": 0, - "failed_at": 0, - "last_error": { - "code": "server_error", - "message": "message" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.run.step", - "run_id": "run_id", - "status": "in_progress", - "step_details": { - "message_creation": { - "message_id": "message_id" - }, - "type": "message_creation" - }, - "thread_id": "thread_id", - "type": "message_creation", - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - } - } - ], - "first_id": "step_abc123", - "has_more": false, - "last_id": "step_abc456", - "object": "list" -} -``` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. -### Example + - `prompt: Optional[BetaResponsePrompt]` -```python -from openai import OpenAI -client = OpenAI() + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). -run_steps = client.beta.threads.runs.steps.list( - thread_id="thread_abc123", - run_id="run_abc123" -) + - `id: str` -print(run_steps) -``` + The unique identifier of the prompt template to use. -#### Response + - `variables: Optional[Dict[str, Variables]]` -```json -{ - "object": "list", - "data": [ - { - "id": "step_abc123", - "object": "thread.run.step", - "created_at": 1699063291, - "run_id": "run_abc123", - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "type": "message_creation", - "status": "completed", - "cancelled_at": null, - "completed_at": 1699063291, - "expired_at": null, - "failed_at": null, - "last_error": null, - "step_details": { - "type": "message_creation", - "message_creation": { - "message_id": "msg_abc123" - } - }, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - } - } - ], - "first_id": "step_abc123", - "last_id": "step_abc456", - "has_more": false -} -``` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. -## Retrieve run step + - `str` -`beta.threads.runs.steps.retrieve(strstep_id, StepRetrieveParams**kwargs) -> RunStep` + - `class BetaResponseInputText: …` -**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` + A text input to the model. -Retrieve run step + - `class BetaResponseInputImage: …` -### Parameters + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). -- `thread_id: str` + - `class BetaResponseInputFile: …` -- `run_id: str` + A file input to the model. -- `step_id: str` + - `version: Optional[str]` -- `include: Optional[List[RunStepInclude]]` + Optional version of the prompt template. - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + - `prompt_cache_key: Optional[str]` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `"step_details.tool_calls[*].file_search.results[*].content"` + - `prompt_cache_options: Optional[PromptCacheOptions]` -### Returns + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. -- `class RunStep: …` + - `mode: Literal["implicit", "explicit"]` - Represents a step in execution of a run. + Whether implicit prompt-cache breakpoints were enabled. - - `id: str` + - `"implicit"` - The identifier of the run step, which can be referenced in API endpoints. + - `"explicit"` - - `assistant_id: str` + - `ttl: Literal["30m"]` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + The minimum lifetime applied to each cache breakpoint. - - `cancelled_at: Optional[int]` + - `"30m"` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` - - `completed_at: Optional[int]` + Deprecated. Use `prompt_cache_options.ttl` instead. - The Unix timestamp (in seconds) for when the run step completed. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `created_at: int` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The Unix timestamp (in seconds) for when the run step was created. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `expired_at: Optional[int]` + - `"in_memory"` + + - `"24h"` + + - `reasoning: Optional[Reasoning]` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. + + - `"auto"` + + - `"current_turn"` + + - `"all_turns"` + + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. + + - `"none"` + + - `"minimal"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `"max"` + + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `str` + + - `Literal["standard", "pro"]` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `"standard"` + + - `"pro"` + + - `summary: Optional[Literal["auto", "concise", "detailed"]]` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `safety_identifier: Optional[str]` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"scale"` + + - `"priority"` + + - `status: Optional[BetaResponseStatus]` + + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + + - `"completed"` + + - `"failed"` + + - `"in_progress"` + + - `"cancelled"` + + - `"queued"` + + - `"incomplete"` + + - `text: Optional[BetaResponseTextConfig]` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + + - `format: Optional[BetaResponseFormatTextConfig]` + + An object specifying the format that the model must output. + + Configuring `{ "type": "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). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `class Text: …` + + Default response format. Used to generate text responses. + + - `type: Literal["text"]` + + The type of response format being defined. Always `text`. + + - `"text"` + + - `class BetaResponseFormatTextJSONSchemaConfig: …` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + + - `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. + + - `schema: 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/). + + - `type: Literal["json_schema"]` + + The type of response format being defined. Always `json_schema`. + + - `"json_schema"` + + - `description: Optional[str]` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `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). + + - `class JSONObject: …` + + 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"` + + - `verbosity: Optional[Literal["low", "medium", "high"]]` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `top_logprobs: Optional[int]` + + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + + - `truncation: Optional[Literal["auto", "disabled"]]` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `"auto"` + + - `"disabled"` + + - `usage: Optional[BetaResponseUsage]` + + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + + - `input_tokens: int` + + The number of input tokens. + + - `input_tokens_details: InputTokensDetails` + + A detailed breakdown of the input tokens. + + - `cache_write_tokens: int` + + The number of input tokens that were written to the cache. + + - `cached_tokens: int` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + + - `output_tokens: int` + + The number of output tokens. + + - `output_tokens_details: OutputTokensDetails` + + A detailed breakdown of the output tokens. + + - `reasoning_tokens: int` + + The number of reasoning tokens. + + - `total_tokens: int` + + The total number of tokens used. + + - `user: Optional[str]` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + +### 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 +) +for response in client.beta.responses.create(): + print(response) +``` + +#### Response + +```json +{ + "id": "id", + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "text": "text", + "type": "output_text", + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ] + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "phase": "commentary" + } + ], + "parallel_tool_calls": true, + "temperature": 1, + "tool_choice": "none", + "tools": [ + { + "name": "name", + "parameters": { + "foo": "bar" + }, + "strict": true, + "type": "function", + "allowed_callers": [ + "direct" + ], + "defer_loading": true, + "description": "description", + "output_schema": { + "foo": "bar" + } + } + ], + "top_p": 1, + "background": true, + "completed_at": 0, + "conversation": { + "id": "id" + }, + "max_output_tokens": 0, + "max_tool_calls": 0, + "moderation": { + "input": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + }, + "output": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + } + }, + "output_text": "output_text", + "previous_response_id": "previous_response_id", + "prompt": { + "id": "id", + "variables": { + "foo": "string" + }, + "version": "version" + }, + "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, + "prompt_cache_retention": "in_memory", + "reasoning": { + "context": "auto", + "effort": "none", + "generate_summary": "auto", + "mode": "standard", + "summary": "auto" + }, + "safety_identifier": "safety-identifier-1234", + "service_tier": "auto", + "status": "completed", + "text": { + "format": { + "type": "text" + }, + "verbosity": "low" + }, + "top_logprobs": 0, + "truncation": "auto", + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "cache_write_tokens": 0, + "cached_tokens": 0 + }, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + }, + "user": "user-1234" +} +``` + +### Text input + +```python +from openai import OpenAI + +client = OpenAI() + +response = client.responses.create( + model="gpt-5.4", + input="Tell me a three sentence bedtime story about a unicorn." +) + +print(response) +``` + +#### Response + +```json +{ + "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b", + "object": "response", + "created_at": 1741476542, + "status": "completed", + "completed_at": 1741476543, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "message", + "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "In a peaceful grove beneath a silver moon, a unicorn named Lumina discovered a hidden pool that reflected the stars. As she dipped her horn into the water, the pool began to shimmer, revealing a pathway to a magical realm of endless night skies. Filled with wonder, Lumina whispered a wish for all who dream to find their own hidden magic, and as she glanced back, her hoofprints sparkled like stardust.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 36, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 87, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 123 + }, + "user": null, + "metadata": {} +} +``` + +### Image input + +```python +from openai import OpenAI + +client = OpenAI() + +response = client.responses.create( + model="gpt-5.4", + input=[ + { + "role": "user", + "content": [ + { "type": "input_text", "text": "what is in this image?" }, + { + "type": "input_image", + "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" + } + ] + } + ] +) + +print(response) +``` + +#### Response + +```json +{ + "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", + "object": "response", + "created_at": 1741476777, + "status": "completed", + "completed_at": 1741476778, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "message", + "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 52, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 380 + }, + "user": null, + "metadata": {} +} +``` + +### File input + +```python +from openai import OpenAI + +client = OpenAI() + +response = client.responses.create( + model="gpt-5.4", + input=[ + { + "role": "user", + "content": [ + { "type": "input_text", "text": "what is in this file?" }, + { + "type": "input_file", + "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf", + "detail": "auto" + } + ] + } + ] +) + +print(response) +``` + +#### Response + +```json +{ + "id": "resp_686eef60237881a2bd1180bb8b13de430e34c516d176ff86", + "object": "response", + "created_at": 1752100704, + "status": "completed", + "completed_at": 1752100705, + "background": false, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "max_tool_calls": null, + "model": "gpt-5.4", + "output": [ + { + "id": "msg_686eef60d3e081a29283bdcbc4322fd90e34c516d176ff86", + "type": "message", + "status": "completed", + "content": [ + { + "type": "output_text", + "annotations": [], + "logprobs": [], + "text": "The file seems to contain excerpts from a letter to the shareholders of Berkshire Hathaway Inc., likely written by Warren Buffett. It covers several topics:\n\n1. **Communication Philosophy**: Buffett emphasizes the importance of transparency and candidness in reporting mistakes and successes to shareholders.\n\n2. **Mistakes and Learnings**: The letter acknowledges past mistakes in business assessments and management hires, highlighting the importance of correcting errors promptly.\n\n3. **CEO Succession**: Mention of Greg Abel stepping in as the new CEO and continuing the tradition of honest communication.\n\n4. **Pete Liegl Story**: A detailed account of acquiring Forest River and the relationship with its founder, highlighting trust and effective business decisions.\n\n5. **2024 Performance**: Overview of business performance, particularly in insurance and investment activities, with a focus on GEICO's improvement.\n\n6. **Tax Contributions**: Discussion of significant tax payments to the U.S. Treasury, credited to shareholders' reinvestments.\n\n7. **Investment Strategy**: A breakdown of Berkshire\u2019s investments in both controlled subsidiaries and marketable equities, along with a focus on long-term holding strategies.\n\n8. **American Capitalism**: Reflections on America\u2019s economic development and Berkshire\u2019s role within it.\n\n9. **Property-Casualty Insurance**: Insights into the P/C insurance business model and its challenges and benefits.\n\n10. **Japanese Investments**: Information about Berkshire\u2019s investments in Japanese companies and future plans.\n\n11. **Annual Meeting**: Details about the upcoming annual gathering in Omaha, including schedule changes and new book releases.\n\n12. **Personal Anecdotes**: Light-hearted stories about family and interactions, conveying Buffett's personable approach.\n\n13. **Financial Performance Data**: Tables comparing Berkshire\u2019s annual performance to the S&P 500, showing impressive long-term gains.\n\nOverall, the letter reinforces Berkshire Hathaway's commitment to transparency, investment in both its businesses and the wider economy, and emphasizes strong leadership and prudent financial management." + } + ], + "role": "assistant" + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "service_tier": "default", + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_logprobs": 0, + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 8438, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 398, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 8836 + }, + "user": null, + "metadata": {} +} +``` + +### Web search + +```python +from openai import OpenAI + +client = OpenAI() + +response = client.responses.create( + model="gpt-5.4", + tools=[{ "type": "web_search_preview" }], + input="What was a positive news story from today?", +) + +print(response) +``` + +#### Response + +```json +{ + "id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c", + "object": "response", + "created_at": 1741484430, + "status": "completed", + "completed_at": 1741484431, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "web_search_call", + "id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c", + "status": "completed" + }, + { + "type": "message", + "id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "As of today, March 9, 2025, one notable positive news story...", + "annotations": [ + { + "type": "url_citation", + "start_index": 442, + "end_index": 557, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + }, + { + "type": "url_citation", + "start_index": 962, + "end_index": 1077, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + }, + { + "type": "url_citation", + "start_index": 1336, + "end_index": 1451, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + } + ] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "web_search_preview", + "domains": [], + "search_context_size": "medium", + "user_location": { + "type": "approximate", + "city": null, + "country": "US", + "region": null, + "timezone": null + } + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 356, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 684 + }, + "user": null, + "metadata": {} +} +``` + +### File search + +```python +from openai import OpenAI + +client = OpenAI() + +response = client.responses.create( + model="gpt-5.4", + tools=[{ + "type": "file_search", + "vector_store_ids": ["vs_1234567890"], + "max_num_results": 20 + }], + input="What are the attributes of an ancient brown dragon?", +) + +print(response) +``` + +#### Response + +```json +{ + "id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7", + "object": "response", + "created_at": 1741485253, + "status": "completed", + "completed_at": 1741485254, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "file_search_call", + "id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7", + "status": "completed", + "queries": [ + "attributes of an ancient brown dragon" + ], + "results": null + }, + { + "type": "message", + "id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The attributes of an ancient brown dragon include...", + "annotations": [ + { + "type": "file_citation", + "index": 320, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 576, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 815, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 815, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1030, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1030, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1156, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1225, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + } + ] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "file_search", + "filters": null, + "max_num_results": 20, + "ranking_options": { + "ranker": "auto", + "score_threshold": 0.0 + }, + "vector_store_ids": [ + "vs_1234567890" + ] + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 18307, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 348, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 18655 + }, + "user": null, + "metadata": {} +} +``` + +### Streaming + +```python +from openai import OpenAI + +client = OpenAI() + +response = client.responses.create( + model="gpt-5.4", + instructions="You are a helpful assistant.", + input="Hello!", + stream=True +) + +for event in response: + print(event) +``` + +#### Response + +```json +event: response.created +data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}} + +event: response.in_progress +data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}} + +event: response.output_item.added +data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}} + +event: response.content_part.added +data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hi"} + +... + +event: response.output_text.done +data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"Hi there! How can I assist you today?"} + +event: response.content_part.done +data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}} + +event: response.output_item.done +data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}} + +event: response.completed +data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}} +``` + +### Functions + +```python +from openai import OpenAI + +client = OpenAI() + +tools = [ + { + "type": "function", + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, + }, + "required": ["location", "unit"], + } + } +] + +response = client.responses.create( + model="gpt-5.4", + tools=tools, + input="What is the weather like in Boston today?", + tool_choice="auto" +) + +print(response) +``` + +#### Response + +```json +{ + "id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0", + "object": "response", + "created_at": 1741294021, + "status": "completed", + "completed_at": 1741294022, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "function_call", + "id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0", + "call_id": "call_unLAR8MvFNptuiZK6K6HCy5k", + "name": "get_current_weather", + "arguments": "{\"location\":\"Boston, MA\",\"unit\":\"celsius\"}", + "status": "completed" + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "function", + "description": "Get the current weather in a given location", + "name": "get_current_weather", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": [ + "celsius", + "fahrenheit" + ] + } + }, + "required": [ + "location", + "unit" + ] + }, + "strict": true + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 291, + "output_tokens": 23, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 314 + }, + "user": null, + "metadata": {} +} +``` + +### Reasoning + +```python +from openai import OpenAI +client = OpenAI() + +response = client.responses.create( + model="o3-mini", + input="How much wood would a woodchuck chuck?", + reasoning={ + "effort": "high" + } +) + +print(response) +``` + +#### Response + +```json +{ + "id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808", + "object": "response", + "created_at": 1741477868, + "status": "completed", + "completed_at": 1741477869, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "o1-2024-12-17", + "output": [ + { + "type": "message", + "id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The classic tongue twister...", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": "high", + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 81, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 1035, + "output_tokens_details": { + "reasoning_tokens": 832 + }, + "total_tokens": 1116 + }, + "user": null, + "metadata": {} +} +``` + +## Get a model response + +`beta.responses.retrieve(strresponse_id, ResponseRetrieveParams**kwargs) -> BetaResponse` + +**get** `/responses/{response_id}?beta=true` + +Retrieves a model response with the given ID. + +### Parameters + +- `response_id: str` + +- `include: Optional[List[BetaResponseIncludable]]` + + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. + + - `"file_search_call.results"` + + - `"web_search_call.results"` + + - `"web_search_call.action.sources"` + + - `"message.input_image.image_url"` + + - `"computer_call_output.output.image_url"` + + - `"code_interpreter_call.outputs"` + + - `"reasoning.encrypted_content"` + + - `"message.output_text.logprobs"` + +- `include_obfuscation: Optional[bool]` + + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events + to normalize payload sizes as a mitigation to certain side-channel + attacks. These obfuscation fields are included by default, but add a + small amount of overhead to the data stream. You can set + `include_obfuscation` to false to optimize for bandwidth if you trust + the network links between your application and the OpenAI API. + +- `starting_after: Optional[int]` + + The sequence number of the event after which to start streaming. + +- `stream: Optional[Literal[false]]` + + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) + for more information. + + - `false` + +- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` + + - `"responses_multi_agent=v1"` + +### Returns + +- `class BetaResponse: …` + + - `id: str` + + Unique identifier for this Response. + + - `created_at: float` + + Unix timestamp (in seconds) of when this Response was created. + + - `error: Optional[BetaResponseError]` + + An error object returned when the model fails to generate a Response. + + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + + The error code for the response. + + - `"server_error"` + + - `"rate_limit_exceeded"` + + - `"invalid_prompt"` + + - `"bio_policy"` + + - `"vector_store_timeout"` + + - `"invalid_image"` + + - `"invalid_image_format"` + + - `"invalid_base64_image"` + + - `"invalid_image_url"` + + - `"image_too_large"` + + - `"image_too_small"` + + - `"image_parse_error"` + + - `"image_content_policy_violation"` + + - `"invalid_image_mode"` + + - `"image_file_too_large"` + + - `"unsupported_image_media_type"` + + - `"empty_image_file"` + + - `"failed_to_download_image"` + + - `"image_file_not_found"` + + - `message: str` + + A human-readable description of the error. + + - `incomplete_details: Optional[IncompleteDetails]` + + Details about why the response is incomplete. + + - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` + + The reason why the response is incomplete. + + - `"max_output_tokens"` + + - `"content_filter"` + + - `instructions: Union[str, List[BetaResponseInputItem], null]` + + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + + - `str` + + A text input to the model, equivalent to a text input with the + `developer` role. + + - `List[BetaResponseInputItem]` + + A list of one or many input items to the model, containing + different content types. + + - `class BetaEasyInputMessage: …` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: Union[str, BetaResponseInputMessageContentList]` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `str` + + A text input to the model. + + - `List[BetaResponseInputContent]` + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `text: str` + + The text input to the model. + + - `type: Literal["input_text"]` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: Literal["low", "high", "auto", "original"]` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: Literal["input_image"]` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `image_url: Optional[str]` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `type: Literal["input_file"]` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: Optional[Literal["auto", "low", "high"]]` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: Optional[str]` + + The content of the file to be sent to the model. + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `file_url: Optional[str]` + + The URL of the file to be sent to the model. + + - `filename: Optional[str]` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `role: Literal["user", "assistant", "system", "developer"]` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"developer"` + + - `phase: Optional[Literal["commentary", "final_answer"]]` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `type: Optional[Literal["message"]]` + + The type of the message input. Always `message`. + + - `"message"` + + - `class Message: …` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: BetaResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `role: Literal["user", "system", "developer"]` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `agent: Optional[MessageAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Optional[Literal["message"]]` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `class BetaResponseOutputMessage: …` + + An output message from the model. + + - `id: str` + + The unique ID of the output message. + + - `content: List[Content]` + + The content of the output message. + + - `class BetaResponseOutputText: …` + + A text output from the model. + + - `annotations: List[Annotation]` + + The annotations of the text output. + + - `class AnnotationFileCitation: …` + + A citation to a file. + + - `file_id: str` + + The ID of the file. + + - `filename: str` + + The filename of the file cited. + + - `index: int` + + The index of the file in the list of files. + + - `type: Literal["file_citation"]` + + The type of the file citation. Always `file_citation`. + + - `"file_citation"` + + - `class AnnotationURLCitation: …` + + A citation for a web resource used to generate a model response. + + - `end_index: int` + + The index of the last character of the URL citation in the message. + + - `start_index: int` + + The index of the first character of the URL citation in the message. + + - `title: str` + + The title of the web resource. + + - `type: Literal["url_citation"]` + + The type of the URL citation. Always `url_citation`. + + - `"url_citation"` + + - `url: str` + + The URL of the web resource. + + - `class AnnotationContainerFileCitation: …` + + A citation for a container file used to generate a model response. + + - `container_id: str` + + The ID of the container file. + + - `end_index: int` + + The index of the last character of the container file citation in the message. + + - `file_id: str` + + The ID of the file. + + - `filename: str` + + The filename of the container file cited. + + - `start_index: int` + + The index of the first character of the container file citation in the message. + + - `type: Literal["container_file_citation"]` + + The type of the container file citation. Always `container_file_citation`. + + - `"container_file_citation"` + + - `class AnnotationFilePath: …` + + A path to a file. + + - `file_id: str` + + The ID of the file. + + - `index: int` + + The index of the file in the list of files. + + - `type: Literal["file_path"]` + + The type of the file path. Always `file_path`. + + - `"file_path"` + + - `text: str` + + The text output from the model. + + - `type: Literal["output_text"]` + + The type of the output text. Always `output_text`. + + - `"output_text"` + + - `logprobs: Optional[List[Logprob]]` + + - `token: str` + + - `bytes: List[int]` + + - `logprob: float` + + - `top_logprobs: List[LogprobTopLogprob]` + + - `token: str` + + - `bytes: List[int]` + + - `logprob: float` + + - `class BetaResponseOutputRefusal: …` + + A refusal from the model. + + - `refusal: str` + + The refusal explanation from the model. + + - `type: Literal["refusal"]` + + The type of the refusal. Always `refusal`. + + - `"refusal"` + + - `role: Literal["assistant"]` + + The role of the output message. Always `assistant`. + + - `"assistant"` + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["message"]` + + The type of the output message. Always `message`. + + - `"message"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `phase: Optional[Literal["commentary", "final_answer"]]` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `class BetaResponseFileSearchToolCall: …` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `id: str` + + The unique ID of the file search tool call. + + - `queries: List[str]` + + The queries used to search for files. + + - `status: Literal["in_progress", "searching", "completed", 2 more]` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: Literal["file_search_call"]` + + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `results: Optional[List[Result]]` + + The results of the file search tool call. + + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + + 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, booleans, or numbers. + + - `str` + + - `float` + + - `bool` + + - `file_id: Optional[str]` + + The unique ID of the file. + + - `filename: Optional[str]` + + The name of the file. + + - `score: Optional[float]` + + The relevance score of the file - a value between 0 and 1. + + - `text: Optional[str]` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall: …` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `id: str` + + The unique ID of the computer call. + + - `call_id: str` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: List[PendingSafetyCheck]` + + The pending safety checks for the computer call. + + - `id: str` + + The ID of the pending safety check. + + - `code: Optional[str]` + + The type of the pending safety check. + + - `message: Optional[str]` + + Details about the pending safety check. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["computer_call"]` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: Optional[BetaComputerAction]` + + A click action. + + - `class Click: …` + + A click action. + + - `button: Literal["left", "right", "wheel", 2 more]` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: Literal["click"]` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: int` + + The x-coordinate where the click occurred. + + - `y: int` + + The y-coordinate where the click occurred. + + - `keys: Optional[List[str]]` + + The keys being held while clicking. + + - `class DoubleClick: …` + + A double click action. + + - `keys: Optional[List[str]]` + + The keys being held while double-clicking. + + - `type: Literal["double_click"]` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: int` + + The x-coordinate where the double click occurred. + + - `y: int` + + The y-coordinate where the double click occurred. + + - `class Drag: …` + + A drag action. + + - `path: List[DragPath]` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: int` + + The x-coordinate. + + - `y: int` + + The y-coordinate. + + - `type: Literal["drag"]` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: Optional[List[str]]` + + The keys being held while dragging the mouse. + + - `class Keypress: …` + + A collection of keypresses the model would like to perform. + + - `keys: List[str]` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: Literal["keypress"]` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `class Move: …` + + A mouse move action. + + - `type: Literal["move"]` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: int` + + The x-coordinate to move to. + + - `y: int` + + The y-coordinate to move to. + + - `keys: Optional[List[str]]` + + The keys being held while moving the mouse. + + - `class Screenshot: …` + + A screenshot action. + + - `type: Literal["screenshot"]` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `class Scroll: …` + + A scroll action. + + - `scroll_x: int` + + The horizontal scroll distance. + + - `scroll_y: int` + + The vertical scroll distance. + + - `type: Literal["scroll"]` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: int` + + The x-coordinate where the scroll occurred. + + - `y: int` + + The y-coordinate where the scroll occurred. + + - `keys: Optional[List[str]]` + + The keys being held while scrolling. + + - `class Type: …` + + An action to type in text. + + - `text: str` + + The text to type. + + - `type: Literal["type"]` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `class Wait: …` + + A wait action. + + - `type: Literal["wait"]` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + + - `actions: Optional[BetaComputerActionList]` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `class Click: …` + + A click action. + + - `class DoubleClick: …` + + A double click action. + + - `class Drag: …` + + A drag action. + + - `class Keypress: …` + + A collection of keypresses the model would like to perform. + + - `class Move: …` + + A mouse move action. + + - `class Screenshot: …` + + A screenshot action. + + - `class Scroll: …` + + A scroll action. + + - `class Type: …` + + An action to type in text. + + - `class Wait: …` + + A wait action. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ComputerCallOutput: …` + + The output of a computer tool call. + + - `call_id: str` + + The ID of the computer tool call that produced the output. + + - `output: BetaResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: Literal["computer_screenshot"]` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `file_id: Optional[str]` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: Optional[str]` + + The URL of the screenshot image. + + - `type: Literal["computer_call_output"]` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `id: Optional[str]` + + The ID of the computer tool call output. + + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + + The safety checks reported by the API that have been acknowledged by the developer. + + - `id: str` + + The ID of the pending safety check. + + - `code: Optional[str]` + + The type of the pending safety check. + + - `message: Optional[str]` + + Details about the pending safety check. + + - `agent: Optional[ComputerCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class BetaResponseFunctionWebSearch: …` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `id: str` + + The unique ID of the web search tool call. + + - `action: Action` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `class ActionSearch: …` + + Action type "search" - Performs a web search query. + + - `type: Literal["search"]` + + The action type. + + - `"search"` + + - `queries: Optional[List[str]]` + + The search queries. + + - `query: Optional[str]` + + The search query. + + - `sources: Optional[List[ActionSearchSource]]` + + The sources used in the search. + + - `type: Literal["url"]` + + The type of source. Always `url`. + + - `"url"` + + - `url: str` + + The URL of the source. + + - `class ActionOpenPage: …` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: Literal["open_page"]` + + The action type. + + - `"open_page"` + + - `url: Optional[str]` + + The URL opened by the model. + + - `class ActionFindInPage: …` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: str` + + The pattern or text to search for within the page. + + - `type: Literal["find_in_page"]` + + The action type. + + - `"find_in_page"` + + - `url: str` + + The URL of the page searched for the pattern. + + - `status: Literal["in_progress", "searching", "completed", "failed"]` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: Literal["web_search_call"]` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionToolCall: …` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `arguments: str` + + A JSON string of the arguments to pass to the function. + + - `call_id: str` + + The unique ID of the function tool call generated by the model. + + - `name: str` + + The name of the function to run. + + - `type: Literal["function_call"]` + + The type of the function tool call. Always `function_call`. + + - `"function_call"` + + - `id: Optional[str]` + + The unique ID of the function tool call. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `namespace: Optional[str]` + + The namespace of the function to run. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class FunctionCallOutput: …` + + The output of a function tool call. + + - `call_id: str` + + The unique ID of the function tool call generated by the model. + + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + + Text, image, or file output of the function tool call. + + - `str` + + A JSON string of the output of the function tool call. + + - `List[BetaResponseFunctionCallOutputItem]` + + - `class BetaResponseInputTextContent: …` + + A text input to the model. + + - `text: str` + + The text input to the model. + + - `type: Literal["input_text"]` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputImageContent: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: Literal["input_image"]` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `detail: Optional[Literal["low", "high", "auto", "original"]]` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `image_url: Optional[str]` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputFileContent: …` + + A file input to the model. + + - `type: Literal["input_file"]` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: Optional[Literal["auto", "low", "high"]]` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: Optional[str]` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `file_url: Optional[str]` + + The URL of the file to be sent to the model. + + - `filename: Optional[str]` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `type: Literal["function_call_output"]` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: Optional[str]` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: Optional[FunctionCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[FunctionCallOutputCaller]` + + The execution context that produced this tool call. + + - `class FunctionCallOutputCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class FunctionCallOutputCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class AgentMessage: …` + + A message routed between agents. + + - `author: str` + + The sending agent identity. + + - `content: List[AgentMessageContent]` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent: …` + + A text input to the model. + + - `class BetaResponseInputImageContent: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `class AgentMessageContentEncryptedContent: …` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: str` + + Opaque encrypted content. + + - `type: Literal["encrypted_content"]` + + The type of the input item. Always `encrypted_content`. + + - `"encrypted_content"` + + - `recipient: str` + + The destination agent identity. + + - `type: Literal["agent_message"]` + + The item type. Always `agent_message`. + + - `"agent_message"` + + - `id: Optional[str]` + + The unique ID of this agent message item. + + - `agent: Optional[AgentMessageAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCall: …` + + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + + The multi-agent action that was executed. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: str` + + The action arguments as a JSON string. + + - `call_id: str` + + The unique ID linking this call to its output. + + - `type: Literal["multi_agent_call"]` + + The item type. Always `multi_agent_call`. + + - `"multi_agent_call"` + + - `id: Optional[str]` + + The unique ID of this multi-agent call. + + - `agent: Optional[MultiAgentCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCallOutput: …` + + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: str` + + The unique ID of the multi-agent call. + + - `output: List[MultiAgentCallOutputOutput]` + + Text output returned by the multi-agent action. + + - `text: str` + + The text content. + + - `type: Literal["output_text"]` + + The content type. Always `output_text`. + + - `"output_text"` + + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + + Citations associated with the text content. + + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + + - `file_id: str` + + The ID of the file. + + - `filename: str` + + The filename of the file cited. + + - `index: int` + + The index of the file in the list of files. + + - `type: Literal["file_citation"]` + + The citation type. Always `file_citation`. + + - `"file_citation"` + + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + + - `end_index: int` + + The index of the last character of the citation in the message. + + - `start_index: int` + + The index of the first character of the citation in the message. + + - `title: str` + + The title of the cited resource. + + - `type: Literal["url_citation"]` + + The citation type. Always `url_citation`. + + - `"url_citation"` + + - `url: str` + + The URL of the cited resource. + + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + + - `container_id: str` + + The ID of the container. + + - `end_index: int` + + The index of the last character of the citation in the message. + + - `file_id: str` + + The ID of the container file. + + - `filename: str` + + The filename of the container file cited. + + - `start_index: int` + + The index of the first character of the citation in the message. + + - `type: Literal["container_file_citation"]` + + The citation type. Always `container_file_citation`. + + - `"container_file_citation"` + + - `type: Literal["multi_agent_call_output"]` + + The item type. Always `multi_agent_call_output`. + + - `"multi_agent_call_output"` + + - `id: Optional[str]` + + The unique ID of this multi-agent call output. + + - `agent: Optional[MultiAgentCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ToolSearchCall: …` + + - `arguments: object` + + The arguments supplied to the tool search call. + + - `type: Literal["tool_search_call"]` + + The item type. Always `tool_search_call`. + + - `"tool_search_call"` + + - `id: Optional[str]` + + The unique ID of this tool search call. + + - `agent: Optional[ToolSearchCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `call_id: Optional[str]` + + The unique ID of the tool search call generated by the model. + + - `execution: Optional[Literal["server", "client"]]` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the tool search call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class BetaResponseToolSearchOutputItemParam: …` + + - `tools: List[BetaTool]` + + The loaded tool definitions returned by the tool search output. + + - `class BetaFunctionTool: …` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: str` + + The name of the function to call. + + - `parameters: Optional[Dict[str, object]]` + + A JSON schema object describing the parameters of the function. + + - `strict: Optional[bool]` + + Whether strict parameter validation is enforced for this function tool. + + - `type: Literal["function"]` + + The type of the function tool. Always `function`. + + - `"function"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: Optional[bool]` + + Whether this function is deferred and loaded via tool search. + + - `description: Optional[str]` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: Optional[Dict[str, object]]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool: …` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: Literal["file_search"]` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: List[str]` + + The IDs of the vector stores to search. + + - `filters: Optional[Filters]` + + A filter to apply. + + - `class FiltersComparisonFilter: …` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: str` + + The key to compare against the value. + + - `type: Literal["eq", "ne", "gt", 5 more]` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: Union[str, float, bool, List[Union[str, float]]]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `str` + + - `float` + + - `bool` + + - `List[Union[str, float]]` + + - `str` + + - `float` + + - `class FiltersCompoundFilter: …` + + Combine multiple filters using `and` or `or`. + + - `filters: List[FiltersCompoundFilterFilter]` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `class FiltersCompoundFilterFilterComparisonFilter: …` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: str` + + The key to compare against the value. + + - `type: Literal["eq", "ne", "gt", 5 more]` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: Union[str, float, bool, List[Union[str, float]]]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `str` + + - `float` + + - `bool` + + - `List[Union[str, float]]` + + - `str` + + - `float` + + - `object` + + - `type: Literal["and", "or"]` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: Optional[int]` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: Optional[RankingOptions]` + + Ranking options for search. + + - `hybrid_search: Optional[RankingOptionsHybridSearch]` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: float` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: float` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: Optional[float]` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `class BetaComputerTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: Literal["computer"]` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `class BetaComputerUsePreviewTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: int` + + The height of the computer display. + + - `display_width: int` + + The width of the computer display. + + - `environment: Literal["windows", "mac", "linux", 2 more]` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: Literal["computer_use_preview"]` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `class BetaWebSearchTool: …` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: Literal["web_search", "web_search_2025_08_26"]` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: Optional[Filters]` + + Filters for the search. + + - `allowed_domains: Optional[List[str]]` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: Optional[Literal["low", "medium", "high"]]` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: Optional[UserLocation]` + + The approximate location of the user. + + - `city: Optional[str]` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: Optional[str]` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: Optional[str]` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: Optional[str]` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: Optional[Literal["approximate"]]` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `class Mcp: …` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `server_label: str` + + A label for this MCP server, used to identify it in tool calls. + + - `type: Literal["mcp"]` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `allowed_tools: Optional[McpAllowedTools]` + + List of allowed tool names or a filter object. + + - `List[str]` + + A string array of allowed tool names + + - `class McpAllowedToolsMcpToolFilter: …` + + A filter object to specify which tools are allowed. + + - `read_only: Optional[bool]` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Optional[List[str]]` + + List of allowed tool names. + + - `authorization: Optional[str]` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: Optional[bool]` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: Optional[Dict[str, str]]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: Optional[McpRequireApproval]` + + Specify which of the MCP server's tools require approval. + + - `class McpRequireApprovalMcpToolApprovalFilter: …` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + + A filter object to specify which tools are allowed. + + - `read_only: Optional[bool]` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Optional[List[str]]` + + List of allowed tool names. + + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + + A filter object to specify which tools are allowed. + + - `read_only: Optional[bool]` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Optional[List[str]]` + + List of allowed tool names. + + - `Literal["always", "never"]` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: Optional[str]` + + Optional description of the MCP server, used to provide more context. + + - `server_url: Optional[str]` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `tunnel_id: Optional[str]` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `class CodeInterpreter: …` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: CodeInterpreterContainer` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `str` + + The container ID. + + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: Literal["auto"]` + + Always `auto`. + + - `"auto"` + + - `file_ids: Optional[List[str]]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled: …` + + - `type: Literal["disabled"]` + + Disable outbound network access. Always `disabled`. + + - `"disabled"` + + - `class BetaContainerNetworkPolicyAllowlist: …` + + - `allowed_domains: List[str]` + + A list of allowed domains when type is `allowlist`. + + - `type: Literal["allowlist"]` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `"allowlist"` + + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + + Optional domain-scoped secrets for allowlisted domains. + + - `domain: str` + + The domain associated with the secret. + + - `name: str` + + The name of the secret to inject for the domain. + + - `value: str` + + The secret value to inject for the domain. + + - `type: Literal["code_interpreter"]` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `class ProgrammaticToolCalling: …` + + - `type: Literal["programmatic_tool_calling"]` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + + - `class ImageGeneration: …` + + A tool that generates images using the GPT image models. + + - `type: Literal["image_generation"]` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: Optional[Literal["generate", "edit", "auto"]]` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: Optional[Literal["transparent", "opaque", "auto"]]` + + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: Optional[Literal["high", "low"]]` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: Optional[ImageGenerationInputImageMask]` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: Optional[str]` + + File ID for the mask image. + + - `image_url: Optional[str]` + + Base64-encoded mask image. + + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + + The image generation model to use. Default: `gpt-image-1`. + + - `str` + + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + + - `"gpt-image-1.5"` + + - `"chatgpt-image-latest"` + + - `moderation: Optional[Literal["auto", "low"]]` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: Optional[int]` + + Compression level for the output image. Default: 100. + + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: Optional[int]` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `str` + + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `class LocalShell: …` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: Literal["local_shell"]` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `class BetaFunctionShellTool: …` + + A tool that allows the model to execute shell commands. + + - `type: Literal["shell"]` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `environment: Optional[Environment]` + + - `class BetaContainerAuto: …` + + - `type: Literal["container_auto"]` + + Automatically creates a container for this request + + - `"container_auto"` + + - `file_ids: Optional[List[str]]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + + The memory limit for the container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: Optional[NetworkPolicy]` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled: …` + + - `class BetaContainerNetworkPolicyAllowlist: …` + + - `skills: Optional[List[Skill]]` + + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference: …` + + - `skill_id: str` + + The ID of the referenced skill. + + - `type: Literal["skill_reference"]` + + References a skill created with the /v1/skills endpoint. + + - `"skill_reference"` + + - `version: Optional[str]` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `class BetaInlineSkill: …` + + - `description: str` + + The description of the skill. + + - `name: str` + + The name of the skill. + + - `source: BetaInlineSkillSource` + + Inline skill payload + + - `data: str` + + Base64-encoded skill zip bundle. + + - `media_type: Literal["application/zip"]` + + The media type of the inline skill payload. Must be `application/zip`. + + - `"application/zip"` + + - `type: Literal["base64"]` + + The type of the inline skill source. Must be `base64`. + + - `"base64"` + + - `type: Literal["inline"]` + + Defines an inline skill for this request. + + - `"inline"` + + - `class BetaLocalEnvironment: …` + + - `type: Literal["local"]` + + Use a local computer environment. + + - `"local"` + + - `skills: Optional[List[BetaLocalSkill]]` + + An optional list of skills. + + - `description: str` + + The description of the skill. + + - `name: str` + + The name of the skill. + + - `path: str` + + The path to the directory containing the skill. + + - `class BetaContainerReference: …` + + - `container_id: str` + + The ID of the referenced container. + + - `type: Literal["container_reference"]` + + References a container created with the /v1/containers endpoint + + - `"container_reference"` + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: str` + + The name of the custom tool, used to identify it in tool calls. + + - `type: Literal["custom"]` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: Optional[bool]` + + Whether this tool should be deferred and discovered via tool search. + + - `description: Optional[str]` + + Optional description of the custom tool, used to provide more context. + + - `format: Optional[Format]` + + The input format for the custom tool. Default is unconstrained text. + + - `class FormatText: …` + + Unconstrained free-form text. + + - `type: Literal["text"]` + + Unconstrained text format. Always `text`. + + - `"text"` + + - `class FormatGrammar: …` + + A grammar defined by the user. + + - `definition: str` + + The grammar definition. + + - `syntax: Literal["lark", "regex"]` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: Literal["grammar"]` + + Grammar format. Always `grammar`. + + - `"grammar"` + + - `class BetaNamespaceTool: …` + + Groups function/custom tools under a shared namespace. + + - `description: str` + + A description of the namespace shown to the model. + + - `name: str` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: List[Tool]` + + The function/custom tools available inside this namespace. + + - `class ToolFunction: …` + + - `name: str` + + - `type: Literal["function"]` + + - `"function"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: Optional[bool]` + + Whether this function should be deferred and discovered via tool search. + + - `description: Optional[str]` + + - `output_schema: Optional[Dict[str, object]]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: Optional[object]` + + - `strict: Optional[bool]` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `type: Literal["namespace"]` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `class BetaToolSearchTool: …` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: Literal["tool_search"]` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: Optional[str]` + + Description shown to the model for a client-executed tool search tool. + + - `execution: Optional[Literal["server", "client"]]` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: Optional[object]` + + Parameter schema for a client-executed tool search tool. + + - `class BetaWebSearchPreviewTool: …` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: Optional[List[Literal["text", "image"]]]` + + - `"text"` + + - `"image"` + + - `search_context_size: Optional[Literal["low", "medium", "high"]]` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: Optional[UserLocation]` + + The user's location. + + - `type: Literal["approximate"]` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: Optional[str]` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: Optional[str]` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: Optional[str]` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: Optional[str]` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `class BetaApplyPatchTool: …` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: Literal["apply_patch"]` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `type: Literal["tool_search_output"]` + + The item type. Always `tool_search_output`. + + - `"tool_search_output"` + + - `id: Optional[str]` + + The unique ID of this tool search output. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `call_id: Optional[str]` + + The unique ID of the tool search call generated by the model. + + - `execution: Optional[Literal["server", "client"]]` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the tool search output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class AdditionalTools: …` + + - `role: Literal["developer"]` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: List[BetaTool]` + + A list of additional tools made available at this item. + + - `class BetaFunctionTool: …` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool: …` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool: …` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class Mcp: …` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `class CodeInterpreter: …` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling: …` + + - `class ImageGeneration: …` + + A tool that generates images using the GPT image models. + + - `class LocalShell: …` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool: …` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool: …` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool: …` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool: …` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool: …` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: Literal["additional_tools"]` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: Optional[str]` + + The unique ID of this additional tools item. + + - `agent: Optional[AdditionalToolsAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseReasoningItem: …` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: str` + + The unique identifier of the reasoning content. + + - `summary: List[Summary]` + + Reasoning summary content. + + - `text: str` + + A summary of the reasoning output from the model so far. + + - `type: Literal["summary_text"]` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `type: Literal["reasoning"]` + + The type of the object. Always `reasoning`. + + - `"reasoning"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `content: Optional[List[Content]]` + + Reasoning text content. + + - `text: str` + + The reasoning text from the model. + + - `type: Literal["reasoning_text"]` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: Optional[str]` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class BetaResponseCompactionItemParam: …` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `encrypted_content: str` + + The encrypted content of the compaction summary. + + - `type: Literal["compaction"]` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `id: Optional[str]` + + The ID of the compaction item. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ImageGenerationCall: …` + + An image generation request made by the model. + + - `id: str` + + The unique ID of the image generation call. + + - `result: Optional[str]` + + The generated image encoded in base64. + + - `status: Literal["in_progress", "completed", "generating", "failed"]` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: Literal["image_generation_call"]` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `agent: Optional[ImageGenerationCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall: …` + + A tool call to run code. + + - `id: str` + + The unique ID of the code interpreter tool call. + + - `code: Optional[str]` + + The code to run, or null if not available. + + - `container_id: str` + + The ID of the container used to run the code. + + - `outputs: Optional[List[Output]]` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `class OutputLogs: …` + + The logs output from the code interpreter. + + - `logs: str` + + The logs output from the code interpreter. + + - `type: Literal["logs"]` + + The type of the output. Always `logs`. + + - `"logs"` + + - `class OutputImage: …` + + The image output from the code interpreter. + + - `type: Literal["image"]` + + The type of the output. Always `image`. + + - `"image"` + + - `url: str` + + The URL of the image output from the code interpreter. + + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: Literal["code_interpreter_call"]` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class LocalShellCall: …` + + A tool call to run a command on the local shell. + + - `id: str` + + The unique ID of the local shell call. + + - `action: LocalShellCallAction` + + Execute a shell command on the server. + + - `command: List[str]` + + The command to run. + + - `env: Dict[str, str]` + + Environment variables to set for the command. + + - `type: Literal["exec"]` + + The type of the local shell action. Always `exec`. + + - `"exec"` + + - `timeout_ms: Optional[int]` + + Optional timeout in milliseconds for the command. + + - `user: Optional[str]` + + Optional user to run the command as. + + - `working_directory: Optional[str]` + + Optional working directory to run the command in. + + - `call_id: str` + + The unique ID of the local shell tool call generated by the model. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["local_shell_call"]` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `agent: Optional[LocalShellCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class LocalShellCallOutput: …` + + The output of a local shell tool call. + + - `id: str` + + The unique ID of the local shell tool call generated by the model. + + - `output: str` + + A JSON string of the output of the local shell tool call. + + - `type: Literal["local_shell_call_output"]` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `agent: Optional[LocalShellCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class ShellCall: …` + + A tool representing a request to execute one or more shell commands. + + - `action: ShellCallAction` + + The shell commands and limits that describe how to run the tool call. + + - `commands: List[str]` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: Optional[int]` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: Optional[int]` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: str` + + The unique ID of the shell tool call generated by the model. + + - `type: Literal["shell_call"]` + + The type of the item. Always `shell_call`. + + - `"shell_call"` + + - `id: Optional[str]` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: Optional[ShellCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[ShellCallCaller]` + + The execution context that produced this tool call. + + - `class ShellCallCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class ShellCallCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `environment: Optional[ShellCallEnvironment]` + + The environment to execute the shell commands in. + + - `class BetaLocalEnvironment: …` + + - `class BetaContainerReference: …` + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class ShellCallOutput: …` + + The streamed output items emitted by a shell tool call. + + - `call_id: str` + + The unique ID of the shell tool call generated by the model. + + - `output: List[BetaResponseFunctionShellCallOutputContent]` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: Outcome` + + The exit or timeout outcome associated with this shell call. + + - `class OutcomeTimeout: …` + + Indicates that the shell call exceeded its configured time limit. + + - `type: Literal["timeout"]` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `class OutcomeExit: …` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: int` + + The exit code returned by the shell process. + + - `type: Literal["exit"]` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: str` + + Captured stderr output for the shell call. + + - `stdout: str` + + Captured stdout output for the shell call. + + - `type: Literal["shell_call_output"]` + + The type of the item. Always `shell_call_output`. + + - `"shell_call_output"` + + - `id: Optional[str]` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: Optional[ShellCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[ShellCallOutputCaller]` + + The execution context that produced this tool call. + + - `class ShellCallOutputCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class ShellCallOutputCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `max_output_length: Optional[int]` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class ApplyPatchCall: …` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: str` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: ApplyPatchCallOperation` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `class ApplyPatchCallOperationCreateFile: …` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: str` + + Unified diff content to apply when creating the file. + + - `path: str` + + Path of the file to create relative to the workspace root. + + - `type: Literal["create_file"]` + + The operation type. Always `create_file`. + + - `"create_file"` + + - `class ApplyPatchCallOperationDeleteFile: …` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: str` + + Path of the file to delete relative to the workspace root. + + - `type: Literal["delete_file"]` + + The operation type. Always `delete_file`. + + - `"delete_file"` + + - `class ApplyPatchCallOperationUpdateFile: …` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: str` + + Unified diff content to apply to the existing file. + + - `path: str` + + Path of the file to update relative to the workspace root. + + - `type: Literal["update_file"]` + + The operation type. Always `update_file`. + + - `"update_file"` + + - `status: Literal["in_progress", "completed"]` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: Literal["apply_patch_call"]` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `id: Optional[str]` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[ApplyPatchCallCaller]` + + The execution context that produced this tool call. + + - `class ApplyPatchCallCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class ApplyPatchCallCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `class ApplyPatchCallOutput: …` + + The streamed output emitted by an apply patch tool call. + + - `call_id: str` + + The unique ID of the apply patch tool call generated by the model. + + - `status: Literal["completed", "failed"]` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: Literal["apply_patch_call_output"]` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `id: Optional[str]` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[ApplyPatchCallOutputCaller]` + + The execution context that produced this tool call. + + - `class ApplyPatchCallOutputCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class ApplyPatchCallOutputCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `output: Optional[str]` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `class McpListTools: …` + + A list of tools available on an MCP server. + + - `id: str` + + The unique ID of the list. + + - `server_label: str` + + The label of the MCP server. + + - `tools: List[McpListToolsTool]` + + The tools available on the server. + + - `input_schema: object` + + The JSON schema describing the tool's input. + + - `name: str` + + The name of the tool. + + - `annotations: Optional[object]` + + Additional annotations about the tool. + + - `description: Optional[str]` + + The description of the tool. + + - `type: Literal["mcp_list_tools"]` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `agent: Optional[McpListToolsAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `error: Optional[str]` + + Error message if the server could not list tools. + + - `class McpApprovalRequest: …` + + A request for human approval of a tool invocation. + + - `id: str` + + The unique ID of the approval request. + + - `arguments: str` + + A JSON string of arguments for the tool. + + - `name: str` + + The name of the tool to run. + + - `server_label: str` + + The label of the MCP server making the request. + + - `type: Literal["mcp_approval_request"]` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `agent: Optional[McpApprovalRequestAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse: …` + + A response to an MCP approval request. + + - `approval_request_id: str` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: Literal["mcp_approval_response"]` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `id: Optional[str]` + + The unique ID of the approval response + + - `agent: Optional[McpApprovalResponseAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `reason: Optional[str]` + + Optional reason for the decision. + + - `class McpCall: …` + + An invocation of a tool on an MCP server. + + - `id: str` + + The unique ID of the tool call. + + - `arguments: str` + + A JSON string of the arguments passed to the tool. + + - `name: str` + + The name of the tool that was run. + + - `server_label: str` + + The label of the MCP server running the tool. + + - `type: Literal["mcp_call"]` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `agent: Optional[McpCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `approval_request_id: Optional[str]` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: Optional[str]` + + The error from the tool call, if any. + + - `output: Optional[str]` + + The output from the tool call. + + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `class BetaResponseCustomToolCallOutput: …` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: str` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: Union[str, List[OutputOutputContentList]]` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `str` + + A string of the output of the custom tool call. + + - `List[OutputOutputContentList]` + + Text, image, or file output of the custom tool call. + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `type: Literal["custom_tool_call_output"]` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `"custom_tool_call_output"` + + - `id: Optional[str]` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `class BetaResponseCustomToolCall: …` + + A call to a custom tool created by the model. + + - `call_id: str` + + An identifier used to map this custom tool call to a tool call output. + + - `input: str` + + The input for the custom tool call generated by the model. + + - `name: str` + + The name of the custom tool being called. + + - `type: Literal["custom_tool_call"]` + + The type of the custom tool call. Always `custom_tool_call`. + + - `"custom_tool_call"` + + - `id: Optional[str]` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `namespace: Optional[str]` + + The namespace of the custom tool being called. + + - `class CompactionTrigger: …` + + Compacts the current context. Must be the final input item. + + - `type: Literal["compaction_trigger"]` + + The type of the item. Always `compaction_trigger`. + + - `"compaction_trigger"` + + - `agent: Optional[CompactionTriggerAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ItemReference: …` + + An internal identifier for an item to reference. + + - `id: str` + + The ID of the item to reference. + + - `agent: Optional[ItemReferenceAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `type: Optional[Literal["item_reference"]]` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + + - `class Program: …` + + - `id: str` + + The unique ID of this program item. + + - `call_id: str` + + The stable call ID of the program item. + + - `code: str` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: str` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: Literal["program"]` + + The item type. Always `program`. + + - `"program"` + + - `agent: Optional[ProgramAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput: …` + + - `id: str` + + The unique ID of this program output item. + + - `call_id: str` + + The call ID of the program item. + + - `result: str` + + The result produced by the program item. + + - `status: Literal["completed", "incomplete"]` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["program_output"]` + + The item type. Always `program_output`. + + - `"program_output"` + + - `agent: Optional[ProgramOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `metadata: Optional[Dict[str, str]]` + + 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: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` + + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. + + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` + + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. + + - `"gpt-5.6-sol"` + + - `"gpt-5.6-terra"` + + - `"gpt-5.6-luna"` + + - `"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"` + + - `"o1-pro"` + + - `"o1-pro-2025-03-19"` + + - `"o3-pro"` + + - `"o3-pro-2025-06-10"` + + - `"o3-deep-research"` + + - `"o3-deep-research-2025-06-26"` + + - `"o4-mini-deep-research"` + + - `"o4-mini-deep-research-2025-06-26"` + + - `"computer-use-preview"` + + - `"computer-use-preview-2025-03-11"` + + - `"gpt-5-codex"` + + - `"gpt-5-pro"` + + - `"gpt-5-pro-2025-10-06"` + + - `"gpt-5.1-codex-max"` + + - `str` + + - `object: Literal["response"]` + + The object type of this resource - always set to `response`. + + - `"response"` + + - `output: List[BetaResponseOutputItem]` + + An array of content items generated by the model. + + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. + + - `class BetaResponseOutputMessage: …` + + An output message from the model. + + - `class BetaResponseFileSearchToolCall: …` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `class BetaResponseFunctionToolCall: …` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `class BetaResponseFunctionToolCallOutputItem: …` + + - `id: str` + + The unique ID of the function call tool output. + + - `call_id: str` + + The unique ID of the function tool call generated by the model. + + - `output: Union[str, List[OutputOutputContentList]]` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `str` + + A string of the output of the function call. + + - `List[OutputOutputContentList]` + + Text, image, or file output of the function call. + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["function_call_output"]` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `class AgentMessage: …` + + - `id: str` + + The unique ID of the agent message. + + - `author: str` + + The sending agent identity. + + - `content: List[AgentMessageContent]` + + Encrypted content sent between agents. + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseOutputText: …` + + A text output from the model. + + - `class AgentMessageContentText: …` + + A text content. + + - `text: str` + + - `type: Literal["text"]` + + - `"text"` + + - `class AgentMessageContentSummaryText: …` + + A summary text from the model. + + - `text: str` + + A summary of the reasoning output from the model so far. + + - `type: Literal["summary_text"]` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `class AgentMessageContentReasoningText: …` + + Reasoning text from the model. + + - `text: str` + + The reasoning text from the model. + + - `type: Literal["reasoning_text"]` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `class BetaResponseOutputRefusal: …` + + A refusal from the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class AgentMessageContentComputerScreenshot: …` + + A screenshot of a computer. + + - `detail: Literal["low", "high", "auto", "original"]` + + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: Optional[str]` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: Optional[str]` + + The URL of the screenshot image. + + - `type: Literal["computer_screenshot"]` + + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `class AgentMessageContentEncryptedContent: …` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: str` + + Opaque encrypted content. + + - `type: Literal["encrypted_content"]` + + The type of the input item. Always `encrypted_content`. + + - `"encrypted_content"` + + - `recipient: str` + + The destination agent identity. + + - `type: Literal["agent_message"]` + + The type of the item. Always `agent_message`. + + - `"agent_message"` + + - `agent: Optional[AgentMessageAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCall: …` + + - `id: str` + + The unique ID of the multi-agent call item. + + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + + The multi-agent action to execute. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: str` + + The JSON string of arguments generated for the action. + + - `call_id: str` + + The unique ID linking this call to its output. + + - `type: Literal["multi_agent_call"]` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `"multi_agent_call"` + + - `agent: Optional[MultiAgentCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCallOutput: …` + + - `id: str` + + The unique ID of the multi-agent call output item. + + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: str` + + The unique ID of the multi-agent call. + + - `output: List[BetaResponseOutputText]` + + Text output returned by the multi-agent action. + + - `annotations: List[Annotation]` + + The annotations of the text output. + + - `text: str` + + The text output from the model. + + - `type: Literal["output_text"]` + + The type of the output text. Always `output_text`. + + - `logprobs: Optional[List[Logprob]]` + + - `type: Literal["multi_agent_call_output"]` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `"multi_agent_call_output"` + + - `agent: Optional[MultiAgentCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionWebSearch: …` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `class BetaResponseComputerToolCall: …` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `class BetaResponseComputerToolCallOutputItem: …` + + - `id: str` + + The unique ID of the computer call tool output. + + - `call_id: str` + + The ID of the computer tool call that produced the output. + + - `output: BetaResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: Literal["computer_call_output"]` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: str` + + The ID of the pending safety check. + + - `code: Optional[str]` + + The type of the pending safety check. + + - `message: Optional[str]` + + Details about the pending safety check. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `class BetaResponseReasoningItem: …` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `class Program: …` + + - `id: str` + + The unique ID of the program item. + + - `call_id: str` + + The stable call ID of the program item. + + - `code: str` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: str` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: Literal["program"]` + + The type of the item. Always `program`. + + - `"program"` + + - `agent: Optional[ProgramAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput: …` + + - `id: str` + + The unique ID of the program output item. + + - `call_id: str` + + The call ID of the program item. + + - `result: str` + + The result produced by the program item. + + - `status: Literal["completed", "incomplete"]` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["program_output"]` + + The type of the item. Always `program_output`. + + - `"program_output"` + + - `agent: Optional[ProgramOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseToolSearchCall: …` + + - `id: str` + + The unique ID of the tool search call item. + + - `arguments: object` + + Arguments used for the tool search call. + + - `call_id: Optional[str]` + + The unique ID of the tool search call generated by the model. + + - `execution: Literal["server", "client"]` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the tool search call item that was recorded. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["tool_search_call"]` + + The type of the item. Always `tool_search_call`. + + - `"tool_search_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem: …` + + - `id: str` + + The unique ID of the tool search output item. + + - `call_id: Optional[str]` + + The unique ID of the tool search call generated by the model. + + - `execution: Literal["server", "client"]` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the tool search output item that was recorded. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `tools: List[BetaTool]` + + The loaded tool definitions returned by tool search. + + - `class BetaFunctionTool: …` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool: …` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool: …` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class Mcp: …` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `class CodeInterpreter: …` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling: …` + + - `class ImageGeneration: …` + + A tool that generates images using the GPT image models. + + - `class LocalShell: …` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool: …` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool: …` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool: …` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool: …` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool: …` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: Literal["tool_search_output"]` + + The type of the item. Always `tool_search_output`. + + - `"tool_search_output"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `class AdditionalTools: …` + + - `id: str` + + The unique ID of the additional tools item. + + - `role: Literal["unknown", "user", "assistant", 5 more]` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: List[BetaTool]` + + The additional tool definitions made available at this item. + + - `class BetaFunctionTool: …` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool: …` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool: …` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class Mcp: …` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `class CodeInterpreter: …` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling: …` + + - `class ImageGeneration: …` + + A tool that generates images using the GPT image models. + + - `class LocalShell: …` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool: …` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool: …` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool: …` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool: …` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool: …` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: Literal["additional_tools"]` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + + - `agent: Optional[AdditionalToolsAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCompactionItem: …` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `id: str` + + The unique ID of the compaction item. + + - `encrypted_content: str` + + The encrypted content that was produced by compaction. + + - `type: Literal["compaction"]` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `class ImageGenerationCall: …` + + An image generation request made by the model. + + - `id: str` + + The unique ID of the image generation call. + + - `result: Optional[str]` + + The generated image encoded in base64. + + - `status: Literal["in_progress", "completed", "generating", "failed"]` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: Literal["image_generation_call"]` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `agent: Optional[ImageGenerationCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall: …` + + A tool call to run code. + + - `class LocalShellCall: …` + + A tool call to run a command on the local shell. + + - `id: str` + + The unique ID of the local shell call. + + - `action: LocalShellCallAction` + + Execute a shell command on the server. + + - `command: List[str]` + + The command to run. + + - `env: Dict[str, str]` + + Environment variables to set for the command. + + - `type: Literal["exec"]` + + The type of the local shell action. Always `exec`. + + - `"exec"` + + - `timeout_ms: Optional[int]` + + Optional timeout in milliseconds for the command. + + - `user: Optional[str]` + + Optional user to run the command as. + + - `working_directory: Optional[str]` + + Optional working directory to run the command in. + + - `call_id: str` + + The unique ID of the local shell tool call generated by the model. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["local_shell_call"]` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `agent: Optional[LocalShellCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class LocalShellCallOutput: …` + + The output of a local shell tool call. + + - `id: str` + + The unique ID of the local shell tool call generated by the model. + + - `output: str` + + A JSON string of the output of the local shell tool call. + + - `type: Literal["local_shell_call_output"]` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `agent: Optional[LocalShellCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class BetaResponseFunctionShellToolCall: …` + + A tool call that executes one or more shell commands in a managed environment. + + - `id: str` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `action: Action` + + The shell commands and limits that describe how to run the tool call. + + - `commands: List[str]` + + - `max_output_length: Optional[int]` + + Optional maximum number of characters to return from each command. + + - `timeout_ms: Optional[int]` + + Optional timeout in milliseconds for the commands. + + - `call_id: str` + + The unique ID of the shell tool call generated by the model. + + - `environment: Optional[Environment]` + + Represents the use of a local environment to perform shell actions. + + - `class BetaResponseLocalEnvironment: …` + + Represents the use of a local environment to perform shell actions. + + - `type: Literal["local"]` + + The environment type. Always `local`. + + - `"local"` + + - `class BetaResponseContainerReference: …` + + Represents a container created with /v1/containers. + + - `container_id: str` + + - `type: Literal["container_reference"]` + + The environment type. Always `container_reference`. + + - `"container_reference"` + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["shell_call"]` + + The type of the item. Always `shell_call`. + + - `"shell_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `created_by: Optional[str]` + + The ID of the entity that created this tool call. + + - `class BetaResponseFunctionShellToolCallOutput: …` + + The output of a shell tool call that was emitted. + + - `id: str` + + The unique ID of the shell call output. Populated when this item is returned via API. + + - `call_id: str` + + The unique ID of the shell tool call generated by the model. + + - `max_output_length: Optional[int]` + + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: List[Output]` + + An array of shell call output contents + + - `outcome: OutputOutcome` + + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + + - `class OutputOutcomeTimeout: …` + + Indicates that the shell call exceeded its configured time limit. + + - `type: Literal["timeout"]` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `class OutputOutcomeExit: …` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: int` + + Exit code from the shell process. + + - `type: Literal["exit"]` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: str` + + The standard error output that was captured. + + - `stdout: str` + + The standard output that was captured. + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["shell_call_output"]` + + The type of the shell call output. Always `shell_call_output`. + + - `"shell_call_output"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `class BetaResponseApplyPatchToolCall: …` + + A tool call that applies file diffs by creating, deleting, or updating files. + + - `id: str` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `call_id: str` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: Operation` + + One of the create_file, delete_file, or update_file operations applied via apply_patch. + + - `class OperationCreateFile: …` + + Instruction describing how to create a file via the apply_patch tool. + + - `diff: str` + + Diff to apply. + + - `path: str` + + Path of the file to create. + + - `type: Literal["create_file"]` + + Create a new file with the provided diff. + + - `"create_file"` + + - `class OperationDeleteFile: …` + + Instruction describing how to delete a file via the apply_patch tool. + + - `path: str` + + Path of the file to delete. + + - `type: Literal["delete_file"]` + + Delete the specified file. + + - `"delete_file"` + + - `class OperationUpdateFile: …` + + Instruction describing how to update a file via the apply_patch tool. + + - `diff: str` + + Diff to apply. + + - `path: str` + + Path of the file to update. + + - `type: Literal["update_file"]` + + Update an existing file with the provided diff. + + - `"update_file"` + + - `status: Literal["in_progress", "completed"]` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: Literal["apply_patch_call"]` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `created_by: Optional[str]` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput: …` + + The output emitted by an apply patch tool call. + + - `id: str` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `call_id: str` + + The unique ID of the apply patch tool call generated by the model. + + - `status: Literal["completed", "failed"]` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: Literal["apply_patch_call_output"]` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `created_by: Optional[str]` + + The ID of the entity that created this tool call output. + + - `output: Optional[str]` + + Optional textual output returned by the apply patch tool. + + - `class McpCall: …` + + An invocation of a tool on an MCP server. + + - `id: str` + + The unique ID of the tool call. + + - `arguments: str` + + A JSON string of the arguments passed to the tool. + + - `name: str` + + The name of the tool that was run. + + - `server_label: str` + + The label of the MCP server running the tool. + + - `type: Literal["mcp_call"]` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `agent: Optional[McpCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `approval_request_id: Optional[str]` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: Optional[str]` + + The error from the tool call, if any. + + - `output: Optional[str]` + + The output from the tool call. + + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `class McpListTools: …` + + A list of tools available on an MCP server. + + - `id: str` + + The unique ID of the list. + + - `server_label: str` + + The label of the MCP server. + + - `tools: List[McpListToolsTool]` + + The tools available on the server. + + - `input_schema: object` + + The JSON schema describing the tool's input. + + - `name: str` + + The name of the tool. + + - `annotations: Optional[object]` + + Additional annotations about the tool. + + - `description: Optional[str]` + + The description of the tool. + + - `type: Literal["mcp_list_tools"]` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `agent: Optional[McpListToolsAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `error: Optional[str]` + + Error message if the server could not list tools. + + - `class McpApprovalRequest: …` + + A request for human approval of a tool invocation. + + - `id: str` + + The unique ID of the approval request. + + - `arguments: str` + + A JSON string of arguments for the tool. + + - `name: str` + + The name of the tool to run. + + - `server_label: str` + + The label of the MCP server making the request. + + - `type: Literal["mcp_approval_request"]` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `agent: Optional[McpApprovalRequestAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse: …` + + A response to an MCP approval request. + + - `id: str` + + The unique ID of the approval response + + - `approval_request_id: str` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: Literal["mcp_approval_response"]` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `agent: Optional[McpApprovalResponseAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `reason: Optional[str]` + + Optional reason for the decision. + + - `class BetaResponseCustomToolCall: …` + + A call to a custom tool created by the model. + + - `class BetaResponseCustomToolCallOutputItem: …` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: str` + + The unique ID of the custom tool call output item. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `parallel_tool_calls: bool` + + Whether to allow the model to run tool calls in parallel. + + - `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. + We generally recommend altering this or `top_p` but not both. + + - `tool_choice: ToolChoice` + + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. + + - `Literal["none", "auto", "required"]` + + - `"none"` + + - `"auto"` + + - `"required"` + + - `class BetaToolChoiceAllowed: …` + + Constrains the tools available to the model to a pre-defined set. + + - `mode: Literal["auto", "required"]` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `"auto"` + + - `"required"` + + - `tools: List[Dict[str, object]]` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `type: Literal["allowed_tools"]` + + Allowed tool configuration type. Always `allowed_tools`. + + - `"allowed_tools"` + + - `class BetaToolChoiceTypes: …` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `"file_search"` + + - `"web_search_preview"` + + - `"computer"` + + - `"computer_use_preview"` + + - `"computer_use"` + + - `"web_search_preview_2025_03_11"` + + - `"image_generation"` + + - `"code_interpreter"` + + - `class BetaToolChoiceFunction: …` + + Use this option to force the model to call a specific function. + + - `name: str` + + The name of the function to call. + + - `type: Literal["function"]` + + For function calling, the type is always `function`. + + - `"function"` + + - `class BetaToolChoiceMcp: …` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `server_label: str` + + The label of the MCP server to use. + + - `type: Literal["mcp"]` + + For MCP tools, the type is always `mcp`. + + - `"mcp"` + + - `name: Optional[str]` + + The name of the tool to call on the server. + + - `class BetaToolChoiceCustom: …` + + Use this option to force the model to call a specific custom tool. + + - `name: str` + + The name of the custom tool to call. + + - `type: Literal["custom"]` + + For custom tool calling, the type is always `custom`. + + - `"custom"` + + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + + - `type: Literal["programmatic_tool_calling"]` + + The tool to call. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + + - `class BetaToolChoiceApplyPatch: …` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `type: Literal["apply_patch"]` + + The tool to call. Always `apply_patch`. + + - `"apply_patch"` + + - `class BetaToolChoiceShell: …` + + Forces the model to call the shell tool when a tool call is required. + + - `type: Literal["shell"]` + + The tool to call. Always `shell`. + + - `"shell"` + + - `tools: List[BetaTool]` + + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. + + - `class BetaFunctionTool: …` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool: …` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool: …` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class Mcp: …` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `class CodeInterpreter: …` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling: …` + + - `class ImageGeneration: …` + + A tool that generates images using the GPT image models. + + - `class LocalShell: …` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool: …` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool: …` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool: …` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool: …` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool: …` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `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. + + - `background: Optional[bool]` + + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + + - `completed_at: Optional[float]` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `conversation: Optional[Conversation]` + + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + + - `id: str` + + The unique ID of the conversation that this response was associated with. + + - `max_output_tokens: Optional[int]` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + + - `max_tool_calls: Optional[int]` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `moderation: Optional[Moderation]` + + Moderation results for the response input and output, if moderated completions were requested. + + - `input: ModerationInput` + + Moderation for the response input. + + - `class ModerationInputModerationResult: …` + + A moderation result produced for the response input or output. + + - `categories: Dict[str, bool]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: Dict[str, float]` + + A dictionary of moderation categories to scores. + + - `flagged: bool` + + A boolean indicating whether the content was flagged by any category. + + - `model: str` + + The moderation model that produced this result. + + - `type: Literal["moderation_result"]` + + The object type, which was always `moderation_result` for successful moderation results. + + - `"moderation_result"` + + - `class ModerationInputError: …` + + An error produced while attempting moderation for the response input or output. + + - `code: str` + + The error code. + + - `message: str` + + The error message. + + - `type: Literal["error"]` + + The object type, which was always `error` for moderation failures. + + - `"error"` + + - `output: ModerationOutput` + + Moderation for the response output. + + - `class ModerationOutputModerationResult: …` + + A moderation result produced for the response input or output. + + - `categories: Dict[str, bool]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: Dict[str, float]` + + A dictionary of moderation categories to scores. + + - `flagged: bool` + + A boolean indicating whether the content was flagged by any category. + + - `model: str` + + The moderation model that produced this result. + + - `type: Literal["moderation_result"]` + + The object type, which was always `moderation_result` for successful moderation results. + + - `"moderation_result"` + + - `class ModerationOutputError: …` + + An error produced while attempting moderation for the response input or output. + + - `code: str` + + The error code. + + - `message: str` + + The error message. + + - `type: Literal["error"]` + + The object type, which was always `error` for moderation failures. + + - `"error"` + + - `previous_response_id: Optional[str]` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `prompt: Optional[BetaResponsePrompt]` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `id: str` + + The unique identifier of the prompt template to use. + + - `variables: Optional[Dict[str, Variables]]` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `str` + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `version: Optional[str]` + + Optional version of the prompt template. + + - `prompt_cache_key: Optional[str]` + + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + + - `prompt_cache_options: Optional[PromptCacheOptions]` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: Literal["implicit", "explicit"]` + + Whether implicit prompt-cache breakpoints were enabled. + + - `"implicit"` + + - `"explicit"` + + - `ttl: Literal["30m"]` + + The minimum lifetime applied to each cache breakpoint. + + - `"30m"` + + - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + + - `"in_memory"` + + - `"24h"` + + - `reasoning: Optional[Reasoning]` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. + + - `"auto"` + + - `"current_turn"` + + - `"all_turns"` + + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. + + - `"none"` + + - `"minimal"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `"max"` + + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `str` + + - `Literal["standard", "pro"]` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `"standard"` + + - `"pro"` + + - `summary: Optional[Literal["auto", "concise", "detailed"]]` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `safety_identifier: Optional[str]` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"scale"` + + - `"priority"` + + - `status: Optional[BetaResponseStatus]` + + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + + - `"completed"` + + - `"failed"` + + - `"in_progress"` + + - `"cancelled"` + + - `"queued"` + + - `"incomplete"` + + - `text: Optional[BetaResponseTextConfig]` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + + - `format: Optional[BetaResponseFormatTextConfig]` + + An object specifying the format that the model must output. + + Configuring `{ "type": "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). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `class Text: …` + + Default response format. Used to generate text responses. + + - `type: Literal["text"]` + + The type of response format being defined. Always `text`. + + - `"text"` + + - `class BetaResponseFormatTextJSONSchemaConfig: …` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + + - `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. + + - `schema: 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/). + + - `type: Literal["json_schema"]` + + The type of response format being defined. Always `json_schema`. + + - `"json_schema"` + + - `description: Optional[str]` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `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). + + - `class JSONObject: …` + + 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"` + + - `verbosity: Optional[Literal["low", "medium", "high"]]` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `top_logprobs: Optional[int]` + + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + + - `truncation: Optional[Literal["auto", "disabled"]]` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `"auto"` + + - `"disabled"` + + - `usage: Optional[BetaResponseUsage]` + + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + + - `input_tokens: int` + + The number of input tokens. + + - `input_tokens_details: InputTokensDetails` + + A detailed breakdown of the input tokens. + + - `cache_write_tokens: int` + + The number of input tokens that were written to the cache. + + - `cached_tokens: int` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + + - `output_tokens: int` + + The number of output tokens. + + - `output_tokens_details: OutputTokensDetails` + + A detailed breakdown of the output tokens. + + - `reasoning_tokens: int` + + The number of reasoning tokens. + + - `total_tokens: int` + + The total number of tokens used. + + - `user: Optional[str]` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + +### 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 +) +for response in client.beta.responses.retrieve( + response_id="resp_677efb5139a88190b512bc3fef8e535d", +): + print(response) +``` + +#### Response + +```json +{ + "id": "id", + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "text": "text", + "type": "output_text", + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ] + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "phase": "commentary" + } + ], + "parallel_tool_calls": true, + "temperature": 1, + "tool_choice": "none", + "tools": [ + { + "name": "name", + "parameters": { + "foo": "bar" + }, + "strict": true, + "type": "function", + "allowed_callers": [ + "direct" + ], + "defer_loading": true, + "description": "description", + "output_schema": { + "foo": "bar" + } + } + ], + "top_p": 1, + "background": true, + "completed_at": 0, + "conversation": { + "id": "id" + }, + "max_output_tokens": 0, + "max_tool_calls": 0, + "moderation": { + "input": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + }, + "output": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + } + }, + "output_text": "output_text", + "previous_response_id": "previous_response_id", + "prompt": { + "id": "id", + "variables": { + "foo": "string" + }, + "version": "version" + }, + "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, + "prompt_cache_retention": "in_memory", + "reasoning": { + "context": "auto", + "effort": "none", + "generate_summary": "auto", + "mode": "standard", + "summary": "auto" + }, + "safety_identifier": "safety-identifier-1234", + "service_tier": "auto", + "status": "completed", + "text": { + "format": { + "type": "text" + }, + "verbosity": "low" + }, + "top_logprobs": 0, + "truncation": "auto", + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "cache_write_tokens": 0, + "cached_tokens": 0 + }, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + }, + "user": "user-1234" +} +``` + +### Example + +```python +from openai import OpenAI +client = OpenAI() + +response = client.responses.retrieve("resp_123") +print(response) +``` + +#### Response + +```json +{ + "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", + "object": "response", + "created_at": 1741386163, + "status": "completed", + "completed_at": 1741386164, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [ + { + "type": "message", + "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 32, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 18, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 50 + }, + "user": null, + "metadata": {} +} +``` + +## Delete a model response + +`beta.responses.delete(strresponse_id, ResponseDeleteParams**kwargs)` + +**delete** `/responses/{response_id}?beta=true` + +Deletes a model response with the given ID. + +### Parameters + +- `response_id: str` + +- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` + + - `"responses_multi_agent=v1"` + +### 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 +) +client.beta.responses.delete( + response_id="resp_677efb5139a88190b512bc3fef8e535d", +) +``` + +### Example + +```python +from openai import OpenAI +client = OpenAI() + +response = client.responses.delete("resp_123") +print(response) +``` + +#### Response + +```json +{ + "id": "resp_6786a1bec27481909a17d673315b29f6", + "object": "response", + "deleted": true +} +``` + +## Cancel a response + +`beta.responses.cancel(strresponse_id, ResponseCancelParams**kwargs) -> BetaResponse` + +**post** `/responses/{response_id}/cancel?beta=true` + +Cancels a model response with the given ID. Only responses created with +the `background` parameter set to `true` can be cancelled. +[Learn more](https://platform.openai.com/docs/guides/background). + +### Parameters + +- `response_id: str` + +- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` + + - `"responses_multi_agent=v1"` + +### Returns + +- `class BetaResponse: …` + + - `id: str` + + Unique identifier for this Response. + + - `created_at: float` + + Unix timestamp (in seconds) of when this Response was created. + + - `error: Optional[BetaResponseError]` + + An error object returned when the model fails to generate a Response. + + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + + The error code for the response. + + - `"server_error"` + + - `"rate_limit_exceeded"` + + - `"invalid_prompt"` + + - `"bio_policy"` + + - `"vector_store_timeout"` + + - `"invalid_image"` + + - `"invalid_image_format"` + + - `"invalid_base64_image"` + + - `"invalid_image_url"` + + - `"image_too_large"` + + - `"image_too_small"` + + - `"image_parse_error"` + + - `"image_content_policy_violation"` + + - `"invalid_image_mode"` + + - `"image_file_too_large"` + + - `"unsupported_image_media_type"` + + - `"empty_image_file"` + + - `"failed_to_download_image"` + + - `"image_file_not_found"` + + - `message: str` + + A human-readable description of the error. + + - `incomplete_details: Optional[IncompleteDetails]` + + Details about why the response is incomplete. + + - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` + + The reason why the response is incomplete. + + - `"max_output_tokens"` + + - `"content_filter"` + + - `instructions: Union[str, List[BetaResponseInputItem], null]` + + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + + - `str` + + A text input to the model, equivalent to a text input with the + `developer` role. + + - `List[BetaResponseInputItem]` + + A list of one or many input items to the model, containing + different content types. + + - `class BetaEasyInputMessage: …` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: Union[str, BetaResponseInputMessageContentList]` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `str` + + A text input to the model. + + - `List[BetaResponseInputContent]` + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `text: str` + + The text input to the model. + + - `type: Literal["input_text"]` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: Literal["low", "high", "auto", "original"]` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: Literal["input_image"]` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `image_url: Optional[str]` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `type: Literal["input_file"]` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: Optional[Literal["auto", "low", "high"]]` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: Optional[str]` + + The content of the file to be sent to the model. + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `file_url: Optional[str]` + + The URL of the file to be sent to the model. + + - `filename: Optional[str]` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `role: Literal["user", "assistant", "system", "developer"]` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"developer"` + + - `phase: Optional[Literal["commentary", "final_answer"]]` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `type: Optional[Literal["message"]]` + + The type of the message input. Always `message`. + + - `"message"` + + - `class Message: …` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: BetaResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `role: Literal["user", "system", "developer"]` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `agent: Optional[MessageAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Optional[Literal["message"]]` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `class BetaResponseOutputMessage: …` + + An output message from the model. + + - `id: str` + + The unique ID of the output message. + + - `content: List[Content]` + + The content of the output message. + + - `class BetaResponseOutputText: …` + + A text output from the model. + + - `annotations: List[Annotation]` + + The annotations of the text output. + + - `class AnnotationFileCitation: …` + + A citation to a file. + + - `file_id: str` + + The ID of the file. + + - `filename: str` + + The filename of the file cited. + + - `index: int` + + The index of the file in the list of files. + + - `type: Literal["file_citation"]` + + The type of the file citation. Always `file_citation`. + + - `"file_citation"` + + - `class AnnotationURLCitation: …` + + A citation for a web resource used to generate a model response. + + - `end_index: int` + + The index of the last character of the URL citation in the message. + + - `start_index: int` + + The index of the first character of the URL citation in the message. + + - `title: str` + + The title of the web resource. + + - `type: Literal["url_citation"]` + + The type of the URL citation. Always `url_citation`. + + - `"url_citation"` + + - `url: str` + + The URL of the web resource. + + - `class AnnotationContainerFileCitation: …` + + A citation for a container file used to generate a model response. + + - `container_id: str` + + The ID of the container file. + + - `end_index: int` + + The index of the last character of the container file citation in the message. + + - `file_id: str` + + The ID of the file. + + - `filename: str` + + The filename of the container file cited. + + - `start_index: int` + + The index of the first character of the container file citation in the message. + + - `type: Literal["container_file_citation"]` + + The type of the container file citation. Always `container_file_citation`. + + - `"container_file_citation"` + + - `class AnnotationFilePath: …` + + A path to a file. + + - `file_id: str` + + The ID of the file. + + - `index: int` + + The index of the file in the list of files. + + - `type: Literal["file_path"]` + + The type of the file path. Always `file_path`. + + - `"file_path"` + + - `text: str` + + The text output from the model. + + - `type: Literal["output_text"]` + + The type of the output text. Always `output_text`. + + - `"output_text"` + + - `logprobs: Optional[List[Logprob]]` + + - `token: str` + + - `bytes: List[int]` + + - `logprob: float` + + - `top_logprobs: List[LogprobTopLogprob]` + + - `token: str` + + - `bytes: List[int]` + + - `logprob: float` + + - `class BetaResponseOutputRefusal: …` + + A refusal from the model. + + - `refusal: str` + + The refusal explanation from the model. + + - `type: Literal["refusal"]` + + The type of the refusal. Always `refusal`. + + - `"refusal"` + + - `role: Literal["assistant"]` + + The role of the output message. Always `assistant`. + + - `"assistant"` + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["message"]` + + The type of the output message. Always `message`. + + - `"message"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `phase: Optional[Literal["commentary", "final_answer"]]` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `class BetaResponseFileSearchToolCall: …` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `id: str` + + The unique ID of the file search tool call. + + - `queries: List[str]` + + The queries used to search for files. + + - `status: Literal["in_progress", "searching", "completed", 2 more]` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: Literal["file_search_call"]` + + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `results: Optional[List[Result]]` + + The results of the file search tool call. + + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + + 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, booleans, or numbers. + + - `str` + + - `float` + + - `bool` + + - `file_id: Optional[str]` + + The unique ID of the file. + + - `filename: Optional[str]` + + The name of the file. + + - `score: Optional[float]` + + The relevance score of the file - a value between 0 and 1. + + - `text: Optional[str]` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall: …` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `id: str` + + The unique ID of the computer call. + + - `call_id: str` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: List[PendingSafetyCheck]` + + The pending safety checks for the computer call. + + - `id: str` + + The ID of the pending safety check. + + - `code: Optional[str]` + + The type of the pending safety check. + + - `message: Optional[str]` + + Details about the pending safety check. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["computer_call"]` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: Optional[BetaComputerAction]` + + A click action. + + - `class Click: …` + + A click action. + + - `button: Literal["left", "right", "wheel", 2 more]` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: Literal["click"]` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: int` + + The x-coordinate where the click occurred. + + - `y: int` + + The y-coordinate where the click occurred. + + - `keys: Optional[List[str]]` + + The keys being held while clicking. + + - `class DoubleClick: …` + + A double click action. + + - `keys: Optional[List[str]]` + + The keys being held while double-clicking. + + - `type: Literal["double_click"]` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: int` + + The x-coordinate where the double click occurred. + + - `y: int` + + The y-coordinate where the double click occurred. + + - `class Drag: …` + + A drag action. + + - `path: List[DragPath]` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: int` + + The x-coordinate. + + - `y: int` + + The y-coordinate. + + - `type: Literal["drag"]` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: Optional[List[str]]` + + The keys being held while dragging the mouse. + + - `class Keypress: …` + + A collection of keypresses the model would like to perform. + + - `keys: List[str]` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: Literal["keypress"]` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `class Move: …` + + A mouse move action. + + - `type: Literal["move"]` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: int` + + The x-coordinate to move to. + + - `y: int` + + The y-coordinate to move to. + + - `keys: Optional[List[str]]` + + The keys being held while moving the mouse. + + - `class Screenshot: …` + + A screenshot action. + + - `type: Literal["screenshot"]` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `class Scroll: …` + + A scroll action. + + - `scroll_x: int` + + The horizontal scroll distance. + + - `scroll_y: int` + + The vertical scroll distance. + + - `type: Literal["scroll"]` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: int` + + The x-coordinate where the scroll occurred. + + - `y: int` + + The y-coordinate where the scroll occurred. + + - `keys: Optional[List[str]]` + + The keys being held while scrolling. + + - `class Type: …` + + An action to type in text. + + - `text: str` + + The text to type. + + - `type: Literal["type"]` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `class Wait: …` + + A wait action. + + - `type: Literal["wait"]` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + + - `actions: Optional[BetaComputerActionList]` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `class Click: …` + + A click action. + + - `class DoubleClick: …` + + A double click action. + + - `class Drag: …` + + A drag action. + + - `class Keypress: …` + + A collection of keypresses the model would like to perform. + + - `class Move: …` + + A mouse move action. + + - `class Screenshot: …` + + A screenshot action. + + - `class Scroll: …` + + A scroll action. + + - `class Type: …` + + An action to type in text. + + - `class Wait: …` + + A wait action. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ComputerCallOutput: …` + + The output of a computer tool call. + + - `call_id: str` + + The ID of the computer tool call that produced the output. + + - `output: BetaResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: Literal["computer_screenshot"]` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `file_id: Optional[str]` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: Optional[str]` + + The URL of the screenshot image. + + - `type: Literal["computer_call_output"]` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `id: Optional[str]` + + The ID of the computer tool call output. + + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + + The safety checks reported by the API that have been acknowledged by the developer. + + - `id: str` + + The ID of the pending safety check. + + - `code: Optional[str]` + + The type of the pending safety check. + + - `message: Optional[str]` + + Details about the pending safety check. + + - `agent: Optional[ComputerCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class BetaResponseFunctionWebSearch: …` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `id: str` + + The unique ID of the web search tool call. + + - `action: Action` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `class ActionSearch: …` + + Action type "search" - Performs a web search query. + + - `type: Literal["search"]` + + The action type. + + - `"search"` + + - `queries: Optional[List[str]]` + + The search queries. + + - `query: Optional[str]` + + The search query. + + - `sources: Optional[List[ActionSearchSource]]` + + The sources used in the search. + + - `type: Literal["url"]` + + The type of source. Always `url`. + + - `"url"` + + - `url: str` + + The URL of the source. + + - `class ActionOpenPage: …` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: Literal["open_page"]` + + The action type. + + - `"open_page"` + + - `url: Optional[str]` + + The URL opened by the model. + + - `class ActionFindInPage: …` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: str` + + The pattern or text to search for within the page. + + - `type: Literal["find_in_page"]` + + The action type. + + - `"find_in_page"` + + - `url: str` + + The URL of the page searched for the pattern. + + - `status: Literal["in_progress", "searching", "completed", "failed"]` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: Literal["web_search_call"]` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionToolCall: …` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `arguments: str` + + A JSON string of the arguments to pass to the function. + + - `call_id: str` + + The unique ID of the function tool call generated by the model. + + - `name: str` + + The name of the function to run. + + - `type: Literal["function_call"]` + + The type of the function tool call. Always `function_call`. + + - `"function_call"` + + - `id: Optional[str]` + + The unique ID of the function tool call. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `namespace: Optional[str]` + + The namespace of the function to run. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class FunctionCallOutput: …` + + The output of a function tool call. + + - `call_id: str` + + The unique ID of the function tool call generated by the model. + + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + + Text, image, or file output of the function tool call. + + - `str` + + A JSON string of the output of the function tool call. + + - `List[BetaResponseFunctionCallOutputItem]` + + - `class BetaResponseInputTextContent: …` + + A text input to the model. + + - `text: str` + + The text input to the model. + + - `type: Literal["input_text"]` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputImageContent: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: Literal["input_image"]` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `detail: Optional[Literal["low", "high", "auto", "original"]]` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `image_url: Optional[str]` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputFileContent: …` + + A file input to the model. + + - `type: Literal["input_file"]` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: Optional[Literal["auto", "low", "high"]]` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: Optional[str]` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `file_url: Optional[str]` + + The URL of the file to be sent to the model. + + - `filename: Optional[str]` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `type: Literal["function_call_output"]` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: Optional[str]` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: Optional[FunctionCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[FunctionCallOutputCaller]` + + The execution context that produced this tool call. + + - `class FunctionCallOutputCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class FunctionCallOutputCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class AgentMessage: …` + + A message routed between agents. + + - `author: str` + + The sending agent identity. + + - `content: List[AgentMessageContent]` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent: …` + + A text input to the model. + + - `class BetaResponseInputImageContent: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `class AgentMessageContentEncryptedContent: …` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: str` + + Opaque encrypted content. + + - `type: Literal["encrypted_content"]` + + The type of the input item. Always `encrypted_content`. + + - `"encrypted_content"` + + - `recipient: str` + + The destination agent identity. + + - `type: Literal["agent_message"]` + + The item type. Always `agent_message`. + + - `"agent_message"` + + - `id: Optional[str]` + + The unique ID of this agent message item. + + - `agent: Optional[AgentMessageAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCall: …` + + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + + The multi-agent action that was executed. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: str` + + The action arguments as a JSON string. + + - `call_id: str` + + The unique ID linking this call to its output. + + - `type: Literal["multi_agent_call"]` + + The item type. Always `multi_agent_call`. + + - `"multi_agent_call"` + + - `id: Optional[str]` + + The unique ID of this multi-agent call. + + - `agent: Optional[MultiAgentCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCallOutput: …` + + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: str` + + The unique ID of the multi-agent call. + + - `output: List[MultiAgentCallOutputOutput]` + + Text output returned by the multi-agent action. + + - `text: str` + + The text content. + + - `type: Literal["output_text"]` + + The content type. Always `output_text`. + + - `"output_text"` + + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + + Citations associated with the text content. + + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + + - `file_id: str` + + The ID of the file. + + - `filename: str` + + The filename of the file cited. + + - `index: int` + + The index of the file in the list of files. + + - `type: Literal["file_citation"]` + + The citation type. Always `file_citation`. + + - `"file_citation"` + + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + + - `end_index: int` + + The index of the last character of the citation in the message. + + - `start_index: int` + + The index of the first character of the citation in the message. + + - `title: str` + + The title of the cited resource. + + - `type: Literal["url_citation"]` + + The citation type. Always `url_citation`. + + - `"url_citation"` + + - `url: str` + + The URL of the cited resource. + + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + + - `container_id: str` + + The ID of the container. + + - `end_index: int` + + The index of the last character of the citation in the message. + + - `file_id: str` + + The ID of the container file. + + - `filename: str` + + The filename of the container file cited. + + - `start_index: int` + + The index of the first character of the citation in the message. + + - `type: Literal["container_file_citation"]` + + The citation type. Always `container_file_citation`. + + - `"container_file_citation"` + + - `type: Literal["multi_agent_call_output"]` + + The item type. Always `multi_agent_call_output`. + + - `"multi_agent_call_output"` + + - `id: Optional[str]` + + The unique ID of this multi-agent call output. + + - `agent: Optional[MultiAgentCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ToolSearchCall: …` + + - `arguments: object` + + The arguments supplied to the tool search call. + + - `type: Literal["tool_search_call"]` + + The item type. Always `tool_search_call`. + + - `"tool_search_call"` + + - `id: Optional[str]` + + The unique ID of this tool search call. + + - `agent: Optional[ToolSearchCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `call_id: Optional[str]` + + The unique ID of the tool search call generated by the model. + + - `execution: Optional[Literal["server", "client"]]` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the tool search call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class BetaResponseToolSearchOutputItemParam: …` + + - `tools: List[BetaTool]` + + The loaded tool definitions returned by the tool search output. + + - `class BetaFunctionTool: …` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: str` + + The name of the function to call. + + - `parameters: Optional[Dict[str, object]]` + + A JSON schema object describing the parameters of the function. + + - `strict: Optional[bool]` + + Whether strict parameter validation is enforced for this function tool. + + - `type: Literal["function"]` + + The type of the function tool. Always `function`. + + - `"function"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: Optional[bool]` + + Whether this function is deferred and loaded via tool search. + + - `description: Optional[str]` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: Optional[Dict[str, object]]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool: …` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: Literal["file_search"]` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: List[str]` + + The IDs of the vector stores to search. + + - `filters: Optional[Filters]` + + A filter to apply. + + - `class FiltersComparisonFilter: …` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: str` + + The key to compare against the value. + + - `type: Literal["eq", "ne", "gt", 5 more]` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: Union[str, float, bool, List[Union[str, float]]]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `str` + + - `float` + + - `bool` + + - `List[Union[str, float]]` + + - `str` + + - `float` + + - `class FiltersCompoundFilter: …` + + Combine multiple filters using `and` or `or`. + + - `filters: List[FiltersCompoundFilterFilter]` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `class FiltersCompoundFilterFilterComparisonFilter: …` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: str` + + The key to compare against the value. + + - `type: Literal["eq", "ne", "gt", 5 more]` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: Union[str, float, bool, List[Union[str, float]]]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `str` + + - `float` + + - `bool` + + - `List[Union[str, float]]` + + - `str` + + - `float` + + - `object` + + - `type: Literal["and", "or"]` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: Optional[int]` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: Optional[RankingOptions]` + + Ranking options for search. + + - `hybrid_search: Optional[RankingOptionsHybridSearch]` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: float` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: float` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: Optional[float]` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `class BetaComputerTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: Literal["computer"]` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `class BetaComputerUsePreviewTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: int` + + The height of the computer display. + + - `display_width: int` + + The width of the computer display. + + - `environment: Literal["windows", "mac", "linux", 2 more]` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: Literal["computer_use_preview"]` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `class BetaWebSearchTool: …` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: Literal["web_search", "web_search_2025_08_26"]` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: Optional[Filters]` + + Filters for the search. + + - `allowed_domains: Optional[List[str]]` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: Optional[Literal["low", "medium", "high"]]` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: Optional[UserLocation]` + + The approximate location of the user. + + - `city: Optional[str]` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: Optional[str]` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: Optional[str]` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: Optional[str]` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: Optional[Literal["approximate"]]` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `class Mcp: …` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `server_label: str` + + A label for this MCP server, used to identify it in tool calls. + + - `type: Literal["mcp"]` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `allowed_tools: Optional[McpAllowedTools]` + + List of allowed tool names or a filter object. + + - `List[str]` + + A string array of allowed tool names + + - `class McpAllowedToolsMcpToolFilter: …` + + A filter object to specify which tools are allowed. + + - `read_only: Optional[bool]` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Optional[List[str]]` + + List of allowed tool names. + + - `authorization: Optional[str]` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: Optional[bool]` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: Optional[Dict[str, str]]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: Optional[McpRequireApproval]` + + Specify which of the MCP server's tools require approval. + + - `class McpRequireApprovalMcpToolApprovalFilter: …` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + + A filter object to specify which tools are allowed. + + - `read_only: Optional[bool]` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Optional[List[str]]` + + List of allowed tool names. + + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + + A filter object to specify which tools are allowed. + + - `read_only: Optional[bool]` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Optional[List[str]]` + + List of allowed tool names. + + - `Literal["always", "never"]` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: Optional[str]` + + Optional description of the MCP server, used to provide more context. + + - `server_url: Optional[str]` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `tunnel_id: Optional[str]` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `class CodeInterpreter: …` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: CodeInterpreterContainer` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `str` + + The container ID. + + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: Literal["auto"]` + + Always `auto`. + + - `"auto"` + + - `file_ids: Optional[List[str]]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled: …` + + - `type: Literal["disabled"]` + + Disable outbound network access. Always `disabled`. + + - `"disabled"` + + - `class BetaContainerNetworkPolicyAllowlist: …` + + - `allowed_domains: List[str]` + + A list of allowed domains when type is `allowlist`. + + - `type: Literal["allowlist"]` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `"allowlist"` + + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + + Optional domain-scoped secrets for allowlisted domains. + + - `domain: str` + + The domain associated with the secret. + + - `name: str` + + The name of the secret to inject for the domain. + + - `value: str` + + The secret value to inject for the domain. + + - `type: Literal["code_interpreter"]` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `class ProgrammaticToolCalling: …` + + - `type: Literal["programmatic_tool_calling"]` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + + - `class ImageGeneration: …` + + A tool that generates images using the GPT image models. + + - `type: Literal["image_generation"]` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: Optional[Literal["generate", "edit", "auto"]]` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: Optional[Literal["transparent", "opaque", "auto"]]` + + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: Optional[Literal["high", "low"]]` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: Optional[ImageGenerationInputImageMask]` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: Optional[str]` + + File ID for the mask image. + + - `image_url: Optional[str]` + + Base64-encoded mask image. + + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + + The image generation model to use. Default: `gpt-image-1`. + + - `str` + + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + + - `"gpt-image-1.5"` + + - `"chatgpt-image-latest"` + + - `moderation: Optional[Literal["auto", "low"]]` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: Optional[int]` + + Compression level for the output image. Default: 100. + + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: Optional[int]` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `str` + + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `class LocalShell: …` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: Literal["local_shell"]` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `class BetaFunctionShellTool: …` + + A tool that allows the model to execute shell commands. + + - `type: Literal["shell"]` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `environment: Optional[Environment]` + + - `class BetaContainerAuto: …` + + - `type: Literal["container_auto"]` + + Automatically creates a container for this request + + - `"container_auto"` + + - `file_ids: Optional[List[str]]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + + The memory limit for the container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: Optional[NetworkPolicy]` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled: …` + + - `class BetaContainerNetworkPolicyAllowlist: …` + + - `skills: Optional[List[Skill]]` + + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference: …` + + - `skill_id: str` + + The ID of the referenced skill. + + - `type: Literal["skill_reference"]` + + References a skill created with the /v1/skills endpoint. + + - `"skill_reference"` + + - `version: Optional[str]` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `class BetaInlineSkill: …` + + - `description: str` + + The description of the skill. + + - `name: str` + + The name of the skill. + + - `source: BetaInlineSkillSource` + + Inline skill payload + + - `data: str` + + Base64-encoded skill zip bundle. + + - `media_type: Literal["application/zip"]` + + The media type of the inline skill payload. Must be `application/zip`. + + - `"application/zip"` + + - `type: Literal["base64"]` + + The type of the inline skill source. Must be `base64`. + + - `"base64"` + + - `type: Literal["inline"]` + + Defines an inline skill for this request. + + - `"inline"` + + - `class BetaLocalEnvironment: …` + + - `type: Literal["local"]` + + Use a local computer environment. + + - `"local"` + + - `skills: Optional[List[BetaLocalSkill]]` + + An optional list of skills. + + - `description: str` + + The description of the skill. + + - `name: str` + + The name of the skill. + + - `path: str` + + The path to the directory containing the skill. + + - `class BetaContainerReference: …` + + - `container_id: str` + + The ID of the referenced container. + + - `type: Literal["container_reference"]` + + References a container created with the /v1/containers endpoint + + - `"container_reference"` + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: str` + + The name of the custom tool, used to identify it in tool calls. + + - `type: Literal["custom"]` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: Optional[bool]` + + Whether this tool should be deferred and discovered via tool search. + + - `description: Optional[str]` + + Optional description of the custom tool, used to provide more context. + + - `format: Optional[Format]` + + The input format for the custom tool. Default is unconstrained text. + + - `class FormatText: …` + + Unconstrained free-form text. + + - `type: Literal["text"]` + + Unconstrained text format. Always `text`. + + - `"text"` + + - `class FormatGrammar: …` + + A grammar defined by the user. + + - `definition: str` + + The grammar definition. + + - `syntax: Literal["lark", "regex"]` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: Literal["grammar"]` + + Grammar format. Always `grammar`. + + - `"grammar"` + + - `class BetaNamespaceTool: …` + + Groups function/custom tools under a shared namespace. + + - `description: str` + + A description of the namespace shown to the model. + + - `name: str` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: List[Tool]` + + The function/custom tools available inside this namespace. + + - `class ToolFunction: …` + + - `name: str` + + - `type: Literal["function"]` + + - `"function"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: Optional[bool]` + + Whether this function should be deferred and discovered via tool search. + + - `description: Optional[str]` + + - `output_schema: Optional[Dict[str, object]]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: Optional[object]` + + - `strict: Optional[bool]` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `type: Literal["namespace"]` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `class BetaToolSearchTool: …` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: Literal["tool_search"]` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: Optional[str]` + + Description shown to the model for a client-executed tool search tool. + + - `execution: Optional[Literal["server", "client"]]` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: Optional[object]` + + Parameter schema for a client-executed tool search tool. + + - `class BetaWebSearchPreviewTool: …` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: Optional[List[Literal["text", "image"]]]` + + - `"text"` + + - `"image"` + + - `search_context_size: Optional[Literal["low", "medium", "high"]]` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: Optional[UserLocation]` + + The user's location. + + - `type: Literal["approximate"]` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: Optional[str]` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: Optional[str]` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: Optional[str]` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: Optional[str]` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `class BetaApplyPatchTool: …` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: Literal["apply_patch"]` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `type: Literal["tool_search_output"]` + + The item type. Always `tool_search_output`. + + - `"tool_search_output"` + + - `id: Optional[str]` + + The unique ID of this tool search output. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `call_id: Optional[str]` + + The unique ID of the tool search call generated by the model. + + - `execution: Optional[Literal["server", "client"]]` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the tool search output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class AdditionalTools: …` + + - `role: Literal["developer"]` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: List[BetaTool]` + + A list of additional tools made available at this item. + + - `class BetaFunctionTool: …` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool: …` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool: …` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class Mcp: …` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `class CodeInterpreter: …` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling: …` + + - `class ImageGeneration: …` + + A tool that generates images using the GPT image models. + + - `class LocalShell: …` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool: …` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool: …` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool: …` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool: …` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool: …` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: Literal["additional_tools"]` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: Optional[str]` + + The unique ID of this additional tools item. + + - `agent: Optional[AdditionalToolsAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseReasoningItem: …` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: str` + + The unique identifier of the reasoning content. + + - `summary: List[Summary]` + + Reasoning summary content. + + - `text: str` + + A summary of the reasoning output from the model so far. + + - `type: Literal["summary_text"]` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `type: Literal["reasoning"]` + + The type of the object. Always `reasoning`. + + - `"reasoning"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `content: Optional[List[Content]]` + + Reasoning text content. + + - `text: str` + + The reasoning text from the model. + + - `type: Literal["reasoning_text"]` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: Optional[str]` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class BetaResponseCompactionItemParam: …` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `encrypted_content: str` + + The encrypted content of the compaction summary. + + - `type: Literal["compaction"]` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `id: Optional[str]` + + The ID of the compaction item. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ImageGenerationCall: …` + + An image generation request made by the model. + + - `id: str` + + The unique ID of the image generation call. + + - `result: Optional[str]` + + The generated image encoded in base64. + + - `status: Literal["in_progress", "completed", "generating", "failed"]` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: Literal["image_generation_call"]` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `agent: Optional[ImageGenerationCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall: …` + + A tool call to run code. + + - `id: str` + + The unique ID of the code interpreter tool call. + + - `code: Optional[str]` + + The code to run, or null if not available. + + - `container_id: str` + + The ID of the container used to run the code. + + - `outputs: Optional[List[Output]]` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `class OutputLogs: …` + + The logs output from the code interpreter. + + - `logs: str` + + The logs output from the code interpreter. + + - `type: Literal["logs"]` + + The type of the output. Always `logs`. + + - `"logs"` + + - `class OutputImage: …` + + The image output from the code interpreter. + + - `type: Literal["image"]` + + The type of the output. Always `image`. + + - `"image"` + + - `url: str` + + The URL of the image output from the code interpreter. + + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: Literal["code_interpreter_call"]` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class LocalShellCall: …` + + A tool call to run a command on the local shell. + + - `id: str` + + The unique ID of the local shell call. + + - `action: LocalShellCallAction` + + Execute a shell command on the server. + + - `command: List[str]` + + The command to run. + + - `env: Dict[str, str]` + + Environment variables to set for the command. + + - `type: Literal["exec"]` + + The type of the local shell action. Always `exec`. + + - `"exec"` + + - `timeout_ms: Optional[int]` + + Optional timeout in milliseconds for the command. + + - `user: Optional[str]` + + Optional user to run the command as. + + - `working_directory: Optional[str]` + + Optional working directory to run the command in. + + - `call_id: str` + + The unique ID of the local shell tool call generated by the model. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["local_shell_call"]` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `agent: Optional[LocalShellCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class LocalShellCallOutput: …` + + The output of a local shell tool call. + + - `id: str` + + The unique ID of the local shell tool call generated by the model. + + - `output: str` + + A JSON string of the output of the local shell tool call. + + - `type: Literal["local_shell_call_output"]` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `agent: Optional[LocalShellCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class ShellCall: …` + + A tool representing a request to execute one or more shell commands. + + - `action: ShellCallAction` + + The shell commands and limits that describe how to run the tool call. + + - `commands: List[str]` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: Optional[int]` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: Optional[int]` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: str` + + The unique ID of the shell tool call generated by the model. + + - `type: Literal["shell_call"]` + + The type of the item. Always `shell_call`. + + - `"shell_call"` + + - `id: Optional[str]` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: Optional[ShellCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[ShellCallCaller]` + + The execution context that produced this tool call. + + - `class ShellCallCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class ShellCallCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `environment: Optional[ShellCallEnvironment]` + + The environment to execute the shell commands in. + + - `class BetaLocalEnvironment: …` + + - `class BetaContainerReference: …` + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class ShellCallOutput: …` + + The streamed output items emitted by a shell tool call. + + - `call_id: str` + + The unique ID of the shell tool call generated by the model. + + - `output: List[BetaResponseFunctionShellCallOutputContent]` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: Outcome` + + The exit or timeout outcome associated with this shell call. + + - `class OutcomeTimeout: …` + + Indicates that the shell call exceeded its configured time limit. + + - `type: Literal["timeout"]` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `class OutcomeExit: …` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: int` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + The exit code returned by the shell process. - - `failed_at: Optional[int]` + - `type: Literal["exit"]` - The Unix timestamp (in seconds) for when the run step failed. + The outcome type. Always `exit`. - - `last_error: Optional[LastError]` + - `"exit"` - The last error associated with this run step. Will be `null` if there are no errors. + - `stderr: str` - - `code: Literal["server_error", "rate_limit_exceeded"]` + Captured stderr output for the shell call. - One of `server_error` or `rate_limit_exceeded`. + - `stdout: str` - - `"server_error"` + Captured stdout output for the shell call. - - `"rate_limit_exceeded"` + - `type: Literal["shell_call_output"]` - - `message: str` + The type of the item. Always `shell_call_output`. - A human-readable description of the error. + - `"shell_call_output"` - - `metadata: Optional[Metadata]` + - `id: Optional[str]` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: Optional[ShellCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[ShellCallOutputCaller]` + + The execution context that produced this tool call. + + - `class ShellCallOutputCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class ShellCallOutputCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `max_output_length: Optional[int]` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class ApplyPatchCall: …` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: str` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: ApplyPatchCallOperation` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `class ApplyPatchCallOperationCreateFile: …` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: str` + + Unified diff content to apply when creating the file. + + - `path: str` + + Path of the file to create relative to the workspace root. + + - `type: Literal["create_file"]` + + The operation type. Always `create_file`. + + - `"create_file"` + + - `class ApplyPatchCallOperationDeleteFile: …` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: str` + + Path of the file to delete relative to the workspace root. + + - `type: Literal["delete_file"]` + + The operation type. Always `delete_file`. + + - `"delete_file"` + + - `class ApplyPatchCallOperationUpdateFile: …` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: str` + + Unified diff content to apply to the existing file. + + - `path: str` + + Path of the file to update relative to the workspace root. + + - `type: Literal["update_file"]` + + The operation type. Always `update_file`. + + - `"update_file"` + + - `status: Literal["in_progress", "completed"]` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: Literal["apply_patch_call"]` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `id: Optional[str]` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[ApplyPatchCallCaller]` + + The execution context that produced this tool call. + + - `class ApplyPatchCallCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class ApplyPatchCallCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `class ApplyPatchCallOutput: …` + + The streamed output emitted by an apply patch tool call. + + - `call_id: str` + + The unique ID of the apply patch tool call generated by the model. + + - `status: Literal["completed", "failed"]` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: Literal["apply_patch_call_output"]` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `id: Optional[str]` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[ApplyPatchCallOutputCaller]` + + The execution context that produced this tool call. + + - `class ApplyPatchCallOutputCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class ApplyPatchCallOutputCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `output: Optional[str]` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `class McpListTools: …` + + A list of tools available on an MCP server. + + - `id: str` + + The unique ID of the list. + + - `server_label: str` + + The label of the MCP server. + + - `tools: List[McpListToolsTool]` + + The tools available on the server. + + - `input_schema: object` + + The JSON schema describing the tool's input. + + - `name: str` + + The name of the tool. + + - `annotations: Optional[object]` + + Additional annotations about the tool. + + - `description: Optional[str]` + + The description of the tool. + + - `type: Literal["mcp_list_tools"]` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `agent: Optional[McpListToolsAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `error: Optional[str]` + + Error message if the server could not list tools. + + - `class McpApprovalRequest: …` + + A request for human approval of a tool invocation. + + - `id: str` + + The unique ID of the approval request. + + - `arguments: str` + + A JSON string of arguments for the tool. + + - `name: str` + + The name of the tool to run. + + - `server_label: str` + + The label of the MCP server making the request. + + - `type: Literal["mcp_approval_request"]` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `agent: Optional[McpApprovalRequestAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse: …` + + A response to an MCP approval request. + + - `approval_request_id: str` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: Literal["mcp_approval_response"]` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `id: Optional[str]` + + The unique ID of the approval response + + - `agent: Optional[McpApprovalResponseAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `reason: Optional[str]` + + Optional reason for the decision. + + - `class McpCall: …` + + An invocation of a tool on an MCP server. + + - `id: str` + + The unique ID of the tool call. + + - `arguments: str` + + A JSON string of the arguments passed to the tool. + + - `name: str` + + The name of the tool that was run. + + - `server_label: str` + + The label of the MCP server running the tool. + + - `type: Literal["mcp_call"]` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `agent: Optional[McpCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `approval_request_id: Optional[str]` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: Optional[str]` + + The error from the tool call, if any. + + - `output: Optional[str]` + + The output from the tool call. + + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `class BetaResponseCustomToolCallOutput: …` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: str` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: Union[str, List[OutputOutputContentList]]` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `str` + + A string of the output of the custom tool call. + + - `List[OutputOutputContentList]` + + Text, image, or file output of the custom tool call. + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `type: Literal["custom_tool_call_output"]` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `"custom_tool_call_output"` + + - `id: Optional[str]` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `class BetaResponseCustomToolCall: …` + + A call to a custom tool created by the model. + + - `call_id: str` + + An identifier used to map this custom tool call to a tool call output. + + - `input: str` + + The input for the custom tool call generated by the model. + + - `name: str` + + The name of the custom tool being called. + + - `type: Literal["custom_tool_call"]` + + The type of the custom tool call. Always `custom_tool_call`. + + - `"custom_tool_call"` + + - `id: Optional[str]` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `namespace: Optional[str]` + + The namespace of the custom tool being called. + + - `class CompactionTrigger: …` + + Compacts the current context. Must be the final input item. + + - `type: Literal["compaction_trigger"]` + + The type of the item. Always `compaction_trigger`. + + - `"compaction_trigger"` + + - `agent: Optional[CompactionTriggerAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ItemReference: …` + + An internal identifier for an item to reference. + + - `id: str` + + The ID of the item to reference. + + - `agent: Optional[ItemReferenceAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `type: Optional[Literal["item_reference"]]` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + + - `class Program: …` + + - `id: str` + + The unique ID of this program item. + + - `call_id: str` + + The stable call ID of the program item. + + - `code: str` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: str` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: Literal["program"]` + + The item type. Always `program`. + + - `"program"` + + - `agent: Optional[ProgramAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput: …` + + - `id: str` + + The unique ID of this program output item. + + - `call_id: str` + + The call ID of the program item. + + - `result: str` + + The result produced by the program item. + + - `status: Literal["completed", "incomplete"]` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["program_output"]` + + The item type. Always `program_output`. + + - `"program_output"` + + - `agent: Optional[ProgramOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `metadata: Optional[Dict[str, str]]` 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 @@ -13037,2717 +22949,3010 @@ Retrieve run step 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"]` + - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` - The object type, which is always `thread.run.step`. + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `"thread.run.step"` + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` - - `run_id: str` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. + + - `"gpt-5.6-sol"` + + - `"gpt-5.6-terra"` + + - `"gpt-5.6-luna"` + + - `"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"` + + - `"o1-pro"` + + - `"o1-pro-2025-03-19"` + + - `"o3-pro"` + + - `"o3-pro-2025-06-10"` + + - `"o3-deep-research"` + + - `"o3-deep-research-2025-06-26"` + + - `"o4-mini-deep-research"` + + - `"o4-mini-deep-research-2025-06-26"` + + - `"computer-use-preview"` + + - `"computer-use-preview-2025-03-11"` + + - `"gpt-5-codex"` + + - `"gpt-5-pro"` + + - `"gpt-5-pro-2025-10-06"` + + - `"gpt-5.1-codex-max"` + + - `str` + + - `object: Literal["response"]` + + The object type of this resource - always set to `response`. + + - `"response"` + + - `output: List[BetaResponseOutputItem]` + + An array of content items generated by the model. + + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. + + - `class BetaResponseOutputMessage: …` + + An output message from the model. + + - `class BetaResponseFileSearchToolCall: …` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `class BetaResponseFunctionToolCall: …` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `class BetaResponseFunctionToolCallOutputItem: …` + + - `id: str` + + The unique ID of the function call tool output. + + - `call_id: str` + + The unique ID of the function tool call generated by the model. + + - `output: Union[str, List[OutputOutputContentList]]` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `str` + + A string of the output of the function call. + + - `List[OutputOutputContentList]` + + Text, image, or file output of the function call. + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["function_call_output"]` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `class AgentMessage: …` + + - `id: str` + + The unique ID of the agent message. + + - `author: str` + + The sending agent identity. + + - `content: List[AgentMessageContent]` + + Encrypted content sent between agents. + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseOutputText: …` + + A text output from the model. + + - `class AgentMessageContentText: …` + + A text content. + + - `text: str` + + - `type: Literal["text"]` + + - `"text"` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `class AgentMessageContentSummaryText: …` - - `status: Literal["in_progress", "cancelled", "failed", 2 more]` + A summary text from the model. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `text: str` - - `"in_progress"` + A summary of the reasoning output from the model so far. - - `"cancelled"` + - `type: Literal["summary_text"]` - - `"failed"` + The type of the object. Always `summary_text`. - - `"completed"` + - `"summary_text"` - - `"expired"` + - `class AgentMessageContentReasoningText: …` - - `step_details: StepDetails` + Reasoning text from the model. - The details of the run step. + - `text: str` - - `class MessageCreationStepDetails: …` + The reasoning text from the model. - Details of the message creation by the run step. + - `type: Literal["reasoning_text"]` - - `message_creation: MessageCreation` + The type of the reasoning text. Always `reasoning_text`. - - `message_id: str` + - `"reasoning_text"` - The ID of the message that was created by this run step. + - `class BetaResponseOutputRefusal: …` - - `type: Literal["message_creation"]` + A refusal from the model. - Always `message_creation`. + - `class BetaResponseInputImage: …` - - `"message_creation"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class ToolCallsStepDetails: …` + - `class AgentMessageContentComputerScreenshot: …` - Details of the tool call. + A screenshot of a computer. - - `tool_calls: List[object]` + - `detail: Literal["low", "high", "auto", "original"]` - 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`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: Literal["tool_calls"]` + - `"low"` - Always `tool_calls`. + - `"high"` - - `"tool_calls"` + - `"auto"` - - `thread_id: str` + - `"original"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `file_id: Optional[str]` - - `type: Literal["message_creation", "tool_calls"]` + The identifier of an uploaded file that contains the screenshot. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `image_url: Optional[str]` - - `"message_creation"` + The URL of the screenshot image. - - `"tool_calls"` + - `type: Literal["computer_screenshot"]` - - `usage: Optional[Usage]` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `"computer_screenshot"` - - `completion_tokens: int` + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - Number of completion tokens used over the course of the run step. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `prompt_tokens: int` + - `mode: Literal["explicit"]` - Number of prompt tokens used over the course of the run step. + The breakpoint mode. Always `explicit`. - - `total_tokens: int` + - `"explicit"` - Total number of tokens used (prompt + completion). + - `class BetaResponseInputFile: …` -### Example + A file input to the model. -```python -import os -from openai import OpenAI + - `class AgentMessageContentEncryptedContent: …` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -run_step = client.beta.threads.runs.steps.retrieve( - step_id="step_id", - thread_id="thread_id", - run_id="run_id", -) -print(run_step.id) -``` + Opaque encrypted content that Responses API decrypts inside trusted model execution. -#### Response + - `encrypted_content: str` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expired_at": 0, - "failed_at": 0, - "last_error": { - "code": "server_error", - "message": "message" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.run.step", - "run_id": "run_id", - "status": "in_progress", - "step_details": { - "message_creation": { - "message_id": "message_id" - }, - "type": "message_creation" - }, - "thread_id": "thread_id", - "type": "message_creation", - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - } -} -``` + Opaque encrypted content. -### Example + - `type: Literal["encrypted_content"]` -```python -from openai import OpenAI -client = OpenAI() + The type of the input item. Always `encrypted_content`. -run_step = client.beta.threads.runs.steps.retrieve( - thread_id="thread_abc123", - run_id="run_abc123", - step_id="step_abc123" -) + - `"encrypted_content"` -print(run_step) -``` + - `recipient: str` -#### Response + The destination agent identity. -```json -{ - "id": "step_abc123", - "object": "thread.run.step", - "created_at": 1699063291, - "run_id": "run_abc123", - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "type": "message_creation", - "status": "completed", - "cancelled_at": null, - "completed_at": 1699063291, - "expired_at": null, - "failed_at": null, - "last_error": null, - "step_details": { - "type": "message_creation", - "message_creation": { - "message_id": "msg_abc123" - } - }, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - } -} -``` + - `type: Literal["agent_message"]` -## Domain Types + The type of the item. Always `agent_message`. -### Code Interpreter Logs + - `"agent_message"` -- `class CodeInterpreterLogs: …` + - `agent: Optional[AgentMessageAgent]` - Text output from the Code Interpreter tool call as part of a run step. + The agent that produced this item. - - `index: int` + - `agent_name: str` - The index of the output in the outputs array. + The canonical name of the agent that produced this item. - - `type: Literal["logs"]` + - `class MultiAgentCall: …` - Always `logs`. + - `id: str` - - `"logs"` + The unique ID of the multi-agent call item. - - `logs: Optional[str]` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - The text output from the Code Interpreter tool call. + The multi-agent action to execute. -### Code Interpreter Output Image + - `"spawn_agent"` -- `class CodeInterpreterOutputImage: …` + - `"interrupt_agent"` - - `index: int` + - `"list_agents"` - The index of the output in the outputs array. + - `"send_message"` - - `type: Literal["image"]` + - `"followup_task"` - Always `image`. + - `"wait_agent"` - - `"image"` + - `arguments: str` - - `image: Optional[Image]` + The JSON string of arguments generated for the action. - - `file_id: Optional[str]` + - `call_id: str` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + The unique ID linking this call to its output. -### Code Interpreter Tool Call + - `type: Literal["multi_agent_call"]` -- `class CodeInterpreterToolCall: …` + The type of the multi-agent call. Always `multi_agent_call`. - Details of the Code Interpreter tool call the run step was involved in. + - `"multi_agent_call"` - - `id: str` + - `agent: Optional[MultiAgentCallAgent]` - The ID of the tool call. + The agent that produced this item. - - `code_interpreter: CodeInterpreter` + - `agent_name: str` - The Code Interpreter tool call definition. + The canonical name of the agent that produced this item. - - `input: str` + - `class MultiAgentCallOutput: …` - The input to the Code Interpreter tool call. + - `id: str` - - `outputs: List[CodeInterpreterOutput]` + The unique ID of the multi-agent call output item. - 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. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `class CodeInterpreterOutputLogs: …` + The multi-agent action that produced this result. - Text output from the Code Interpreter tool call as part of a run step. + - `"spawn_agent"` - - `logs: str` + - `"interrupt_agent"` - The text output from the Code Interpreter tool call. + - `"list_agents"` - - `type: Literal["logs"]` + - `"send_message"` - Always `logs`. + - `"followup_task"` - - `"logs"` + - `"wait_agent"` - - `class CodeInterpreterOutputImage: …` + - `call_id: str` - - `image: CodeInterpreterOutputImageImage` + The unique ID of the multi-agent call. - - `file_id: str` + - `output: List[BetaResponseOutputText]` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + Text output returned by the multi-agent action. - - `type: Literal["image"]` + - `annotations: List[Annotation]` - Always `image`. + The annotations of the text output. - - `"image"` + - `text: str` - - `type: Literal["code_interpreter"]` + The text output from the model. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `type: Literal["output_text"]` - - `"code_interpreter"` + The type of the output text. Always `output_text`. -### Code Interpreter Tool Call Delta + - `logprobs: Optional[List[Logprob]]` -- `class CodeInterpreterToolCallDelta: …` + - `type: Literal["multi_agent_call_output"]` - Details of the Code Interpreter tool call the run step was involved in. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `index: int` + - `"multi_agent_call_output"` - The index of the tool call in the tool calls array. + - `agent: Optional[MultiAgentCallOutputAgent]` - - `type: Literal["code_interpreter"]` + The agent that produced this item. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `agent_name: str` - - `"code_interpreter"` + The canonical name of the agent that produced this item. - - `id: Optional[str]` + - `class BetaResponseFunctionWebSearch: …` - The ID of the tool call. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `code_interpreter: Optional[CodeInterpreter]` + - `class BetaResponseComputerToolCall: …` - The Code Interpreter tool call definition. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `input: Optional[str]` + - `class BetaResponseComputerToolCallOutputItem: …` - The input to the Code Interpreter tool call. + - `id: str` - - `outputs: Optional[List[CodeInterpreterOutput]]` + The unique ID of the computer call tool output. - 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. + - `call_id: str` - - `class CodeInterpreterLogs: …` + The ID of the computer tool call that produced the output. - Text output from the Code Interpreter tool call as part of a run step. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `index: int` + A computer screenshot image used with the computer use tool. - The index of the output in the outputs array. + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - `type: Literal["logs"]` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Always `logs`. + - `"completed"` - - `"logs"` + - `"incomplete"` - - `logs: Optional[str]` + - `"failed"` - The text output from the Code Interpreter tool call. + - `"in_progress"` - - `class CodeInterpreterOutputImage: …` + - `type: Literal["computer_call_output"]` - - `index: int` + The type of the computer tool call output. Always `computer_call_output`. - The index of the output in the outputs array. + - `"computer_call_output"` - - `type: Literal["image"]` + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - Always `image`. + The safety checks reported by the API that have been acknowledged by the + developer. - - `"image"` + - `id: str` - - `image: Optional[Image]` + The ID of the pending safety check. - - `file_id: Optional[str]` + - `code: Optional[str]` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + The type of the pending safety check. -### File Search Tool Call + - `message: Optional[str]` -- `class FileSearchToolCall: …` + Details about the pending safety check. - - `id: str` + - `agent: Optional[Agent]` - The ID of the tool call object. + The agent that produced this item. - - `file_search: FileSearch` + - `agent_name: str` - For now, this is always going to be an empty object. + The canonical name of the agent that produced this item. - - `ranking_options: Optional[FileSearchRankingOptions]` + - `created_by: Optional[str]` - The ranking options for the file search. + The identifier of the actor that created the item. - - `ranker: Literal["auto", "default_2024_08_21"]` + - `class BetaResponseReasoningItem: …` - The ranker to use for the file search. If not specified will use the `auto` ranker. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `"auto"` + - `class Program: …` - - `"default_2024_08_21"` + - `id: str` - - `score_threshold: float` + The unique ID of the program item. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `call_id: str` - - `results: Optional[List[FileSearchResult]]` + The stable call ID of the program item. - The results of the file search. + - `code: str` - - `file_id: str` + The JavaScript source executed by programmatic tool calling. - The ID of the file that result was found in. + - `fingerprint: str` - - `file_name: str` + Opaque program replay fingerprint that must be round-tripped. - The name of the file that result was found in. + - `type: Literal["program"]` - - `score: float` + The type of the item. Always `program`. - The score of the result. All values must be a floating point number between 0 and 1. + - `"program"` - - `content: Optional[List[FileSearchResultContent]]` + - `agent: Optional[ProgramAgent]` - The content of the result that was found. The content is only included if requested via the include query parameter. + The agent that produced this item. - - `text: Optional[str]` + - `agent_name: str` - The text content of the file. + The canonical name of the agent that produced this item. - - `type: Optional[Literal["text"]]` + - `class ProgramOutput: …` - The type of the content. + - `id: str` - - `"text"` + The unique ID of the program output item. - - `type: Literal["file_search"]` + - `call_id: str` - The type of tool call. This is always going to be `file_search` for this type of tool call. + The call ID of the program item. - - `"file_search"` + - `result: str` -### File Search Tool Call Delta + The result produced by the program item. -- `class FileSearchToolCallDelta: …` + - `status: Literal["completed", "incomplete"]` - - `file_search: object` + The terminal status of the program output item. - For now, this is always going to be an empty object. + - `"completed"` - - `index: int` + - `"incomplete"` - The index of the tool call in the tool calls array. + - `type: Literal["program_output"]` - - `type: Literal["file_search"]` + The type of the item. Always `program_output`. - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `"program_output"` - - `"file_search"` + - `agent: Optional[ProgramOutputAgent]` - - `id: Optional[str]` + The agent that produced this item. - The ID of the tool call object. + - `agent_name: str` -### Function Tool Call + The canonical name of the agent that produced this item. -- `class FunctionToolCall: …` + - `class BetaResponseToolSearchCall: …` - `id: str` - The ID of the tool call object. + The unique ID of the tool search call item. - - `function: Function` + - `arguments: object` - The definition of the function that was called. + Arguments used for the tool search call. - - `arguments: str` + - `call_id: Optional[str]` - The arguments passed to the function. + The unique ID of the tool search call generated by the model. - - `name: str` + - `execution: Literal["server", "client"]` - The name of the function. + Whether tool search was executed by the server or by the client. - - `output: Optional[str]` + - `"server"` - 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. + - `"client"` - - `type: Literal["function"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The type of tool call. This is always going to be `function` for this type of tool call. + The status of the tool search call item that was recorded. - - `"function"` + - `"in_progress"` -### Function Tool Call Delta + - `"completed"` -- `class FunctionToolCallDelta: …` + - `"incomplete"` - - `index: int` + - `type: Literal["tool_search_call"]` - The index of the tool call in the tool calls array. + The type of the item. Always `tool_search_call`. - - `type: Literal["function"]` + - `"tool_search_call"` - The type of tool call. This is always going to be `function` for this type of tool call. + - `agent: Optional[Agent]` - - `"function"` + The agent that produced this item. - - `id: Optional[str]` + - `agent_name: str` - The ID of the tool call object. + The canonical name of the agent that produced this item. - - `function: Optional[Function]` + - `created_by: Optional[str]` - The definition of the function that was called. + The identifier of the actor that created the item. - - `arguments: Optional[str]` + - `class BetaResponseToolSearchOutputItem: …` - The arguments passed to the function. + - `id: str` - - `name: Optional[str]` + The unique ID of the tool search output item. - The name of the function. + - `call_id: Optional[str]` - - `output: Optional[str]` + The unique ID of the tool search call generated by the model. - 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. + - `execution: Literal["server", "client"]` -### Message Creation Step Details + Whether tool search was executed by the server or by the client. -- `class MessageCreationStepDetails: …` + - `"server"` - Details of the message creation by the run step. + - `"client"` - - `message_creation: MessageCreation` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `message_id: str` + The status of the tool search output item that was recorded. - The ID of the message that was created by this run step. + - `"in_progress"` - - `type: Literal["message_creation"]` + - `"completed"` - Always `message_creation`. + - `"incomplete"` - - `"message_creation"` + - `tools: List[BetaTool]` -### Run Step + The loaded tool definitions returned by tool search. -- `class RunStep: …` + - `class BetaFunctionTool: …` - Represents a step in execution of a run. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `id: str` + - `class BetaFileSearchTool: …` - The identifier of the run step, which can be referenced in API endpoints. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `assistant_id: str` + - `class BetaComputerTool: …` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `cancelled_at: Optional[int]` + - `class BetaComputerUsePreviewTool: …` - The Unix timestamp (in seconds) for when the run step was cancelled. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `completed_at: Optional[int]` + - `class BetaWebSearchTool: …` - The Unix timestamp (in seconds) for when the run step completed. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `created_at: int` + - `class Mcp: …` - The Unix timestamp (in seconds) for when the run step was created. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `expired_at: Optional[int]` + - `class CodeInterpreter: …` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + A tool that runs Python code to help generate a response to a prompt. - - `failed_at: Optional[int]` + - `class ProgrammaticToolCalling: …` - The Unix timestamp (in seconds) for when the run step failed. + - `class ImageGeneration: …` - - `last_error: Optional[LastError]` + A tool that generates images using the GPT image models. - The last error associated with this run step. Will be `null` if there are no errors. + - `class LocalShell: …` - - `code: Literal["server_error", "rate_limit_exceeded"]` + A tool that allows the model to execute shell commands in a local environment. - One of `server_error` or `rate_limit_exceeded`. + - `class BetaFunctionShellTool: …` - - `"server_error"` + A tool that allows the model to execute shell commands. - - `"rate_limit_exceeded"` + - `class BetaCustomTool: …` - - `message: str` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - A human-readable description of the error. + - `class BetaNamespaceTool: …` - - `metadata: Optional[Metadata]` + Groups function/custom tools under a shared namespace. - 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. + - `class BetaToolSearchTool: …` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Hosted or BYOT tool search configuration for deferred tools. - - `object: Literal["thread.run.step"]` + - `class BetaWebSearchPreviewTool: …` - The object type, which is always `thread.run.step`. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"thread.run.step"` + - `class BetaApplyPatchTool: …` - - `run_id: str` + Allows the assistant to create, delete, or update files using unified diffs. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `type: Literal["tool_search_output"]` - - `status: Literal["in_progress", "cancelled", "failed", 2 more]` + The type of the item. Always `tool_search_output`. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `"tool_search_output"` - - `"in_progress"` + - `agent: Optional[Agent]` - - `"cancelled"` + The agent that produced this item. - - `"failed"` + - `agent_name: str` - - `"completed"` + The canonical name of the agent that produced this item. - - `"expired"` + - `created_by: Optional[str]` - - `step_details: StepDetails` + The identifier of the actor that created the item. - The details of the run step. + - `class AdditionalTools: …` - - `class MessageCreationStepDetails: …` + - `id: str` - Details of the message creation by the run step. + The unique ID of the additional tools item. - - `message_creation: MessageCreation` + - `role: Literal["unknown", "user", "assistant", 5 more]` - - `message_id: str` + The role that provided the additional tools. - The ID of the message that was created by this run step. + - `"unknown"` - - `type: Literal["message_creation"]` + - `"user"` - Always `message_creation`. + - `"assistant"` - - `"message_creation"` + - `"system"` - - `class ToolCallsStepDetails: …` + - `"critic"` - Details of the tool call. + - `"discriminator"` - - `tool_calls: List[object]` + - `"developer"` - 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`. + - `"tool"` - - `type: Literal["tool_calls"]` + - `tools: List[BetaTool]` - Always `tool_calls`. + The additional tool definitions made available at this item. - - `"tool_calls"` + - `class BetaFunctionTool: …` - - `thread_id: str` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `class BetaFileSearchTool: …` - - `type: Literal["message_creation", "tool_calls"]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The type of run step, which can be either `message_creation` or `tool_calls`. + - `class BetaComputerTool: …` - - `"message_creation"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"tool_calls"` + - `class BetaComputerUsePreviewTool: …` - - `usage: Optional[Usage]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `class BetaWebSearchTool: …` - - `completion_tokens: int` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Number of completion tokens used over the course of the run step. + - `class Mcp: …` - - `prompt_tokens: int` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - Number of prompt tokens used over the course of the run step. + - `class CodeInterpreter: …` - - `total_tokens: int` + A tool that runs Python code to help generate a response to a prompt. - Total number of tokens used (prompt + completion). + - `class ProgrammaticToolCalling: …` -### Run Step Delta + - `class ImageGeneration: …` -- `object` + A tool that generates images using the GPT image models. -### Run Step Delta Event + - `class LocalShell: …` -- `class RunStepDeltaEvent: …` + A tool that allows the model to execute shell commands in a local environment. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `class BetaFunctionShellTool: …` - - `id: str` + A tool that allows the model to execute shell commands. - The identifier of the run step, which can be referenced in API endpoints. + - `class BetaCustomTool: …` - - `delta: object` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `object: Literal["thread.run.step.delta"]` + - `class BetaNamespaceTool: …` - The object type, which is always `thread.run.step.delta`. + Groups function/custom tools under a shared namespace. - - `"thread.run.step.delta"` + - `class BetaToolSearchTool: …` -### Run Step Delta Message Delta + Hosted or BYOT tool search configuration for deferred tools. -- `class RunStepDeltaMessageDelta: …` + - `class BetaWebSearchPreviewTool: …` - Details of the message creation by the run step. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `type: Literal["message_creation"]` + - `class BetaApplyPatchTool: …` - Always `message_creation`. + Allows the assistant to create, delete, or update files using unified diffs. - - `"message_creation"` + - `type: Literal["additional_tools"]` - - `message_creation: Optional[MessageCreation]` + The type of the item. Always `additional_tools`. - - `message_id: Optional[str]` + - `"additional_tools"` - The ID of the message that was created by this run step. + - `agent: Optional[AdditionalToolsAgent]` -### Run Step Include + The agent that produced this item. -- `Literal["step_details.tool_calls[*].file_search.results[*].content"]` + - `agent_name: str` - - `"step_details.tool_calls[*].file_search.results[*].content"` + The canonical name of the agent that produced this item. -### Tool Call + - `class BetaResponseCompactionItem: …` -- `object` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). -### Tool Call Delta + - `id: str` -- `object` + The unique ID of the compaction item. -### Tool Call Delta Object + - `encrypted_content: str` -- `class ToolCallDeltaObject: …` + The encrypted content that was produced by compaction. - Details of the tool call. + - `type: Literal["compaction"]` - - `type: Literal["tool_calls"]` + The type of the item. Always `compaction`. - Always `tool_calls`. + - `"compaction"` - - `"tool_calls"` + - `agent: Optional[Agent]` - - `tool_calls: Optional[List[object]]` + The agent that produced this item. - 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`. + - `agent_name: str` -### Tool Calls Step Details + The canonical name of the agent that produced this item. -- `class ToolCallsStepDetails: …` + - `created_by: Optional[str]` - Details of the tool call. + The identifier of the actor that created the item. - - `tool_calls: List[object]` + - `class ImageGenerationCall: …` - 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`. + An image generation request made by the model. - - `type: Literal["tool_calls"]` + - `id: str` - Always `tool_calls`. + The unique ID of the image generation call. - - `"tool_calls"` + - `result: Optional[str]` -# Messages + The generated image encoded in base64. -## List messages + - `status: Literal["in_progress", "completed", "generating", "failed"]` -`beta.threads.messages.list(strthread_id, MessageListParams**kwargs) -> SyncCursorPage[Message]` + The status of the image generation call. -**get** `/threads/{thread_id}/messages` + - `"in_progress"` -List messages + - `"completed"` -### Parameters + - `"generating"` -- `thread_id: str` + - `"failed"` -- `after: Optional[str]` + - `type: Literal["image_generation_call"]` - 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. + The type of the image generation call. Always `image_generation_call`. -- `before: Optional[str]` + - `"image_generation_call"` - 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. + - `agent: Optional[ImageGenerationCallAgent]` -- `limit: Optional[int]` + The agent that produced this item. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `agent_name: str` -- `order: Optional[Literal["asc", "desc"]]` + The canonical name of the agent that produced this item. - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `class BetaResponseCodeInterpreterToolCall: …` - - `"asc"` + A tool call to run code. - - `"desc"` + - `class LocalShellCall: …` -- `run_id: Optional[str]` + A tool call to run a command on the local shell. - Filter messages by the run ID that generated them. + - `id: str` -### Returns + The unique ID of the local shell call. -- `class Message: …` + - `action: LocalShellCallAction` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + Execute a shell command on the server. - - `id: str` + - `command: List[str]` - The identifier, which can be referenced in API endpoints. + The command to run. - - `assistant_id: Optional[str]` + - `env: Dict[str, str]` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + Environment variables to set for the command. - - `attachments: Optional[List[Attachment]]` + - `type: Literal["exec"]` - A list of files attached to the message, and the tools they were added to. + The type of the local shell action. Always `exec`. - - `file_id: Optional[str]` + - `"exec"` - The ID of the file to attach to the message. + - `timeout_ms: Optional[int]` - - `tools: Optional[List[AttachmentTool]]` + Optional timeout in milliseconds for the command. - The tools to add this file to. + - `user: Optional[str]` - - `class CodeInterpreterTool: …` + Optional user to run the command as. - - `type: Literal["code_interpreter"]` + - `working_directory: Optional[str]` - The type of tool being defined: `code_interpreter` + Optional working directory to run the command in. - - `"code_interpreter"` + - `call_id: str` - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + The unique ID of the local shell tool call generated by the model. - - `type: Literal["file_search"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The type of tool being defined: `file_search` + The status of the local shell call. - - `"file_search"` + - `"in_progress"` - - `completed_at: Optional[int]` + - `"completed"` - The Unix timestamp (in seconds) for when the message was completed. + - `"incomplete"` - - `content: List[object]` + - `type: Literal["local_shell_call"]` - The content of the message in array of text and/or images. + The type of the local shell call. Always `local_shell_call`. - - `created_at: int` + - `"local_shell_call"` - The Unix timestamp (in seconds) for when the message was created. + - `agent: Optional[LocalShellCallAgent]` - - `incomplete_at: Optional[int]` + The agent that produced this item. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `agent_name: str` - - `incomplete_details: Optional[IncompleteDetails]` + The canonical name of the agent that produced this item. - On an incomplete message, details about why the message is incomplete. + - `class LocalShellCallOutput: …` - - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` + The output of a local shell tool call. - The reason the message is incomplete. + - `id: str` - - `"content_filter"` + The unique ID of the local shell tool call generated by the model. - - `"max_tokens"` + - `output: str` - - `"run_cancelled"` + A JSON string of the output of the local shell tool call. - - `"run_expired"` + - `type: Literal["local_shell_call_output"]` - - `"run_failed"` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `metadata: Optional[Metadata]` + - `"local_shell_call_output"` - 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. + - `agent: Optional[LocalShellCallOutputAgent]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The agent that produced this item. - - `object: Literal["thread.message"]` + - `agent_name: str` - The object type, which is always `thread.message`. + The canonical name of the agent that produced this item. - - `"thread.message"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `role: Literal["user", "assistant"]` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The entity that produced the message. One of `user` or `assistant`. + - `"in_progress"` - - `"user"` + - `"completed"` - - `"assistant"` + - `"incomplete"` - - `run_id: Optional[str]` + - `class BetaResponseFunctionShellToolCall: …` - 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. + A tool call that executes one or more shell commands in a managed environment. - - `status: Literal["in_progress", "incomplete", "completed"]` + - `id: str` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"in_progress"` + - `action: Action` - - `"incomplete"` + The shell commands and limits that describe how to run the tool call. - - `"completed"` + - `commands: List[str]` - - `thread_id: str` + - `max_output_length: Optional[int]` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + Optional maximum number of characters to return from each command. -### Example + - `timeout_ms: Optional[int]` -```python -import os -from openai import OpenAI + Optional timeout in milliseconds for the commands. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -page = client.beta.threads.messages.list( - thread_id="thread_id", -) -page = page.data[0] -print(page.id) -``` + - `call_id: str` -#### Response + The unique ID of the shell tool call generated by the model. -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" - } - ], - "first_id": "msg_abc123", - "has_more": false, - "last_id": "msg_abc123", - "object": "list" -} -``` + - `environment: Optional[Environment]` -### Example + Represents the use of a local environment to perform shell actions. -```python -from openai import OpenAI -client = OpenAI() + - `class BetaResponseLocalEnvironment: …` -thread_messages = client.beta.threads.messages.list("thread_abc123") -print(thread_messages.data) -``` + Represents the use of a local environment to perform shell actions. -#### Response + - `type: Literal["local"]` -```json -{ - "object": "list", - "data": [ - { - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699016383, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} - }, - { - "id": "msg_abc456", - "object": "thread.message", - "created_at": 1699016383, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "Hello, what is AI?", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} - } - ], - "first_id": "msg_abc123", - "last_id": "msg_abc456", - "has_more": false -} -``` + The environment type. Always `local`. -## Create message + - `"local"` + + - `class BetaResponseContainerReference: …` -`beta.threads.messages.create(strthread_id, MessageCreateParams**kwargs) -> Message` + Represents a container created with /v1/containers. -**post** `/threads/{thread_id}/messages` + - `container_id: str` -Create message + - `type: Literal["container_reference"]` -### Parameters + The environment type. Always `container_reference`. -- `thread_id: str` + - `"container_reference"` -- `content: Union[str, Iterable[MessageContentPartParam]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The text contents of the message. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `str` + - `"in_progress"` - The text contents of the message. + - `"completed"` - - `Iterable[MessageContentPartParam]` + - `"incomplete"` - An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](https://platform.openai.com/docs/models). + - `type: Literal["shell_call"]` - - `class ImageFileContentBlock: …` + The type of the item. Always `shell_call`. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `"shell_call"` - - `image_file: ImageFileParam` + - `agent: Optional[Agent]` - - `file_id: str` + The agent that produced this item. - 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. + - `agent_name: str` - - `detail: Optional[Literal["auto", "low", "high"]]` + The canonical name of the agent that produced this item. - 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`. + - `caller: Optional[Caller]` - - `"auto"` + The execution context that produced this tool call. - - `"low"` + - `class CallerDirect: …` - - `"high"` + - `type: Literal["direct"]` - - `type: Literal["image_file"]` + - `"direct"` - Always `image_file`. + - `class CallerProgram: …` - - `"image_file"` + - `caller_id: str` - - `class ImageURLContentBlock: …` + The call ID of the program item that produced this tool call. - References an image URL in the content of a message. + - `type: Literal["program"]` - - `image_url: ImageURLParam` + - `"program"` - - `url: str` + - `created_by: Optional[str]` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The ID of the entity that created this tool call. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `class BetaResponseFunctionShellToolCallOutput: …` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + The output of a shell tool call that was emitted. - - `"auto"` + - `id: str` - - `"low"` + The unique ID of the shell call output. Populated when this item is returned via API. - - `"high"` + - `call_id: str` - - `type: Literal["image_url"]` + The unique ID of the shell tool call generated by the model. - The type of the content part. + - `max_output_length: Optional[int]` - - `"image_url"` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `class TextContentBlockParam: …` + - `output: List[Output]` - The text content that is part of a message. + An array of shell call output contents - - `text: str` + - `outcome: OutputOutcome` - Text content to be sent to the model + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `type: Literal["text"]` + - `class OutputOutcomeTimeout: …` - Always `text`. + Indicates that the shell call exceeded its configured time limit. - - `"text"` + - `type: Literal["timeout"]` -- `role: Literal["user", "assistant"]` + The outcome type. Always `timeout`. - The role of the entity that is creating the message. Allowed values include: + - `"timeout"` - - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + - `class OutputOutcomeExit: …` - - `"user"` + Indicates that the shell commands finished and returned an exit code. - - `"assistant"` + - `exit_code: int` -- `attachments: Optional[Iterable[Attachment]]` + Exit code from the shell process. - A list of files attached to the message, and the tools they should be added to. + - `type: Literal["exit"]` - - `file_id: Optional[str]` + The outcome type. Always `exit`. - The ID of the file to attach to the message. + - `"exit"` - - `tools: Optional[Iterable[AttachmentTool]]` + - `stderr: str` - The tools to add this file to. + The standard error output that was captured. - - `class CodeInterpreterTool: …` + - `stdout: str` - - `type: Literal["code_interpreter"]` + The standard output that was captured. - The type of tool being defined: `code_interpreter` + - `created_by: Optional[str]` - - `"code_interpreter"` + The identifier of the actor that created the item. - - `class AttachmentToolFileSearch: …` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["file_search"]` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The type of tool being defined: `file_search` + - `"in_progress"` - - `"file_search"` + - `"completed"` -- `metadata: Optional[Metadata]` + - `"incomplete"` - 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. + - `type: Literal["shell_call_output"]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The type of the shell call output. Always `shell_call_output`. -### Returns + - `"shell_call_output"` -- `class Message: …` + - `agent: Optional[Agent]` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + The agent that produced this item. - - `id: str` + - `agent_name: str` - The identifier, which can be referenced in API endpoints. + The canonical name of the agent that produced this item. - - `assistant_id: Optional[str]` + - `caller: Optional[Caller]` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The execution context that produced this tool call. - - `attachments: Optional[List[Attachment]]` + - `class CallerDirect: …` - A list of files attached to the message, and the tools they were added to. + - `type: Literal["direct"]` - - `file_id: Optional[str]` + - `"direct"` - The ID of the file to attach to the message. + - `class CallerProgram: …` - - `tools: Optional[List[AttachmentTool]]` + - `caller_id: str` - The tools to add this file to. + The call ID of the program item that produced this tool call. - - `class CodeInterpreterTool: …` + - `type: Literal["program"]` - - `type: Literal["code_interpreter"]` + - `"program"` - The type of tool being defined: `code_interpreter` + - `created_by: Optional[str]` - - `"code_interpreter"` + The identifier of the actor that created the item. - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + - `class BetaResponseApplyPatchToolCall: …` - - `type: Literal["file_search"]` + A tool call that applies file diffs by creating, deleting, or updating files. - The type of tool being defined: `file_search` + - `id: str` - - `"file_search"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `completed_at: Optional[int]` + - `call_id: str` - The Unix timestamp (in seconds) for when the message was completed. + The unique ID of the apply patch tool call generated by the model. - - `content: List[object]` + - `operation: Operation` - The content of the message in array of text and/or images. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `created_at: int` + - `class OperationCreateFile: …` - The Unix timestamp (in seconds) for when the message was created. + Instruction describing how to create a file via the apply_patch tool. - - `incomplete_at: Optional[int]` + - `diff: str` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + Diff to apply. - - `incomplete_details: Optional[IncompleteDetails]` + - `path: str` - On an incomplete message, details about why the message is incomplete. + Path of the file to create. - - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` + - `type: Literal["create_file"]` - The reason the message is incomplete. + Create a new file with the provided diff. - - `"content_filter"` + - `"create_file"` - - `"max_tokens"` + - `class OperationDeleteFile: …` - - `"run_cancelled"` + Instruction describing how to delete a file via the apply_patch tool. - - `"run_expired"` + - `path: str` - - `"run_failed"` + Path of the file to delete. - - `metadata: Optional[Metadata]` + - `type: Literal["delete_file"]` - 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. + Delete the specified file. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"delete_file"` - - `object: Literal["thread.message"]` + - `class OperationUpdateFile: …` - The object type, which is always `thread.message`. + Instruction describing how to update a file via the apply_patch tool. - - `"thread.message"` + - `diff: str` - - `role: Literal["user", "assistant"]` + Diff to apply. - The entity that produced the message. One of `user` or `assistant`. + - `path: str` - - `"user"` + Path of the file to update. - - `"assistant"` + - `type: Literal["update_file"]` - - `run_id: Optional[str]` + Update an existing file with the provided diff. - 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. + - `"update_file"` - - `status: Literal["in_progress", "incomplete", "completed"]` + - `status: Literal["in_progress", "completed"]` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - `"in_progress"` - - `"incomplete"` - - `"completed"` - - `thread_id: str` + - `type: Literal["apply_patch_call"]` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + The type of the item. Always `apply_patch_call`. -### Example + - `"apply_patch_call"` -```python -import os -from openai import OpenAI + - `agent: Optional[Agent]` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -message = client.beta.threads.messages.create( - thread_id="thread_id", - content="string", - role="user", -) -print(message.id) -``` + The agent that produced this item. -#### Response + - `agent_name: str` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + The canonical name of the agent that produced this item. -### Example + - `caller: Optional[Caller]` -```python -from openai import OpenAI -client = OpenAI() + The execution context that produced this tool call. -thread_message = client.beta.threads.messages.create( - "thread_abc123", - role="user", - content="How does AI work? Explain it in simple terms.", -) -print(thread_message) -``` + - `class CallerDirect: …` -#### Response + - `type: Literal["direct"]` -```json -{ - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1713226573, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} -} -``` + - `"direct"` -## Modify message + - `class CallerProgram: …` -`beta.threads.messages.update(strmessage_id, MessageUpdateParams**kwargs) -> Message` + - `caller_id: str` -**post** `/threads/{thread_id}/messages/{message_id}` + The call ID of the program item that produced this tool call. -Modify message + - `type: Literal["program"]` -### Parameters + - `"program"` -- `thread_id: str` + - `created_by: Optional[str]` -- `message_id: str` + The ID of the entity that created this tool call. -- `metadata: Optional[Metadata]` + - `class BetaResponseApplyPatchToolCallOutput: …` - 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. + The output emitted by an apply patch tool call. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `id: str` -### Returns + The unique ID of the apply patch tool call output. Populated when this item is returned via API. -- `class Message: …` + - `call_id: str` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + The unique ID of the apply patch tool call generated by the model. - - `id: str` + - `status: Literal["completed", "failed"]` - The identifier, which can be referenced in API endpoints. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `assistant_id: Optional[str]` + - `"completed"` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `"failed"` - - `attachments: Optional[List[Attachment]]` + - `type: Literal["apply_patch_call_output"]` - A list of files attached to the message, and the tools they were added to. + The type of the item. Always `apply_patch_call_output`. - - `file_id: Optional[str]` + - `"apply_patch_call_output"` - The ID of the file to attach to the message. + - `agent: Optional[Agent]` - - `tools: Optional[List[AttachmentTool]]` + The agent that produced this item. - The tools to add this file to. + - `agent_name: str` - - `class CodeInterpreterTool: …` + The canonical name of the agent that produced this item. - - `type: Literal["code_interpreter"]` + - `caller: Optional[Caller]` - The type of tool being defined: `code_interpreter` + The execution context that produced this tool call. - - `"code_interpreter"` + - `class CallerDirect: …` - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + - `type: Literal["direct"]` - - `type: Literal["file_search"]` + - `"direct"` - The type of tool being defined: `file_search` + - `class CallerProgram: …` - - `"file_search"` + - `caller_id: str` - - `completed_at: Optional[int]` + The call ID of the program item that produced this tool call. - The Unix timestamp (in seconds) for when the message was completed. + - `type: Literal["program"]` - - `content: List[object]` + - `"program"` - The content of the message in array of text and/or images. + - `created_by: Optional[str]` - - `created_at: int` + The ID of the entity that created this tool call output. - The Unix timestamp (in seconds) for when the message was created. + - `output: Optional[str]` - - `incomplete_at: Optional[int]` + Optional textual output returned by the apply patch tool. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `class McpCall: …` - - `incomplete_details: Optional[IncompleteDetails]` + An invocation of a tool on an MCP server. - On an incomplete message, details about why the message is incomplete. + - `id: str` - - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` + The unique ID of the tool call. - The reason the message is incomplete. + - `arguments: str` - - `"content_filter"` + A JSON string of the arguments passed to the tool. - - `"max_tokens"` + - `name: str` - - `"run_cancelled"` + The name of the tool that was run. - - `"run_expired"` + - `server_label: str` - - `"run_failed"` + The label of the MCP server running the tool. - - `metadata: Optional[Metadata]` + - `type: Literal["mcp_call"]` - 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. + The type of the item. Always `mcp_call`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"mcp_call"` - - `object: Literal["thread.message"]` + - `agent: Optional[McpCallAgent]` - The object type, which is always `thread.message`. + The agent that produced this item. - - `"thread.message"` + - `agent_name: str` - - `role: Literal["user", "assistant"]` + The canonical name of the agent that produced this item. - The entity that produced the message. One of `user` or `assistant`. + - `approval_request_id: Optional[str]` - - `"user"` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `"assistant"` + - `error: Optional[str]` - - `run_id: Optional[str]` + The error from the tool call, if any. - 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. + - `output: Optional[str]` - - `status: Literal["in_progress", "incomplete", "completed"]` + The output from the tool call. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `"in_progress"` + - `"completed"` + - `"incomplete"` - - `"completed"` + - `"calling"` - - `thread_id: str` + - `"failed"` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `class McpListTools: …` -### Example + A list of tools available on an MCP server. -```python -import os -from openai import OpenAI + - `id: str` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -message = client.beta.threads.messages.update( - message_id="message_id", - thread_id="thread_id", -) -print(message.id) -``` + The unique ID of the list. -#### Response + - `server_label: str` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + The label of the MCP server. -### Example + - `tools: List[McpListToolsTool]` -```python -from openai import OpenAI -client = OpenAI() + The tools available on the server. -message = client.beta.threads.messages.update( - message_id="msg_abc12", - thread_id="thread_abc123", - metadata={ - "modified": "true", - "user": "abc123", - }, -) -print(message) -``` + - `input_schema: object` -#### Response + The JSON schema describing the tool's input. -```json -{ - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699017614, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "file_ids": [], - "metadata": { - "modified": "true", - "user": "abc123" - } -} -``` + - `name: str` -## Retrieve message + The name of the tool. -`beta.threads.messages.retrieve(strmessage_id, MessageRetrieveParams**kwargs) -> Message` + - `annotations: Optional[object]` -**get** `/threads/{thread_id}/messages/{message_id}` + Additional annotations about the tool. -Retrieve message + - `description: Optional[str]` -### Parameters + The description of the tool. -- `thread_id: str` + - `type: Literal["mcp_list_tools"]` -- `message_id: str` + The type of the item. Always `mcp_list_tools`. -### Returns + - `"mcp_list_tools"` -- `class Message: …` + - `agent: Optional[McpListToolsAgent]` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `error: Optional[str]` + + Error message if the server could not list tools. + + - `class McpApprovalRequest: …` + + A request for human approval of a tool invocation. - `id: str` - The identifier, which can be referenced in API endpoints. + The unique ID of the approval request. - - `assistant_id: Optional[str]` + - `arguments: str` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + A JSON string of arguments for the tool. - - `attachments: Optional[List[Attachment]]` + - `name: str` - A list of files attached to the message, and the tools they were added to. + The name of the tool to run. - - `file_id: Optional[str]` + - `server_label: str` - The ID of the file to attach to the message. + The label of the MCP server making the request. - - `tools: Optional[List[AttachmentTool]]` + - `type: Literal["mcp_approval_request"]` - The tools to add this file to. + The type of the item. Always `mcp_approval_request`. - - `class CodeInterpreterTool: …` + - `"mcp_approval_request"` - - `type: Literal["code_interpreter"]` + - `agent: Optional[McpApprovalRequestAgent]` - The type of tool being defined: `code_interpreter` + The agent that produced this item. - - `"code_interpreter"` + - `agent_name: str` - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + The canonical name of the agent that produced this item. - - `type: Literal["file_search"]` + - `class McpApprovalResponse: …` - The type of tool being defined: `file_search` + A response to an MCP approval request. - - `"file_search"` + - `id: str` - - `completed_at: Optional[int]` + The unique ID of the approval response - The Unix timestamp (in seconds) for when the message was completed. + - `approval_request_id: str` - - `content: List[object]` + The ID of the approval request being answered. - The content of the message in array of text and/or images. + - `approve: bool` - - `created_at: int` + Whether the request was approved. - The Unix timestamp (in seconds) for when the message was created. + - `type: Literal["mcp_approval_response"]` - - `incomplete_at: Optional[int]` + The type of the item. Always `mcp_approval_response`. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `"mcp_approval_response"` - - `incomplete_details: Optional[IncompleteDetails]` + - `agent: Optional[McpApprovalResponseAgent]` - On an incomplete message, details about why the message is incomplete. + The agent that produced this item. - - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` + - `agent_name: str` - The reason the message is incomplete. + The canonical name of the agent that produced this item. - - `"content_filter"` + - `reason: Optional[str]` - - `"max_tokens"` + Optional reason for the decision. - - `"run_cancelled"` + - `class BetaResponseCustomToolCall: …` - - `"run_expired"` + A call to a custom tool created by the model. - - `"run_failed"` + - `class BetaResponseCustomToolCallOutputItem: …` - - `metadata: Optional[Metadata]` + The output of a custom tool call from your code, being sent back to the model. - 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. + - `id: str` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The unique ID of the custom tool call output item. - - `object: Literal["thread.message"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The object type, which is always `thread.message`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"thread.message"` + - `"in_progress"` - - `role: Literal["user", "assistant"]` + - `"completed"` - The entity that produced the message. One of `user` or `assistant`. + - `"incomplete"` - - `"user"` + - `created_by: Optional[str]` - - `"assistant"` + The identifier of the actor that created the item. - - `run_id: Optional[str]` + - `parallel_tool_calls: bool` - 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. + Whether to allow the model to run tool calls in parallel. - - `status: Literal["in_progress", "incomplete", "completed"]` + - `temperature: Optional[float]` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + 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. + We generally recommend altering this or `top_p` but not both. - - `"in_progress"` + - `tool_choice: ToolChoice` - - `"incomplete"` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `"completed"` + - `Literal["none", "auto", "required"]` - - `thread_id: str` + - `"none"` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `"auto"` -### Example + - `"required"` -```python -import os -from openai import OpenAI + - `class BetaToolChoiceAllowed: …` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -message = client.beta.threads.messages.retrieve( - message_id="message_id", - thread_id="thread_id", -) -print(message.id) -``` + Constrains the tools available to the model to a pre-defined set. -#### Response + - `mode: Literal["auto", "required"]` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `"auto"` + + - `"required"` + + - `tools: List[Dict[str, object]]` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + ``` -### Example + - `type: Literal["allowed_tools"]` -```python -from openai import OpenAI -client = OpenAI() + Allowed tool configuration type. Always `allowed_tools`. -message = client.beta.threads.messages.retrieve( - message_id="msg_abc123", - thread_id="thread_abc123", -) -print(message) -``` + - `"allowed_tools"` -#### Response + - `class BetaToolChoiceTypes: …` -```json -{ - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699017614, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} -} -``` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). -## Delete message + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` -`beta.threads.messages.delete(strmessage_id, MessageDeleteParams**kwargs) -> MessageDeleted` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). -**delete** `/threads/{thread_id}/messages/{message_id}` + Allowed values are: -Delete message + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` -### Parameters + - `"file_search"` -- `thread_id: str` + - `"web_search_preview"` -- `message_id: str` + - `"computer"` -### Returns + - `"computer_use_preview"` -- `class MessageDeleted: …` + - `"computer_use"` - - `id: str` + - `"web_search_preview_2025_03_11"` - - `deleted: bool` + - `"image_generation"` - - `object: Literal["thread.message.deleted"]` + - `"code_interpreter"` - - `"thread.message.deleted"` + - `class BetaToolChoiceFunction: …` -### Example + Use this option to force the model to call a specific function. -```python -import os -from openai import OpenAI + - `name: str` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -message_deleted = client.beta.threads.messages.delete( - message_id="message_id", - thread_id="thread_id", -) -print(message_deleted.id) -``` + The name of the function to call. -#### Response + - `type: Literal["function"]` -```json -{ - "id": "id", - "deleted": true, - "object": "thread.message.deleted" -} -``` + For function calling, the type is always `function`. -### Example + - `"function"` -```python -from openai import OpenAI -client = OpenAI() + - `class BetaToolChoiceMcp: …` -deleted_message = client.beta.threads.messages.delete( - message_id="msg_abc12", - thread_id="thread_abc123", -) -print(deleted_message) -``` + Use this option to force the model to call a specific tool on a remote MCP server. -#### Response + - `server_label: str` -```json -{ - "id": "msg_abc123", - "object": "thread.message.deleted", - "deleted": true -} -``` + The label of the MCP server to use. -## Domain Types + - `type: Literal["mcp"]` -### Annotation + For MCP tools, the type is always `mcp`. -- `object` + - `"mcp"` -### Annotation Delta + - `name: Optional[str]` -- `object` + The name of the tool to call on the server. -### File Citation Annotation + - `class BetaToolChoiceCustom: …` -- `class FileCitationAnnotation: …` + Use this option to force the model to call a specific custom tool. - 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. + - `name: str` - - `end_index: int` + The name of the custom tool to call. - - `file_citation: FileCitation` + - `type: Literal["custom"]` - - `file_id: str` + For custom tool calling, the type is always `custom`. - The ID of the specific File the citation is from. + - `"custom"` - - `start_index: int` + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` - - `text: str` + - `type: Literal["programmatic_tool_calling"]` - The text in the message content that needs to be replaced. + The tool to call. Always `programmatic_tool_calling`. - - `type: Literal["file_citation"]` + - `"programmatic_tool_calling"` - Always `file_citation`. + - `class BetaToolChoiceApplyPatch: …` - - `"file_citation"` + Forces the model to call the apply_patch tool when executing a tool call. -### File Citation Delta Annotation + - `type: Literal["apply_patch"]` -- `class FileCitationDeltaAnnotation: …` + The tool to call. Always `apply_patch`. - 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. + - `"apply_patch"` - - `index: int` + - `class BetaToolChoiceShell: …` - The index of the annotation in the text content part. + Forces the model to call the shell tool when a tool call is required. - - `type: Literal["file_citation"]` + - `type: Literal["shell"]` - Always `file_citation`. + The tool to call. Always `shell`. - - `"file_citation"` + - `"shell"` - - `end_index: Optional[int]` + - `tools: List[BetaTool]` - - `file_citation: Optional[FileCitation]` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `file_id: Optional[str]` + We support the following categories of tools: - The ID of the specific File the citation is from. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `quote: Optional[str]` + - `class BetaFunctionTool: …` - The specific quote in the file. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `start_index: Optional[int]` + - `class BetaFileSearchTool: …` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool: …` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class Mcp: …` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `class CodeInterpreter: …` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling: …` + + - `class ImageGeneration: …` + + A tool that generates images using the GPT image models. + + - `class LocalShell: …` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool: …` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `text: Optional[str]` + - `class BetaNamespaceTool: …` - The text in the message content that needs to be replaced. + Groups function/custom tools under a shared namespace. -### File Path Annotation + - `class BetaToolSearchTool: …` -- `class FilePathAnnotation: …` + Hosted or BYOT tool search configuration for deferred tools. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `class BetaWebSearchPreviewTool: …` - - `end_index: int` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `file_path: FilePath` + - `class BetaApplyPatchTool: …` - - `file_id: str` + Allows the assistant to create, delete, or update files using unified diffs. - The ID of the file that was generated. + - `top_p: Optional[float]` - - `start_index: int` + 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. - - `text: str` + We generally recommend altering this or `temperature` but not both. - The text in the message content that needs to be replaced. + - `background: Optional[bool]` - - `type: Literal["file_path"]` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - Always `file_path`. + - `completed_at: Optional[float]` - - `"file_path"` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. -### File Path Delta Annotation + - `conversation: Optional[Conversation]` -- `class FilePathDeltaAnnotation: …` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `id: str` - - `index: int` + The unique ID of the conversation that this response was associated with. - The index of the annotation in the text content part. + - `max_output_tokens: Optional[int]` - - `type: Literal["file_path"]` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - Always `file_path`. + - `max_tool_calls: Optional[int]` - - `"file_path"` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `end_index: Optional[int]` + - `moderation: Optional[Moderation]` - - `file_path: Optional[FilePath]` + Moderation results for the response input and output, if moderated completions were requested. - - `file_id: Optional[str]` + - `input: ModerationInput` - The ID of the file that was generated. + Moderation for the response input. - - `start_index: Optional[int]` + - `class ModerationInputModerationResult: …` - - `text: Optional[str]` + A moderation result produced for the response input or output. - The text in the message content that needs to be replaced. + - `categories: Dict[str, bool]` -### Image File + A dictionary of moderation categories to booleans, True if the input is flagged under this category. -- `class ImageFile: …` + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - - `file_id: str` + Which modalities of input are reflected by the score for each category. - 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. + - `"text"` - - `detail: Optional[Literal["auto", "low", "high"]]` + - `"image"` - 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`. + - `category_scores: Dict[str, float]` - - `"auto"` + A dictionary of moderation categories to scores. - - `"low"` + - `flagged: bool` - - `"high"` + A boolean indicating whether the content was flagged by any category. -### Image File Content Block + - `model: str` -- `class ImageFileContentBlock: …` + The moderation model that produced this result. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `type: Literal["moderation_result"]` - - `image_file: ImageFileParam` + The object type, which was always `moderation_result` for successful moderation results. - - `file_id: str` + - `"moderation_result"` - 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 ModerationInputError: …` - - `detail: Optional[Literal["auto", "low", "high"]]` + An error produced while attempting moderation for the response input or output. - 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`. + - `code: str` - - `"auto"` + The error code. - - `"low"` + - `message: str` - - `"high"` + The error message. - - `type: Literal["image_file"]` + - `type: Literal["error"]` - Always `image_file`. + The object type, which was always `error` for moderation failures. - - `"image_file"` + - `"error"` -### Image File Delta + - `output: ModerationOutput` -- `class ImageFileDelta: …` + Moderation for the response output. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `class ModerationOutputModerationResult: …` - 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`. + A moderation result produced for the response input or output. - - `"auto"` + - `categories: Dict[str, bool]` - - `"low"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"high"` + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - - `file_id: Optional[str]` + Which modalities of input are reflected by the score for each category. - 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. + - `"text"` -### Image File Delta Block + - `"image"` -- `class ImageFileDeltaBlock: …` + - `category_scores: Dict[str, float]` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + A dictionary of moderation categories to scores. - - `index: int` + - `flagged: bool` - The index of the content part in the message. + A boolean indicating whether the content was flagged by any category. - - `type: Literal["image_file"]` + - `model: str` - Always `image_file`. + The moderation model that produced this result. - - `"image_file"` + - `type: Literal["moderation_result"]` - - `image_file: Optional[ImageFileDelta]` + The object type, which was always `moderation_result` for successful moderation results. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `"moderation_result"` - 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`. + - `class ModerationOutputError: …` - - `"auto"` + An error produced while attempting moderation for the response input or output. - - `"low"` + - `code: str` - - `"high"` + The error code. - - `file_id: Optional[str]` + - `message: 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. + The error message. -### Image URL + - `type: Literal["error"]` -- `class ImageURL: …` + The object type, which was always `error` for moderation failures. - - `url: str` + - `"error"` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `previous_response_id: Optional[str]` - - `detail: Optional[Literal["auto", "low", "high"]]` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `prompt: Optional[BetaResponsePrompt]` - - `"auto"` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `"low"` + - `id: str` - - `"high"` + The unique identifier of the prompt template to use. -### Image URL Content Block + - `variables: Optional[Dict[str, Variables]]` -- `class ImageURLContentBlock: …` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - References an image URL in the content of a message. + - `str` - - `image_url: ImageURLParam` + - `class BetaResponseInputText: …` - - `url: str` + A text input to the model. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `class BetaResponseInputImage: …` - - `detail: Optional[Literal["auto", "low", "high"]]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `class BetaResponseInputFile: …` - - `"auto"` + A file input to the model. - - `"low"` + - `version: Optional[str]` - - `"high"` + Optional version of the prompt template. - - `type: Literal["image_url"]` + - `prompt_cache_key: Optional[str]` - The type of the content part. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `"image_url"` + - `prompt_cache_options: Optional[PromptCacheOptions]` -### Image URL Delta + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. -- `class ImageURLDelta: …` + - `mode: Literal["implicit", "explicit"]` - - `detail: Optional[Literal["auto", "low", "high"]]` + Whether implicit prompt-cache breakpoints were enabled. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `"implicit"` - - `"auto"` + - `"explicit"` - - `"low"` + - `ttl: Literal["30m"]` - - `"high"` + The minimum lifetime applied to each cache breakpoint. - - `url: Optional[str]` + - `"30m"` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` -### Image URL Delta Block + Deprecated. Use `prompt_cache_options.ttl` instead. -- `class ImageURLDeltaBlock: …` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - References an image URL in the content of a message. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `index: int` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The index of the content part in the message. + - `"in_memory"` - - `type: Literal["image_url"]` + - `"24h"` - Always `image_url`. + - `reasoning: Optional[Reasoning]` - - `"image_url"` + **gpt-5 and o-series models only** - - `image_url: Optional[ImageURLDelta]` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `detail: Optional[Literal["auto", "low", "high"]]` + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - `"auto"` - - `"low"` + - `"current_turn"` - - `"high"` + - `"all_turns"` - - `url: Optional[str]` + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. -### Message + - `"none"` -- `class Message: …` + - `"minimal"` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"low"` - - `id: str` + - `"medium"` - The identifier, which can be referenced in API endpoints. + - `"high"` - - `assistant_id: Optional[str]` + - `"xhigh"` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `"max"` - - `attachments: Optional[List[Attachment]]` + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` - A list of files attached to the message, and the tools they were added to. + **Deprecated:** use `summary` instead. - - `file_id: Optional[str]` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The ID of the file to attach to the message. + - `"auto"` - - `tools: Optional[List[AttachmentTool]]` + - `"concise"` - The tools to add this file to. + - `"detailed"` - - `class CodeInterpreterTool: …` + - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` - - `type: Literal["code_interpreter"]` + Controls the reasoning execution mode for the request. - The type of tool being defined: `code_interpreter` + When returned on a response, this is the effective execution mode. - - `"code_interpreter"` + - `str` - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + - `Literal["standard", "pro"]` - - `type: Literal["file_search"]` + Controls the reasoning execution mode for the request. - The type of tool being defined: `file_search` + When returned on a response, this is the effective execution mode. - - `"file_search"` + - `"standard"` - - `completed_at: Optional[int]` + - `"pro"` - The Unix timestamp (in seconds) for when the message was completed. + - `summary: Optional[Literal["auto", "concise", "detailed"]]` - - `content: List[object]` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The content of the message in array of text and/or images. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `created_at: int` + - `"auto"` - The Unix timestamp (in seconds) for when the message was created. + - `"concise"` - - `incomplete_at: Optional[int]` + - `"detailed"` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `safety_identifier: Optional[str]` - - `incomplete_details: Optional[IncompleteDetails]` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - On an incomplete message, details about why the message is incomplete. + - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` - - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` + Specifies the processing type used for serving the request. - The reason the message is incomplete. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `"content_filter"` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `"max_tokens"` + - `"auto"` - - `"run_cancelled"` + - `"default"` - - `"run_expired"` + - `"flex"` - - `"run_failed"` + - `"scale"` - - `metadata: Optional[Metadata]` + - `"priority"` - 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. + - `status: Optional[BetaResponseStatus]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `object: Literal["thread.message"]` + - `"completed"` - The object type, which is always `thread.message`. + - `"failed"` - - `"thread.message"` + - `"in_progress"` - - `role: Literal["user", "assistant"]` + - `"cancelled"` - The entity that produced the message. One of `user` or `assistant`. + - `"queued"` - - `"user"` + - `"incomplete"` - - `"assistant"` + - `text: Optional[BetaResponseTextConfig]` - - `run_id: Optional[str]` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - 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. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `status: Literal["in_progress", "incomplete", "completed"]` + - `format: Optional[BetaResponseFormatTextConfig]` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + An object specifying the format that the model must output. - - `"in_progress"` + Configuring `{ "type": "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). - - `"incomplete"` + The default format is `{ "type": "text" }` with no additional options. - - `"completed"` + **Not recommended for gpt-4o and newer models:** - - `thread_id: str` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `class Text: …` -### Message Content + Default response format. Used to generate text responses. -- `object` + - `type: Literal["text"]` -### Message Content Delta + The type of response format being defined. Always `text`. -- `object` + - `"text"` -### Message Content Part Param + - `class BetaResponseFormatTextJSONSchemaConfig: …` -- `MessageContentPartParam` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `name: str` - - `class ImageFileContentBlock: …` + 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. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `schema: Dict[str, object]` - - `image_file: ImageFileParam` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `file_id: str` + - `type: Literal["json_schema"]` - 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. + The type of response format being defined. Always `json_schema`. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `"json_schema"` - 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`. + - `description: Optional[str]` - - `"auto"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"low"` + - `strict: Optional[bool]` - - `"high"` + 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["image_file"]` + - `class JSONObject: …` - Always `image_file`. + 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. - - `"image_file"` + - `type: Literal["json_object"]` - - `class ImageURLContentBlock: …` + The type of response format being defined. Always `json_object`. - References an image URL in the content of a message. + - `"json_object"` - - `image_url: ImageURLParam` + - `verbosity: Optional[Literal["low", "medium", "high"]]` - - `url: str` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"low"` - - `detail: Optional[Literal["auto", "low", "high"]]` + - `"medium"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `"high"` - - `"auto"` + - `top_logprobs: Optional[int]` - - `"low"` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `"high"` + - `truncation: Optional[Literal["auto", "disabled"]]` - - `type: Literal["image_url"]` + The truncation strategy to use for the model response. - The type of the content part. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `"image_url"` + - `"auto"` - - `class TextContentBlockParam: …` + - `"disabled"` - The text content that is part of a message. + - `usage: Optional[BetaResponseUsage]` - - `text: str` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - Text content to be sent to the model + - `input_tokens: int` - - `type: Literal["text"]` + The number of input tokens. - Always `text`. + - `input_tokens_details: InputTokensDetails` - - `"text"` + A detailed breakdown of the input tokens. -### Message Deleted + - `cache_write_tokens: int` -- `class MessageDeleted: …` + The number of input tokens that were written to the cache. - - `id: str` + - `cached_tokens: int` - - `deleted: bool` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `object: Literal["thread.message.deleted"]` + - `output_tokens: int` - - `"thread.message.deleted"` + The number of output tokens. -### Message Delta + - `output_tokens_details: OutputTokensDetails` -- `class MessageDelta: …` + A detailed breakdown of the output tokens. - The delta containing the fields that have changed on the Message. + - `reasoning_tokens: int` - - `content: Optional[List[object]]` + The number of reasoning tokens. - The content of the message in array of text and/or images. + - `total_tokens: int` - - `role: Optional[Literal["user", "assistant"]]` + The total number of tokens used. - The entity that produced the message. One of `user` or `assistant`. + - `user: Optional[str]` - - `"user"` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `"assistant"` +### Example -### Message Delta Event +```python +import os +from openai import OpenAI -- `class MessageDeltaEvent: …` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +beta_response = client.beta.responses.cancel( + response_id="resp_677efb5139a88190b512bc3fef8e535d", +) +print(beta_response.id) +``` - Represents a message delta i.e. any changed fields on a message during streaming. +#### Response - - `id: str` +```json +{ + "id": "id", + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "text": "text", + "type": "output_text", + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ] + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "phase": "commentary" + } + ], + "parallel_tool_calls": true, + "temperature": 1, + "tool_choice": "none", + "tools": [ + { + "name": "name", + "parameters": { + "foo": "bar" + }, + "strict": true, + "type": "function", + "allowed_callers": [ + "direct" + ], + "defer_loading": true, + "description": "description", + "output_schema": { + "foo": "bar" + } + } + ], + "top_p": 1, + "background": true, + "completed_at": 0, + "conversation": { + "id": "id" + }, + "max_output_tokens": 0, + "max_tool_calls": 0, + "moderation": { + "input": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + }, + "output": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + } + }, + "output_text": "output_text", + "previous_response_id": "previous_response_id", + "prompt": { + "id": "id", + "variables": { + "foo": "string" + }, + "version": "version" + }, + "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, + "prompt_cache_retention": "in_memory", + "reasoning": { + "context": "auto", + "effort": "none", + "generate_summary": "auto", + "mode": "standard", + "summary": "auto" + }, + "safety_identifier": "safety-identifier-1234", + "service_tier": "auto", + "status": "completed", + "text": { + "format": { + "type": "text" + }, + "verbosity": "low" + }, + "top_logprobs": 0, + "truncation": "auto", + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "cache_write_tokens": 0, + "cached_tokens": 0 + }, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + }, + "user": "user-1234" +} +``` - The identifier of the message, which can be referenced in API endpoints. +### Example - - `delta: MessageDelta` +```python +from openai import OpenAI +client = OpenAI() - The delta containing the fields that have changed on the Message. +response = client.responses.cancel("resp_123") +print(response) +``` - - `content: Optional[List[object]]` +#### Response - The content of the message in array of text and/or images. +```json +{ + "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", + "object": "response", + "created_at": 1741386163, + "status": "cancelled", + "background": true, + "completed_at": null, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [ + { + "type": "message", + "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", + "status": "in_progress", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} +} +``` - - `role: Optional[Literal["user", "assistant"]]` +## Compact a response - The entity that produced the message. One of `user` or `assistant`. +`beta.responses.compact(ResponseCompactParams**kwargs) -> BetaCompactedResponse` - - `"user"` +**post** `/responses/compact?beta=true` - - `"assistant"` +Compact a conversation. Returns a compacted response object. - - `object: Literal["thread.message.delta"]` +Learn when and how to compact long-running conversations in the [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced). - The object type, which is always `thread.message.delta`. +### Parameters - - `"thread.message.delta"` +- `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str, null]` -### Refusal Content Block + Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. -- `class RefusalContentBlock: …` + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` - The refusal content generated by the assistant. + Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - - `refusal: str` + - `"gpt-5.6-sol"` - - `type: Literal["refusal"]` + - `"gpt-5.6-terra"` - Always `refusal`. + - `"gpt-5.6-luna"` - - `"refusal"` + - `"gpt-5.4"` -### Refusal Delta Block + - `"gpt-5.4-mini"` -- `class RefusalDeltaBlock: …` + - `"gpt-5.4-nano"` - The refusal content that is part of a message. + - `"gpt-5.4-mini-2026-03-17"` - - `index: int` + - `"gpt-5.4-nano-2026-03-17"` - The index of the refusal part in the message. + - `"gpt-5.3-chat-latest"` - - `type: Literal["refusal"]` + - `"gpt-5.2"` - Always `refusal`. + - `"gpt-5.2-2025-12-11"` - - `"refusal"` + - `"gpt-5.2-chat-latest"` - - `refusal: Optional[str]` + - `"gpt-5.2-pro"` -### Text + - `"gpt-5.2-pro-2025-12-11"` -- `class Text: …` + - `"gpt-5.1"` - - `annotations: List[object]` + - `"gpt-5.1-2025-11-13"` - - `value: str` + - `"gpt-5.1-codex"` - The data that makes up the text. + - `"gpt-5.1-mini"` -### Text Content Block + - `"gpt-5.1-chat-latest"` -- `class TextContentBlock: …` + - `"gpt-5"` - The text content that is part of a message. + - `"gpt-5-mini"` - - `text: Text` + - `"gpt-5-nano"` - - `annotations: List[object]` + - `"gpt-5-2025-08-07"` - - `value: str` + - `"gpt-5-mini-2025-08-07"` - The data that makes up the text. + - `"gpt-5-nano-2025-08-07"` - - `type: Literal["text"]` + - `"gpt-5-chat-latest"` - Always `text`. + - `"gpt-4.1"` - - `"text"` + - `"gpt-4.1-mini"` -### Text Content Block Param + - `"gpt-4.1-nano"` -- `class TextContentBlockParam: …` + - `"gpt-4.1-2025-04-14"` - The text content that is part of a message. + - `"gpt-4.1-mini-2025-04-14"` - - `text: str` + - `"gpt-4.1-nano-2025-04-14"` - Text content to be sent to the model + - `"o4-mini"` - - `type: Literal["text"]` + - `"o4-mini-2025-04-16"` - Always `text`. + - `"o3"` - - `"text"` + - `"o3-2025-04-16"` -### Text Delta + - `"o3-mini"` -- `class TextDelta: …` + - `"o3-mini-2025-01-31"` - - `annotations: Optional[List[object]]` + - `"o1"` - - `value: Optional[str]` + - `"o1-2024-12-17"` - The data that makes up the text. + - `"o1-preview"` -### Text Delta Block + - `"o1-preview-2024-09-12"` -- `class TextDeltaBlock: …` + - `"o1-mini"` - The text content that is part of a message. + - `"o1-mini-2024-09-12"` - - `index: int` + - `"gpt-4o"` - The index of the content part in the message. + - `"gpt-4o-2024-11-20"` - - `type: Literal["text"]` + - `"gpt-4o-2024-08-06"` - Always `text`. + - `"gpt-4o-2024-05-13"` - - `"text"` + - `"gpt-4o-audio-preview"` - - `text: Optional[TextDelta]` + - `"gpt-4o-audio-preview-2024-10-01"` - - `annotations: Optional[List[object]]` + - `"gpt-4o-audio-preview-2024-12-17"` - - `value: Optional[str]` + - `"gpt-4o-audio-preview-2025-06-03"` - The data that makes up the text. + - `"gpt-4o-mini-audio-preview"` -# Responses + - `"gpt-4o-mini-audio-preview-2024-12-17"` -## + - `"gpt-4o-search-preview"` -`beta.responses.connect()` + - `"gpt-4o-mini-search-preview"` -**** `` + - `"gpt-4o-search-preview-2025-03-11"` -Connect to a persistent Responses API WebSocket. Send `response.create` events and receive response stream events over the socket. + - `"gpt-4o-mini-search-preview-2025-03-11"` -### Example + - `"chatgpt-4o-latest"` -```python -import os -from openai import OpenAI + - `"codex-mini-latest"` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -client.beta.responses.connect() -``` + - `"gpt-4o-mini"` -## Create a model response + - `"gpt-4o-mini-2024-07-18"` -`beta.responses.create(ResponseCreateParams**kwargs) -> BetaResponse` + - `"gpt-4-turbo"` -**post** `/responses?beta=true` + - `"gpt-4-turbo-2024-04-09"` -Create a model response + - `"gpt-4-0125-preview"` -### Parameters + - `"gpt-4-turbo-preview"` -- `background: Optional[bool]` + - `"gpt-4-1106-preview"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `"gpt-4-vision-preview"` -- `context_management: Optional[Iterable[ContextManagement]]` + - `"gpt-4"` - Context management configuration for this request. + - `"gpt-4-0314"` - - `type: str` + - `"gpt-4-0613"` - The context management entry type. Currently only 'compaction' is supported. + - `"gpt-4-32k"` - - `compact_threshold: Optional[int]` + - `"gpt-4-32k-0314"` - Token threshold at which compaction should be triggered for this entry. + - `"gpt-4-32k-0613"` -- `conversation: Optional[Conversation]` + - `"gpt-3.5-turbo"` - The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. - Input items and output items from this response are automatically added to this conversation after this response completes. + - `"gpt-3.5-turbo-16k"` - - `str` + - `"gpt-3.5-turbo-0301"` - The unique ID of the conversation. + - `"gpt-3.5-turbo-0613"` - - `class BetaResponseConversationParam: …` + - `"gpt-3.5-turbo-1106"` - The conversation that this response belongs to. + - `"gpt-3.5-turbo-0125"` - - `id: str` + - `"gpt-3.5-turbo-16k-0613"` - The unique ID of the conversation. + - `"o1-pro"` -- `include: Optional[List[BetaResponseIncludable]]` + - `"o1-pro-2025-03-19"` - Specify additional output data to include in the model response. Currently supported values are: + - `"o3-pro"` - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + - `"o3-pro-2025-06-10"` - - `"file_search_call.results"` + - `"o3-deep-research"` - - `"web_search_call.results"` + - `"o3-deep-research-2025-06-26"` - - `"web_search_call.action.sources"` + - `"o4-mini-deep-research"` - - `"message.input_image.image_url"` + - `"o4-mini-deep-research-2025-06-26"` - - `"computer_call_output.output.image_url"` + - `"computer-use-preview"` - - `"code_interpreter_call.outputs"` + - `"computer-use-preview-2025-03-11"` - - `"reasoning.encrypted_content"` + - `"gpt-5-codex"` - - `"message.output_text.logprobs"` + - `"gpt-5-pro"` -- `input: Optional[Union[str, BetaResponseInputParam]]` + - `"gpt-5-pro-2025-10-06"` - Text, image, or file inputs to the model, used to generate a response. + - `"gpt-5.1-codex-max"` - Learn more: + - `str` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Image inputs](https://platform.openai.com/docs/guides/images) - - [File inputs](https://platform.openai.com/docs/guides/pdf-files) - - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) - - [Function calling](https://platform.openai.com/docs/guides/function-calling) +- `input: Optional[Union[str, Iterable[BetaResponseInputItemParam], null]]` + + Text, image, or file inputs to the model, used to generate a response - `str` - A text input to the model, equivalent to a text input with the - `user` role. + A text input to the model, equivalent to a text input with the `user` role. - `Iterable[BetaResponseInputItemParam]` + A list of one or many input items to the model, containing different content types. + - `class BetaEasyInputMessage: …` A message input to the model with a role indicating instruction following @@ -15890,7 +26095,7 @@ Create a model response - `"developer"` - - `phase: Optional[Literal["commentary"]]` + - `phase: Optional[Literal["commentary", "final_answer"]]` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -15898,6 +26103,8 @@ Create a model response - `"commentary"` + - `"final_answer"` + - `type: Optional[Literal["message"]]` The type of the message input. Always `message`. @@ -16149,7 +26356,7 @@ Create a model response The canonical name of the agent that produced this item. - - `phase: Optional[Literal["commentary"]]` + - `phase: Optional[Literal["commentary", "final_answer"]]` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -16157,6 +26364,8 @@ Create a model response - `"commentary"` + - `"final_answer"` + - `class BetaResponseFileSearchToolCall: …` The results of a file search tool call. See the @@ -17327,7 +27536,7 @@ Create a model response - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -17337,7 +27546,11 @@ Create a model response - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `class FiltersCompoundFilter: …` @@ -17384,7 +27597,7 @@ Create a model response - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -17394,7 +27607,11 @@ Create a model response - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `object` @@ -18956,81 +29173,851 @@ Create a model response - `call_id: str` - The unique ID of the apply patch tool call generated by the model. + The unique ID of the apply patch tool call generated by the model. + + - `operation: ApplyPatchCallOperation` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `class ApplyPatchCallOperationCreateFile: …` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: str` + + Unified diff content to apply when creating the file. + + - `path: str` + + Path of the file to create relative to the workspace root. + + - `type: Literal["create_file"]` + + The operation type. Always `create_file`. + + - `"create_file"` + + - `class ApplyPatchCallOperationDeleteFile: …` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: str` + + Path of the file to delete relative to the workspace root. + + - `type: Literal["delete_file"]` + + The operation type. Always `delete_file`. + + - `"delete_file"` + + - `class ApplyPatchCallOperationUpdateFile: …` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: str` + + Unified diff content to apply to the existing file. + + - `path: str` + + Path of the file to update relative to the workspace root. + + - `type: Literal["update_file"]` + + The operation type. Always `update_file`. + + - `"update_file"` + + - `status: Literal["in_progress", "completed"]` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: Literal["apply_patch_call"]` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `id: Optional[str]` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[ApplyPatchCallCaller]` + + The execution context that produced this tool call. + + - `class ApplyPatchCallCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class ApplyPatchCallCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `class ApplyPatchCallOutput: …` + + The streamed output emitted by an apply patch tool call. + + - `call_id: str` + + The unique ID of the apply patch tool call generated by the model. + + - `status: Literal["completed", "failed"]` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: Literal["apply_patch_call_output"]` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `id: Optional[str]` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[ApplyPatchCallOutputCaller]` + + The execution context that produced this tool call. + + - `class ApplyPatchCallOutputCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class ApplyPatchCallOutputCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `output: Optional[str]` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `class McpListTools: …` + + A list of tools available on an MCP server. + + - `id: str` + + The unique ID of the list. + + - `server_label: str` + + The label of the MCP server. + + - `tools: List[McpListToolsTool]` + + The tools available on the server. + + - `input_schema: object` + + The JSON schema describing the tool's input. + + - `name: str` + + The name of the tool. + + - `annotations: Optional[object]` + + Additional annotations about the tool. + + - `description: Optional[str]` + + The description of the tool. + + - `type: Literal["mcp_list_tools"]` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `agent: Optional[McpListToolsAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `error: Optional[str]` + + Error message if the server could not list tools. + + - `class McpApprovalRequest: …` + + A request for human approval of a tool invocation. + + - `id: str` + + The unique ID of the approval request. + + - `arguments: str` + + A JSON string of arguments for the tool. + + - `name: str` + + The name of the tool to run. + + - `server_label: str` + + The label of the MCP server making the request. + + - `type: Literal["mcp_approval_request"]` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `agent: Optional[McpApprovalRequestAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse: …` + + A response to an MCP approval request. + + - `approval_request_id: str` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: Literal["mcp_approval_response"]` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `id: Optional[str]` + + The unique ID of the approval response + + - `agent: Optional[McpApprovalResponseAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `reason: Optional[str]` + + Optional reason for the decision. + + - `class McpCall: …` + + An invocation of a tool on an MCP server. + + - `id: str` + + The unique ID of the tool call. + + - `arguments: str` + + A JSON string of the arguments passed to the tool. + + - `name: str` + + The name of the tool that was run. + + - `server_label: str` + + The label of the MCP server running the tool. + + - `type: Literal["mcp_call"]` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `agent: Optional[McpCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `approval_request_id: Optional[str]` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: Optional[str]` + + The error from the tool call, if any. + + - `output: Optional[str]` + + The output from the tool call. + + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `class BetaResponseCustomToolCallOutput: …` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: str` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: Union[str, List[OutputOutputContentList]]` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `str` + + A string of the output of the custom tool call. + + - `List[OutputOutputContentList]` + + Text, image, or file output of the custom tool call. + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `type: Literal["custom_tool_call_output"]` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `"custom_tool_call_output"` + + - `id: Optional[str]` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `class BetaResponseCustomToolCall: …` + + A call to a custom tool created by the model. + + - `call_id: str` + + An identifier used to map this custom tool call to a tool call output. + + - `input: str` + + The input for the custom tool call generated by the model. + + - `name: str` + + The name of the custom tool being called. + + - `type: Literal["custom_tool_call"]` + + The type of the custom tool call. Always `custom_tool_call`. + + - `"custom_tool_call"` + + - `id: Optional[str]` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `namespace: Optional[str]` + + The namespace of the custom tool being called. + + - `class CompactionTrigger: …` + + Compacts the current context. Must be the final input item. + + - `type: Literal["compaction_trigger"]` + + The type of the item. Always `compaction_trigger`. + + - `"compaction_trigger"` + + - `agent: Optional[CompactionTriggerAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ItemReference: …` + + An internal identifier for an item to reference. + + - `id: str` + + The ID of the item to reference. + + - `agent: Optional[ItemReferenceAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `type: Optional[Literal["item_reference"]]` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + + - `class Program: …` + + - `id: str` + + The unique ID of this program item. + + - `call_id: str` + + The stable call ID of the program item. + + - `code: str` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: str` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: Literal["program"]` + + The item type. Always `program`. + + - `"program"` + + - `agent: Optional[ProgramAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput: …` + + - `id: str` + + The unique ID of this program output item. + + - `call_id: str` + + The call ID of the program item. + + - `result: str` + + The result produced by the program item. + + - `status: Literal["completed", "incomplete"]` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["program_output"]` + + The item type. Always `program_output`. + + - `"program_output"` + + - `agent: Optional[ProgramOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + +- `instructions: Optional[str]` + + A system (or developer) message inserted into the model's context. + When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + +- `previous_response_id: Optional[str]` + + The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + +- `prompt_cache_key: Optional[str]` + + A key to use when reading from or writing to the prompt cache. + +- `prompt_cache_options: Optional[PromptCacheOptions]` + + Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. + + - `mode: Optional[Literal["implicit", "explicit"]]` + + Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + + - `"implicit"` + + - `"explicit"` + + - `ttl: Optional[Literal["30m"]]` + + The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + + - `"30m"` + +- `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + + How long to retain a prompt cache entry created by this request. + + - `"in_memory"` + + - `"24h"` + +- `service_tier: Optional[Literal["auto", "default", "flex", "priority"]]` + + The service tier to use for this request. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"priority"` + +- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` + + - `"responses_multi_agent=v1"` + +### Returns + +- `class BetaCompactedResponse: …` + + - `id: str` + + The unique identifier for the compacted response. + + - `created_at: int` + + Unix timestamp (in seconds) when the compacted conversation was created. + + - `object: Literal["response.compaction"]` + + The object type. Always `response.compaction`. + + - `"response.compaction"` + + - `output: List[BetaResponseOutputItem]` + + The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + + - `class BetaResponseOutputMessage: …` + + An output message from the model. + + - `id: str` + + The unique ID of the output message. + + - `content: List[Content]` + + The content of the output message. + + - `class BetaResponseOutputText: …` + + A text output from the model. + + - `annotations: List[Annotation]` + + The annotations of the text output. + + - `class AnnotationFileCitation: …` + + A citation to a file. + + - `file_id: str` + + The ID of the file. + + - `filename: str` + + The filename of the file cited. + + - `index: int` + + The index of the file in the list of files. + + - `type: Literal["file_citation"]` + + The type of the file citation. Always `file_citation`. + + - `"file_citation"` + + - `class AnnotationURLCitation: …` + + A citation for a web resource used to generate a model response. + + - `end_index: int` + + The index of the last character of the URL citation in the message. + + - `start_index: int` + + The index of the first character of the URL citation in the message. + + - `title: str` + + The title of the web resource. + + - `type: Literal["url_citation"]` + + The type of the URL citation. Always `url_citation`. + + - `"url_citation"` + + - `url: str` + + The URL of the web resource. + + - `class AnnotationContainerFileCitation: …` + + A citation for a container file used to generate a model response. + + - `container_id: str` + + The ID of the container file. + + - `end_index: int` + + The index of the last character of the container file citation in the message. + + - `file_id: str` + + The ID of the file. + + - `filename: str` + + The filename of the container file cited. + + - `start_index: int` + + The index of the first character of the container file citation in the message. + + - `type: Literal["container_file_citation"]` + + The type of the container file citation. Always `container_file_citation`. + + - `"container_file_citation"` + + - `class AnnotationFilePath: …` + + A path to a file. + + - `file_id: str` + + The ID of the file. + + - `index: int` - - `operation: ApplyPatchCallOperation` + The index of the file in the list of files. - The specific create, delete, or update instruction for the apply_patch tool call. + - `type: Literal["file_path"]` - - `class ApplyPatchCallOperationCreateFile: …` + The type of the file path. Always `file_path`. - Instruction for creating a new file via the apply_patch tool. + - `"file_path"` - - `diff: str` + - `text: str` - Unified diff content to apply when creating the file. + The text output from the model. - - `path: str` + - `type: Literal["output_text"]` - Path of the file to create relative to the workspace root. + The type of the output text. Always `output_text`. - - `type: Literal["create_file"]` + - `"output_text"` - The operation type. Always `create_file`. + - `logprobs: Optional[List[Logprob]]` - - `"create_file"` + - `token: str` - - `class ApplyPatchCallOperationDeleteFile: …` + - `bytes: List[int]` - Instruction for deleting an existing file via the apply_patch tool. + - `logprob: float` - - `path: str` + - `top_logprobs: List[LogprobTopLogprob]` - Path of the file to delete relative to the workspace root. + - `token: str` - - `type: Literal["delete_file"]` + - `bytes: List[int]` - The operation type. Always `delete_file`. + - `logprob: float` - - `"delete_file"` + - `class BetaResponseOutputRefusal: …` - - `class ApplyPatchCallOperationUpdateFile: …` + A refusal from the model. - Instruction for updating an existing file via the apply_patch tool. + - `refusal: str` - - `diff: str` + The refusal explanation from the model. - Unified diff content to apply to the existing file. + - `type: Literal["refusal"]` - - `path: str` + The type of the refusal. Always `refusal`. - Path of the file to update relative to the workspace root. + - `"refusal"` - - `type: Literal["update_file"]` + - `role: Literal["assistant"]` - The operation type. Always `update_file`. + The role of the output message. Always `assistant`. - - `"update_file"` + - `"assistant"` - - `status: Literal["in_progress", "completed"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"in_progress"` - `"completed"` - - `type: Literal["apply_patch_call"]` - - The type of the item. Always `apply_patch_call`. + - `"incomplete"` - - `"apply_patch_call"` + - `type: Literal["message"]` - - `id: Optional[str]` + The type of the output message. Always `message`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"message"` - - `agent: Optional[ApplyPatchCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -19038,57 +30025,51 @@ Create a model response The canonical name of the agent that produced this item. - - `caller: Optional[ApplyPatchCallCaller]` - - The execution context that produced this tool call. - - - `class ApplyPatchCallCallerDirect: …` - - - `type: Literal["direct"]` - - The caller type. Always `direct`. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `"direct"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `class ApplyPatchCallCallerProgram: …` + - `"commentary"` - - `caller_id: str` + - `"final_answer"` - The call ID of the program item that produced this tool call. + - `class BetaResponseFileSearchToolCall: …` - - `type: Literal["program"]` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The caller type. Always `program`. + - `id: str` - - `"program"` + The unique ID of the file search tool call. - - `class ApplyPatchCallOutput: …` + - `queries: List[str]` - The streamed output emitted by an apply patch tool call. + The queries used to search for files. - - `call_id: str` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - The unique ID of the apply patch tool call generated by the model. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `status: Literal["completed", "failed"]` + - `"in_progress"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"searching"` - `"completed"` - - `"failed"` - - - `type: Literal["apply_patch_call_output"]` + - `"incomplete"` - The type of the item. Always `apply_patch_call_output`. + - `"failed"` - - `"apply_patch_call_output"` + - `type: Literal["file_search_call"]` - - `id: Optional[str]` + The type of the file search tool call. Always `file_search_call`. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"file_search_call"` - - `agent: Optional[ApplyPatchCallOutputAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -19096,73 +30077,68 @@ Create a model response The canonical name of the agent that produced this item. - - `caller: Optional[ApplyPatchCallOutputCaller]` - - The execution context that produced this tool call. - - - `class ApplyPatchCallOutputCallerDirect: …` - - - `type: Literal["direct"]` + - `results: Optional[List[Result]]` - The caller type. Always `direct`. + The results of the file search tool call. - - `"direct"` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - - `class ApplyPatchCallOutputCallerProgram: …` + 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, booleans, or numbers. - - `caller_id: str` + - `str` - The call ID of the program item that produced this tool call. + - `float` - - `type: Literal["program"]` + - `bool` - The caller type. Always `program`. + - `file_id: Optional[str]` - - `"program"` + The unique ID of the file. - - `output: Optional[str]` + - `filename: Optional[str]` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The name of the file. - - `class McpListTools: …` + - `score: Optional[float]` - A list of tools available on an MCP server. + The relevance score of the file - a value between 0 and 1. - - `id: str` + - `text: Optional[str]` - The unique ID of the list. + The text that was retrieved from the file. - - `server_label: str` + - `class BetaResponseFunctionToolCall: …` - The label of the MCP server. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `tools: List[McpListToolsTool]` + - `arguments: str` - The tools available on the server. + A JSON string of the arguments to pass to the function. - - `input_schema: object` + - `call_id: str` - The JSON schema describing the tool's input. + The unique ID of the function tool call generated by the model. - `name: str` - The name of the tool. - - - `annotations: Optional[object]` - - Additional annotations about the tool. + The name of the function to run. - - `description: Optional[str]` + - `type: Literal["function_call"]` - The description of the tool. + The type of the function tool call. Always `function_call`. - - `type: Literal["mcp_list_tools"]` + - `"function_call"` - The type of the item. Always `mcp_list_tools`. + - `id: Optional[str]` - - `"mcp_list_tools"` + The unique ID of the function tool call. - - `agent: Optional[McpListToolsAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -19170,181 +30146,190 @@ Create a model response The canonical name of the agent that produced this item. - - `error: Optional[str]` + - `caller: Optional[Caller]` - Error message if the server could not list tools. + The execution context that produced this tool call. - - `class McpApprovalRequest: …` + - `class CallerDirect: …` - A request for human approval of a tool invocation. + - `type: Literal["direct"]` - - `id: str` + - `"direct"` - The unique ID of the approval request. + - `class CallerProgram: …` - - `arguments: str` + - `caller_id: str` - A JSON string of arguments for the tool. + The call ID of the program item that produced this tool call. - - `name: str` + - `type: Literal["program"]` - The name of the tool to run. + - `"program"` - - `server_label: str` + - `namespace: Optional[str]` - The label of the MCP server making the request. + The namespace of the function to run. - - `type: Literal["mcp_approval_request"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The type of the item. Always `mcp_approval_request`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"mcp_approval_request"` + - `"in_progress"` - - `agent: Optional[McpApprovalRequestAgent]` + - `"completed"` - The agent that produced this item. + - `"incomplete"` - - `agent_name: str` + - `class BetaResponseFunctionToolCallOutputItem: …` - The canonical name of the agent that produced this item. + - `id: str` - - `class McpApprovalResponse: …` + The unique ID of the function call tool output. - A response to an MCP approval request. + - `call_id: str` - - `approval_request_id: str` + The unique ID of the function tool call generated by the model. - The ID of the approval request being answered. + - `output: Union[str, List[OutputOutputContentList]]` - - `approve: bool` + The output from the function call generated by your code. + Can be a string or an list of output content. - Whether the request was approved. + - `str` - - `type: Literal["mcp_approval_response"]` + A string of the output of the function call. - The type of the item. Always `mcp_approval_response`. + - `List[OutputOutputContentList]` - - `"mcp_approval_response"` + Text, image, or file output of the function call. - - `id: Optional[str]` + - `class BetaResponseInputText: …` - The unique ID of the approval response + A text input to the model. - - `agent: Optional[McpApprovalResponseAgent]` + - `text: str` - The agent that produced this item. + The text input to the model. - - `agent_name: str` + - `type: Literal["input_text"]` - The canonical name of the agent that produced this item. + The type of the input item. Always `input_text`. - - `reason: Optional[str]` + - `"input_text"` - Optional reason for the decision. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `class McpCall: …` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - An invocation of a tool on an MCP server. + - `mode: Literal["explicit"]` - - `id: str` + The breakpoint mode. Always `explicit`. - The unique ID of the tool call. + - `"explicit"` - - `arguments: str` + - `class BetaResponseInputImage: …` - A JSON string of the arguments passed to the tool. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `name: str` + - `detail: Literal["low", "high", "auto", "original"]` - The name of the tool that was run. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `server_label: str` + - `"low"` - The label of the MCP server running the tool. + - `"high"` - - `type: Literal["mcp_call"]` + - `"auto"` - The type of the item. Always `mcp_call`. + - `"original"` - - `"mcp_call"` + - `type: Literal["input_image"]` - - `agent: Optional[McpCallAgent]` + The type of the input item. Always `input_image`. - The agent that produced this item. + - `"input_image"` - - `agent_name: str` + - `file_id: Optional[str]` - The canonical name of the agent that produced this item. + The ID of the file to be sent to the model. - - `approval_request_id: Optional[str]` + - `image_url: Optional[str]` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `error: Optional[str]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The error from the tool call, if any. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `output: Optional[str]` + - `mode: Literal["explicit"]` - The output from the tool call. + The breakpoint mode. Always `explicit`. - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `"explicit"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `class BetaResponseInputFile: …` - - `"in_progress"` + A file input to the model. - - `"completed"` + - `type: Literal["input_file"]` - - `"incomplete"` + The type of the input item. Always `input_file`. - - `"calling"` + - `"input_file"` - - `"failed"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `class BetaResponseCustomToolCallOutput: …` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The output of a custom tool call from your code, being sent back to the model. + - `"auto"` - - `call_id: str` + - `"low"` - The call ID, used to map this custom tool call output to a custom tool call. + - `"high"` - - `output: Union[str, List[OutputOutputContentList]]` + - `file_data: Optional[str]` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The content of the file to be sent to the model. - - `str` + - `file_id: Optional[str]` - A string of the output of the custom tool call. + The ID of the file to be sent to the model. - - `List[OutputOutputContentList]` + - `file_url: Optional[str]` - Text, image, or file output of the custom tool call. + The URL of the file to be sent to the model. - - `class BetaResponseInputText: …` + - `filename: Optional[str]` - A text input to the model. + The name of the file to be sent to the model. - - `class BetaResponseInputImage: …` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaResponseInputFile: …` + - `mode: Literal["explicit"]` - A file input to the model. + The breakpoint mode. Always `explicit`. - - `type: Literal["custom_tool_call_output"]` + - `"explicit"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"custom_tool_call_output"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `id: Optional[str]` + - `"in_progress"` - The unique ID of the custom tool call output in the OpenAI platform. + - `"completed"` + + - `"incomplete"` + + - `type: Literal["function_call_output"]` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` - `agent: Optional[Agent]` @@ -19378,165 +30363,147 @@ Create a model response - `"program"` - - `class BetaResponseCustomToolCall: …` - - A call to a custom tool created by the model. - - - `call_id: str` - - An identifier used to map this custom tool call to a tool call output. - - - `input: str` - - The input for the custom tool call generated by the model. - - - `name: str` - - The name of the custom tool being called. - - - `type: Literal["custom_tool_call"]` - - The type of the custom tool call. Always `custom_tool_call`. + - `created_by: Optional[str]` - - `"custom_tool_call"` + The identifier of the actor that created the item. - - `id: Optional[str]` + - `class AgentMessage: …` - The unique ID of the custom tool call in the OpenAI platform. + - `id: str` - - `agent: Optional[Agent]` + The unique ID of the agent message. - The agent that produced this item. + - `author: str` - - `agent_name: str` + The sending agent identity. - The canonical name of the agent that produced this item. + - `content: List[AgentMessageContent]` - - `caller: Optional[Caller]` + Encrypted content sent between agents. - The execution context that produced this tool call. + - `class BetaResponseInputText: …` - - `class CallerDirect: …` + A text input to the model. - - `type: Literal["direct"]` + - `class BetaResponseOutputText: …` - - `"direct"` + A text output from the model. - - `class CallerProgram: …` + - `class AgentMessageContentText: …` - - `caller_id: str` + A text content. - The call ID of the program item that produced this tool call. + - `text: str` - - `type: Literal["program"]` + - `type: Literal["text"]` - - `"program"` + - `"text"` - - `namespace: Optional[str]` + - `class AgentMessageContentSummaryText: …` - The namespace of the custom tool being called. + A summary text from the model. - - `class CompactionTrigger: …` + - `text: str` - Compacts the current context. Must be the final input item. + A summary of the reasoning output from the model so far. - - `type: Literal["compaction_trigger"]` + - `type: Literal["summary_text"]` - The type of the item. Always `compaction_trigger`. + The type of the object. Always `summary_text`. - - `"compaction_trigger"` + - `"summary_text"` - - `agent: Optional[CompactionTriggerAgent]` + - `class AgentMessageContentReasoningText: …` - The agent that produced this item. + Reasoning text from the model. - - `agent_name: str` + - `text: str` - The canonical name of the agent that produced this item. + The reasoning text from the model. - - `class ItemReference: …` + - `type: Literal["reasoning_text"]` - An internal identifier for an item to reference. + The type of the reasoning text. Always `reasoning_text`. - - `id: str` + - `"reasoning_text"` - The ID of the item to reference. + - `class BetaResponseOutputRefusal: …` - - `agent: Optional[ItemReferenceAgent]` + A refusal from the model. - The agent that produced this item. + - `class BetaResponseInputImage: …` - - `agent_name: str` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The canonical name of the agent that produced this item. + - `class AgentMessageContentComputerScreenshot: …` - - `type: Optional[Literal["item_reference"]]` + A screenshot of a computer. - The type of item to reference. Always `item_reference`. + - `detail: Literal["low", "high", "auto", "original"]` - - `"item_reference"` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `class Program: …` + - `"low"` - - `id: str` + - `"high"` - The unique ID of this program item. + - `"auto"` - - `call_id: str` + - `"original"` - The stable call ID of the program item. + - `file_id: Optional[str]` - - `code: str` + The identifier of an uploaded file that contains the screenshot. - The JavaScript source executed by programmatic tool calling. + - `image_url: Optional[str]` - - `fingerprint: str` + The URL of the screenshot image. - Opaque program replay fingerprint that must be round-tripped. + - `type: Literal["computer_screenshot"]` - - `type: Literal["program"]` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The item type. Always `program`. + - `"computer_screenshot"` - - `"program"` + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - - `agent: Optional[ProgramAgent]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The agent that produced this item. + - `mode: Literal["explicit"]` - - `agent_name: str` + The breakpoint mode. Always `explicit`. - The canonical name of the agent that produced this item. + - `"explicit"` - - `class ProgramOutput: …` + - `class BetaResponseInputFile: …` - - `id: str` + A file input to the model. - The unique ID of this program output item. + - `class AgentMessageContentEncryptedContent: …` - - `call_id: str` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The call ID of the program item. + - `encrypted_content: str` - - `result: str` + Opaque encrypted content. - The result produced by the program item. + - `type: Literal["encrypted_content"]` - - `status: Literal["completed", "incomplete"]` + The type of the input item. Always `encrypted_content`. - The terminal status of the program output. + - `"encrypted_content"` - - `"completed"` + - `recipient: str` - - `"incomplete"` + The destination agent identity. - - `type: Literal["program_output"]` + - `type: Literal["agent_message"]` - The item type. Always `program_output`. + The type of the item. Always `agent_message`. - - `"program_output"` + - `"agent_message"` - - `agent: Optional[ProgramOutputAgent]` + - `agent: Optional[AgentMessageAgent]` The agent that produced this item. @@ -19544,1960 +30511,1897 @@ Create a model response The canonical name of the agent that produced this item. -- `instructions: Optional[str]` + - `class MultiAgentCall: …` - A system (or developer) message inserted into the model's context. + - `id: str` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + The unique ID of the multi-agent call item. -- `max_output_tokens: Optional[int]` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The multi-agent action to execute. -- `max_tool_calls: Optional[int]` + - `"spawn_agent"` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `"interrupt_agent"` -- `metadata: Optional[Dict[str, str]]` + - `"list_agents"` - 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. + - `"send_message"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"followup_task"` -- `model: Optional[Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]]` + - `"wait_agent"` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `arguments: str` - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` + The JSON string of arguments generated for the action. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `call_id: str` - - `"gpt-5.6-sol"` + The unique ID linking this call to its output. - - `"gpt-5.6-terra"` + - `type: Literal["multi_agent_call"]` - - `"gpt-5.6-luna"` + The type of the multi-agent call. Always `multi_agent_call`. - - `"gpt-5.4"` + - `"multi_agent_call"` - - `"gpt-5.4-mini"` + - `agent: Optional[MultiAgentCallAgent]` - - `"gpt-5.4-nano"` + The agent that produced this item. - - `"gpt-5.4-mini-2026-03-17"` + - `agent_name: str` - - `"gpt-5.4-nano-2026-03-17"` + The canonical name of the agent that produced this item. - - `"gpt-5.3-chat-latest"` + - `class MultiAgentCallOutput: …` - - `"gpt-5.2"` + - `id: str` - - `"gpt-5.2-2025-12-11"` + The unique ID of the multi-agent call output item. - - `"gpt-5.2-chat-latest"` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"gpt-5.2-pro"` + The multi-agent action that produced this result. - - `"gpt-5.2-pro-2025-12-11"` + - `"spawn_agent"` - - `"gpt-5.1"` + - `"interrupt_agent"` - - `"gpt-5.1-2025-11-13"` + - `"list_agents"` - - `"gpt-5.1-codex"` + - `"send_message"` - - `"gpt-5.1-mini"` + - `"followup_task"` - - `"gpt-5.1-chat-latest"` + - `"wait_agent"` - - `"gpt-5"` + - `call_id: str` - - `"gpt-5-mini"` + The unique ID of the multi-agent call. - - `"gpt-5-nano"` + - `output: List[BetaResponseOutputText]` - - `"gpt-5-2025-08-07"` + Text output returned by the multi-agent action. - - `"gpt-5-mini-2025-08-07"` + - `annotations: List[Annotation]` - - `"gpt-5-nano-2025-08-07"` + The annotations of the text output. - - `"gpt-5-chat-latest"` + - `text: str` - - `"gpt-4.1"` + The text output from the model. - - `"gpt-4.1-mini"` + - `type: Literal["output_text"]` - - `"gpt-4.1-nano"` + The type of the output text. Always `output_text`. - - `"gpt-4.1-2025-04-14"` + - `logprobs: Optional[List[Logprob]]` - - `"gpt-4.1-mini-2025-04-14"` + - `type: Literal["multi_agent_call_output"]` - - `"gpt-4.1-nano-2025-04-14"` + The type of the multi-agent result. Always `multi_agent_call_output`. - - `"o4-mini"` + - `"multi_agent_call_output"` - - `"o4-mini-2025-04-16"` + - `agent: Optional[MultiAgentCallOutputAgent]` - - `"o3"` + The agent that produced this item. - - `"o3-2025-04-16"` + - `agent_name: str` - - `"o3-mini"` + The canonical name of the agent that produced this item. - - `"o3-mini-2025-01-31"` + - `class BetaResponseFunctionWebSearch: …` - - `"o1"` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `"o1-2024-12-17"` + - `id: str` - - `"o1-preview"` + The unique ID of the web search tool call. - - `"o1-preview-2024-09-12"` + - `action: Action` - - `"o1-mini"` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `"o1-mini-2024-09-12"` + - `class ActionSearch: …` - - `"gpt-4o"` + Action type "search" - Performs a web search query. - - `"gpt-4o-2024-11-20"` + - `type: Literal["search"]` - - `"gpt-4o-2024-08-06"` + The action type. - - `"gpt-4o-2024-05-13"` + - `"search"` - - `"gpt-4o-audio-preview"` + - `queries: Optional[List[str]]` - - `"gpt-4o-audio-preview-2024-10-01"` + The search queries. - - `"gpt-4o-audio-preview-2024-12-17"` + - `query: Optional[str]` - - `"gpt-4o-audio-preview-2025-06-03"` + The search query. - - `"gpt-4o-mini-audio-preview"` + - `sources: Optional[List[ActionSearchSource]]` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The sources used in the search. - - `"gpt-4o-search-preview"` + - `type: Literal["url"]` - - `"gpt-4o-mini-search-preview"` + The type of source. Always `url`. - - `"gpt-4o-search-preview-2025-03-11"` + - `"url"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `url: str` - - `"chatgpt-4o-latest"` + The URL of the source. - - `"codex-mini-latest"` + - `class ActionOpenPage: …` - - `"gpt-4o-mini"` + Action type "open_page" - Opens a specific URL from search results. - - `"gpt-4o-mini-2024-07-18"` + - `type: Literal["open_page"]` - - `"gpt-4-turbo"` + The action type. - - `"gpt-4-turbo-2024-04-09"` + - `"open_page"` - - `"gpt-4-0125-preview"` + - `url: Optional[str]` - - `"gpt-4-turbo-preview"` + The URL opened by the model. - - `"gpt-4-1106-preview"` + - `class ActionFindInPage: …` - - `"gpt-4-vision-preview"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"gpt-4"` + - `pattern: str` - - `"gpt-4-0314"` + The pattern or text to search for within the page. - - `"gpt-4-0613"` + - `type: Literal["find_in_page"]` - - `"gpt-4-32k"` + The action type. - - `"gpt-4-32k-0314"` + - `"find_in_page"` - - `"gpt-4-32k-0613"` + - `url: str` - - `"gpt-3.5-turbo"` + The URL of the page searched for the pattern. - - `"gpt-3.5-turbo-16k"` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - - `"gpt-3.5-turbo-0301"` + The status of the web search tool call. - - `"gpt-3.5-turbo-0613"` + - `"in_progress"` - - `"gpt-3.5-turbo-1106"` + - `"searching"` - - `"gpt-3.5-turbo-0125"` + - `"completed"` - - `"gpt-3.5-turbo-16k-0613"` + - `"failed"` - - `"o1-pro"` + - `type: Literal["web_search_call"]` - - `"o1-pro-2025-03-19"` + The type of the web search tool call. Always `web_search_call`. - - `"o3-pro"` + - `"web_search_call"` - - `"o3-pro-2025-06-10"` + - `agent: Optional[Agent]` - - `"o3-deep-research"` + The agent that produced this item. - - `"o3-deep-research-2025-06-26"` + - `agent_name: str` - - `"o4-mini-deep-research"` + The canonical name of the agent that produced this item. - - `"o4-mini-deep-research-2025-06-26"` + - `class BetaResponseComputerToolCall: …` - - `"computer-use-preview"` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `"computer-use-preview-2025-03-11"` + - `id: str` - - `"gpt-5-codex"` + The unique ID of the computer call. - - `"gpt-5-pro"` + - `call_id: str` - - `"gpt-5-pro-2025-10-06"` + An identifier used when responding to the tool call with output. - - `"gpt-5.1-codex-max"` + - `pending_safety_checks: List[PendingSafetyCheck]` - - `str` + The pending safety checks for the computer call. -- `moderation: Optional[Moderation]` + - `id: str` - Configuration for running moderation on the input and output of this response. + The ID of the pending safety check. - - `model: str` + - `code: Optional[str]` - The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + The type of the pending safety check. - - `policy: Optional[ModerationPolicy]` + - `message: Optional[str]` - The policy to apply to moderated response input and output. + Details about the pending safety check. - - `input: Optional[ModerationPolicyInput]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The moderation policy for the response input. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `mode: Literal["score", "block"]` + - `"in_progress"` - - `"score"` + - `"completed"` - - `"block"` + - `"incomplete"` - - `output: Optional[ModerationPolicyOutput]` + - `type: Literal["computer_call"]` - The moderation policy for the response output. + The type of the computer call. Always `computer_call`. - - `mode: Literal["score", "block"]` + - `"computer_call"` - - `"score"` + - `action: Optional[BetaComputerAction]` - - `"block"` + A click action. -- `multi_agent: Optional[MultiAgent]` + - `class Click: …` - Configuration for server-hosted multi-agent execution. + A click action. - - `enabled: bool` + - `button: Literal["left", "right", "wheel", 2 more]` - Whether to enable server-hosted multi-agent execution for this response. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `max_concurrent_subagents: Optional[int]` + - `"left"` - `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. - The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. + - `"right"` -- `parallel_tool_calls: Optional[bool]` + - `"wheel"` - Whether to allow the model to run tool calls in parallel. + - `"back"` -- `previous_response_id: Optional[str]` + - `"forward"` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `type: Literal["click"]` -- `prompt: Optional[BetaResponsePromptParam]` + Specifies the event type. For a click action, this property is always `click`. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `"click"` - - `id: str` + - `x: int` - The unique identifier of the prompt template to use. + The x-coordinate where the click occurred. - - `variables: Optional[Dict[str, Variables]]` + - `y: int` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The y-coordinate where the click occurred. - - `str` + - `keys: Optional[List[str]]` - - `class BetaResponseInputText: …` + The keys being held while clicking. - A text input to the model. + - `class DoubleClick: …` - - `class BetaResponseInputImage: …` + A double click action. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `keys: Optional[List[str]]` - - `class BetaResponseInputFile: …` + The keys being held while double-clicking. - A file input to the model. + - `type: Literal["double_click"]` - - `version: Optional[str]` + Specifies the event type. For a double click action, this property is always set to `double_click`. - Optional version of the prompt template. + - `"double_click"` -- `prompt_cache_key: Optional[str]` + - `x: int` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + The x-coordinate where the double click occurred. -- `prompt_cache_options: Optional[PromptCacheOptions]` + - `y: int` - Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. + The y-coordinate where the double click occurred. - - `mode: Optional[Literal["implicit", "explicit"]]` + - `class Drag: …` - Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + A drag action. - - `"implicit"` + - `path: List[DragPath]` - - `"explicit"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `ttl: Optional[Literal["30m"]]` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + - `x: int` - - `"30m"` + The x-coordinate. -- `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + - `y: int` - Deprecated. Use `prompt_cache_options.ttl` instead. + The y-coordinate. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `type: Literal["drag"]` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + Specifies the event type. For a drag action, this property is always set to `drag`. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `"drag"` - - `"in_memory"` + - `keys: Optional[List[str]]` - - `"24h"` + The keys being held while dragging the mouse. -- `reasoning: Optional[Reasoning]` + - `class Keypress: …` - **gpt-5 and o-series models only** + A collection of keypresses the model would like to perform. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `keys: List[str]` - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `type: Literal["keypress"]` - - `"auto"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `"current_turn"` + - `"keypress"` - - `"all_turns"` + - `class Move: …` - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + A mouse move action. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `type: Literal["move"]` - - `"none"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"minimal"` + - `"move"` - - `"low"` + - `x: int` - - `"medium"` + The x-coordinate to move to. - - `"high"` + - `y: int` - - `"xhigh"` + The y-coordinate to move to. - - `"max"` + - `keys: Optional[List[str]]` - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + The keys being held while moving the mouse. - **Deprecated:** use `summary` instead. + - `class Screenshot: …` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + A screenshot action. - - `"auto"` + - `type: Literal["screenshot"]` - - `"concise"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"detailed"` + - `"screenshot"` - - `mode: Optional[Union[str, Literal["standard", "pro"]]]` + - `class Scroll: …` - Controls the reasoning execution mode for the request. + A scroll action. - When returned on a response, this is the effective execution mode. + - `scroll_x: int` - - `str` + The horizontal scroll distance. - - `Literal["standard", "pro"]` + - `scroll_y: int` - Controls the reasoning execution mode for the request. + The vertical scroll distance. - When returned on a response, this is the effective execution mode. + - `type: Literal["scroll"]` - - `"standard"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"pro"` + - `"scroll"` - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + - `x: int` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The x-coordinate where the scroll occurred. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `y: int` - - `"auto"` + The y-coordinate where the scroll occurred. - - `"concise"` + - `keys: Optional[List[str]]` - - `"detailed"` + The keys being held while scrolling. -- `safety_identifier: Optional[str]` + - `class Type: …` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + An action to type in text. -- `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + - `text: str` - Specifies the processing type used for serving the request. + The text to type. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `type: Literal["type"]` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `class Wait: …` + + A wait action. - - `"auto"` + - `type: Literal["wait"]` - - `"default"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"flex"` + - `"wait"` - - `"scale"` + - `actions: Optional[BetaComputerActionList]` - - `"priority"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. -- `store: Optional[bool]` + - `class Click: …` - Whether to store the generated model response for later retrieval via - API. + A click action. -- `stream: Optional[Literal[false]]` + - `class DoubleClick: …` - If set to true, the model response data will be streamed to the client - as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). - See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) - for more information. + A double click action. - - `false` + - `class Drag: …` -- `stream_options: Optional[StreamOptions]` + A drag action. - Options for streaming responses. Only set this when you set `stream: true`. + - `class Keypress: …` - - `include_obfuscation: Optional[bool]` + A collection of keypresses the model would like to perform. - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events to - normalize payload sizes as a mitigation to certain side-channel attacks. - These obfuscation fields are included by default, but add a small amount - of overhead to the data stream. You can set `include_obfuscation` to - false to optimize for bandwidth if you trust the network links between - your application and the OpenAI API. + - `class Move: …` -- `temperature: Optional[float]` + A mouse move action. - 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. - We generally recommend altering this or `top_p` but not both. + - `class Screenshot: …` -- `text: Optional[BetaResponseTextConfigParam]` + A screenshot action. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `class Scroll: …` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + A scroll action. - - `format: Optional[BetaResponseFormatTextConfig]` + - `class Type: …` - An object specifying the format that the model must output. + An action to type in text. - Configuring `{ "type": "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). + - `class Wait: …` - The default format is `{ "type": "text" }` with no additional options. + A wait action. - **Not recommended for gpt-4o and newer models:** + - `agent: Optional[Agent]` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The agent that produced this item. - - `class Text: …` + - `agent_name: str` - Default response format. Used to generate text responses. + The canonical name of the agent that produced this item. - - `type: Literal["text"]` + - `class BetaResponseComputerToolCallOutputItem: …` - The type of response format being defined. Always `text`. + - `id: str` - - `"text"` + The unique ID of the computer call tool output. - - `class BetaResponseFormatTextJSONSchemaConfig: …` + - `call_id: str` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The ID of the computer tool call that produced the output. - - `name: str` + - `output: BetaResponseComputerToolCallOutputScreenshot` - 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. + A computer screenshot image used with the computer use tool. - - `schema: Dict[str, object]` + - `type: Literal["computer_screenshot"]` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `type: Literal["json_schema"]` + - `"computer_screenshot"` - The type of response format being defined. Always `json_schema`. + - `file_id: Optional[str]` - - `"json_schema"` + The identifier of an uploaded file that contains the screenshot. - - `description: Optional[str]` + - `image_url: Optional[str]` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The URL of the screenshot image. - - `strict: Optional[bool]` + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - 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). + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `class JSONObject: …` + - `"completed"` - 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. + - `"incomplete"` - - `type: Literal["json_object"]` + - `"failed"` - The type of response format being defined. Always `json_object`. + - `"in_progress"` - - `"json_object"` + - `type: Literal["computer_call_output"]` - - `verbosity: Optional[Literal["low", "medium", "high"]]` + The type of the computer tool call output. Always `computer_call_output`. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `"computer_call_output"` - - `"low"` + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - - `"medium"` + The safety checks reported by the API that have been acknowledged by the + developer. - - `"high"` + - `id: str` -- `tool_choice: Optional[ToolChoice]` + The ID of the pending safety check. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `code: Optional[str]` - - `Literal["none", "auto", "required"]` + The type of the pending safety check. - - `"none"` + - `message: Optional[str]` - - `"auto"` + Details about the pending safety check. - - `"required"` + - `agent: Optional[Agent]` - - `class BetaToolChoiceAllowed: …` + The agent that produced this item. - Constrains the tools available to the model to a pre-defined set. + - `agent_name: str` - - `mode: Literal["auto", "required"]` + The canonical name of the agent that produced this item. - Constrains the tools available to the model to a pre-defined set. + - `created_by: Optional[str]` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The identifier of the actor that created the item. - `required` requires the model to call one or more of the allowed tools. + - `class BetaResponseReasoningItem: …` - - `"auto"` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `"required"` + - `id: str` - - `tools: List[Dict[str, object]]` + The unique identifier of the reasoning content. - A list of tool definitions that the model should be allowed to call. + - `summary: List[Summary]` - For the Responses API, the list of tool definitions might look like: + Reasoning summary content. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `text: str` - - `type: Literal["allowed_tools"]` + A summary of the reasoning output from the model so far. - Allowed tool configuration type. Always `allowed_tools`. + - `type: Literal["summary_text"]` - - `"allowed_tools"` + The type of the object. Always `summary_text`. - - `class BetaToolChoiceTypes: …` + - `"summary_text"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `type: Literal["reasoning"]` - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + The type of the object. Always `reasoning`. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"reasoning"` - Allowed values are: + - `agent: Optional[Agent]` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The agent that produced this item. - - `"file_search"` + - `agent_name: str` - - `"web_search_preview"` + The canonical name of the agent that produced this item. - - `"computer"` + - `content: Optional[List[Content]]` - - `"computer_use_preview"` + Reasoning text content. - - `"computer_use"` + - `text: str` - - `"web_search_preview_2025_03_11"` + The reasoning text from the model. - - `"image_generation"` + - `type: Literal["reasoning_text"]` - - `"code_interpreter"` + The type of the reasoning text. Always `reasoning_text`. - - `class BetaToolChoiceFunction: …` + - `"reasoning_text"` - Use this option to force the model to call a specific function. + - `encrypted_content: Optional[str]` - - `name: str` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The name of the function to call. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `type: Literal["function"]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - For function calling, the type is always `function`. + - `"in_progress"` - - `"function"` + - `"completed"` - - `class BetaToolChoiceMcp: …` + - `"incomplete"` - Use this option to force the model to call a specific tool on a remote MCP server. + - `class Program: …` - - `server_label: str` + - `id: str` - The label of the MCP server to use. + The unique ID of the program item. - - `type: Literal["mcp"]` + - `call_id: str` - For MCP tools, the type is always `mcp`. + The stable call ID of the program item. - - `"mcp"` + - `code: str` - - `name: Optional[str]` + The JavaScript source executed by programmatic tool calling. - The name of the tool to call on the server. + - `fingerprint: str` - - `class BetaToolChoiceCustom: …` + Opaque program replay fingerprint that must be round-tripped. - Use this option to force the model to call a specific custom tool. + - `type: Literal["program"]` - - `name: str` + The type of the item. Always `program`. - The name of the custom tool to call. + - `"program"` - - `type: Literal["custom"]` + - `agent: Optional[ProgramAgent]` - For custom tool calling, the type is always `custom`. + The agent that produced this item. - - `"custom"` + - `agent_name: str` - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + The canonical name of the agent that produced this item. - - `type: Literal["programmatic_tool_calling"]` + - `class ProgramOutput: …` - The tool to call. Always `programmatic_tool_calling`. + - `id: str` - - `"programmatic_tool_calling"` + The unique ID of the program output item. - - `class BetaToolChoiceApplyPatch: …` + - `call_id: str` - Forces the model to call the apply_patch tool when executing a tool call. + The call ID of the program item. - - `type: Literal["apply_patch"]` + - `result: str` - The tool to call. Always `apply_patch`. + The result produced by the program item. - - `"apply_patch"` + - `status: Literal["completed", "incomplete"]` - - `class BetaToolChoiceShell: …` + The terminal status of the program output item. - Forces the model to call the shell tool when a tool call is required. + - `"completed"` - - `type: Literal["shell"]` + - `"incomplete"` - The tool to call. Always `shell`. + - `type: Literal["program_output"]` - - `"shell"` + The type of the item. Always `program_output`. -- `tools: Optional[Iterable[BetaToolParam]]` + - `"program_output"` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `agent: Optional[ProgramOutputAgent]` - We support the following categories of tools: + The agent that produced this item. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `agent_name: str` - - `class BetaFunctionTool: …` + The canonical name of the agent that produced this item. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class BetaResponseToolSearchCall: …` - - `class BetaFileSearchTool: …` + - `id: str` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The unique ID of the tool search call item. - - `class BetaComputerTool: …` + - `arguments: object` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Arguments used for the tool search call. - - `class BetaComputerUsePreviewTool: …` + - `call_id: Optional[str]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The unique ID of the tool search call generated by the model. - - `class BetaWebSearchTool: …` + - `execution: Literal["server", "client"]` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Whether tool search was executed by the server or by the client. - - `class Mcp: …` + - `"server"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"client"` - - `class CodeInterpreter: …` + - `status: Literal["in_progress", "completed", "incomplete"]` - A tool that runs Python code to help generate a response to a prompt. + The status of the tool search call item that was recorded. - - `class ProgrammaticToolCalling: …` + - `"in_progress"` - - `class ImageGeneration: …` + - `"completed"` - A tool that generates images using the GPT image models. + - `"incomplete"` - - `class LocalShell: …` + - `type: Literal["tool_search_call"]` - A tool that allows the model to execute shell commands in a local environment. + The type of the item. Always `tool_search_call`. - - `class BetaFunctionShellTool: …` + - `"tool_search_call"` - A tool that allows the model to execute shell commands. + - `agent: Optional[Agent]` - - `class BetaCustomTool: …` + The agent that produced this item. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `agent_name: str` - - `class BetaNamespaceTool: …` + The canonical name of the agent that produced this item. - Groups function/custom tools under a shared namespace. + - `created_by: Optional[str]` - - `class BetaToolSearchTool: …` + The identifier of the actor that created the item. - Hosted or BYOT tool search configuration for deferred tools. + - `class BetaResponseToolSearchOutputItem: …` - - `class BetaWebSearchPreviewTool: …` + - `id: str` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The unique ID of the tool search output item. - - `class BetaApplyPatchTool: …` + - `call_id: Optional[str]` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of the tool search call generated by the model. -- `top_logprobs: Optional[int]` + - `execution: Literal["server", "client"]` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + Whether tool search was executed by the server or by the client. -- `top_p: Optional[float]` + - `"server"` - 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. + - `"client"` - We generally recommend altering this or `temperature` but not both. + - `status: Literal["in_progress", "completed", "incomplete"]` -- `truncation: Optional[Literal["auto", "disabled"]]` + The status of the tool search output item that was recorded. - The truncation strategy to use for the model response. + - `"in_progress"` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `"completed"` - - `"auto"` + - `"incomplete"` - - `"disabled"` + - `tools: List[BetaTool]` -- `user: Optional[str]` + The loaded tool definitions returned by tool search. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `class BetaFunctionTool: …` -- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"responses_multi_agent=v1"` + - `name: str` -### Returns + The name of the function to call. -- `class BetaResponse: …` + - `parameters: Optional[Dict[str, object]]` - - `id: str` + A JSON schema object describing the parameters of the function. - Unique identifier for this Response. + - `strict: Optional[bool]` - - `created_at: float` + Whether strict parameter validation is enforced for this function tool. - Unix timestamp (in seconds) of when this Response was created. + - `type: Literal["function"]` - - `error: Optional[BetaResponseError]` + The type of the function tool. Always `function`. - An error object returned when the model fails to generate a Response. + - `"function"` - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The error code for the response. + The tool invocation context(s). - - `"server_error"` + - `"direct"` - - `"rate_limit_exceeded"` + - `"programmatic"` - - `"invalid_prompt"` + - `defer_loading: Optional[bool]` - - `"bio_policy"` + Whether this function is deferred and loaded via tool search. - - `"vector_store_timeout"` + - `description: Optional[str]` - - `"invalid_image"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"invalid_image_format"` + - `output_schema: Optional[Dict[str, object]]` - - `"invalid_base64_image"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"invalid_image_url"` + - `class BetaFileSearchTool: …` - - `"image_too_large"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `"image_too_small"` + - `type: Literal["file_search"]` - - `"image_parse_error"` + The type of the file search tool. Always `file_search`. - - `"image_content_policy_violation"` + - `"file_search"` - - `"invalid_image_mode"` + - `vector_store_ids: List[str]` - - `"image_file_too_large"` + The IDs of the vector stores to search. - - `"unsupported_image_media_type"` + - `filters: Optional[Filters]` - - `"empty_image_file"` + A filter to apply. - - `"failed_to_download_image"` + - `class FiltersComparisonFilter: …` - - `"image_file_not_found"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `message: str` + - `key: str` - A human-readable description of the error. + The key to compare against the value. - - `incomplete_details: Optional[IncompleteDetails]` + - `type: Literal["eq", "ne", "gt", 5 more]` - Details about why the response is incomplete. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The reason why the response is incomplete. + - `"eq"` - - `"max_output_tokens"` + - `"ne"` - - `"content_filter"` + - `"gt"` - - `instructions: Union[str, List[BetaResponseInputItem], null]` + - `"gte"` - A system (or developer) message inserted into the model's context. + - `"lt"` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `"lte"` - - `str` + - `"in"` - A text input to the model, equivalent to a text input with the - `developer` role. + - `"nin"` - - `List[BetaResponseInputItem]` + - `value: Union[str, float, bool, List[Union[str, float]]]` - A list of one or many input items to the model, containing - different content types. + The value to compare against the attribute key; supports string, number, or boolean types. - - `class BetaEasyInputMessage: …` + - `str` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `float` - - `content: Union[str, BetaResponseInputMessageContentList]` + - `bool` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `List[Union[str, float]]` - `str` - A text input to the model. + - `float` - - `List[BetaResponseInputContent]` + - `class FiltersCompoundFilter: …` - - `class BetaResponseInputText: …` + Combine multiple filters using `and` or `or`. - A text input to the model. + - `filters: List[FiltersCompoundFilterFilter]` - - `text: str` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The text input to the model. + - `class FiltersCompoundFilterFilterComparisonFilter: …` - - `type: Literal["input_text"]` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The type of the input item. Always `input_text`. + - `key: str` - - `"input_text"` + The key to compare against the value. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["eq", "ne", "gt", 5 more]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `mode: Literal["explicit"]` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The breakpoint mode. Always `explicit`. + - `"eq"` - - `"explicit"` + - `"ne"` - - `class BetaResponseInputImage: …` + - `"gt"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"gte"` - - `detail: Literal["low", "high", "auto", "original"]` + - `"lt"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"lte"` - - `"low"` + - `"in"` - - `"high"` + - `"nin"` - - `"auto"` + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `"original"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `type: Literal["input_image"]` + - `str` - The type of the input item. Always `input_image`. + - `float` - - `"input_image"` + - `bool` - - `file_id: Optional[str]` + - `List[Union[str, float]]` - The ID of the file to be sent to the model. + - `str` - - `image_url: Optional[str]` + - `float` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `object` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["and", "or"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Type of operation: `and` or `or`. - - `mode: Literal["explicit"]` + - `"and"` - The breakpoint mode. Always `explicit`. + - `"or"` - - `"explicit"` + - `max_num_results: Optional[int]` - - `class BetaResponseInputFile: …` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - A file input to the model. + - `ranking_options: Optional[RankingOptions]` - - `type: Literal["input_file"]` + Ranking options for search. - The type of the input item. Always `input_file`. + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - `"input_file"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `embedding_weight: float` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The weight of the embedding in the reciprocal ranking fusion. - - `"auto"` + - `text_weight: float` - - `"low"` + The weight of the text in the reciprocal ranking fusion. - - `"high"` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - - `file_data: Optional[str]` + The ranker to use for the file search. - The content of the file to be sent to the model. + - `"auto"` - - `file_id: Optional[str]` + - `"default-2024-11-15"` - The ID of the file to be sent to the model. + - `score_threshold: Optional[float]` - - `file_url: Optional[str]` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The URL of the file to be sent to the model. + - `class BetaComputerTool: …` - - `filename: Optional[str]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The name of the file to be sent to the model. + - `type: Literal["computer"]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The type of the computer tool. Always `computer`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"computer"` - - `mode: Literal["explicit"]` + - `class BetaComputerUsePreviewTool: …` - The breakpoint mode. Always `explicit`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"explicit"` + - `display_height: int` - - `role: Literal["user", "assistant", "system", "developer"]` + The height of the computer display. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `display_width: int` - - `"user"` + The width of the computer display. - - `"assistant"` + - `environment: Literal["windows", "mac", "linux", 2 more]` - - `"system"` + The type of computer environment to control. - - `"developer"` + - `"windows"` - - `phase: Optional[Literal["commentary"]]` + - `"mac"` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `"linux"` - - `"commentary"` + - `"ubuntu"` - - `type: Optional[Literal["message"]]` + - `"browser"` - The type of the message input. Always `message`. + - `type: Literal["computer_use_preview"]` - - `"message"` + The type of the computer use tool. Always `computer_use_preview`. - - `class Message: …` + - `"computer_use_preview"` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + - `class BetaWebSearchTool: …` - - `content: BetaResponseInputMessageContentList` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - A list of one or many input items to the model, containing different content - types. + - `type: Literal["web_search", "web_search_2025_08_26"]` - - `class BetaResponseInputText: …` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - A text input to the model. + - `"web_search"` - - `class BetaResponseInputImage: …` + - `"web_search_2025_08_26"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `filters: Optional[Filters]` - - `class BetaResponseInputFile: …` + Filters for the search. - A file input to the model. + - `allowed_domains: Optional[List[str]]` - - `role: Literal["user", "system", "developer"]` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The role of the message input. One of `user`, `system`, or `developer`. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"user"` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `"system"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `"developer"` + - `"low"` - - `agent: Optional[MessageAgent]` + - `"medium"` - The agent that produced this item. + - `"high"` - - `agent_name: str` + - `user_location: Optional[UserLocation]` - The canonical name of the agent that produced this item. + The approximate location of the user. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `city: Optional[str]` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Free text input for the city of the user, e.g. `San Francisco`. - - `"in_progress"` + - `country: Optional[str]` - - `"completed"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"incomplete"` + - `region: Optional[str]` - - `type: Optional[Literal["message"]]` + Free text input for the region of the user, e.g. `California`. - The type of the message input. Always set to `message`. + - `timezone: Optional[str]` - - `"message"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `class BetaResponseOutputMessage: …` + - `type: Optional[Literal["approximate"]]` - An output message from the model. + The type of location approximation. Always `approximate`. - - `id: str` + - `"approximate"` - The unique ID of the output message. + - `class Mcp: …` - - `content: List[Content]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The content of the output message. + - `server_label: str` - - `class BetaResponseOutputText: …` + A label for this MCP server, used to identify it in tool calls. - A text output from the model. + - `type: Literal["mcp"]` - - `annotations: List[Annotation]` + The type of the MCP tool. Always `mcp`. - The annotations of the text output. + - `"mcp"` - - `class AnnotationFileCitation: …` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - A citation to a file. + The tool invocation context(s). - - `file_id: str` + - `"direct"` - The ID of the file. + - `"programmatic"` - - `filename: str` + - `allowed_tools: Optional[McpAllowedTools]` - The filename of the file cited. + List of allowed tool names or a filter object. - - `index: int` + - `List[str]` - The index of the file in the list of files. + A string array of allowed tool names - - `type: Literal["file_citation"]` + - `class McpAllowedToolsMcpToolFilter: …` - The type of the file citation. Always `file_citation`. + A filter object to specify which tools are allowed. - - `"file_citation"` + - `read_only: Optional[bool]` - - `class AnnotationURLCitation: …` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - A citation for a web resource used to generate a model response. + - `tool_names: Optional[List[str]]` - - `end_index: int` + List of allowed tool names. - The index of the last character of the URL citation in the message. + - `authorization: Optional[str]` - - `start_index: int` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The index of the first character of the URL citation in the message. + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `title: str` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - The title of the web resource. + Currently supported `connector_id` values are: - - `type: Literal["url_citation"]` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The type of the URL citation. Always `url_citation`. + - `"connector_dropbox"` - - `"url_citation"` + - `"connector_gmail"` - - `url: str` + - `"connector_googlecalendar"` - The URL of the web resource. + - `"connector_googledrive"` - - `class AnnotationContainerFileCitation: …` + - `"connector_microsoftteams"` - A citation for a container file used to generate a model response. + - `"connector_outlookcalendar"` - - `container_id: str` + - `"connector_outlookemail"` - The ID of the container file. + - `"connector_sharepoint"` - - `end_index: int` + - `defer_loading: Optional[bool]` - The index of the last character of the container file citation in the message. + Whether this MCP tool is deferred and discovered via tool search. - - `file_id: str` + - `headers: Optional[Dict[str, str]]` - The ID of the file. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `filename: str` + - `require_approval: Optional[McpRequireApproval]` - The filename of the container file cited. + Specify which of the MCP server's tools require approval. - - `start_index: int` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - The index of the first character of the container file citation in the message. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `type: Literal["container_file_citation"]` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - The type of the container file citation. Always `container_file_citation`. + A filter object to specify which tools are allowed. - - `"container_file_citation"` + - `read_only: Optional[bool]` - - `class AnnotationFilePath: …` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - A path to a file. + - `tool_names: Optional[List[str]]` - - `file_id: str` + List of allowed tool names. - The ID of the file. + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - - `index: int` + A filter object to specify which tools are allowed. - The index of the file in the list of files. + - `read_only: Optional[bool]` - - `type: Literal["file_path"]` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The type of the file path. Always `file_path`. + - `tool_names: Optional[List[str]]` - - `"file_path"` + List of allowed tool names. - - `text: str` + - `Literal["always", "never"]` - The text output from the model. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `type: Literal["output_text"]` + - `"always"` - The type of the output text. Always `output_text`. + - `"never"` - - `"output_text"` + - `server_description: Optional[str]` - - `logprobs: Optional[List[Logprob]]` + Optional description of the MCP server, used to provide more context. - - `token: str` + - `server_url: Optional[str]` - - `bytes: List[int]` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `logprob: float` + - `tunnel_id: Optional[str]` - - `top_logprobs: List[LogprobTopLogprob]` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `token: str` + - `class CodeInterpreter: …` - - `bytes: List[int]` + A tool that runs Python code to help generate a response to a prompt. - - `logprob: float` + - `container: CodeInterpreterContainer` - - `class BetaResponseOutputRefusal: …` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - A refusal from the model. + - `str` - - `refusal: str` + The container ID. - The refusal explanation from the model. + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `type: Literal["refusal"]` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The type of the refusal. Always `refusal`. + - `type: Literal["auto"]` - - `"refusal"` + Always `auto`. - - `role: Literal["assistant"]` + - `"auto"` - The role of the output message. Always `assistant`. + - `file_ids: Optional[List[str]]` - - `"assistant"` + An optional list of uploaded files to make available to your code. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The memory limit for the code interpreter container. - - `"in_progress"` + - `"1g"` - - `"completed"` + - `"4g"` - - `"incomplete"` + - `"16g"` - - `type: Literal["message"]` + - `"64g"` - The type of the output message. Always `message`. + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - - `"message"` + Network access policy for the container. - - `agent: Optional[Agent]` + - `class BetaContainerNetworkPolicyDisabled: …` - The agent that produced this item. + - `type: Literal["disabled"]` - - `agent_name: str` + Disable outbound network access. Always `disabled`. - The canonical name of the agent that produced this item. + - `"disabled"` + + - `class BetaContainerNetworkPolicyAllowlist: …` - - `phase: Optional[Literal["commentary"]]` + - `allowed_domains: List[str]` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + A list of allowed domains when type is `allowlist`. - - `"commentary"` + - `type: Literal["allowlist"]` - - `class BetaResponseFileSearchToolCall: …` + Allow outbound network access only to specified domains. Always `allowlist`. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"allowlist"` - - `id: str` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - The unique ID of the file search tool call. + Optional domain-scoped secrets for allowlisted domains. - - `queries: List[str]` + - `domain: str` - The queries used to search for files. + The domain associated with the secret. - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `name: str` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The name of the secret to inject for the domain. - - `"in_progress"` + - `value: str` - - `"searching"` + The secret value to inject for the domain. - - `"completed"` + - `type: Literal["code_interpreter"]` - - `"incomplete"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"failed"` + - `"code_interpreter"` - - `type: Literal["file_search_call"]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The type of the file search tool call. Always `file_search_call`. + The tool invocation context(s). - - `"file_search_call"` + - `"direct"` - - `agent: Optional[Agent]` + - `"programmatic"` - The agent that produced this item. + - `class ProgrammaticToolCalling: …` - - `agent_name: str` + - `type: Literal["programmatic_tool_calling"]` - The canonical name of the agent that produced this item. + The type of the tool. Always `programmatic_tool_calling`. - - `results: Optional[List[Result]]` + - `"programmatic_tool_calling"` - The results of the file search tool call. + - `class ImageGeneration: …` - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + A tool that generates images using the GPT image models. - 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, booleans, or numbers. + - `type: Literal["image_generation"]` + + The type of the image generation tool. Always `image_generation`. - - `str` + - `"image_generation"` - - `float` + - `action: Optional[Literal["generate", "edit", "auto"]]` - - `bool` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `file_id: Optional[str]` + - `"generate"` - The unique ID of the file. + - `"edit"` - - `filename: Optional[str]` + - `"auto"` - The name of the file. + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `score: Optional[float]` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - The relevance score of the file - a value between 0 and 1. + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `text: Optional[str]` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - The text that was retrieved from the file. + - `"transparent"` - - `class BetaResponseComputerToolCall: …` + - `"opaque"` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `"auto"` - - `id: str` + - `input_fidelity: Optional[Literal["high", "low"]]` - The unique ID of the computer call. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `call_id: str` + - `"high"` - An identifier used when responding to the tool call with output. + - `"low"` - - `pending_safety_checks: List[PendingSafetyCheck]` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - The pending safety checks for the computer call. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `id: str` + - `file_id: Optional[str]` - The ID of the pending safety check. + File ID for the mask image. - - `code: Optional[str]` + - `image_url: Optional[str]` - The type of the pending safety check. + Base64-encoded mask image. - - `message: Optional[str]` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - Details about the pending safety check. + The image generation model to use. Default: `gpt-image-1`. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `str` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `"in_progress"` + The image generation model to use. Default: `gpt-image-1`. - - `"completed"` + - `"gpt-image-1"` - - `"incomplete"` + - `"gpt-image-1-mini"` - - `type: Literal["computer_call"]` + - `"gpt-image-2"` - The type of the computer call. Always `computer_call`. + - `"gpt-image-2-2026-04-21"` - - `"computer_call"` + - `"gpt-image-1.5"` - - `action: Optional[BetaComputerAction]` + - `"chatgpt-image-latest"` - A click action. + - `moderation: Optional[Literal["auto", "low"]]` - - `class Click: …` + Moderation level for the generated image. Default: `auto`. - A click action. + - `"auto"` - - `button: Literal["left", "right", "wheel", 2 more]` + - `"low"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `output_compression: Optional[int]` - - `"left"` + Compression level for the output image. Default: 100. - - `"right"` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `"wheel"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"back"` + - `"png"` - - `"forward"` + - `"webp"` - - `type: Literal["click"]` + - `"jpeg"` - Specifies the event type. For a click action, this property is always `click`. + - `partial_images: Optional[int]` - - `"click"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `x: int` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - The x-coordinate where the click occurred. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `y: int` + - `"low"` - The y-coordinate where the click occurred. + - `"medium"` - - `keys: Optional[List[str]]` + - `"high"` - The keys being held while clicking. + - `"auto"` - - `class DoubleClick: …` + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - A double click action. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `keys: Optional[List[str]]` + - `str` - The keys being held while double-clicking. + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `type: Literal["double_click"]` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"1024x1024"` - - `"double_click"` + - `"1024x1536"` - - `x: int` + - `"1536x1024"` - The x-coordinate where the double click occurred. + - `"auto"` - - `y: int` + - `class LocalShell: …` - The y-coordinate where the double click occurred. + A tool that allows the model to execute shell commands in a local environment. - - `class Drag: …` + - `type: Literal["local_shell"]` - A drag action. + The type of the local shell tool. Always `local_shell`. - - `path: List[DragPath]` + - `"local_shell"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `class BetaFunctionShellTool: …` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + A tool that allows the model to execute shell commands. - - `x: int` + - `type: Literal["shell"]` - The x-coordinate. + The type of the shell tool. Always `shell`. - - `y: int` + - `"shell"` - The y-coordinate. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `type: Literal["drag"]` + The tool invocation context(s). - Specifies the event type. For a drag action, this property is always set to `drag`. + - `"direct"` - - `"drag"` + - `"programmatic"` - - `keys: Optional[List[str]]` + - `environment: Optional[Environment]` - The keys being held while dragging the mouse. + - `class BetaContainerAuto: …` - - `class Keypress: …` + - `type: Literal["container_auto"]` - A collection of keypresses the model would like to perform. + Automatically creates a container for this request - - `keys: List[str]` + - `"container_auto"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `file_ids: Optional[List[str]]` - - `type: Literal["keypress"]` + An optional list of uploaded files to make available to your code. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `"keypress"` + The memory limit for the container. - - `class Move: …` + - `"1g"` - A mouse move action. + - `"4g"` - - `type: Literal["move"]` + - `"16g"` - Specifies the event type. For a move action, this property is always set to `move`. + - `"64g"` - - `"move"` + - `network_policy: Optional[NetworkPolicy]` - - `x: int` + Network access policy for the container. - The x-coordinate to move to. + - `class BetaContainerNetworkPolicyDisabled: …` - - `y: int` + - `class BetaContainerNetworkPolicyAllowlist: …` - The y-coordinate to move to. + - `skills: Optional[List[Skill]]` - - `keys: Optional[List[str]]` + An optional list of skills referenced by id or inline data. - The keys being held while moving the mouse. + - `class BetaSkillReference: …` - - `class Screenshot: …` + - `skill_id: str` - A screenshot action. + The ID of the referenced skill. - - `type: Literal["screenshot"]` + - `type: Literal["skill_reference"]` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + References a skill created with the /v1/skills endpoint. - - `"screenshot"` + - `"skill_reference"` - - `class Scroll: …` + - `version: Optional[str]` - A scroll action. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `scroll_x: int` + - `class BetaInlineSkill: …` - The horizontal scroll distance. + - `description: str` - - `scroll_y: int` + The description of the skill. - The vertical scroll distance. + - `name: str` - - `type: Literal["scroll"]` + The name of the skill. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `source: BetaInlineSkillSource` - - `"scroll"` + Inline skill payload - - `x: int` + - `data: str` - The x-coordinate where the scroll occurred. + Base64-encoded skill zip bundle. - - `y: int` + - `media_type: Literal["application/zip"]` - The y-coordinate where the scroll occurred. + The media type of the inline skill payload. Must be `application/zip`. - - `keys: Optional[List[str]]` + - `"application/zip"` - The keys being held while scrolling. + - `type: Literal["base64"]` - - `class Type: …` + The type of the inline skill source. Must be `base64`. - An action to type in text. + - `"base64"` - - `text: str` + - `type: Literal["inline"]` - The text to type. + Defines an inline skill for this request. - - `type: Literal["type"]` + - `"inline"` - Specifies the event type. For a type action, this property is always set to `type`. + - `class BetaLocalEnvironment: …` - - `"type"` + - `type: Literal["local"]` - - `class Wait: …` + Use a local computer environment. - A wait action. + - `"local"` - - `type: Literal["wait"]` + - `skills: Optional[List[BetaLocalSkill]]` - Specifies the event type. For a wait action, this property is always set to `wait`. + An optional list of skills. - - `"wait"` + - `description: str` - - `actions: Optional[BetaComputerActionList]` + The description of the skill. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `name: str` - - `class Click: …` + The name of the skill. - A click action. + - `path: str` - - `class DoubleClick: …` + The path to the directory containing the skill. - A double click action. + - `class BetaContainerReference: …` - - `class Drag: …` + - `container_id: str` - A drag action. + The ID of the referenced container. - - `class Keypress: …` + - `type: Literal["container_reference"]` - A collection of keypresses the model would like to perform. + References a container created with the /v1/containers endpoint - - `class Move: …` + - `"container_reference"` - A mouse move action. + - `class BetaCustomTool: …` - - `class Screenshot: …` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - A screenshot action. + - `name: str` - - `class Scroll: …` + The name of the custom tool, used to identify it in tool calls. - A scroll action. + - `type: Literal["custom"]` - - `class Type: …` + The type of the custom tool. Always `custom`. - An action to type in text. + - `"custom"` - - `class Wait: …` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - A wait action. + The tool invocation context(s). - - `agent: Optional[Agent]` + - `"direct"` - The agent that produced this item. + - `"programmatic"` - - `agent_name: str` + - `defer_loading: Optional[bool]` - The canonical name of the agent that produced this item. + Whether this tool should be deferred and discovered via tool search. - - `class ComputerCallOutput: …` + - `description: Optional[str]` - The output of a computer tool call. + Optional description of the custom tool, used to provide more context. - - `call_id: str` + - `format: Optional[Format]` - The ID of the computer tool call that produced the output. + The input format for the custom tool. Default is unconstrained text. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `class FormatText: …` - A computer screenshot image used with the computer use tool. + Unconstrained free-form text. - - `type: Literal["computer_screenshot"]` + - `type: Literal["text"]` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + Unconstrained text format. Always `text`. - - `"computer_screenshot"` + - `"text"` - - `file_id: Optional[str]` + - `class FormatGrammar: …` - The identifier of an uploaded file that contains the screenshot. + A grammar defined by the user. - - `image_url: Optional[str]` + - `definition: str` - The URL of the screenshot image. + The grammar definition. - - `type: Literal["computer_call_output"]` + - `syntax: Literal["lark", "regex"]` - The type of the computer tool call output. Always `computer_call_output`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `"computer_call_output"` + - `"lark"` - - `id: Optional[str]` + - `"regex"` - The ID of the computer tool call output. + - `type: Literal["grammar"]` - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + Grammar format. Always `grammar`. - The safety checks reported by the API that have been acknowledged by the developer. + - `"grammar"` - - `id: str` + - `class BetaNamespaceTool: …` - The ID of the pending safety check. + Groups function/custom tools under a shared namespace. - - `code: Optional[str]` + - `description: str` - The type of the pending safety check. + A description of the namespace shown to the model. - - `message: Optional[str]` + - `name: str` - Details about the pending safety check. + The namespace name used in tool calls (for example, `crm`). - - `agent: Optional[ComputerCallOutputAgent]` + - `tools: List[Tool]` - The agent that produced this item. + The function/custom tools available inside this namespace. - - `agent_name: str` + - `class ToolFunction: …` - The canonical name of the agent that produced this item. + - `name: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `type: Literal["function"]` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `"function"` - - `"in_progress"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"completed"` + The tool invocation context(s). - - `"incomplete"` + - `"direct"` - - `class BetaResponseFunctionWebSearch: …` + - `"programmatic"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `defer_loading: Optional[bool]` - - `id: str` + Whether this function should be deferred and discovered via tool search. - The unique ID of the web search tool call. + - `description: Optional[str]` - - `action: Action` + - `output_schema: Optional[Dict[str, object]]` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `class ActionSearch: …` + - `parameters: Optional[object]` - Action type "search" - Performs a web search query. + - `strict: Optional[bool]` - - `type: Literal["search"]` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - The action type. + - `class BetaCustomTool: …` - - `"search"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `queries: Optional[List[str]]` + - `type: Literal["namespace"]` - The search queries. + The type of the tool. Always `namespace`. - - `query: Optional[str]` + - `"namespace"` - The search query. + - `class BetaToolSearchTool: …` - - `sources: Optional[List[ActionSearchSource]]` + Hosted or BYOT tool search configuration for deferred tools. - The sources used in the search. + - `type: Literal["tool_search"]` - - `type: Literal["url"]` + The type of the tool. Always `tool_search`. - The type of source. Always `url`. + - `"tool_search"` - - `"url"` + - `description: Optional[str]` - - `url: str` + Description shown to the model for a client-executed tool search tool. - The URL of the source. + - `execution: Optional[Literal["server", "client"]]` - - `class ActionOpenPage: …` + Whether tool search is executed by the server or by the client. - Action type "open_page" - Opens a specific URL from search results. + - `"server"` - - `type: Literal["open_page"]` + - `"client"` - The action type. + - `parameters: Optional[object]` - - `"open_page"` + Parameter schema for a client-executed tool search tool. - - `url: Optional[str]` + - `class BetaWebSearchPreviewTool: …` - The URL opened by the model. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class ActionFindInPage: …` + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - Action type "find_in_page": Searches for a pattern within a loaded page. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `pattern: str` + - `"web_search_preview"` - The pattern or text to search for within the page. + - `"web_search_preview_2025_03_11"` - - `type: Literal["find_in_page"]` + - `search_content_types: Optional[List[Literal["text", "image"]]]` - The action type. + - `"text"` - - `"find_in_page"` + - `"image"` - - `url: str` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The URL of the page searched for the pattern. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `status: Literal["in_progress", "searching", "completed", "failed"]` + - `"low"` - The status of the web search tool call. + - `"medium"` - - `"in_progress"` + - `"high"` - - `"searching"` + - `user_location: Optional[UserLocation]` - - `"completed"` + The user's location. - - `"failed"` + - `type: Literal["approximate"]` - - `type: Literal["web_search_call"]` + The type of location approximation. Always `approximate`. - The type of the web search tool call. Always `web_search_call`. + - `"approximate"` - - `"web_search_call"` + - `city: Optional[str]` - - `agent: Optional[Agent]` + Free text input for the city of the user, e.g. `San Francisco`. - The agent that produced this item. + - `country: Optional[str]` - - `agent_name: str` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The canonical name of the agent that produced this item. + - `region: Optional[str]` - - `class BetaResponseFunctionToolCall: …` + Free text input for the region of the user, e.g. `California`. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `timezone: Optional[str]` - - `arguments: str` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A JSON string of the arguments to pass to the function. + - `class BetaApplyPatchTool: …` - - `call_id: str` + Allows the assistant to create, delete, or update files using unified diffs. - The unique ID of the function tool call generated by the model. + - `type: Literal["apply_patch"]` - - `name: str` + The type of the tool. Always `apply_patch`. - The name of the function to run. + - `"apply_patch"` - - `type: Literal["function_call"]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The type of the function tool call. Always `function_call`. + The tool invocation context(s). - - `"function_call"` + - `"direct"` - - `id: Optional[str]` + - `"programmatic"` - The unique ID of the function tool call. + - `type: Literal["tool_search_output"]` + + The type of the item. Always `tool_search_output`. + + - `"tool_search_output"` - `agent: Optional[Agent]` @@ -21507,180 +32411,179 @@ Create a model response The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. + - `created_by: Optional[str]` - - `class CallerDirect: …` + The identifier of the actor that created the item. - - `type: Literal["direct"]` + - `class AdditionalTools: …` - - `"direct"` + - `id: str` - - `class CallerProgram: …` + The unique ID of the additional tools item. - - `caller_id: str` + - `role: Literal["unknown", "user", "assistant", 5 more]` - The call ID of the program item that produced this tool call. + The role that provided the additional tools. - - `type: Literal["program"]` + - `"unknown"` - - `"program"` + - `"user"` - - `namespace: Optional[str]` + - `"assistant"` - The namespace of the function to run. + - `"system"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"critic"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"discriminator"` - - `"in_progress"` + - `"developer"` - - `"completed"` + - `"tool"` - - `"incomplete"` + - `tools: List[BetaTool]` - - `class FunctionCallOutput: …` + The additional tool definitions made available at this item. - The output of a function tool call. + - `class BetaFunctionTool: …` - - `call_id: str` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The unique ID of the function tool call generated by the model. + - `class BetaFileSearchTool: …` - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - Text, image, or file output of the function tool call. + - `class BetaComputerTool: …` - - `str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A JSON string of the output of the function tool call. + - `class BetaComputerUsePreviewTool: …` - - `List[BetaResponseFunctionCallOutputItem]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class BetaResponseInputTextContent: …` + - `class BetaWebSearchTool: …` - A text input to the model. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `text: str` + - `class Mcp: …` - The text input to the model. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `type: Literal["input_text"]` + - `class CodeInterpreter: …` - The type of the input item. Always `input_text`. + A tool that runs Python code to help generate a response to a prompt. - - `"input_text"` + - `class ProgrammaticToolCalling: …` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `class ImageGeneration: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A tool that generates images using the GPT image models. - - `mode: Literal["explicit"]` + - `class LocalShell: …` - The breakpoint mode. Always `explicit`. + A tool that allows the model to execute shell commands in a local environment. - - `"explicit"` + - `class BetaFunctionShellTool: …` - - `class BetaResponseInputImageContent: …` + A tool that allows the model to execute shell commands. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `class BetaCustomTool: …` - - `type: Literal["input_image"]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The type of the input item. Always `input_image`. + - `class BetaNamespaceTool: …` - - `"input_image"` + Groups function/custom tools under a shared namespace. - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + - `class BetaToolSearchTool: …` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Hosted or BYOT tool search configuration for deferred tools. - - `"low"` + - `class BetaWebSearchPreviewTool: …` - - `"high"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"auto"` + - `class BetaApplyPatchTool: …` - - `"original"` + Allows the assistant to create, delete, or update files using unified diffs. - - `file_id: Optional[str]` + - `type: Literal["additional_tools"]` - The ID of the file to be sent to the model. + The type of the item. Always `additional_tools`. - - `image_url: Optional[str]` + - `"additional_tools"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `agent: Optional[AdditionalToolsAgent]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The agent that produced this item. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `agent_name: str` - - `mode: Literal["explicit"]` + The canonical name of the agent that produced this item. - The breakpoint mode. Always `explicit`. + - `class BetaResponseCompactionItem: …` - - `"explicit"` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `class BetaResponseInputFileContent: …` + - `id: str` - A file input to the model. + The unique ID of the compaction item. - - `type: Literal["input_file"]` + - `encrypted_content: str` - The type of the input item. Always `input_file`. + The encrypted content that was produced by compaction. - - `"input_file"` + - `type: Literal["compaction"]` - - `detail: Optional[Literal["auto", "low", "high"]]` + The type of the item. Always `compaction`. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"compaction"` - - `"auto"` + - `agent: Optional[Agent]` - - `"low"` + The agent that produced this item. - - `"high"` + - `agent_name: str` - - `file_data: Optional[str]` + The canonical name of the agent that produced this item. - The base64-encoded data of the file to be sent to the model. + - `created_by: Optional[str]` - - `file_id: Optional[str]` + The identifier of the actor that created the item. - The ID of the file to be sent to the model. + - `class ImageGenerationCall: …` - - `file_url: Optional[str]` + An image generation request made by the model. - The URL of the file to be sent to the model. + - `id: str` - - `filename: Optional[str]` + The unique ID of the image generation call. - The name of the file to be sent to the model. + - `result: Optional[str]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The generated image encoded in base64. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `status: Literal["in_progress", "completed", "generating", "failed"]` - - `mode: Literal["explicit"]` + The status of the image generation call. - The breakpoint mode. Always `explicit`. + - `"in_progress"` - - `"explicit"` + - `"completed"` - - `type: Literal["function_call_output"]` + - `"generating"` - The type of the function tool call output. Always `function_call_output`. + - `"failed"` - - `"function_call_output"` + - `type: Literal["image_generation_call"]` - - `id: Optional[str]` + The type of the image generation call. Always `image_generation_call`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"image_generation_call"` - - `agent: Optional[FunctionCallOutputAgent]` + - `agent: Optional[ImageGenerationCallAgent]` The agent that produced this item. @@ -21688,133 +32591,142 @@ Create a model response The canonical name of the agent that produced this item. - - `caller: Optional[FunctionCallOutputCaller]` + - `class BetaResponseCodeInterpreterToolCall: …` - The execution context that produced this tool call. + A tool call to run code. - - `class FunctionCallOutputCallerDirect: …` + - `id: str` - - `type: Literal["direct"]` + The unique ID of the code interpreter tool call. - The caller type. Always `direct`. + - `code: Optional[str]` - - `"direct"` + The code to run, or null if not available. - - `class FunctionCallOutputCallerProgram: …` + - `container_id: str` - - `caller_id: str` + The ID of the container used to run the code. - The call ID of the program item that produced this tool call. + - `outputs: Optional[List[Output]]` - - `type: Literal["program"]` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The caller type. Always `program`. + - `class OutputLogs: …` - - `"program"` + The logs output from the code interpreter. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `logs: str` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The logs output from the code interpreter. - - `"in_progress"` + - `type: Literal["logs"]` - - `"completed"` + The type of the output. Always `logs`. - - `"incomplete"` + - `"logs"` - - `class AgentMessage: …` + - `class OutputImage: …` - A message routed between agents. + The image output from the code interpreter. - - `author: str` + - `type: Literal["image"]` - The sending agent identity. + The type of the output. Always `image`. - - `content: List[AgentMessageContent]` + - `"image"` - Plaintext, image, or encrypted content sent between agents. + - `url: str` - - `class BetaResponseInputTextContent: …` + The URL of the image output from the code interpreter. - A text input to the model. + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - - `class BetaResponseInputImageContent: …` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"in_progress"` - - `class AgentMessageContentEncryptedContent: …` + - `"completed"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"incomplete"` - - `encrypted_content: str` + - `"interpreting"` - Opaque encrypted content. + - `"failed"` - - `type: Literal["encrypted_content"]` + - `type: Literal["code_interpreter_call"]` - The type of the input item. Always `encrypted_content`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"encrypted_content"` + - `"code_interpreter_call"` - - `recipient: str` + - `agent: Optional[Agent]` - The destination agent identity. + The agent that produced this item. - - `type: Literal["agent_message"]` + - `agent_name: str` - The item type. Always `agent_message`. + The canonical name of the agent that produced this item. - - `"agent_message"` + - `class LocalShellCall: …` - - `id: Optional[str]` + A tool call to run a command on the local shell. - The unique ID of this agent message item. + - `id: str` - - `agent: Optional[AgentMessageAgent]` + The unique ID of the local shell call. - The agent that produced this item. + - `action: LocalShellCallAction` - - `agent_name: str` + Execute a shell command on the server. - The canonical name of the agent that produced this item. + - `command: List[str]` - - `class MultiAgentCall: …` + The command to run. - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `env: Dict[str, str]` - The multi-agent action that was executed. + Environment variables to set for the command. - - `"spawn_agent"` + - `type: Literal["exec"]` - - `"interrupt_agent"` + The type of the local shell action. Always `exec`. - - `"list_agents"` + - `"exec"` - - `"send_message"` + - `timeout_ms: Optional[int]` - - `"followup_task"` + Optional timeout in milliseconds for the command. - - `"wait_agent"` + - `user: Optional[str]` - - `arguments: str` + Optional user to run the command as. - The action arguments as a JSON string. + - `working_directory: Optional[str]` + + Optional working directory to run the command in. - `call_id: str` - The unique ID linking this call to its output. + The unique ID of the local shell tool call generated by the model. - - `type: Literal["multi_agent_call"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The item type. Always `multi_agent_call`. + The status of the local shell call. - - `"multi_agent_call"` + - `"in_progress"` - - `id: Optional[str]` + - `"completed"` - The unique ID of this multi-agent call. + - `"incomplete"` - - `agent: Optional[MultiAgentCallAgent]` + - `type: Literal["local_shell_call"]` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `agent: Optional[LocalShellCallAgent]` The agent that produced this item. @@ -21822,1307 +32734,1401 @@ Create a model response The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput: …` - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `class LocalShellCallOutput: …` - The multi-agent action that produced this result. + The output of a local shell tool call. - - `"spawn_agent"` + - `id: str` - - `"interrupt_agent"` + The unique ID of the local shell tool call generated by the model. - - `"list_agents"` + - `output: str` - - `"send_message"` + A JSON string of the output of the local shell tool call. - - `"followup_task"` + - `type: Literal["local_shell_call_output"]` - - `"wait_agent"` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `call_id: str` + - `"local_shell_call_output"` - The unique ID of the multi-agent call. + - `agent: Optional[LocalShellCallOutputAgent]` - - `output: List[MultiAgentCallOutputOutput]` + The agent that produced this item. - Text output returned by the multi-agent action. + - `agent_name: str` - - `text: str` + The canonical name of the agent that produced this item. - The text content. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `type: Literal["output_text"]` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The content type. Always `output_text`. + - `"in_progress"` - - `"output_text"` + - `"completed"` - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + - `"incomplete"` - Citations associated with the text content. + - `class BetaResponseFunctionShellToolCall: …` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + A tool call that executes one or more shell commands in a managed environment. - - `file_id: str` + - `id: str` - The ID of the file. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `filename: str` + - `action: Action` - The filename of the file cited. + The shell commands and limits that describe how to run the tool call. - - `index: int` + - `commands: List[str]` - The index of the file in the list of files. + - `max_output_length: Optional[int]` - - `type: Literal["file_citation"]` + Optional maximum number of characters to return from each command. - The citation type. Always `file_citation`. + - `timeout_ms: Optional[int]` - - `"file_citation"` + Optional timeout in milliseconds for the commands. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + - `call_id: str` - - `end_index: int` + The unique ID of the shell tool call generated by the model. - The index of the last character of the citation in the message. + - `environment: Optional[Environment]` - - `start_index: int` + Represents the use of a local environment to perform shell actions. - The index of the first character of the citation in the message. + - `class BetaResponseLocalEnvironment: …` - - `title: str` + Represents the use of a local environment to perform shell actions. - The title of the cited resource. + - `type: Literal["local"]` - - `type: Literal["url_citation"]` + The environment type. Always `local`. - The citation type. Always `url_citation`. + - `"local"` - - `"url_citation"` + - `class BetaResponseContainerReference: …` - - `url: str` + Represents a container created with /v1/containers. - The URL of the cited resource. + - `container_id: str` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `type: Literal["container_reference"]` - - `container_id: str` + The environment type. Always `container_reference`. - The ID of the container. + - `"container_reference"` - - `end_index: int` + - `status: Literal["in_progress", "completed", "incomplete"]` - The index of the last character of the citation in the message. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `file_id: str` + - `"in_progress"` - The ID of the container file. + - `"completed"` - - `filename: str` + - `"incomplete"` - The filename of the container file cited. + - `type: Literal["shell_call"]` - - `start_index: int` + The type of the item. Always `shell_call`. - The index of the first character of the citation in the message. + - `"shell_call"` - - `type: Literal["container_file_citation"]` + - `agent: Optional[Agent]` - The citation type. Always `container_file_citation`. + The agent that produced this item. - - `"container_file_citation"` + - `agent_name: str` - - `type: Literal["multi_agent_call_output"]` + The canonical name of the agent that produced this item. - The item type. Always `multi_agent_call_output`. + - `caller: Optional[Caller]` - - `"multi_agent_call_output"` + The execution context that produced this tool call. - - `id: Optional[str]` + - `class CallerDirect: …` - The unique ID of this multi-agent call output. + - `type: Literal["direct"]` - - `agent: Optional[MultiAgentCallOutputAgent]` + - `"direct"` - The agent that produced this item. + - `class CallerProgram: …` - - `agent_name: str` + - `caller_id: str` - The canonical name of the agent that produced this item. + The call ID of the program item that produced this tool call. - - `class ToolSearchCall: …` + - `type: Literal["program"]` - - `arguments: object` + - `"program"` - The arguments supplied to the tool search call. + - `created_by: Optional[str]` - - `type: Literal["tool_search_call"]` + The ID of the entity that created this tool call. - The item type. Always `tool_search_call`. + - `class BetaResponseFunctionShellToolCallOutput: …` - - `"tool_search_call"` + The output of a shell tool call that was emitted. - - `id: Optional[str]` + - `id: str` - The unique ID of this tool search call. + The unique ID of the shell call output. Populated when this item is returned via API. - - `agent: Optional[ToolSearchCallAgent]` + - `call_id: str` - The agent that produced this item. + The unique ID of the shell tool call generated by the model. - - `agent_name: str` + - `max_output_length: Optional[int]` - The canonical name of the agent that produced this item. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `call_id: Optional[str]` + - `output: List[Output]` - The unique ID of the tool search call generated by the model. + An array of shell call output contents - - `execution: Optional[Literal["server", "client"]]` + - `outcome: OutputOutcome` - Whether tool search was executed by the server or by the client. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `"server"` + - `class OutputOutcomeTimeout: …` - - `"client"` + Indicates that the shell call exceeded its configured time limit. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `type: Literal["timeout"]` - The status of the tool search call. + The outcome type. Always `timeout`. - - `"in_progress"` + - `"timeout"` - - `"completed"` + - `class OutputOutcomeExit: …` - - `"incomplete"` + Indicates that the shell commands finished and returned an exit code. - - `class BetaResponseToolSearchOutputItemParam: …` + - `exit_code: int` - - `tools: List[BetaTool]` + Exit code from the shell process. - The loaded tool definitions returned by the tool search output. + - `type: Literal["exit"]` - - `class BetaFunctionTool: …` + The outcome type. Always `exit`. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `"exit"` - - `name: str` + - `stderr: str` - The name of the function to call. + The standard error output that was captured. - - `parameters: Optional[Dict[str, object]]` + - `stdout: str` - A JSON schema object describing the parameters of the function. + The standard output that was captured. - - `strict: Optional[bool]` + - `created_by: Optional[str]` - Whether strict parameter validation is enforced for this function tool. + The identifier of the actor that created the item. - - `type: Literal["function"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The type of the function tool. Always `function`. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `"function"` + - `"in_progress"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"completed"` - The tool invocation context(s). + - `"incomplete"` - - `"direct"` + - `type: Literal["shell_call_output"]` - - `"programmatic"` + The type of the shell call output. Always `shell_call_output`. - - `defer_loading: Optional[bool]` + - `"shell_call_output"` - Whether this function is deferred and loaded via tool search. + - `agent: Optional[Agent]` - - `description: Optional[str]` + The agent that produced this item. - A description of the function. Used by the model to determine whether or not to call the function. + - `agent_name: str` - - `output_schema: Optional[Dict[str, object]]` + The canonical name of the agent that produced this item. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `caller: Optional[Caller]` - - `class BetaFileSearchTool: …` + The execution context that produced this tool call. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `class CallerDirect: …` - - `type: Literal["file_search"]` + - `type: Literal["direct"]` - The type of the file search tool. Always `file_search`. + - `"direct"` - - `"file_search"` + - `class CallerProgram: …` - - `vector_store_ids: List[str]` + - `caller_id: str` - The IDs of the vector stores to search. + The call ID of the program item that produced this tool call. - - `filters: Optional[Filters]` + - `type: Literal["program"]` - A filter to apply. + - `"program"` - - `class FiltersComparisonFilter: …` + - `created_by: Optional[str]` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The identifier of the actor that created the item. - - `key: str` + - `class BetaResponseApplyPatchToolCall: …` - The key to compare against the value. + A tool call that applies file diffs by creating, deleting, or updating files. - - `type: Literal["eq", "ne", "gt", 5 more]` + - `id: str` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `call_id: str` - - `"eq"` + The unique ID of the apply patch tool call generated by the model. - - `"ne"` + - `operation: Operation` - - `"gt"` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `"gte"` + - `class OperationCreateFile: …` - - `"lt"` + Instruction describing how to create a file via the apply_patch tool. - - `"lte"` + - `diff: str` - - `"in"` + Diff to apply. - - `"nin"` + - `path: str` - - `value: Union[str, float, bool, List[object]]` + Path of the file to create. - The value to compare against the attribute key; supports string, number, or boolean types. + - `type: Literal["create_file"]` - - `str` + Create a new file with the provided diff. - - `float` + - `"create_file"` - - `bool` + - `class OperationDeleteFile: …` - - `List[object]` + Instruction describing how to delete a file via the apply_patch tool. - - `class FiltersCompoundFilter: …` + - `path: str` - Combine multiple filters using `and` or `or`. + Path of the file to delete. - - `filters: List[FiltersCompoundFilterFilter]` + - `type: Literal["delete_file"]` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Delete the specified file. - - `class FiltersCompoundFilterFilterComparisonFilter: …` + - `"delete_file"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `class OperationUpdateFile: …` - - `key: str` + Instruction describing how to update a file via the apply_patch tool. - The key to compare against the value. + - `diff: str` - - `type: Literal["eq", "ne", "gt", 5 more]` + Diff to apply. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `path: str` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + Path of the file to update. - - `"eq"` + - `type: Literal["update_file"]` - - `"ne"` + Update an existing file with the provided diff. - - `"gt"` + - `"update_file"` - - `"gte"` + - `status: Literal["in_progress", "completed"]` - - `"lt"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"lte"` + - `"in_progress"` - - `"in"` + - `"completed"` - - `"nin"` + - `type: Literal["apply_patch_call"]` - - `value: Union[str, float, bool, List[object]]` + The type of the item. Always `apply_patch_call`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `"apply_patch_call"` - - `str` + - `agent: Optional[Agent]` - - `float` + The agent that produced this item. - - `bool` + - `agent_name: str` - - `List[object]` + The canonical name of the agent that produced this item. - - `object` + - `caller: Optional[Caller]` - - `type: Literal["and", "or"]` + The execution context that produced this tool call. - Type of operation: `and` or `or`. + - `class CallerDirect: …` - - `"and"` + - `type: Literal["direct"]` - - `"or"` + - `"direct"` - - `max_num_results: Optional[int]` + - `class CallerProgram: …` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `caller_id: str` - - `ranking_options: Optional[RankingOptions]` + The call ID of the program item that produced this tool call. - Ranking options for search. + - `type: Literal["program"]` - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + - `"program"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `created_by: Optional[str]` - - `embedding_weight: float` + The ID of the entity that created this tool call. - The weight of the embedding in the reciprocal ranking fusion. + - `class BetaResponseApplyPatchToolCallOutput: …` - - `text_weight: float` + The output emitted by an apply patch tool call. - The weight of the text in the reciprocal ranking fusion. + - `id: str` - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The ranker to use for the file search. + - `call_id: str` - - `"auto"` + The unique ID of the apply patch tool call generated by the model. - - `"default-2024-11-15"` + - `status: Literal["completed", "failed"]` - - `score_threshold: Optional[float]` + The status of the apply patch tool call output. One of `completed` or `failed`. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `"completed"` - - `class BetaComputerTool: …` + - `"failed"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: Literal["apply_patch_call_output"]` - - `type: Literal["computer"]` + The type of the item. Always `apply_patch_call_output`. - The type of the computer tool. Always `computer`. + - `"apply_patch_call_output"` - - `"computer"` + - `agent: Optional[Agent]` - - `class BetaComputerUsePreviewTool: …` + The agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent_name: str` - - `display_height: int` + The canonical name of the agent that produced this item. - The height of the computer display. + - `caller: Optional[Caller]` - - `display_width: int` + The execution context that produced this tool call. - The width of the computer display. + - `class CallerDirect: …` - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `type: Literal["direct"]` - The type of computer environment to control. + - `"direct"` - - `"windows"` + - `class CallerProgram: …` - - `"mac"` + - `caller_id: str` - - `"linux"` + The call ID of the program item that produced this tool call. - - `"ubuntu"` + - `type: Literal["program"]` - - `"browser"` + - `"program"` - - `type: Literal["computer_use_preview"]` + - `created_by: Optional[str]` - The type of the computer use tool. Always `computer_use_preview`. + The ID of the entity that created this tool call output. - - `"computer_use_preview"` + - `output: Optional[str]` - - `class BetaWebSearchTool: …` + Optional textual output returned by the apply patch tool. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class McpCall: …` - - `type: Literal["web_search", "web_search_2025_08_26"]` + An invocation of a tool on an MCP server. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `id: str` - - `"web_search"` + The unique ID of the tool call. - - `"web_search_2025_08_26"` + - `arguments: str` - - `filters: Optional[Filters]` + A JSON string of the arguments passed to the tool. - Filters for the search. + - `name: str` - - `allowed_domains: Optional[List[str]]` + The name of the tool that was run. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `server_label: str` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The label of the MCP server running the tool. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `type: Literal["mcp_call"]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of the item. Always `mcp_call`. - - `"low"` + - `"mcp_call"` - - `"medium"` + - `agent: Optional[McpCallAgent]` - - `"high"` + The agent that produced this item. - - `user_location: Optional[UserLocation]` + - `agent_name: str` - The approximate location of the user. + The canonical name of the agent that produced this item. - - `city: Optional[str]` + - `approval_request_id: Optional[str]` - Free text input for the city of the user, e.g. `San Francisco`. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `country: Optional[str]` + - `error: Optional[str]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The error from the tool call, if any. - - `region: Optional[str]` + - `output: Optional[str]` - Free text input for the region of the user, e.g. `California`. + The output from the tool call. - - `timezone: Optional[str]` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `type: Optional[Literal["approximate"]]` + - `"in_progress"` - The type of location approximation. Always `approximate`. + - `"completed"` - - `"approximate"` + - `"incomplete"` - - `class Mcp: …` + - `"calling"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"failed"` - - `server_label: str` + - `class McpListTools: …` - A label for this MCP server, used to identify it in tool calls. + A list of tools available on an MCP server. - - `type: Literal["mcp"]` + - `id: str` - The type of the MCP tool. Always `mcp`. + The unique ID of the list. - - `"mcp"` + - `server_label: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The label of the MCP server. - The tool invocation context(s). + - `tools: List[McpListToolsTool]` - - `"direct"` + The tools available on the server. - - `"programmatic"` + - `input_schema: object` - - `allowed_tools: Optional[McpAllowedTools]` + The JSON schema describing the tool's input. - List of allowed tool names or a filter object. + - `name: str` - - `List[str]` + The name of the tool. - A string array of allowed tool names + - `annotations: Optional[object]` - - `class McpAllowedToolsMcpToolFilter: …` + Additional annotations about the tool. - A filter object to specify which tools are allowed. + - `description: Optional[str]` - - `read_only: Optional[bool]` + The description of the tool. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `type: Literal["mcp_list_tools"]` - - `tool_names: Optional[List[str]]` + The type of the item. Always `mcp_list_tools`. - List of allowed tool names. + - `"mcp_list_tools"` - - `authorization: Optional[str]` + - `agent: Optional[McpListToolsAgent]` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The agent that produced this item. - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + - `agent_name: str` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The canonical name of the agent that produced this item. - Currently supported `connector_id` values are: + - `error: Optional[str]` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + Error message if the server could not list tools. - - `"connector_dropbox"` + - `class McpApprovalRequest: …` - - `"connector_gmail"` + A request for human approval of a tool invocation. - - `"connector_googlecalendar"` + - `id: str` - - `"connector_googledrive"` + The unique ID of the approval request. - - `"connector_microsoftteams"` + - `arguments: str` - - `"connector_outlookcalendar"` + A JSON string of arguments for the tool. - - `"connector_outlookemail"` + - `name: str` - - `"connector_sharepoint"` + The name of the tool to run. - - `defer_loading: Optional[bool]` + - `server_label: str` - Whether this MCP tool is deferred and discovered via tool search. + The label of the MCP server making the request. - - `headers: Optional[Dict[str, str]]` + - `type: Literal["mcp_approval_request"]` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The type of the item. Always `mcp_approval_request`. - - `require_approval: Optional[McpRequireApproval]` + - `"mcp_approval_request"` - Specify which of the MCP server's tools require approval. + - `agent: Optional[McpApprovalRequestAgent]` - - `class McpRequireApprovalMcpToolApprovalFilter: …` + The agent that produced this item. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `agent_name: str` - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + The canonical name of the agent that produced this item. - A filter object to specify which tools are allowed. + - `class McpApprovalResponse: …` - - `read_only: Optional[bool]` + A response to an MCP approval request. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `id: str` - - `tool_names: Optional[List[str]]` + The unique ID of the approval response - List of allowed tool names. + - `approval_request_id: str` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + The ID of the approval request being answered. - A filter object to specify which tools are allowed. + - `approve: bool` - - `read_only: Optional[bool]` + Whether the request was approved. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `type: Literal["mcp_approval_response"]` - - `tool_names: Optional[List[str]]` + The type of the item. Always `mcp_approval_response`. - List of allowed tool names. + - `"mcp_approval_response"` - - `Literal["always", "never"]` + - `agent: Optional[McpApprovalResponseAgent]` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The agent that produced this item. - - `"always"` + - `agent_name: str` - - `"never"` + The canonical name of the agent that produced this item. - - `server_description: Optional[str]` + - `reason: Optional[str]` - Optional description of the MCP server, used to provide more context. + Optional reason for the decision. - - `server_url: Optional[str]` + - `class BetaResponseCustomToolCall: …` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + A call to a custom tool created by the model. - - `tunnel_id: Optional[str]` + - `call_id: str` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + An identifier used to map this custom tool call to a tool call output. - - `class CodeInterpreter: …` + - `input: str` - A tool that runs Python code to help generate a response to a prompt. + The input for the custom tool call generated by the model. - - `container: CodeInterpreterContainer` + - `name: str` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The name of the custom tool being called. - - `str` + - `type: Literal["custom_tool_call"]` - The container ID. + The type of the custom tool call. Always `custom_tool_call`. - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `"custom_tool_call"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `id: Optional[str]` - - `type: Literal["auto"]` + The unique ID of the custom tool call in the OpenAI platform. - Always `auto`. + - `agent: Optional[Agent]` - - `"auto"` + The agent that produced this item. - - `file_ids: Optional[List[str]]` + - `agent_name: str` - An optional list of uploaded files to make available to your code. + The canonical name of the agent that produced this item. - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `caller: Optional[Caller]` - The memory limit for the code interpreter container. + The execution context that produced this tool call. - - `"1g"` + - `class CallerDirect: …` - - `"4g"` + - `type: Literal["direct"]` - - `"16g"` + - `"direct"` - - `"64g"` + - `class CallerProgram: …` - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `caller_id: str` - Network access policy for the container. + The call ID of the program item that produced this tool call. - - `class BetaContainerNetworkPolicyDisabled: …` + - `type: Literal["program"]` - - `type: Literal["disabled"]` + - `"program"` - Disable outbound network access. Always `disabled`. + - `namespace: Optional[str]` - - `"disabled"` + The namespace of the custom tool being called. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `class BetaResponseCustomToolCallOutputItem: …` - - `allowed_domains: List[str]` + The output of a custom tool call from your code, being sent back to the model. - A list of allowed domains when type is `allowlist`. + - `id: str` - - `type: Literal["allowlist"]` + The unique ID of the custom tool call output item. - Allow outbound network access only to specified domains. Always `allowlist`. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"allowlist"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `"in_progress"` - Optional domain-scoped secrets for allowlisted domains. + - `"completed"` - - `domain: str` + - `"incomplete"` - The domain associated with the secret. + - `created_by: Optional[str]` - - `name: str` + The identifier of the actor that created the item. - The name of the secret to inject for the domain. + - `usage: BetaResponseUsage` - - `value: str` + Token accounting for the compaction pass, including cached, reasoning, and total tokens. - The secret value to inject for the domain. + - `input_tokens: int` - - `type: Literal["code_interpreter"]` + The number of input tokens. - The type of the code interpreter tool. Always `code_interpreter`. + - `input_tokens_details: InputTokensDetails` - - `"code_interpreter"` + A detailed breakdown of the input tokens. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `cache_write_tokens: int` - The tool invocation context(s). + The number of input tokens that were written to the cache. - - `"direct"` + - `cached_tokens: int` - - `"programmatic"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `class ProgrammaticToolCalling: …` + - `output_tokens: int` - - `type: Literal["programmatic_tool_calling"]` + The number of output tokens. - The type of the tool. Always `programmatic_tool_calling`. + - `output_tokens_details: OutputTokensDetails` - - `"programmatic_tool_calling"` + A detailed breakdown of the output tokens. - - `class ImageGeneration: …` + - `reasoning_tokens: int` - A tool that generates images using the GPT image models. + The number of reasoning tokens. - - `type: Literal["image_generation"]` + - `total_tokens: int` - The type of the image generation tool. Always `image_generation`. + The total number of tokens used. - - `"image_generation"` +### Example - - `action: Optional[Literal["generate", "edit", "auto"]]` +```python +import os +from openai import OpenAI - Whether to generate a new image or edit an existing image. Default: `auto`. +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +beta_compacted_response = client.beta.responses.compact( + model="gpt-5.6-sol", +) +print(beta_compacted_response.id) +``` - - `"generate"` +#### Response - - `"edit"` +```json +{ + "id": "id", + "created_at": 0, + "object": "response.compaction", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "text": "text", + "type": "output_text", + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ] + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "phase": "commentary" + } + ], + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "cache_write_tokens": 0, + "cached_tokens": 0 + }, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + } +} +``` - - `"auto"` +### Example - - `background: Optional[Literal["transparent", "opaque", "auto"]]` +```python +from openai import OpenAI - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. +client = OpenAI() - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. +compacted_response = client.responses.compact( + model="gpt-5.1-codex-max", + input=[ + { + "role": "user", + "content": "Create a simple landing page for a dog petting cafe.", + }, + # All items returned from previous requests are included here, like reasoning, message, function call, etc. + { + "id": "msg_001", + "type": "message", + "status": "completed", + "content": [ + { + "type": "output_text", + "annotations": [], + "logprobs": [], + "text": "Below is a single file, ready-to-use landing page for a dog petting café:...", + }, + ], + "role": "assistant", + }, + ] +) +# Pass the compacted_response.output as input to the next request +print(compacted_response) +``` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. +#### Response - - `"transparent"` +```json +{ + "id": "resp_001", + "object": "response.compaction", + "created_at": 1764967971, + "output": [ + { + "id": "msg_000", + "type": "message", + "status": "completed", + "content": [ + { + "type": "input_text", + "text": "Create a simple landing page for a dog petting cafe." + } + ], + "role": "user" + }, + { + "id": "cmp_001", + "type": "compaction", + "encrypted_content": "gAAAAABpM0Yj-...=" + } + ], + "usage": { + "input_tokens": 139, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 438, + "output_tokens_details": { + "reasoning_tokens": 64 + }, + "total_tokens": 577 + } +} +``` - - `"opaque"` +## Domain Types - - `"auto"` +### Beta Apply Patch Tool - - `input_fidelity: Optional[Literal["high", "low"]]` +- `class BetaApplyPatchTool: …` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + Allows the assistant to create, delete, or update files using unified diffs. - - `"high"` + - `type: Literal["apply_patch"]` - - `"low"` + The type of the tool. Always `apply_patch`. - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + - `"apply_patch"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `file_id: Optional[str]` + The tool invocation context(s). - File ID for the mask image. + - `"direct"` - - `image_url: Optional[str]` + - `"programmatic"` - Base64-encoded mask image. +### Beta Compacted Response - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` +- `class BetaCompactedResponse: …` - The image generation model to use. Default: `gpt-image-1`. + - `id: str` - - `str` + The unique identifier for the compacted response. - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `created_at: int` - The image generation model to use. Default: `gpt-image-1`. + Unix timestamp (in seconds) when the compacted conversation was created. - - `"gpt-image-1"` + - `object: Literal["response.compaction"]` - - `"gpt-image-1-mini"` + The object type. Always `response.compaction`. - - `"gpt-image-2"` + - `"response.compaction"` - - `"gpt-image-2-2026-04-21"` + - `output: List[BetaResponseOutputItem]` - - `"gpt-image-1.5"` + The compacted list of output items. This is a list of all user messages, followed by a single compaction item. - - `"chatgpt-image-latest"` + - `class BetaResponseOutputMessage: …` - - `moderation: Optional[Literal["auto", "low"]]` + An output message from the model. - Moderation level for the generated image. Default: `auto`. + - `id: str` - - `"auto"` + The unique ID of the output message. - - `"low"` + - `content: List[Content]` - - `output_compression: Optional[int]` + The content of the output message. - Compression level for the output image. Default: 100. + - `class BetaResponseOutputText: …` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + A text output from the model. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `annotations: List[Annotation]` - - `"png"` + The annotations of the text output. - - `"webp"` + - `class AnnotationFileCitation: …` - - `"jpeg"` + A citation to a file. - - `partial_images: Optional[int]` + - `file_id: str` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The ID of the file. - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + - `filename: str` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The filename of the file cited. - - `"low"` + - `index: int` - - `"medium"` + The index of the file in the list of files. - - `"high"` + - `type: Literal["file_citation"]` - - `"auto"` + The type of the file citation. Always `file_citation`. - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + - `"file_citation"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `class AnnotationURLCitation: …` - - `str` + A citation for a web resource used to generate a model response. - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `end_index: int` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The index of the last character of the URL citation in the message. - - `"1024x1024"` + - `start_index: int` - - `"1024x1536"` + The index of the first character of the URL citation in the message. - - `"1536x1024"` + - `title: str` - - `"auto"` + The title of the web resource. - - `class LocalShell: …` + - `type: Literal["url_citation"]` - A tool that allows the model to execute shell commands in a local environment. + The type of the URL citation. Always `url_citation`. - - `type: Literal["local_shell"]` + - `"url_citation"` - The type of the local shell tool. Always `local_shell`. + - `url: str` - - `"local_shell"` + The URL of the web resource. - - `class BetaFunctionShellTool: …` + - `class AnnotationContainerFileCitation: …` - A tool that allows the model to execute shell commands. + A citation for a container file used to generate a model response. - - `type: Literal["shell"]` + - `container_id: str` - The type of the shell tool. Always `shell`. + The ID of the container file. - - `"shell"` + - `end_index: int` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The index of the last character of the container file citation in the message. - The tool invocation context(s). + - `file_id: str` - - `"direct"` + The ID of the file. - - `"programmatic"` + - `filename: str` - - `environment: Optional[Environment]` + The filename of the container file cited. - - `class BetaContainerAuto: …` + - `start_index: int` - - `type: Literal["container_auto"]` + The index of the first character of the container file citation in the message. - Automatically creates a container for this request + - `type: Literal["container_file_citation"]` - - `"container_auto"` + The type of the container file citation. Always `container_file_citation`. - - `file_ids: Optional[List[str]]` + - `"container_file_citation"` - An optional list of uploaded files to make available to your code. + - `class AnnotationFilePath: …` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + A path to a file. - The memory limit for the container. + - `file_id: str` - - `"1g"` + The ID of the file. - - `"4g"` + - `index: int` - - `"16g"` + The index of the file in the list of files. - - `"64g"` + - `type: Literal["file_path"]` - - `network_policy: Optional[NetworkPolicy]` + The type of the file path. Always `file_path`. - Network access policy for the container. + - `"file_path"` - - `class BetaContainerNetworkPolicyDisabled: …` + - `text: str` - - `class BetaContainerNetworkPolicyAllowlist: …` + The text output from the model. - - `skills: Optional[List[Skill]]` + - `type: Literal["output_text"]` - An optional list of skills referenced by id or inline data. + The type of the output text. Always `output_text`. - - `class BetaSkillReference: …` + - `"output_text"` - - `skill_id: str` + - `logprobs: Optional[List[Logprob]]` - The ID of the referenced skill. + - `token: str` - - `type: Literal["skill_reference"]` + - `bytes: List[int]` - References a skill created with the /v1/skills endpoint. + - `logprob: float` - - `"skill_reference"` + - `top_logprobs: List[LogprobTopLogprob]` - - `version: Optional[str]` + - `token: str` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `bytes: List[int]` - - `class BetaInlineSkill: …` + - `logprob: float` - - `description: str` + - `class BetaResponseOutputRefusal: …` - The description of the skill. + A refusal from the model. - - `name: str` + - `refusal: str` - The name of the skill. + The refusal explanation from the model. - - `source: BetaInlineSkillSource` + - `type: Literal["refusal"]` - Inline skill payload + The type of the refusal. Always `refusal`. - - `data: str` + - `"refusal"` - Base64-encoded skill zip bundle. + - `role: Literal["assistant"]` - - `media_type: Literal["application/zip"]` + The role of the output message. Always `assistant`. - The media type of the inline skill payload. Must be `application/zip`. + - `"assistant"` - - `"application/zip"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["base64"]` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The type of the inline skill source. Must be `base64`. + - `"in_progress"` - - `"base64"` + - `"completed"` - - `type: Literal["inline"]` + - `"incomplete"` - Defines an inline skill for this request. + - `type: Literal["message"]` - - `"inline"` + The type of the output message. Always `message`. - - `class BetaLocalEnvironment: …` + - `"message"` - - `type: Literal["local"]` + - `agent: Optional[Agent]` - Use a local computer environment. + The agent that produced this item. - - `"local"` + - `agent_name: str` - - `skills: Optional[List[BetaLocalSkill]]` + The canonical name of the agent that produced this item. - An optional list of skills. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `description: str` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - The description of the skill. + - `"commentary"` - - `name: str` + - `"final_answer"` - The name of the skill. + - `class BetaResponseFileSearchToolCall: …` - - `path: str` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The path to the directory containing the skill. + - `id: str` - - `class BetaContainerReference: …` + The unique ID of the file search tool call. - - `container_id: str` + - `queries: List[str]` - The ID of the referenced container. + The queries used to search for files. - - `type: Literal["container_reference"]` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - References a container created with the /v1/containers endpoint + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"container_reference"` + - `"in_progress"` - - `class BetaCustomTool: …` + - `"searching"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"completed"` - - `name: str` + - `"incomplete"` - The name of the custom tool, used to identify it in tool calls. + - `"failed"` - - `type: Literal["custom"]` + - `type: Literal["file_search_call"]` - The type of the custom tool. Always `custom`. + The type of the file search tool call. Always `file_search_call`. - - `"custom"` + - `"file_search_call"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `agent: Optional[Agent]` - The tool invocation context(s). + The agent that produced this item. - - `"direct"` + - `agent_name: str` - - `"programmatic"` + The canonical name of the agent that produced this item. - - `defer_loading: Optional[bool]` + - `results: Optional[List[Result]]` - Whether this tool should be deferred and discovered via tool search. + The results of the file search tool call. - - `description: Optional[str]` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - Optional description of the custom tool, used to provide more context. + 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, booleans, or numbers. - - `format: Optional[Format]` + - `str` - The input format for the custom tool. Default is unconstrained text. + - `float` - - `class FormatText: …` + - `bool` - Unconstrained free-form text. + - `file_id: Optional[str]` - - `type: Literal["text"]` + The unique ID of the file. - Unconstrained text format. Always `text`. + - `filename: Optional[str]` - - `"text"` + The name of the file. - - `class FormatGrammar: …` + - `score: Optional[float]` - A grammar defined by the user. + The relevance score of the file - a value between 0 and 1. - - `definition: str` + - `text: Optional[str]` - The grammar definition. + The text that was retrieved from the file. - - `syntax: Literal["lark", "regex"]` + - `class BetaResponseFunctionToolCall: …` - The syntax of the grammar definition. One of `lark` or `regex`. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `"lark"` + - `arguments: str` - - `"regex"` + A JSON string of the arguments to pass to the function. - - `type: Literal["grammar"]` + - `call_id: str` - Grammar format. Always `grammar`. + The unique ID of the function tool call generated by the model. - - `"grammar"` + - `name: str` - - `class BetaNamespaceTool: …` + The name of the function to run. - Groups function/custom tools under a shared namespace. + - `type: Literal["function_call"]` - - `description: str` + The type of the function tool call. Always `function_call`. - A description of the namespace shown to the model. + - `"function_call"` - - `name: str` + - `id: Optional[str]` - The namespace name used in tool calls (for example, `crm`). + The unique ID of the function tool call. - - `tools: List[Tool]` + - `agent: Optional[Agent]` - The function/custom tools available inside this namespace. + The agent that produced this item. - - `class ToolFunction: …` + - `agent_name: str` - - `name: str` + The canonical name of the agent that produced this item. - - `type: Literal["function"]` + - `caller: Optional[Caller]` - - `"function"` + The execution context that produced this tool call. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `class CallerDirect: …` - The tool invocation context(s). + - `type: Literal["direct"]` - `"direct"` - - `"programmatic"` + - `class CallerProgram: …` - - `defer_loading: Optional[bool]` + - `caller_id: str` - Whether this function should be deferred and discovered via tool search. + The call ID of the program item that produced this tool call. - - `description: Optional[str]` + - `type: Literal["program"]` - - `output_schema: Optional[Dict[str, object]]` + - `"program"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `namespace: Optional[str]` - - `parameters: Optional[object]` + The namespace of the function to run. - - `strict: Optional[bool]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class BetaCustomTool: …` + - `"in_progress"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"completed"` - - `type: Literal["namespace"]` + - `"incomplete"` - The type of the tool. Always `namespace`. + - `class BetaResponseFunctionToolCallOutputItem: …` - - `"namespace"` + - `id: str` - - `class BetaToolSearchTool: …` + The unique ID of the function call tool output. - Hosted or BYOT tool search configuration for deferred tools. + - `call_id: str` - - `type: Literal["tool_search"]` + The unique ID of the function tool call generated by the model. - The type of the tool. Always `tool_search`. + - `output: Union[str, List[OutputOutputContentList]]` - - `"tool_search"` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `description: Optional[str]` + - `str` - Description shown to the model for a client-executed tool search tool. + A string of the output of the function call. - - `execution: Optional[Literal["server", "client"]]` + - `List[OutputOutputContentList]` - Whether tool search is executed by the server or by the client. + Text, image, or file output of the function call. - - `"server"` + - `class BetaResponseInputText: …` - - `"client"` + A text input to the model. - - `parameters: Optional[object]` + - `text: str` - Parameter schema for a client-executed tool search tool. + The text input to the model. - - `class BetaWebSearchPreviewTool: …` + - `type: Literal["input_text"]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The type of the input item. Always `input_text`. - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + - `"input_text"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"web_search_preview"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"web_search_preview_2025_03_11"` + - `mode: Literal["explicit"]` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + The breakpoint mode. Always `explicit`. - - `"text"` + - `"explicit"` - - `"image"` + - `class BetaResponseInputImage: …` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `detail: Literal["low", "high", "auto", "original"]` - - `"low"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"medium"` + - `"low"` - `"high"` - - `user_location: Optional[UserLocation]` + - `"auto"` - The user's location. + - `"original"` - - `type: Literal["approximate"]` + - `type: Literal["input_image"]` - The type of location approximation. Always `approximate`. + The type of the input item. Always `input_image`. - - `"approximate"` + - `"input_image"` - - `city: Optional[str]` + - `file_id: Optional[str]` - Free text input for the city of the user, e.g. `San Francisco`. + The ID of the file to be sent to the model. - - `country: Optional[str]` + - `image_url: Optional[str]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `region: Optional[str]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Free text input for the region of the user, e.g. `California`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `timezone: Optional[str]` + - `mode: Literal["explicit"]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The breakpoint mode. Always `explicit`. - - `class BetaApplyPatchTool: …` + - `"explicit"` - Allows the assistant to create, delete, or update files using unified diffs. + - `class BetaResponseInputFile: …` - - `type: Literal["apply_patch"]` + A file input to the model. - The type of the tool. Always `apply_patch`. + - `type: Literal["input_file"]` - - `"apply_patch"` + The type of the input item. Always `input_file`. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"input_file"` - The tool invocation context(s). + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"direct"` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `"programmatic"` + - `"auto"` - - `type: Literal["tool_search_output"]` + - `"low"` - The item type. Always `tool_search_output`. + - `"high"` - - `"tool_search_output"` + - `file_data: Optional[str]` - - `id: Optional[str]` + The content of the file to be sent to the model. - The unique ID of this tool search output. + - `file_id: Optional[str]` - - `agent: Optional[Agent]` + The ID of the file to be sent to the model. - The agent that produced this item. + - `file_url: Optional[str]` - - `agent_name: str` + The URL of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `filename: Optional[str]` - - `call_id: Optional[str]` + The name of the file to be sent to the model. - The unique ID of the tool search call generated by the model. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `execution: Optional[Literal["server", "client"]]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Whether tool search was executed by the server or by the client. + - `mode: Literal["explicit"]` - - `"server"` + The breakpoint mode. Always `explicit`. - - `"client"` + - `"explicit"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the tool search output. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -23130,188 +34136,185 @@ Create a model response - `"incomplete"` - - `class AdditionalTools: …` - - - `role: Literal["developer"]` + - `type: Literal["function_call_output"]` - The role that provided the additional tools. Only `developer` is supported. + The type of the function tool call output. Always `function_call_output`. - - `"developer"` + - `"function_call_output"` - - `tools: List[BetaTool]` + - `agent: Optional[Agent]` - A list of additional tools made available at this item. + The agent that produced this item. - - `class BetaFunctionTool: …` + - `agent_name: str` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The canonical name of the agent that produced this item. - - `class BetaFileSearchTool: …` + - `caller: Optional[Caller]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The execution context that produced this tool call. - - `class BetaComputerTool: …` + - `class CallerDirect: …` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: Literal["direct"]` - - `class BetaComputerUsePreviewTool: …` + The caller type. Always `direct`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"direct"` - - `class BetaWebSearchTool: …` + - `class CallerProgram: …` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `caller_id: str` - - `class Mcp: …` + The call ID of the program item that produced this tool call. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: Literal["program"]` - - `class CodeInterpreter: …` + The caller type. Always `program`. - A tool that runs Python code to help generate a response to a prompt. + - `"program"` - - `class ProgrammaticToolCalling: …` + - `created_by: Optional[str]` - - `class ImageGeneration: …` + The identifier of the actor that created the item. - A tool that generates images using the GPT image models. + - `class AgentMessage: …` - - `class LocalShell: …` + - `id: str` - A tool that allows the model to execute shell commands in a local environment. + The unique ID of the agent message. - - `class BetaFunctionShellTool: …` + - `author: str` - A tool that allows the model to execute shell commands. + The sending agent identity. - - `class BetaCustomTool: …` + - `content: List[AgentMessageContent]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + Encrypted content sent between agents. - - `class BetaNamespaceTool: …` + - `class BetaResponseInputText: …` - Groups function/custom tools under a shared namespace. + A text input to the model. - - `class BetaToolSearchTool: …` + - `class BetaResponseOutputText: …` - Hosted or BYOT tool search configuration for deferred tools. + A text output from the model. - - `class BetaWebSearchPreviewTool: …` + - `class AgentMessageContentText: …` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A text content. - - `class BetaApplyPatchTool: …` + - `text: str` - Allows the assistant to create, delete, or update files using unified diffs. + - `type: Literal["text"]` - - `type: Literal["additional_tools"]` + - `"text"` - The item type. Always `additional_tools`. + - `class AgentMessageContentSummaryText: …` - - `"additional_tools"` + A summary text from the model. - - `id: Optional[str]` + - `text: str` - The unique ID of this additional tools item. + A summary of the reasoning output from the model so far. - - `agent: Optional[AdditionalToolsAgent]` + - `type: Literal["summary_text"]` - The agent that produced this item. + The type of the object. Always `summary_text`. - - `agent_name: str` + - `"summary_text"` - The canonical name of the agent that produced this item. + - `class AgentMessageContentReasoningText: …` - - `class BetaResponseReasoningItem: …` + Reasoning text from the model. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `text: str` - - `id: str` + The reasoning text from the model. - The unique identifier of the reasoning content. + - `type: Literal["reasoning_text"]` - - `summary: List[Summary]` + The type of the reasoning text. Always `reasoning_text`. - Reasoning summary content. + - `"reasoning_text"` - - `text: str` + - `class BetaResponseOutputRefusal: …` - A summary of the reasoning output from the model so far. + A refusal from the model. - - `type: Literal["summary_text"]` + - `class BetaResponseInputImage: …` - The type of the object. Always `summary_text`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"summary_text"` + - `class AgentMessageContentComputerScreenshot: …` - - `type: Literal["reasoning"]` + A screenshot of a computer. - The type of the object. Always `reasoning`. + - `detail: Literal["low", "high", "auto", "original"]` - - `"reasoning"` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `agent: Optional[Agent]` + - `"low"` - The agent that produced this item. + - `"high"` - - `agent_name: str` + - `"auto"` - The canonical name of the agent that produced this item. + - `"original"` - - `content: Optional[List[Content]]` + - `file_id: Optional[str]` - Reasoning text content. + The identifier of an uploaded file that contains the screenshot. - - `text: str` + - `image_url: Optional[str]` - The reasoning text from the model. + The URL of the screenshot image. - - `type: Literal["reasoning_text"]` + - `type: Literal["computer_screenshot"]` - The type of the reasoning text. Always `reasoning_text`. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `"reasoning_text"` + - `"computer_screenshot"` - - `encrypted_content: Optional[str]` + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `mode: Literal["explicit"]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The breakpoint mode. Always `explicit`. - - `"in_progress"` + - `"explicit"` - - `"completed"` + - `class BetaResponseInputFile: …` - - `"incomplete"` + A file input to the model. - - `class BetaResponseCompactionItemParam: …` + - `class AgentMessageContentEncryptedContent: …` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Opaque encrypted content that Responses API decrypts inside trusted model execution. - `encrypted_content: str` - The encrypted content of the compaction summary. + Opaque encrypted content. - - `type: Literal["compaction"]` + - `type: Literal["encrypted_content"]` - The type of the item. Always `compaction`. + The type of the input item. Always `encrypted_content`. - - `"compaction"` + - `"encrypted_content"` - - `id: Optional[str]` + - `recipient: str` - The ID of the compaction item. + The destination agent identity. - - `agent: Optional[Agent]` + - `type: Literal["agent_message"]` + + The type of the item. Always `agent_message`. + + - `"agent_message"` + + - `agent: Optional[AgentMessageAgent]` The agent that produced this item. @@ -23319,206 +34322,205 @@ Create a model response The canonical name of the agent that produced this item. - - `class ImageGenerationCall: …` - - An image generation request made by the model. + - `class MultiAgentCall: …` - `id: str` - The unique ID of the image generation call. + The unique ID of the multi-agent call item. - - `result: Optional[str]` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - The generated image encoded in base64. + The multi-agent action to execute. - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `"spawn_agent"` - The status of the image generation call. + - `"interrupt_agent"` - - `"in_progress"` + - `"list_agents"` - - `"completed"` + - `"send_message"` - - `"generating"` + - `"followup_task"` - - `"failed"` + - `"wait_agent"` - - `type: Literal["image_generation_call"]` + - `arguments: str` - The type of the image generation call. Always `image_generation_call`. + The JSON string of arguments generated for the action. - - `"image_generation_call"` + - `call_id: str` - - `agent: Optional[ImageGenerationCallAgent]` + The unique ID linking this call to its output. - The agent that produced this item. + - `type: Literal["multi_agent_call"]` - - `agent_name: str` + The type of the multi-agent call. Always `multi_agent_call`. - The canonical name of the agent that produced this item. + - `"multi_agent_call"` - - `class BetaResponseCodeInterpreterToolCall: …` + - `agent: Optional[MultiAgentCallAgent]` - A tool call to run code. + The agent that produced this item. - - `id: str` + - `agent_name: str` - The unique ID of the code interpreter tool call. + The canonical name of the agent that produced this item. - - `code: Optional[str]` + - `class MultiAgentCallOutput: …` - The code to run, or null if not available. + - `id: str` - - `container_id: str` + The unique ID of the multi-agent call output item. - The ID of the container used to run the code. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `outputs: Optional[List[Output]]` + The multi-agent action that produced this result. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"spawn_agent"` - - `class OutputLogs: …` + - `"interrupt_agent"` - The logs output from the code interpreter. + - `"list_agents"` - - `logs: str` + - `"send_message"` - The logs output from the code interpreter. + - `"followup_task"` - - `type: Literal["logs"]` + - `"wait_agent"` - The type of the output. Always `logs`. + - `call_id: str` - - `"logs"` + The unique ID of the multi-agent call. - - `class OutputImage: …` + - `output: List[BetaResponseOutputText]` - The image output from the code interpreter. + Text output returned by the multi-agent action. - - `type: Literal["image"]` + - `annotations: List[Annotation]` - The type of the output. Always `image`. + The annotations of the text output. - - `"image"` + - `text: str` - - `url: str` + The text output from the model. - The URL of the image output from the code interpreter. + - `type: Literal["output_text"]` - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + The type of the output text. Always `output_text`. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `logprobs: Optional[List[Logprob]]` - - `"in_progress"` + - `type: Literal["multi_agent_call_output"]` - - `"completed"` + The type of the multi-agent result. Always `multi_agent_call_output`. - - `"incomplete"` + - `"multi_agent_call_output"` - - `"interpreting"` + - `agent: Optional[MultiAgentCallOutputAgent]` - - `"failed"` + The agent that produced this item. - - `type: Literal["code_interpreter_call"]` + - `agent_name: str` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The canonical name of the agent that produced this item. - - `"code_interpreter_call"` + - `class BetaResponseFunctionWebSearch: …` - - `agent: Optional[Agent]` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The agent that produced this item. + - `id: str` - - `agent_name: str` + The unique ID of the web search tool call. - The canonical name of the agent that produced this item. + - `action: Action` - - `class LocalShellCall: …` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - A tool call to run a command on the local shell. + - `class ActionSearch: …` - - `id: str` + Action type "search" - Performs a web search query. - The unique ID of the local shell call. + - `type: Literal["search"]` - - `action: LocalShellCallAction` + The action type. - Execute a shell command on the server. + - `"search"` - - `command: List[str]` + - `queries: Optional[List[str]]` - The command to run. + The search queries. - - `env: Dict[str, str]` + - `query: Optional[str]` - Environment variables to set for the command. + The search query. - - `type: Literal["exec"]` + - `sources: Optional[List[ActionSearchSource]]` - The type of the local shell action. Always `exec`. + The sources used in the search. - - `"exec"` + - `type: Literal["url"]` - - `timeout_ms: Optional[int]` + The type of source. Always `url`. - Optional timeout in milliseconds for the command. + - `"url"` - - `user: Optional[str]` + - `url: str` - Optional user to run the command as. + The URL of the source. - - `working_directory: Optional[str]` + - `class ActionOpenPage: …` - Optional working directory to run the command in. + Action type "open_page" - Opens a specific URL from search results. - - `call_id: str` + - `type: Literal["open_page"]` - The unique ID of the local shell tool call generated by the model. + The action type. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"open_page"` - The status of the local shell call. + - `url: Optional[str]` - - `"in_progress"` + The URL opened by the model. - - `"completed"` + - `class ActionFindInPage: …` - - `"incomplete"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `type: Literal["local_shell_call"]` + - `pattern: str` - The type of the local shell call. Always `local_shell_call`. + The pattern or text to search for within the page. - - `"local_shell_call"` + - `type: Literal["find_in_page"]` - - `agent: Optional[LocalShellCallAgent]` + The action type. - The agent that produced this item. + - `"find_in_page"` - - `agent_name: str` + - `url: str` - The canonical name of the agent that produced this item. + The URL of the page searched for the pattern. - - `class LocalShellCallOutput: …` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - The output of a local shell tool call. + The status of the web search tool call. - - `id: str` + - `"in_progress"` - The unique ID of the local shell tool call generated by the model. + - `"searching"` - - `output: str` + - `"completed"` - A JSON string of the output of the local shell tool call. + - `"failed"` - - `type: Literal["local_shell_call_output"]` + - `type: Literal["web_search_call"]` - The type of the local shell tool call output. Always `local_shell_call_output`. + The type of the web search tool call. Always `web_search_call`. - - `"local_shell_call_output"` + - `"web_search_call"` - - `agent: Optional[LocalShellCallOutputAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -23526,285 +34528,289 @@ Create a model response The canonical name of the agent that produced this item. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` + - `class BetaResponseComputerToolCall: …` - - `"completed"` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `"incomplete"` + - `id: str` - - `class ShellCall: …` + The unique ID of the computer call. - A tool representing a request to execute one or more shell commands. + - `call_id: str` - - `action: ShellCallAction` + An identifier used when responding to the tool call with output. - The shell commands and limits that describe how to run the tool call. + - `pending_safety_checks: List[PendingSafetyCheck]` - - `commands: List[str]` + The pending safety checks for the computer call. - Ordered shell commands for the execution environment to run. + - `id: str` - - `max_output_length: Optional[int]` + The ID of the pending safety check. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `code: Optional[str]` - - `timeout_ms: Optional[int]` + The type of the pending safety check. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `message: Optional[str]` - - `call_id: str` + Details about the pending safety check. - The unique ID of the shell tool call generated by the model. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["shell_call"]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the item. Always `shell_call`. + - `"in_progress"` - - `"shell_call"` + - `"completed"` - - `id: Optional[str]` + - `"incomplete"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `type: Literal["computer_call"]` - - `agent: Optional[ShellCallAgent]` + The type of the computer call. Always `computer_call`. - The agent that produced this item. + - `"computer_call"` - - `agent_name: str` + - `action: Optional[BetaComputerAction]` - The canonical name of the agent that produced this item. + A click action. - - `caller: Optional[ShellCallCaller]` + - `class Click: …` - The execution context that produced this tool call. + A click action. - - `class ShellCallCallerDirect: …` + - `button: Literal["left", "right", "wheel", 2 more]` - - `type: Literal["direct"]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The caller type. Always `direct`. + - `"left"` - - `"direct"` + - `"right"` - - `class ShellCallCallerProgram: …` + - `"wheel"` - - `caller_id: str` + - `"back"` - The call ID of the program item that produced this tool call. + - `"forward"` - - `type: Literal["program"]` + - `type: Literal["click"]` - The caller type. Always `program`. + Specifies the event type. For a click action, this property is always `click`. - - `"program"` + - `"click"` - - `environment: Optional[ShellCallEnvironment]` + - `x: int` - The environment to execute the shell commands in. + The x-coordinate where the click occurred. - - `class BetaLocalEnvironment: …` + - `y: int` - - `class BetaContainerReference: …` + The y-coordinate where the click occurred. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `keys: Optional[List[str]]` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The keys being held while clicking. - - `"in_progress"` + - `class DoubleClick: …` - - `"completed"` + A double click action. - - `"incomplete"` + - `keys: Optional[List[str]]` - - `class ShellCallOutput: …` + The keys being held while double-clicking. - The streamed output items emitted by a shell tool call. + - `type: Literal["double_click"]` - - `call_id: str` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The unique ID of the shell tool call generated by the model. + - `"double_click"` - - `output: List[BetaResponseFunctionShellCallOutputContent]` + - `x: int` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The x-coordinate where the double click occurred. - - `outcome: Outcome` + - `y: int` - The exit or timeout outcome associated with this shell call. + The y-coordinate where the double click occurred. - - `class OutcomeTimeout: …` + - `class Drag: …` - Indicates that the shell call exceeded its configured time limit. + A drag action. - - `type: Literal["timeout"]` + - `path: List[DragPath]` - The outcome type. Always `timeout`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"timeout"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `class OutcomeExit: …` + - `x: int` - Indicates that the shell commands finished and returned an exit code. + The x-coordinate. - - `exit_code: int` + - `y: int` - The exit code returned by the shell process. + The y-coordinate. - - `type: Literal["exit"]` + - `type: Literal["drag"]` - The outcome type. Always `exit`. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"exit"` + - `"drag"` - - `stderr: str` + - `keys: Optional[List[str]]` - Captured stderr output for the shell call. + The keys being held while dragging the mouse. - - `stdout: str` + - `class Keypress: …` - Captured stdout output for the shell call. + A collection of keypresses the model would like to perform. - - `type: Literal["shell_call_output"]` + - `keys: List[str]` - The type of the item. Always `shell_call_output`. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"shell_call_output"` + - `type: Literal["keypress"]` - - `id: Optional[str]` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"keypress"` - - `agent: Optional[ShellCallOutputAgent]` + - `class Move: …` - The agent that produced this item. + A mouse move action. - - `agent_name: str` + - `type: Literal["move"]` - The canonical name of the agent that produced this item. + Specifies the event type. For a move action, this property is always set to `move`. - - `caller: Optional[ShellCallOutputCaller]` + - `"move"` - The execution context that produced this tool call. + - `x: int` - - `class ShellCallOutputCallerDirect: …` + The x-coordinate to move to. - - `type: Literal["direct"]` + - `y: int` - The caller type. Always `direct`. + The y-coordinate to move to. - - `"direct"` + - `keys: Optional[List[str]]` - - `class ShellCallOutputCallerProgram: …` + The keys being held while moving the mouse. - - `caller_id: str` + - `class Screenshot: …` - The call ID of the program item that produced this tool call. + A screenshot action. - - `type: Literal["program"]` + - `type: Literal["screenshot"]` - The caller type. Always `program`. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"program"` + - `"screenshot"` - - `max_output_length: Optional[int]` + - `class Scroll: …` - The maximum number of UTF-8 characters captured for this shell call's combined output. + A scroll action. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `scroll_x: int` - The status of the shell call output. + The horizontal scroll distance. - - `"in_progress"` + - `scroll_y: int` - - `"completed"` + The vertical scroll distance. - - `"incomplete"` + - `type: Literal["scroll"]` - - `class ApplyPatchCall: …` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - A tool call representing a request to create, delete, or update files using diff patches. + - `"scroll"` - - `call_id: str` + - `x: int` - The unique ID of the apply patch tool call generated by the model. + The x-coordinate where the scroll occurred. - - `operation: ApplyPatchCallOperation` + - `y: int` - The specific create, delete, or update instruction for the apply_patch tool call. + The y-coordinate where the scroll occurred. - - `class ApplyPatchCallOperationCreateFile: …` + - `keys: Optional[List[str]]` - Instruction for creating a new file via the apply_patch tool. + The keys being held while scrolling. - - `diff: str` + - `class Type: …` - Unified diff content to apply when creating the file. + An action to type in text. - - `path: str` + - `text: str` - Path of the file to create relative to the workspace root. + The text to type. - - `type: Literal["create_file"]` + - `type: Literal["type"]` - The operation type. Always `create_file`. + Specifies the event type. For a type action, this property is always set to `type`. - - `"create_file"` + - `"type"` - - `class ApplyPatchCallOperationDeleteFile: …` + - `class Wait: …` - Instruction for deleting an existing file via the apply_patch tool. + A wait action. - - `path: str` + - `type: Literal["wait"]` - Path of the file to delete relative to the workspace root. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `type: Literal["delete_file"]` + - `"wait"` - The operation type. Always `delete_file`. + - `actions: Optional[BetaComputerActionList]` - - `"delete_file"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `class ApplyPatchCallOperationUpdateFile: …` + - `class Click: …` - Instruction for updating an existing file via the apply_patch tool. + A click action. - - `diff: str` + - `class DoubleClick: …` - Unified diff content to apply to the existing file. + A double click action. - - `path: str` + - `class Drag: …` - Path of the file to update relative to the workspace root. + A drag action. - - `type: Literal["update_file"]` + - `class Keypress: …` - The operation type. Always `update_file`. + A collection of keypresses the model would like to perform. - - `"update_file"` + - `class Move: …` - - `status: Literal["in_progress", "completed"]` + A mouse move action. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `class Screenshot: …` - - `"in_progress"` + A screenshot action. - - `"completed"` + - `class Scroll: …` - - `type: Literal["apply_patch_call"]` + A scroll action. - The type of the item. Always `apply_patch_call`. + - `class Type: …` - - `"apply_patch_call"` + An action to type in text. - - `id: Optional[str]` + - `class Wait: …` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + A wait action. - - `agent: Optional[ApplyPatchCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -23812,131 +34818,115 @@ Create a model response The canonical name of the agent that produced this item. - - `caller: Optional[ApplyPatchCallCaller]` - - The execution context that produced this tool call. - - - `class ApplyPatchCallCallerDirect: …` + - `class BetaResponseComputerToolCallOutputItem: …` - - `type: Literal["direct"]` + - `id: str` - The caller type. Always `direct`. + The unique ID of the computer call tool output. - - `"direct"` + - `call_id: str` - - `class ApplyPatchCallCallerProgram: …` + The ID of the computer tool call that produced the output. - - `caller_id: str` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The call ID of the program item that produced this tool call. + A computer screenshot image used with the computer use tool. - - `type: Literal["program"]` + - `type: Literal["computer_screenshot"]` - The caller type. Always `program`. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `"program"` + - `"computer_screenshot"` - - `class ApplyPatchCallOutput: …` + - `file_id: Optional[str]` - The streamed output emitted by an apply patch tool call. + The identifier of an uploaded file that contains the screenshot. - - `call_id: str` + - `image_url: Optional[str]` - The unique ID of the apply patch tool call generated by the model. + The URL of the screenshot image. - - `status: Literal["completed", "failed"]` + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - The status of the apply patch tool call output. One of `completed` or `failed`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"completed"` - - `"failed"` - - - `type: Literal["apply_patch_call_output"]` - - The type of the item. Always `apply_patch_call_output`. - - - `"apply_patch_call_output"` - - - `id: Optional[str]` + - `"incomplete"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"failed"` - - `agent: Optional[ApplyPatchCallOutputAgent]` + - `"in_progress"` - The agent that produced this item. + - `type: Literal["computer_call_output"]` - - `agent_name: str` + The type of the computer tool call output. Always `computer_call_output`. - The canonical name of the agent that produced this item. + - `"computer_call_output"` - - `caller: Optional[ApplyPatchCallOutputCaller]` + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - The execution context that produced this tool call. + The safety checks reported by the API that have been acknowledged by the + developer. - - `class ApplyPatchCallOutputCallerDirect: …` + - `id: str` - - `type: Literal["direct"]` + The ID of the pending safety check. - The caller type. Always `direct`. + - `code: Optional[str]` - - `"direct"` + The type of the pending safety check. - - `class ApplyPatchCallOutputCallerProgram: …` + - `message: Optional[str]` - - `caller_id: str` + Details about the pending safety check. - The call ID of the program item that produced this tool call. + - `agent: Optional[Agent]` - - `type: Literal["program"]` + The agent that produced this item. - The caller type. Always `program`. + - `agent_name: str` - - `"program"` + The canonical name of the agent that produced this item. - - `output: Optional[str]` + - `created_by: Optional[str]` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The identifier of the actor that created the item. - - `class McpListTools: …` + - `class BetaResponseReasoningItem: …` - A list of tools available on an MCP server. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: str` - The unique ID of the list. - - - `server_label: str` - - The label of the MCP server. - - - `tools: List[McpListToolsTool]` - - The tools available on the server. - - - `input_schema: object` + The unique identifier of the reasoning content. - The JSON schema describing the tool's input. + - `summary: List[Summary]` - - `name: str` + Reasoning summary content. - The name of the tool. + - `text: str` - - `annotations: Optional[object]` + A summary of the reasoning output from the model so far. - Additional annotations about the tool. + - `type: Literal["summary_text"]` - - `description: Optional[str]` + The type of the object. Always `summary_text`. - The description of the tool. + - `"summary_text"` - - `type: Literal["mcp_list_tools"]` + - `type: Literal["reasoning"]` - The type of the item. Always `mcp_list_tools`. + The type of the object. Always `reasoning`. - - `"mcp_list_tools"` + - `"reasoning"` - - `agent: Optional[McpListToolsAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -23944,67 +34934,61 @@ Create a model response The canonical name of the agent that produced this item. - - `error: Optional[str]` - - Error message if the server could not list tools. - - - `class McpApprovalRequest: …` - - A request for human approval of a tool invocation. - - - `id: str` + - `content: Optional[List[Content]]` - The unique ID of the approval request. + Reasoning text content. - - `arguments: str` + - `text: str` - A JSON string of arguments for the tool. + The reasoning text from the model. - - `name: str` + - `type: Literal["reasoning_text"]` - The name of the tool to run. + The type of the reasoning text. Always `reasoning_text`. - - `server_label: str` + - `"reasoning_text"` - The label of the MCP server making the request. + - `encrypted_content: Optional[str]` - - `type: Literal["mcp_approval_request"]` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The type of the item. Always `mcp_approval_request`. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"mcp_approval_request"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `agent: Optional[McpApprovalRequestAgent]` + - `"in_progress"` - The agent that produced this item. + - `"completed"` - - `agent_name: str` + - `"incomplete"` - The canonical name of the agent that produced this item. + - `class Program: …` - - `class McpApprovalResponse: …` + - `id: str` - A response to an MCP approval request. + The unique ID of the program item. - - `approval_request_id: str` + - `call_id: str` - The ID of the approval request being answered. + The stable call ID of the program item. - - `approve: bool` + - `code: str` - Whether the request was approved. + The JavaScript source executed by programmatic tool calling. - - `type: Literal["mcp_approval_response"]` + - `fingerprint: str` - The type of the item. Always `mcp_approval_response`. + Opaque program replay fingerprint that must be round-tripped. - - `"mcp_approval_response"` + - `type: Literal["program"]` - - `id: Optional[str]` + The type of the item. Always `program`. - The unique ID of the approval response + - `"program"` - - `agent: Optional[McpApprovalResponseAgent]` + - `agent: Optional[ProgramAgent]` The agent that produced this item. @@ -24012,37 +34996,35 @@ Create a model response The canonical name of the agent that produced this item. - - `reason: Optional[str]` - - Optional reason for the decision. + - `class ProgramOutput: …` - - `class McpCall: …` + - `id: str` - An invocation of a tool on an MCP server. + The unique ID of the program output item. - - `id: str` + - `call_id: str` - The unique ID of the tool call. + The call ID of the program item. - - `arguments: str` + - `result: str` - A JSON string of the arguments passed to the tool. + The result produced by the program item. - - `name: str` + - `status: Literal["completed", "incomplete"]` - The name of the tool that was run. + The terminal status of the program output item. - - `server_label: str` + - `"completed"` - The label of the MCP server running the tool. + - `"incomplete"` - - `type: Literal["mcp_call"]` + - `type: Literal["program_output"]` - The type of the item. Always `mcp_call`. + The type of the item. Always `program_output`. - - `"mcp_call"` + - `"program_output"` - - `agent: Optional[McpCallAgent]` + - `agent: Optional[ProgramOutputAgent]` The agent that produced this item. @@ -24050,22 +35032,31 @@ Create a model response The canonical name of the agent that produced this item. - - `approval_request_id: Optional[str]` + - `class BetaResponseToolSearchCall: …` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `id: str` - - `error: Optional[str]` + The unique ID of the tool search call item. - The error from the tool call, if any. + - `arguments: object` - - `output: Optional[str]` + Arguments used for the tool search call. - The output from the tool call. + - `call_id: Optional[str]` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + The unique ID of the tool search call generated by the model. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `execution: Literal["server", "client"]` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the tool search call item that was recorded. - `"in_progress"` @@ -24073,1123 +35064,1149 @@ Create a model response - `"incomplete"` - - `"calling"` + - `type: Literal["tool_search_call"]` - - `"failed"` + The type of the item. Always `tool_search_call`. - - `class BetaResponseCustomToolCallOutput: …` + - `"tool_search_call"` - The output of a custom tool call from your code, being sent back to the model. + - `agent: Optional[Agent]` - - `call_id: str` + The agent that produced this item. - The call ID, used to map this custom tool call output to a custom tool call. + - `agent_name: str` - - `output: Union[str, List[OutputOutputContentList]]` + The canonical name of the agent that produced this item. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `created_by: Optional[str]` - - `str` + The identifier of the actor that created the item. - A string of the output of the custom tool call. + - `class BetaResponseToolSearchOutputItem: …` - - `List[OutputOutputContentList]` + - `id: str` - Text, image, or file output of the custom tool call. + The unique ID of the tool search output item. - - `class BetaResponseInputText: …` + - `call_id: Optional[str]` - A text input to the model. + The unique ID of the tool search call generated by the model. - - `class BetaResponseInputImage: …` + - `execution: Literal["server", "client"]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Whether tool search was executed by the server or by the client. - - `class BetaResponseInputFile: …` + - `"server"` - A file input to the model. + - `"client"` - - `type: Literal["custom_tool_call_output"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The type of the custom tool call output. Always `custom_tool_call_output`. + The status of the tool search output item that was recorded. - - `"custom_tool_call_output"` + - `"in_progress"` - - `id: Optional[str]` + - `"completed"` - The unique ID of the custom tool call output in the OpenAI platform. + - `"incomplete"` - - `agent: Optional[Agent]` + - `tools: List[BetaTool]` - The agent that produced this item. + The loaded tool definitions returned by tool search. - - `agent_name: str` + - `class BetaFunctionTool: …` - The canonical name of the agent that produced this item. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `caller: Optional[Caller]` + - `name: str` - The execution context that produced this tool call. + The name of the function to call. - - `class CallerDirect: …` + - `parameters: Optional[Dict[str, object]]` - - `type: Literal["direct"]` + A JSON schema object describing the parameters of the function. - The caller type. Always `direct`. + - `strict: Optional[bool]` - - `"direct"` + Whether strict parameter validation is enforced for this function tool. - - `class CallerProgram: …` + - `type: Literal["function"]` - - `caller_id: str` + The type of the function tool. Always `function`. - The call ID of the program item that produced this tool call. + - `"function"` - - `type: Literal["program"]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The caller type. Always `program`. + The tool invocation context(s). - - `"program"` + - `"direct"` - - `class BetaResponseCustomToolCall: …` + - `"programmatic"` - A call to a custom tool created by the model. + - `defer_loading: Optional[bool]` - - `call_id: str` + Whether this function is deferred and loaded via tool search. - An identifier used to map this custom tool call to a tool call output. + - `description: Optional[str]` - - `input: str` + A description of the function. Used by the model to determine whether or not to call the function. - The input for the custom tool call generated by the model. + - `output_schema: Optional[Dict[str, object]]` - - `name: str` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The name of the custom tool being called. + - `class BetaFileSearchTool: …` - - `type: Literal["custom_tool_call"]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The type of the custom tool call. Always `custom_tool_call`. + - `type: Literal["file_search"]` - - `"custom_tool_call"` + The type of the file search tool. Always `file_search`. - - `id: Optional[str]` + - `"file_search"` - The unique ID of the custom tool call in the OpenAI platform. + - `vector_store_ids: List[str]` - - `agent: Optional[Agent]` + The IDs of the vector stores to search. - The agent that produced this item. + - `filters: Optional[Filters]` - - `agent_name: str` + A filter to apply. - The canonical name of the agent that produced this item. + - `class FiltersComparisonFilter: …` - - `caller: Optional[Caller]` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The execution context that produced this tool call. + - `key: str` - - `class CallerDirect: …` + The key to compare against the value. - - `type: Literal["direct"]` + - `type: Literal["eq", "ne", "gt", 5 more]` - - `"direct"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `class CallerProgram: …` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `caller_id: str` + - `"eq"` - The call ID of the program item that produced this tool call. + - `"ne"` - - `type: Literal["program"]` + - `"gt"` - - `"program"` + - `"gte"` - - `namespace: Optional[str]` + - `"lt"` - The namespace of the custom tool being called. + - `"lte"` - - `class CompactionTrigger: …` + - `"in"` - Compacts the current context. Must be the final input item. + - `"nin"` - - `type: Literal["compaction_trigger"]` + - `value: Union[str, float, bool, List[Union[str, float]]]` - The type of the item. Always `compaction_trigger`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"compaction_trigger"` + - `str` - - `agent: Optional[CompactionTriggerAgent]` + - `float` - The agent that produced this item. + - `bool` - - `agent_name: str` + - `List[Union[str, float]]` - The canonical name of the agent that produced this item. + - `str` - - `class ItemReference: …` + - `float` - An internal identifier for an item to reference. + - `class FiltersCompoundFilter: …` - - `id: str` + Combine multiple filters using `and` or `or`. - The ID of the item to reference. + - `filters: List[FiltersCompoundFilterFilter]` - - `agent: Optional[ItemReferenceAgent]` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The agent that produced this item. + - `class FiltersCompoundFilterFilterComparisonFilter: …` - - `agent_name: str` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The canonical name of the agent that produced this item. + - `key: str` - - `type: Optional[Literal["item_reference"]]` + The key to compare against the value. - The type of item to reference. Always `item_reference`. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `"item_reference"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `class Program: …` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `id: str` + - `"eq"` - The unique ID of this program item. + - `"ne"` - - `call_id: str` + - `"gt"` - The stable call ID of the program item. + - `"gte"` - - `code: str` + - `"lt"` - The JavaScript source executed by programmatic tool calling. + - `"lte"` - - `fingerprint: str` + - `"in"` - Opaque program replay fingerprint that must be round-tripped. + - `"nin"` - - `type: Literal["program"]` + - `value: Union[str, float, bool, List[Union[str, float]]]` - The item type. Always `program`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"program"` + - `str` - - `agent: Optional[ProgramAgent]` + - `float` - The agent that produced this item. + - `bool` - - `agent_name: str` + - `List[Union[str, float]]` - The canonical name of the agent that produced this item. + - `str` - - `class ProgramOutput: …` + - `float` - - `id: str` + - `object` - The unique ID of this program output item. + - `type: Literal["and", "or"]` - - `call_id: str` + Type of operation: `and` or `or`. - The call ID of the program item. + - `"and"` - - `result: str` + - `"or"` - The result produced by the program item. + - `max_num_results: Optional[int]` - - `status: Literal["completed", "incomplete"]` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The terminal status of the program output. + - `ranking_options: Optional[RankingOptions]` - - `"completed"` + Ranking options for search. - - `"incomplete"` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - `type: Literal["program_output"]` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The item type. Always `program_output`. + - `embedding_weight: float` - - `"program_output"` + The weight of the embedding in the reciprocal ranking fusion. - - `agent: Optional[ProgramOutputAgent]` + - `text_weight: float` - The agent that produced this item. + The weight of the text in the reciprocal ranking fusion. - - `agent_name: str` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - The canonical name of the agent that produced this item. + The ranker to use for the file search. - - `metadata: Optional[Dict[str, str]]` + - `"auto"` - 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. + - `"default-2024-11-15"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `score_threshold: Optional[float]` - - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `class BetaComputerTool: …` - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `type: Literal["computer"]` - - `"gpt-5.6-sol"` + The type of the computer tool. Always `computer`. - - `"gpt-5.6-terra"` + - `"computer"` - - `"gpt-5.6-luna"` + - `class BetaComputerUsePreviewTool: …` - - `"gpt-5.4"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-5.4-mini"` + - `display_height: int` - - `"gpt-5.4-nano"` + The height of the computer display. - - `"gpt-5.4-mini-2026-03-17"` + - `display_width: int` - - `"gpt-5.4-nano-2026-03-17"` + The width of the computer display. - - `"gpt-5.3-chat-latest"` + - `environment: Literal["windows", "mac", "linux", 2 more]` - - `"gpt-5.2"` + The type of computer environment to control. - - `"gpt-5.2-2025-12-11"` + - `"windows"` - - `"gpt-5.2-chat-latest"` + - `"mac"` - - `"gpt-5.2-pro"` + - `"linux"` - - `"gpt-5.2-pro-2025-12-11"` + - `"ubuntu"` - - `"gpt-5.1"` + - `"browser"` - - `"gpt-5.1-2025-11-13"` + - `type: Literal["computer_use_preview"]` - - `"gpt-5.1-codex"` + The type of the computer use tool. Always `computer_use_preview`. - - `"gpt-5.1-mini"` + - `"computer_use_preview"` - - `"gpt-5.1-chat-latest"` + - `class BetaWebSearchTool: …` - - `"gpt-5"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"gpt-5-mini"` + - `type: Literal["web_search", "web_search_2025_08_26"]` - - `"gpt-5-nano"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"gpt-5-2025-08-07"` + - `"web_search"` - - `"gpt-5-mini-2025-08-07"` + - `"web_search_2025_08_26"` - - `"gpt-5-nano-2025-08-07"` + - `filters: Optional[Filters]` - - `"gpt-5-chat-latest"` + Filters for the search. - - `"gpt-4.1"` + - `allowed_domains: Optional[List[str]]` - - `"gpt-4.1-mini"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `"gpt-4.1-nano"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"gpt-4.1-2025-04-14"` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `"gpt-4.1-mini-2025-04-14"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `"gpt-4.1-nano-2025-04-14"` + - `"low"` - - `"o4-mini"` + - `"medium"` - - `"o4-mini-2025-04-16"` + - `"high"` - - `"o3"` + - `user_location: Optional[UserLocation]` - - `"o3-2025-04-16"` + The approximate location of the user. - - `"o3-mini"` + - `city: Optional[str]` - - `"o3-mini-2025-01-31"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"o1"` + - `country: Optional[str]` - - `"o1-2024-12-17"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"o1-preview"` + - `region: Optional[str]` - - `"o1-preview-2024-09-12"` + Free text input for the region of the user, e.g. `California`. - - `"o1-mini"` + - `timezone: Optional[str]` - - `"o1-mini-2024-09-12"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"gpt-4o"` + - `type: Optional[Literal["approximate"]]` - - `"gpt-4o-2024-11-20"` + The type of location approximation. Always `approximate`. - - `"gpt-4o-2024-08-06"` + - `"approximate"` - - `"gpt-4o-2024-05-13"` + - `class Mcp: …` - - `"gpt-4o-audio-preview"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"gpt-4o-audio-preview-2024-10-01"` + - `server_label: str` - - `"gpt-4o-audio-preview-2024-12-17"` + A label for this MCP server, used to identify it in tool calls. - - `"gpt-4o-audio-preview-2025-06-03"` + - `type: Literal["mcp"]` - - `"gpt-4o-mini-audio-preview"` + The type of the MCP tool. Always `mcp`. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `"mcp"` - - `"gpt-4o-search-preview"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"gpt-4o-mini-search-preview"` + The tool invocation context(s). - - `"gpt-4o-search-preview-2025-03-11"` + - `"direct"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `"programmatic"` - - `"chatgpt-4o-latest"` + - `allowed_tools: Optional[McpAllowedTools]` - - `"codex-mini-latest"` + List of allowed tool names or a filter object. - - `"gpt-4o-mini"` + - `List[str]` - - `"gpt-4o-mini-2024-07-18"` + A string array of allowed tool names - - `"gpt-4-turbo"` + - `class McpAllowedToolsMcpToolFilter: …` - - `"gpt-4-turbo-2024-04-09"` + A filter object to specify which tools are allowed. - - `"gpt-4-0125-preview"` + - `read_only: Optional[bool]` - - `"gpt-4-turbo-preview"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"gpt-4-1106-preview"` + - `tool_names: Optional[List[str]]` - - `"gpt-4-vision-preview"` + List of allowed tool names. - - `"gpt-4"` + - `authorization: Optional[str]` - - `"gpt-4-0314"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `"gpt-4-0613"` + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `"gpt-4-32k"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `"gpt-4-32k-0314"` + Currently supported `connector_id` values are: - - `"gpt-4-32k-0613"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `"gpt-3.5-turbo"` + - `"connector_dropbox"` - - `"gpt-3.5-turbo-16k"` + - `"connector_gmail"` - - `"gpt-3.5-turbo-0301"` + - `"connector_googlecalendar"` - - `"gpt-3.5-turbo-0613"` + - `"connector_googledrive"` - - `"gpt-3.5-turbo-1106"` + - `"connector_microsoftteams"` - - `"gpt-3.5-turbo-0125"` + - `"connector_outlookcalendar"` - - `"gpt-3.5-turbo-16k-0613"` + - `"connector_outlookemail"` - - `"o1-pro"` + - `"connector_sharepoint"` - - `"o1-pro-2025-03-19"` + - `defer_loading: Optional[bool]` - - `"o3-pro"` + Whether this MCP tool is deferred and discovered via tool search. - - `"o3-pro-2025-06-10"` + - `headers: Optional[Dict[str, str]]` - - `"o3-deep-research"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"o3-deep-research-2025-06-26"` + - `require_approval: Optional[McpRequireApproval]` - - `"o4-mini-deep-research"` + Specify which of the MCP server's tools require approval. - - `"o4-mini-deep-research-2025-06-26"` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - - `"computer-use-preview"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"computer-use-preview-2025-03-11"` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `"gpt-5-codex"` + A filter object to specify which tools are allowed. - - `"gpt-5-pro"` + - `read_only: Optional[bool]` - - `"gpt-5-pro-2025-10-06"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"gpt-5.1-codex-max"` + - `tool_names: Optional[List[str]]` - - `str` + List of allowed tool names. - - `object: Literal["response"]` + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - The object type of this resource - always set to `response`. + A filter object to specify which tools are allowed. - - `"response"` + - `read_only: Optional[bool]` - - `output: List[BetaResponseOutputItem]` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - An array of content items generated by the model. + - `tool_names: Optional[List[str]]` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + List of allowed tool names. - - `class BetaResponseOutputMessage: …` + - `Literal["always", "never"]` - An output message from the model. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `class BetaResponseFileSearchToolCall: …` + - `"always"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"never"` - - `class BetaResponseFunctionToolCall: …` + - `server_description: Optional[str]` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Optional description of the MCP server, used to provide more context. - - `class BetaResponseFunctionToolCallOutputItem: …` + - `server_url: Optional[str]` - - `id: str` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The unique ID of the function call tool output. + - `tunnel_id: Optional[str]` - - `call_id: str` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The unique ID of the function tool call generated by the model. + - `class CodeInterpreter: …` - - `output: Union[str, List[OutputOutputContentList]]` + A tool that runs Python code to help generate a response to a prompt. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `container: CodeInterpreterContainer` - - `str` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - A string of the output of the function call. + - `str` - - `List[OutputOutputContentList]` + The container ID. - Text, image, or file output of the function call. + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `class BetaResponseInputText: …` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - A text input to the model. + - `type: Literal["auto"]` - - `class BetaResponseInputImage: …` + Always `auto`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"auto"` - - `class BetaResponseInputFile: …` + - `file_ids: Optional[List[str]]` - A file input to the model. + An optional list of uploaded files to make available to your code. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The memory limit for the code interpreter container. - - `"in_progress"` + - `"1g"` - - `"completed"` + - `"4g"` - - `"incomplete"` + - `"16g"` - - `type: Literal["function_call_output"]` + - `"64g"` - The type of the function tool call output. Always `function_call_output`. + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - - `"function_call_output"` + Network access policy for the container. - - `agent: Optional[Agent]` + - `class BetaContainerNetworkPolicyDisabled: …` - The agent that produced this item. + - `type: Literal["disabled"]` - - `agent_name: str` + Disable outbound network access. Always `disabled`. - The canonical name of the agent that produced this item. + - `"disabled"` - - `caller: Optional[Caller]` + - `class BetaContainerNetworkPolicyAllowlist: …` - The execution context that produced this tool call. + - `allowed_domains: List[str]` - - `class CallerDirect: …` + A list of allowed domains when type is `allowlist`. - - `type: Literal["direct"]` + - `type: Literal["allowlist"]` - The caller type. Always `direct`. + Allow outbound network access only to specified domains. Always `allowlist`. - - `"direct"` + - `"allowlist"` - - `class CallerProgram: …` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `caller_id: str` + Optional domain-scoped secrets for allowlisted domains. - The call ID of the program item that produced this tool call. + - `domain: str` - - `type: Literal["program"]` + The domain associated with the secret. - The caller type. Always `program`. + - `name: str` - - `"program"` + The name of the secret to inject for the domain. - - `created_by: Optional[str]` + - `value: str` - The identifier of the actor that created the item. + The secret value to inject for the domain. - - `class AgentMessage: …` + - `type: Literal["code_interpreter"]` - - `id: str` + The type of the code interpreter tool. Always `code_interpreter`. - The unique ID of the agent message. + - `"code_interpreter"` - - `author: str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The sending agent identity. + The tool invocation context(s). - - `content: List[AgentMessageContent]` + - `"direct"` - Encrypted content sent between agents. + - `"programmatic"` - - `class BetaResponseInputText: …` + - `class ProgrammaticToolCalling: …` - A text input to the model. + - `type: Literal["programmatic_tool_calling"]` - - `class BetaResponseOutputText: …` + The type of the tool. Always `programmatic_tool_calling`. - A text output from the model. + - `"programmatic_tool_calling"` - - `class AgentMessageContentText: …` + - `class ImageGeneration: …` - A text content. + A tool that generates images using the GPT image models. - - `text: str` + - `type: Literal["image_generation"]` - - `type: Literal["text"]` + The type of the image generation tool. Always `image_generation`. - - `"text"` + - `"image_generation"` - - `class AgentMessageContentSummaryText: …` + - `action: Optional[Literal["generate", "edit", "auto"]]` - A summary text from the model. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `text: str` + - `"generate"` - A summary of the reasoning output from the model so far. + - `"edit"` - - `type: Literal["summary_text"]` + - `"auto"` - The type of the object. Always `summary_text`. + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `"summary_text"` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `class AgentMessageContentReasoningText: …` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - Reasoning text from the model. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `text: str` + - `"transparent"` - The reasoning text from the model. + - `"opaque"` - - `type: Literal["reasoning_text"]` + - `"auto"` - The type of the reasoning text. Always `reasoning_text`. + - `input_fidelity: Optional[Literal["high", "low"]]` - - `"reasoning_text"` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `class BetaResponseOutputRefusal: …` + - `"high"` - A refusal from the model. + - `"low"` - - `class BetaResponseInputImage: …` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `class AgentMessageContentComputerScreenshot: …` + - `file_id: Optional[str]` - A screenshot of a computer. + File ID for the mask image. - - `detail: Literal["low", "high", "auto", "original"]` + - `image_url: Optional[str]` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Base64-encoded mask image. - - `"low"` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - - `"high"` + The image generation model to use. Default: `gpt-image-1`. - - `"auto"` + - `str` - - `"original"` + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `file_id: Optional[str]` + The image generation model to use. Default: `gpt-image-1`. - The identifier of an uploaded file that contains the screenshot. + - `"gpt-image-1"` - - `image_url: Optional[str]` + - `"gpt-image-1-mini"` - The URL of the screenshot image. + - `"gpt-image-2"` - - `type: Literal["computer_screenshot"]` + - `"gpt-image-2-2026-04-21"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"gpt-image-1.5"` - - `"computer_screenshot"` + - `"chatgpt-image-latest"` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `moderation: Optional[Literal["auto", "low"]]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Moderation level for the generated image. Default: `auto`. - - `mode: Literal["explicit"]` + - `"auto"` - The breakpoint mode. Always `explicit`. + - `"low"` - - `"explicit"` + - `output_compression: Optional[int]` - - `class BetaResponseInputFile: …` + Compression level for the output image. Default: 100. - A file input to the model. + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `class AgentMessageContentEncryptedContent: …` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"png"` - - `encrypted_content: str` + - `"webp"` - Opaque encrypted content. + - `"jpeg"` - - `type: Literal["encrypted_content"]` + - `partial_images: Optional[int]` - The type of the input item. Always `encrypted_content`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"encrypted_content"` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - - `recipient: str` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The destination agent identity. + - `"low"` - - `type: Literal["agent_message"]` + - `"medium"` - The type of the item. Always `agent_message`. + - `"high"` - - `"agent_message"` + - `"auto"` - - `agent: Optional[AgentMessageAgent]` + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - The agent that produced this item. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `agent_name: str` + - `str` - The canonical name of the agent that produced this item. + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `class MultiAgentCall: …` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `id: str` + - `"1024x1024"` - The unique ID of the multi-agent call item. + - `"1024x1536"` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `"1536x1024"` - The multi-agent action to execute. + - `"auto"` - - `"spawn_agent"` + - `class LocalShell: …` - - `"interrupt_agent"` + A tool that allows the model to execute shell commands in a local environment. - - `"list_agents"` + - `type: Literal["local_shell"]` - - `"send_message"` + The type of the local shell tool. Always `local_shell`. - - `"followup_task"` + - `"local_shell"` - - `"wait_agent"` + - `class BetaFunctionShellTool: …` - - `arguments: str` + A tool that allows the model to execute shell commands. - The JSON string of arguments generated for the action. + - `type: Literal["shell"]` - - `call_id: str` + The type of the shell tool. Always `shell`. - The unique ID linking this call to its output. + - `"shell"` - - `type: Literal["multi_agent_call"]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The type of the multi-agent call. Always `multi_agent_call`. + The tool invocation context(s). - - `"multi_agent_call"` + - `"direct"` - - `agent: Optional[MultiAgentCallAgent]` + - `"programmatic"` - The agent that produced this item. + - `environment: Optional[Environment]` - - `agent_name: str` + - `class BetaContainerAuto: …` - The canonical name of the agent that produced this item. + - `type: Literal["container_auto"]` - - `class MultiAgentCallOutput: …` + Automatically creates a container for this request - - `id: str` + - `"container_auto"` - The unique ID of the multi-agent call output item. + - `file_ids: Optional[List[str]]` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + An optional list of uploaded files to make available to your code. - The multi-agent action that produced this result. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `"spawn_agent"` + The memory limit for the container. - - `"interrupt_agent"` + - `"1g"` - - `"list_agents"` + - `"4g"` - - `"send_message"` + - `"16g"` - - `"followup_task"` + - `"64g"` - - `"wait_agent"` + - `network_policy: Optional[NetworkPolicy]` - - `call_id: str` + Network access policy for the container. - The unique ID of the multi-agent call. + - `class BetaContainerNetworkPolicyDisabled: …` - - `output: List[BetaResponseOutputText]` + - `class BetaContainerNetworkPolicyAllowlist: …` - Text output returned by the multi-agent action. + - `skills: Optional[List[Skill]]` - - `annotations: List[Annotation]` + An optional list of skills referenced by id or inline data. - The annotations of the text output. + - `class BetaSkillReference: …` - - `text: str` + - `skill_id: str` - The text output from the model. + The ID of the referenced skill. - - `type: Literal["output_text"]` + - `type: Literal["skill_reference"]` - The type of the output text. Always `output_text`. + References a skill created with the /v1/skills endpoint. - - `logprobs: Optional[List[Logprob]]` + - `"skill_reference"` - - `type: Literal["multi_agent_call_output"]` + - `version: Optional[str]` - The type of the multi-agent result. Always `multi_agent_call_output`. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `"multi_agent_call_output"` + - `class BetaInlineSkill: …` - - `agent: Optional[MultiAgentCallOutputAgent]` + - `description: str` - The agent that produced this item. + The description of the skill. - - `agent_name: str` + - `name: str` - The canonical name of the agent that produced this item. + The name of the skill. - - `class BetaResponseFunctionWebSearch: …` + - `source: BetaInlineSkillSource` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + Inline skill payload - - `class BetaResponseComputerToolCall: …` + - `data: str` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Base64-encoded skill zip bundle. - - `class BetaResponseComputerToolCallOutputItem: …` + - `media_type: Literal["application/zip"]` - - `id: str` + The media type of the inline skill payload. Must be `application/zip`. - The unique ID of the computer call tool output. + - `"application/zip"` - - `call_id: str` + - `type: Literal["base64"]` - The ID of the computer tool call that produced the output. + The type of the inline skill source. Must be `base64`. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"base64"` - A computer screenshot image used with the computer use tool. + - `type: Literal["inline"]` - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + Defines an inline skill for this request. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"inline"` - - `"completed"` + - `class BetaLocalEnvironment: …` - - `"incomplete"` + - `type: Literal["local"]` - - `"failed"` + Use a local computer environment. - - `"in_progress"` + - `"local"` - - `type: Literal["computer_call_output"]` + - `skills: Optional[List[BetaLocalSkill]]` - The type of the computer tool call output. Always `computer_call_output`. + An optional list of skills. - - `"computer_call_output"` + - `description: str` - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + The description of the skill. - The safety checks reported by the API that have been acknowledged by the - developer. + - `name: str` - - `id: str` + The name of the skill. - The ID of the pending safety check. + - `path: str` - - `code: Optional[str]` + The path to the directory containing the skill. - The type of the pending safety check. + - `class BetaContainerReference: …` - - `message: Optional[str]` + - `container_id: str` - Details about the pending safety check. + The ID of the referenced container. - - `agent: Optional[Agent]` + - `type: Literal["container_reference"]` - The agent that produced this item. + References a container created with the /v1/containers endpoint - - `agent_name: str` + - `"container_reference"` - The canonical name of the agent that produced this item. + - `class BetaCustomTool: …` - - `created_by: Optional[str]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The identifier of the actor that created the item. + - `name: str` - - `class BetaResponseReasoningItem: …` + The name of the custom tool, used to identify it in tool calls. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `type: Literal["custom"]` - - `class Program: …` + The type of the custom tool. Always `custom`. - - `id: str` + - `"custom"` - The unique ID of the program item. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `call_id: str` + The tool invocation context(s). - The stable call ID of the program item. + - `"direct"` - - `code: str` + - `"programmatic"` - The JavaScript source executed by programmatic tool calling. + - `defer_loading: Optional[bool]` - - `fingerprint: str` + Whether this tool should be deferred and discovered via tool search. - Opaque program replay fingerprint that must be round-tripped. + - `description: Optional[str]` - - `type: Literal["program"]` + Optional description of the custom tool, used to provide more context. - The type of the item. Always `program`. + - `format: Optional[Format]` - - `"program"` + The input format for the custom tool. Default is unconstrained text. - - `agent: Optional[ProgramAgent]` + - `class FormatText: …` - The agent that produced this item. + Unconstrained free-form text. - - `agent_name: str` + - `type: Literal["text"]` - The canonical name of the agent that produced this item. + Unconstrained text format. Always `text`. - - `class ProgramOutput: …` + - `"text"` - - `id: str` + - `class FormatGrammar: …` - The unique ID of the program output item. + A grammar defined by the user. - - `call_id: str` + - `definition: str` - The call ID of the program item. + The grammar definition. - - `result: str` + - `syntax: Literal["lark", "regex"]` - The result produced by the program item. + The syntax of the grammar definition. One of `lark` or `regex`. - - `status: Literal["completed", "incomplete"]` + - `"lark"` - The terminal status of the program output item. + - `"regex"` - - `"completed"` + - `type: Literal["grammar"]` - - `"incomplete"` + Grammar format. Always `grammar`. - - `type: Literal["program_output"]` + - `"grammar"` - The type of the item. Always `program_output`. + - `class BetaNamespaceTool: …` - - `"program_output"` + Groups function/custom tools under a shared namespace. - - `agent: Optional[ProgramOutputAgent]` + - `description: str` - The agent that produced this item. + A description of the namespace shown to the model. - - `agent_name: str` + - `name: str` - The canonical name of the agent that produced this item. + The namespace name used in tool calls (for example, `crm`). - - `class BetaResponseToolSearchCall: …` + - `tools: List[Tool]` - - `id: str` + The function/custom tools available inside this namespace. - The unique ID of the tool search call item. + - `class ToolFunction: …` - - `arguments: object` + - `name: str` - Arguments used for the tool search call. + - `type: Literal["function"]` - - `call_id: Optional[str]` + - `"function"` - The unique ID of the tool search call generated by the model. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `execution: Literal["server", "client"]` + The tool invocation context(s). - Whether tool search was executed by the server or by the client. + - `"direct"` - - `"server"` + - `"programmatic"` - - `"client"` + - `defer_loading: Optional[bool]` - - `status: Literal["in_progress", "completed", "incomplete"]` + Whether this function should be deferred and discovered via tool search. - The status of the tool search call item that was recorded. + - `description: Optional[str]` - - `"in_progress"` + - `output_schema: Optional[Dict[str, object]]` - - `"completed"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"incomplete"` + - `parameters: Optional[object]` - - `type: Literal["tool_search_call"]` + - `strict: Optional[bool]` - The type of the item. Always `tool_search_call`. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `"tool_search_call"` + - `class BetaCustomTool: …` - - `agent: Optional[Agent]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The agent that produced this item. + - `type: Literal["namespace"]` - - `agent_name: str` + The type of the tool. Always `namespace`. - The canonical name of the agent that produced this item. + - `"namespace"` - - `created_by: Optional[str]` + - `class BetaToolSearchTool: …` - The identifier of the actor that created the item. + Hosted or BYOT tool search configuration for deferred tools. - - `class BetaResponseToolSearchOutputItem: …` + - `type: Literal["tool_search"]` - - `id: str` + The type of the tool. Always `tool_search`. - The unique ID of the tool search output item. + - `"tool_search"` - - `call_id: Optional[str]` + - `description: Optional[str]` - The unique ID of the tool search call generated by the model. + Description shown to the model for a client-executed tool search tool. - - `execution: Literal["server", "client"]` + - `execution: Optional[Literal["server", "client"]]` - Whether tool search was executed by the server or by the client. + Whether tool search is executed by the server or by the client. - `"server"` - `"client"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `parameters: Optional[object]` - The status of the tool search output item that was recorded. + Parameter schema for a client-executed tool search tool. - - `"in_progress"` + - `class BetaWebSearchPreviewTool: …` - - `"completed"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"incomplete"` + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - - `tools: List[BetaTool]` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The loaded tool definitions returned by tool search. + - `"web_search_preview"` - - `class BetaFunctionTool: …` + - `"web_search_preview_2025_03_11"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `class BetaFileSearchTool: …` + - `"text"` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `"image"` - - `class BetaComputerTool: …` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `class BetaComputerUsePreviewTool: …` + - `"low"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"medium"` - - `class BetaWebSearchTool: …` + - `"high"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `user_location: Optional[UserLocation]` - - `class Mcp: …` + The user's location. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: Literal["approximate"]` - - `class CodeInterpreter: …` + The type of location approximation. Always `approximate`. - A tool that runs Python code to help generate a response to a prompt. + - `"approximate"` - - `class ProgrammaticToolCalling: …` + - `city: Optional[str]` - - `class ImageGeneration: …` + Free text input for the city of the user, e.g. `San Francisco`. - A tool that generates images using the GPT image models. + - `country: Optional[str]` - - `class LocalShell: …` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A tool that allows the model to execute shell commands in a local environment. + - `region: Optional[str]` - - `class BetaFunctionShellTool: …` + Free text input for the region of the user, e.g. `California`. - A tool that allows the model to execute shell commands. + - `timezone: Optional[str]` - - `class BetaCustomTool: …` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `class BetaApplyPatchTool: …` - - `class BetaNamespaceTool: …` + Allows the assistant to create, delete, or update files using unified diffs. - Groups function/custom tools under a shared namespace. + - `type: Literal["apply_patch"]` - - `class BetaToolSearchTool: …` + The type of the tool. Always `apply_patch`. - Hosted or BYOT tool search configuration for deferred tools. + - `"apply_patch"` - - `class BetaWebSearchPreviewTool: …` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The tool invocation context(s). - - `class BetaApplyPatchTool: …` + - `"direct"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"programmatic"` - `type: Literal["tool_search_output"]` @@ -25389,6 +36406,79 @@ Create a model response A tool call to run code. + - `id: str` + + The unique ID of the code interpreter tool call. + + - `code: Optional[str]` + + The code to run, or null if not available. + + - `container_id: str` + + The ID of the container used to run the code. + + - `outputs: Optional[List[Output]]` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `class OutputLogs: …` + + The logs output from the code interpreter. + + - `logs: str` + + The logs output from the code interpreter. + + - `type: Literal["logs"]` + + The type of the output. Always `logs`. + + - `"logs"` + + - `class OutputImage: …` + + The image output from the code interpreter. + + - `type: Literal["image"]` + + The type of the output. Always `image`. + + - `"image"` + + - `url: str` + + The URL of the image output from the code interpreter. + + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: Literal["code_interpreter_call"]` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + - `class LocalShellCall: …` A tool call to run a command on the local shell. @@ -25863,2023 +36953,1797 @@ Create a model response - `type: Literal["program"]` - - `"program"` + - `"program"` + + - `created_by: Optional[str]` + + The ID of the entity that created this tool call output. + + - `output: Optional[str]` + + Optional textual output returned by the apply patch tool. + + - `class McpCall: …` + + An invocation of a tool on an MCP server. + + - `id: str` + + The unique ID of the tool call. + + - `arguments: str` + + A JSON string of the arguments passed to the tool. + + - `name: str` + + The name of the tool that was run. + + - `server_label: str` + + The label of the MCP server running the tool. + + - `type: Literal["mcp_call"]` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `agent: Optional[McpCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `approval_request_id: Optional[str]` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: Optional[str]` + + The error from the tool call, if any. + + - `output: Optional[str]` + + The output from the tool call. + + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `class McpListTools: …` + + A list of tools available on an MCP server. + + - `id: str` + + The unique ID of the list. + + - `server_label: str` + + The label of the MCP server. + + - `tools: List[McpListToolsTool]` + + The tools available on the server. + + - `input_schema: object` + + The JSON schema describing the tool's input. + + - `name: str` + + The name of the tool. + + - `annotations: Optional[object]` + + Additional annotations about the tool. + + - `description: Optional[str]` + + The description of the tool. + + - `type: Literal["mcp_list_tools"]` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `agent: Optional[McpListToolsAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `error: Optional[str]` + + Error message if the server could not list tools. + + - `class McpApprovalRequest: …` + + A request for human approval of a tool invocation. + + - `id: str` + + The unique ID of the approval request. + + - `arguments: str` + + A JSON string of arguments for the tool. + + - `name: str` + + The name of the tool to run. + + - `server_label: str` + + The label of the MCP server making the request. + + - `type: Literal["mcp_approval_request"]` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `agent: Optional[McpApprovalRequestAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse: …` + + A response to an MCP approval request. + + - `id: str` + + The unique ID of the approval response + + - `approval_request_id: str` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: Literal["mcp_approval_response"]` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `agent: Optional[McpApprovalResponseAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `reason: Optional[str]` + + Optional reason for the decision. + + - `class BetaResponseCustomToolCall: …` + + A call to a custom tool created by the model. + + - `call_id: str` + + An identifier used to map this custom tool call to a tool call output. + + - `input: str` + + The input for the custom tool call generated by the model. + + - `name: str` + + The name of the custom tool being called. + + - `type: Literal["custom_tool_call"]` + + The type of the custom tool call. Always `custom_tool_call`. + + - `"custom_tool_call"` + + - `id: Optional[str]` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `namespace: Optional[str]` + + The namespace of the custom tool being called. + + - `class BetaResponseCustomToolCallOutputItem: …` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: str` + + The unique ID of the custom tool call output item. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `usage: BetaResponseUsage` + + Token accounting for the compaction pass, including cached, reasoning, and total tokens. + + - `input_tokens: int` + + The number of input tokens. + + - `input_tokens_details: InputTokensDetails` + + A detailed breakdown of the input tokens. + + - `cache_write_tokens: int` + + The number of input tokens that were written to the cache. + + - `cached_tokens: int` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + + - `output_tokens: int` + + The number of output tokens. + + - `output_tokens_details: OutputTokensDetails` + + A detailed breakdown of the output tokens. + + - `reasoning_tokens: int` + + The number of reasoning tokens. + + - `total_tokens: int` + + The total number of tokens used. + +### Beta Computer Action + +- `BetaComputerAction` + + A click action. + + - `class Click: …` + + A click action. + + - `button: Literal["left", "right", "wheel", 2 more]` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: Literal["click"]` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: int` + + The x-coordinate where the click occurred. + + - `y: int` + + The y-coordinate where the click occurred. + + - `keys: Optional[List[str]]` + + The keys being held while clicking. + + - `class DoubleClick: …` + + A double click action. + + - `keys: Optional[List[str]]` + + The keys being held while double-clicking. + + - `type: Literal["double_click"]` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: int` + + The x-coordinate where the double click occurred. + + - `y: int` + + The y-coordinate where the double click occurred. + + - `class Drag: …` + + A drag action. + + - `path: List[DragPath]` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: int` + + The x-coordinate. + + - `y: int` + + The y-coordinate. + + - `type: Literal["drag"]` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: Optional[List[str]]` + + The keys being held while dragging the mouse. + + - `class Keypress: …` + + A collection of keypresses the model would like to perform. + + - `keys: List[str]` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: Literal["keypress"]` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `class Move: …` + + A mouse move action. + + - `type: Literal["move"]` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: int` + + The x-coordinate to move to. + + - `y: int` + + The y-coordinate to move to. + + - `keys: Optional[List[str]]` + + The keys being held while moving the mouse. + + - `class Screenshot: …` + + A screenshot action. + + - `type: Literal["screenshot"]` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `class Scroll: …` + + A scroll action. + + - `scroll_x: int` + + The horizontal scroll distance. + + - `scroll_y: int` + + The vertical scroll distance. + + - `type: Literal["scroll"]` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: int` + + The x-coordinate where the scroll occurred. + + - `y: int` + + The y-coordinate where the scroll occurred. + + - `keys: Optional[List[str]]` + + The keys being held while scrolling. + + - `class Type: …` + + An action to type in text. + + - `text: str` + + The text to type. + + - `type: Literal["type"]` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `class Wait: …` + + A wait action. + + - `type: Literal["wait"]` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + +### Beta Computer Action List + +- `List[BetaComputerAction]` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `class Click: …` + + A click action. + + - `button: Literal["left", "right", "wheel", 2 more]` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: Literal["click"]` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: int` + + The x-coordinate where the click occurred. + + - `y: int` + + The y-coordinate where the click occurred. + + - `keys: Optional[List[str]]` + + The keys being held while clicking. + + - `class DoubleClick: …` + + A double click action. + + - `keys: Optional[List[str]]` + + The keys being held while double-clicking. + + - `type: Literal["double_click"]` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: int` + + The x-coordinate where the double click occurred. + + - `y: int` + + The y-coordinate where the double click occurred. + + - `class Drag: …` + + A drag action. + + - `path: List[DragPath]` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: int` + + The x-coordinate. + + - `y: int` + + The y-coordinate. + + - `type: Literal["drag"]` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: Optional[List[str]]` + + The keys being held while dragging the mouse. + + - `class Keypress: …` + + A collection of keypresses the model would like to perform. + + - `keys: List[str]` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: Literal["keypress"]` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `class Move: …` + + A mouse move action. + + - `type: Literal["move"]` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: int` + + The x-coordinate to move to. + + - `y: int` + + The y-coordinate to move to. + + - `keys: Optional[List[str]]` + + The keys being held while moving the mouse. + + - `class Screenshot: …` + + A screenshot action. + + - `type: Literal["screenshot"]` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `class Scroll: …` + + A scroll action. + + - `scroll_x: int` + + The horizontal scroll distance. + + - `scroll_y: int` + + The vertical scroll distance. + + - `type: Literal["scroll"]` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: int` + + The x-coordinate where the scroll occurred. + + - `y: int` + + The y-coordinate where the scroll occurred. + + - `keys: Optional[List[str]]` - - `created_by: Optional[str]` + The keys being held while scrolling. - The ID of the entity that created this tool call output. + - `class Type: …` - - `output: Optional[str]` + An action to type in text. - Optional textual output returned by the apply patch tool. + - `text: str` - - `class McpCall: …` + The text to type. - An invocation of a tool on an MCP server. + - `type: Literal["type"]` - - `id: str` + Specifies the event type. For a type action, this property is always set to `type`. - The unique ID of the tool call. + - `"type"` - - `arguments: str` + - `class Wait: …` - A JSON string of the arguments passed to the tool. + A wait action. - - `name: str` + - `type: Literal["wait"]` - The name of the tool that was run. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `server_label: str` + - `"wait"` - The label of the MCP server running the tool. +### Beta Computer Tool - - `type: Literal["mcp_call"]` +- `class BetaComputerTool: …` - The type of the item. Always `mcp_call`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"mcp_call"` + - `type: Literal["computer"]` - - `agent: Optional[McpCallAgent]` + The type of the computer tool. Always `computer`. - The agent that produced this item. + - `"computer"` - - `agent_name: str` +### Beta Computer Use Preview Tool - The canonical name of the agent that produced this item. +- `class BetaComputerUsePreviewTool: …` - - `approval_request_id: Optional[str]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `display_height: int` - - `error: Optional[str]` + The height of the computer display. - The error from the tool call, if any. + - `display_width: int` - - `output: Optional[str]` + The width of the computer display. - The output from the tool call. + - `environment: Literal["windows", "mac", "linux", 2 more]` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + The type of computer environment to control. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"windows"` - - `"in_progress"` + - `"mac"` - - `"completed"` + - `"linux"` - - `"incomplete"` + - `"ubuntu"` - - `"calling"` + - `"browser"` - - `"failed"` + - `type: Literal["computer_use_preview"]` - - `class McpListTools: …` + The type of the computer use tool. Always `computer_use_preview`. - A list of tools available on an MCP server. + - `"computer_use_preview"` - - `id: str` +### Beta Container Auto - The unique ID of the list. +- `class BetaContainerAuto: …` - - `server_label: str` + - `type: Literal["container_auto"]` - The label of the MCP server. + Automatically creates a container for this request - - `tools: List[McpListToolsTool]` + - `"container_auto"` - The tools available on the server. + - `file_ids: Optional[List[str]]` - - `input_schema: object` + An optional list of uploaded files to make available to your code. - The JSON schema describing the tool's input. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `name: str` + The memory limit for the container. - The name of the tool. + - `"1g"` - - `annotations: Optional[object]` + - `"4g"` - Additional annotations about the tool. + - `"16g"` - - `description: Optional[str]` + - `"64g"` - The description of the tool. + - `network_policy: Optional[NetworkPolicy]` - - `type: Literal["mcp_list_tools"]` + Network access policy for the container. - The type of the item. Always `mcp_list_tools`. + - `class BetaContainerNetworkPolicyDisabled: …` - - `"mcp_list_tools"` + - `type: Literal["disabled"]` - - `agent: Optional[McpListToolsAgent]` + Disable outbound network access. Always `disabled`. - The agent that produced this item. + - `"disabled"` - - `agent_name: str` + - `class BetaContainerNetworkPolicyAllowlist: …` - The canonical name of the agent that produced this item. + - `allowed_domains: List[str]` - - `error: Optional[str]` + A list of allowed domains when type is `allowlist`. - Error message if the server could not list tools. + - `type: Literal["allowlist"]` - - `class McpApprovalRequest: …` + Allow outbound network access only to specified domains. Always `allowlist`. - A request for human approval of a tool invocation. + - `"allowlist"` - - `id: str` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - The unique ID of the approval request. + Optional domain-scoped secrets for allowlisted domains. - - `arguments: str` + - `domain: str` - A JSON string of arguments for the tool. + The domain associated with the secret. - `name: str` - The name of the tool to run. + The name of the secret to inject for the domain. - - `server_label: str` + - `value: str` - The label of the MCP server making the request. + The secret value to inject for the domain. - - `type: Literal["mcp_approval_request"]` + - `skills: Optional[List[Skill]]` - The type of the item. Always `mcp_approval_request`. + An optional list of skills referenced by id or inline data. - - `"mcp_approval_request"` + - `class BetaSkillReference: …` - - `agent: Optional[McpApprovalRequestAgent]` + - `skill_id: str` - The agent that produced this item. + The ID of the referenced skill. - - `agent_name: str` + - `type: Literal["skill_reference"]` - The canonical name of the agent that produced this item. + References a skill created with the /v1/skills endpoint. - - `class McpApprovalResponse: …` + - `"skill_reference"` - A response to an MCP approval request. + - `version: Optional[str]` - - `id: str` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The unique ID of the approval response + - `class BetaInlineSkill: …` - - `approval_request_id: str` + - `description: str` - The ID of the approval request being answered. + The description of the skill. - - `approve: bool` + - `name: str` - Whether the request was approved. + The name of the skill. - - `type: Literal["mcp_approval_response"]` + - `source: BetaInlineSkillSource` - The type of the item. Always `mcp_approval_response`. + Inline skill payload - - `"mcp_approval_response"` + - `data: str` - - `agent: Optional[McpApprovalResponseAgent]` + Base64-encoded skill zip bundle. - The agent that produced this item. + - `media_type: Literal["application/zip"]` - - `agent_name: str` + The media type of the inline skill payload. Must be `application/zip`. - The canonical name of the agent that produced this item. + - `"application/zip"` - - `reason: Optional[str]` + - `type: Literal["base64"]` - Optional reason for the decision. + The type of the inline skill source. Must be `base64`. - - `class BetaResponseCustomToolCall: …` + - `"base64"` - A call to a custom tool created by the model. + - `type: Literal["inline"]` - - `class BetaResponseCustomToolCallOutputItem: …` + Defines an inline skill for this request. - The output of a custom tool call from your code, being sent back to the model. + - `"inline"` - - `id: str` +### Beta Container Network Policy Allowlist - The unique ID of the custom tool call output item. +- `class BetaContainerNetworkPolicyAllowlist: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `allowed_domains: List[str]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A list of allowed domains when type is `allowlist`. - - `"in_progress"` + - `type: Literal["allowlist"]` - - `"completed"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"incomplete"` + - `"allowlist"` - - `created_by: Optional[str]` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - The identifier of the actor that created the item. + Optional domain-scoped secrets for allowlisted domains. - - `parallel_tool_calls: bool` + - `domain: str` - Whether to allow the model to run tool calls in parallel. + The domain associated with the secret. - - `temperature: Optional[float]` + - `name: str` - 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. - We generally recommend altering this or `top_p` but not both. + The name of the secret to inject for the domain. - - `tool_choice: ToolChoice` + - `value: str` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + The secret value to inject for the domain. - - `Literal["none", "auto", "required"]` +### Beta Container Network Policy Disabled - - `"none"` +- `class BetaContainerNetworkPolicyDisabled: …` - - `"auto"` + - `type: Literal["disabled"]` - - `"required"` + Disable outbound network access. Always `disabled`. - - `class BetaToolChoiceAllowed: …` + - `"disabled"` - Constrains the tools available to the model to a pre-defined set. +### Beta Container Network Policy Domain Secret - - `mode: Literal["auto", "required"]` +- `class BetaContainerNetworkPolicyDomainSecret: …` - Constrains the tools available to the model to a pre-defined set. + - `domain: str` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The domain associated with the secret. - `required` requires the model to call one or more of the allowed tools. + - `name: str` - - `"auto"` + The name of the secret to inject for the domain. - - `"required"` + - `value: str` - - `tools: List[Dict[str, object]]` + The secret value to inject for the domain. - A list of tool definitions that the model should be allowed to call. +### Beta Container Reference - For the Responses API, the list of tool definitions might look like: +- `class BetaContainerReference: …` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `container_id: str` - - `type: Literal["allowed_tools"]` + The ID of the referenced container. - Allowed tool configuration type. Always `allowed_tools`. + - `type: Literal["container_reference"]` - - `"allowed_tools"` + References a container created with the /v1/containers endpoint - - `class BetaToolChoiceTypes: …` + - `"container_reference"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). +### Beta Custom Tool - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` +- `class BetaCustomTool: …` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - Allowed values are: + - `name: str` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The name of the custom tool, used to identify it in tool calls. - - `"file_search"` + - `type: Literal["custom"]` - - `"web_search_preview"` + The type of the custom tool. Always `custom`. - - `"computer"` + - `"custom"` - - `"computer_use_preview"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"computer_use"` + The tool invocation context(s). - - `"web_search_preview_2025_03_11"` + - `"direct"` - - `"image_generation"` + - `"programmatic"` - - `"code_interpreter"` + - `defer_loading: Optional[bool]` - - `class BetaToolChoiceFunction: …` + Whether this tool should be deferred and discovered via tool search. - Use this option to force the model to call a specific function. + - `description: Optional[str]` - - `name: str` + Optional description of the custom tool, used to provide more context. - The name of the function to call. + - `format: Optional[Format]` - - `type: Literal["function"]` + The input format for the custom tool. Default is unconstrained text. - For function calling, the type is always `function`. + - `class FormatText: …` - - `"function"` + Unconstrained free-form text. - - `class BetaToolChoiceMcp: …` + - `type: Literal["text"]` - Use this option to force the model to call a specific tool on a remote MCP server. + Unconstrained text format. Always `text`. - - `server_label: str` + - `"text"` - The label of the MCP server to use. + - `class FormatGrammar: …` - - `type: Literal["mcp"]` + A grammar defined by the user. - For MCP tools, the type is always `mcp`. + - `definition: str` - - `"mcp"` + The grammar definition. - - `name: Optional[str]` + - `syntax: Literal["lark", "regex"]` - The name of the tool to call on the server. + The syntax of the grammar definition. One of `lark` or `regex`. - - `class BetaToolChoiceCustom: …` + - `"lark"` - Use this option to force the model to call a specific custom tool. + - `"regex"` - - `name: str` + - `type: Literal["grammar"]` - The name of the custom tool to call. + Grammar format. Always `grammar`. - - `type: Literal["custom"]` + - `"grammar"` - For custom tool calling, the type is always `custom`. +### Beta Easy Input Message - - `"custom"` +- `class BetaEasyInputMessage: …` - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `type: Literal["programmatic_tool_calling"]` + - `content: Union[str, BetaResponseInputMessageContentList]` - The tool to call. Always `programmatic_tool_calling`. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"programmatic_tool_calling"` + - `str` - - `class BetaToolChoiceApplyPatch: …` + A text input to the model. - Forces the model to call the apply_patch tool when executing a tool call. + - `List[BetaResponseInputContent]` - - `type: Literal["apply_patch"]` + - `class BetaResponseInputText: …` - The tool to call. Always `apply_patch`. + A text input to the model. - - `"apply_patch"` + - `text: str` - - `class BetaToolChoiceShell: …` + The text input to the model. - Forces the model to call the shell tool when a tool call is required. + - `type: Literal["input_text"]` - - `type: Literal["shell"]` + The type of the input item. Always `input_text`. - The tool to call. Always `shell`. + - `"input_text"` - - `"shell"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `tools: List[BetaTool]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `mode: Literal["explicit"]` - We support the following categories of tools: + The breakpoint mode. Always `explicit`. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `"explicit"` - - `class BetaFunctionTool: …` + - `class BetaResponseInputImage: …` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class BetaFileSearchTool: …` + - `detail: Literal["low", "high", "auto", "original"]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `class BetaComputerTool: …` + - `"low"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"high"` - - `class BetaComputerUsePreviewTool: …` + - `"auto"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"original"` - - `class BetaWebSearchTool: …` + - `type: Literal["input_image"]` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The type of the input item. Always `input_image`. - - `class Mcp: …` + - `"input_image"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `file_id: Optional[str]` - - `class CodeInterpreter: …` + The ID of the file to be sent to the model. - A tool that runs Python code to help generate a response to a prompt. + - `image_url: Optional[str]` - - `class ProgrammaticToolCalling: …` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `class ImageGeneration: …` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - A tool that generates images using the GPT image models. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class LocalShell: …` + - `mode: Literal["explicit"]` - A tool that allows the model to execute shell commands in a local environment. + The breakpoint mode. Always `explicit`. - - `class BetaFunctionShellTool: …` + - `"explicit"` - A tool that allows the model to execute shell commands. + - `class BetaResponseInputFile: …` - - `class BetaCustomTool: …` + A file input to the model. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: Literal["input_file"]` - - `class BetaNamespaceTool: …` + The type of the input item. Always `input_file`. - Groups function/custom tools under a shared namespace. + - `"input_file"` - - `class BetaToolSearchTool: …` + - `detail: Optional[Literal["auto", "low", "high"]]` - Hosted or BYOT tool search configuration for deferred tools. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `class BetaWebSearchPreviewTool: …` + - `"auto"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"low"` - - `class BetaApplyPatchTool: …` + - `"high"` - Allows the assistant to create, delete, or update files using unified diffs. + - `file_data: Optional[str]` - - `top_p: Optional[float]` + The content of the file to be sent to the model. - 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. + - `file_id: Optional[str]` - We generally recommend altering this or `temperature` but not both. + The ID of the file to be sent to the model. - - `background: Optional[bool]` + - `file_url: Optional[str]` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The URL of the file to be sent to the model. - - `completed_at: Optional[float]` + - `filename: Optional[str]` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The name of the file to be sent to the model. - - `conversation: Optional[Conversation]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `id: str` + - `mode: Literal["explicit"]` - The unique ID of the conversation that this response was associated with. + The breakpoint mode. Always `explicit`. - - `max_output_tokens: Optional[int]` + - `"explicit"` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `role: Literal["user", "assistant", "system", "developer"]` - - `max_tool_calls: Optional[int]` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `"user"` - - `moderation: Optional[Moderation]` + - `"assistant"` - Moderation results for the response input and output, if moderated completions were requested. + - `"system"` - - `input: ModerationInput` + - `"developer"` - Moderation for the response input. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `class ModerationInputModerationResult: …` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - A moderation result produced for the response input or output. + - `"commentary"` - - `categories: Dict[str, bool]` + - `"final_answer"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `type: Optional[Literal["message"]]` - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + The type of the message input. Always `message`. - Which modalities of input are reflected by the score for each category. + - `"message"` - - `"text"` +### Beta File Search Tool - - `"image"` +- `class BetaFileSearchTool: …` - - `category_scores: Dict[str, float]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - A dictionary of moderation categories to scores. + - `type: Literal["file_search"]` - - `flagged: bool` + The type of the file search tool. Always `file_search`. - A boolean indicating whether the content was flagged by any category. + - `"file_search"` - - `model: str` + - `vector_store_ids: List[str]` - The moderation model that produced this result. + The IDs of the vector stores to search. - - `type: Literal["moderation_result"]` + - `filters: Optional[Filters]` - The object type, which was always `moderation_result` for successful moderation results. + A filter to apply. - - `"moderation_result"` + - `class FiltersComparisonFilter: …` - - `class ModerationInputError: …` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - An error produced while attempting moderation for the response input or output. + - `key: str` - - `code: str` + The key to compare against the value. - The error code. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `message: str` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The error message. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `type: Literal["error"]` + - `"eq"` - The object type, which was always `error` for moderation failures. + - `"ne"` - - `"error"` + - `"gt"` - - `output: ModerationOutput` + - `"gte"` - Moderation for the response output. + - `"lt"` - - `class ModerationOutputModerationResult: …` + - `"lte"` - A moderation result produced for the response input or output. + - `"in"` - - `categories: Dict[str, bool]` + - `"nin"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + The value to compare against the attribute key; supports string, number, or boolean types. - Which modalities of input are reflected by the score for each category. + - `str` - - `"text"` + - `float` - - `"image"` + - `bool` - - `category_scores: Dict[str, float]` + - `List[Union[str, float]]` - A dictionary of moderation categories to scores. + - `str` - - `flagged: bool` + - `float` - A boolean indicating whether the content was flagged by any category. + - `class FiltersCompoundFilter: …` - - `model: str` + Combine multiple filters using `and` or `or`. - The moderation model that produced this result. + - `filters: List[FiltersCompoundFilterFilter]` - - `type: Literal["moderation_result"]` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The object type, which was always `moderation_result` for successful moderation results. + - `class FiltersCompoundFilterFilterComparisonFilter: …` - - `"moderation_result"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `class ModerationOutputError: …` + - `key: str` - An error produced while attempting moderation for the response input or output. + The key to compare against the value. - - `code: str` + - `type: Literal["eq", "ne", "gt", 5 more]` - The error code. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `message: str` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The error message. + - `"eq"` - - `type: Literal["error"]` + - `"ne"` - The object type, which was always `error` for moderation failures. + - `"gt"` - - `"error"` + - `"gte"` - - `previous_response_id: Optional[str]` + - `"lt"` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `"lte"` - - `prompt: Optional[BetaResponsePrompt]` + - `"in"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `"nin"` - - `id: str` + - `value: Union[str, float, bool, List[Union[str, float]]]` - The unique identifier of the prompt template to use. + The value to compare against the attribute key; supports string, number, or boolean types. - - `variables: Optional[Dict[str, Variables]]` + - `str` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `float` + + - `bool` + + - `List[Union[str, float]]` - `str` - - `class BetaResponseInputText: …` + - `float` - A text input to the model. + - `object` - - `class BetaResponseInputImage: …` + - `type: Literal["and", "or"]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Type of operation: `and` or `or`. - - `class BetaResponseInputFile: …` + - `"and"` - A file input to the model. + - `"or"` - - `version: Optional[str]` + - `max_num_results: Optional[int]` - Optional version of the prompt template. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `prompt_cache_key: Optional[str]` + - `ranking_options: Optional[RankingOptions]` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + Ranking options for search. - - `prompt_cache_options: Optional[PromptCacheOptions]` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `mode: Literal["implicit", "explicit"]` + - `embedding_weight: float` - Whether implicit prompt-cache breakpoints were enabled. + The weight of the embedding in the reciprocal ranking fusion. - - `"implicit"` + - `text_weight: float` - - `"explicit"` + The weight of the text in the reciprocal ranking fusion. - - `ttl: Literal["30m"]` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - The minimum lifetime applied to each cache breakpoint. + The ranker to use for the file search. - - `"30m"` + - `"auto"` - - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + - `"default-2024-11-15"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `score_threshold: Optional[float]` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: +### Beta Function Shell Tool - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. +- `class BetaFunctionShellTool: …` - - `"in_memory"` + A tool that allows the model to execute shell commands. - - `"24h"` + - `type: Literal["shell"]` - - `reasoning: Optional[Reasoning]` + The type of the shell tool. Always `shell`. - **gpt-5 and o-series models only** + - `"shell"` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + The tool invocation context(s). - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `"direct"` - - `"auto"` + - `"programmatic"` - - `"current_turn"` + - `environment: Optional[Environment]` - - `"all_turns"` + - `class BetaContainerAuto: …` - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + - `type: Literal["container_auto"]` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + Automatically creates a container for this request - - `"none"` + - `"container_auto"` - - `"minimal"` + - `file_ids: Optional[List[str]]` - - `"low"` + An optional list of uploaded files to make available to your code. - - `"medium"` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `"high"` + The memory limit for the container. - - `"xhigh"` + - `"1g"` - - `"max"` + - `"4g"` - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + - `"16g"` - **Deprecated:** use `summary` instead. + - `"64g"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `network_policy: Optional[NetworkPolicy]` - - `"auto"` + Network access policy for the container. - - `"concise"` + - `class BetaContainerNetworkPolicyDisabled: …` - - `"detailed"` + - `type: Literal["disabled"]` - - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + Disable outbound network access. Always `disabled`. - Controls the reasoning execution mode for the request. + - `"disabled"` - When returned on a response, this is the effective execution mode. + - `class BetaContainerNetworkPolicyAllowlist: …` - - `str` + - `allowed_domains: List[str]` - - `Literal["standard", "pro"]` + A list of allowed domains when type is `allowlist`. - Controls the reasoning execution mode for the request. + - `type: Literal["allowlist"]` - When returned on a response, this is the effective execution mode. + Allow outbound network access only to specified domains. Always `allowlist`. - - `"standard"` + - `"allowlist"` - - `"pro"` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + Optional domain-scoped secrets for allowlisted domains. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `domain: str` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The domain associated with the secret. - - `"auto"` + - `name: str` - - `"concise"` + The name of the secret to inject for the domain. - - `"detailed"` + - `value: str` - - `safety_identifier: Optional[str]` + The secret value to inject for the domain. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `skills: Optional[List[Skill]]` - - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + An optional list of skills referenced by id or inline data. - Specifies the processing type used for serving the request. + - `class BetaSkillReference: …` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `skill_id: str` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + The ID of the referenced skill. - - `"auto"` + - `type: Literal["skill_reference"]` - - `"default"` + References a skill created with the /v1/skills endpoint. - - `"flex"` + - `"skill_reference"` - - `"scale"` + - `version: Optional[str]` - - `"priority"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `status: Optional[BetaResponseStatus]` + - `class BetaInlineSkill: …` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `description: str` - - `"completed"` + The description of the skill. - - `"failed"` + - `name: str` - - `"in_progress"` + The name of the skill. - - `"cancelled"` + - `source: BetaInlineSkillSource` - - `"queued"` + Inline skill payload - - `"incomplete"` + - `data: str` - - `text: Optional[BetaResponseTextConfig]` + Base64-encoded skill zip bundle. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `media_type: Literal["application/zip"]` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The media type of the inline skill payload. Must be `application/zip`. - - `format: Optional[BetaResponseFormatTextConfig]` + - `"application/zip"` - An object specifying the format that the model must output. + - `type: Literal["base64"]` - Configuring `{ "type": "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). + The type of the inline skill source. Must be `base64`. - The default format is `{ "type": "text" }` with no additional options. + - `"base64"` - **Not recommended for gpt-4o and newer models:** + - `type: Literal["inline"]` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + Defines an inline skill for this request. - - `class Text: …` + - `"inline"` - Default response format. Used to generate text responses. + - `class BetaLocalEnvironment: …` - - `type: Literal["text"]` + - `type: Literal["local"]` - The type of response format being defined. Always `text`. + Use a local computer environment. - - `"text"` + - `"local"` - - `class BetaResponseFormatTextJSONSchemaConfig: …` + - `skills: Optional[List[BetaLocalSkill]]` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + An optional list of skills. + + - `description: str` + + The description of the skill. - `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. + The name of the skill. - - `schema: Dict[str, object]` + - `path: str` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The path to the directory containing the skill. - - `type: Literal["json_schema"]` + - `class BetaContainerReference: …` - The type of response format being defined. Always `json_schema`. + - `container_id: str` - - `"json_schema"` + The ID of the referenced container. - - `description: Optional[str]` + - `type: Literal["container_reference"]` - A description of what the response format is for, used by the model to - determine how to respond in the format. + References a container created with the /v1/containers endpoint - - `strict: Optional[bool]` + - `"container_reference"` - 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). +### Beta Function Tool - - `class JSONObject: …` +- `class BetaFunctionTool: …` - 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. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `type: Literal["json_object"]` + - `name: str` - The type of response format being defined. Always `json_object`. + The name of the function to call. - - `"json_object"` + - `parameters: Optional[Dict[str, object]]` - - `verbosity: Optional[Literal["low", "medium", "high"]]` + A JSON schema object describing the parameters of the function. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `strict: Optional[bool]` - - `"low"` + Whether strict parameter validation is enforced for this function tool. - - `"medium"` + - `type: Literal["function"]` - - `"high"` + The type of the function tool. Always `function`. - - `top_logprobs: Optional[int]` + - `"function"` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `truncation: Optional[Literal["auto", "disabled"]]` + The tool invocation context(s). - The truncation strategy to use for the model response. + - `"direct"` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `"programmatic"` - - `"auto"` + - `defer_loading: Optional[bool]` - - `"disabled"` + Whether this function is deferred and loaded via tool search. - - `usage: Optional[BetaResponseUsage]` + - `description: Optional[str]` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + A description of the function. Used by the model to determine whether or not to call the function. - - `input_tokens: int` + - `output_schema: Optional[Dict[str, object]]` - The number of input tokens. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `input_tokens_details: InputTokensDetails` +### Beta Inline Skill - A detailed breakdown of the input tokens. +- `class BetaInlineSkill: …` - - `cache_write_tokens: int` + - `description: str` - The number of input tokens that were written to the cache. + The description of the skill. - - `cached_tokens: int` + - `name: str` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The name of the skill. - - `output_tokens: int` + - `source: BetaInlineSkillSource` - The number of output tokens. + Inline skill payload - - `output_tokens_details: OutputTokensDetails` + - `data: str` - A detailed breakdown of the output tokens. + Base64-encoded skill zip bundle. - - `reasoning_tokens: int` + - `media_type: Literal["application/zip"]` - The number of reasoning tokens. + The media type of the inline skill payload. Must be `application/zip`. - - `total_tokens: int` + - `"application/zip"` - The total number of tokens used. + - `type: Literal["base64"]` - - `user: Optional[str]` + The type of the inline skill source. Must be `base64`. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"base64"` -### Example + - `type: Literal["inline"]` -```python -import os -from openai import OpenAI + Defines an inline skill for this request. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -for response in client.beta.responses.create(): - print(response) -``` + - `"inline"` + +### Beta Inline Skill Source -#### Response +- `class BetaInlineSkillSource: …` -```json -{ - "id": "id", - "created_at": 0, - "error": { - "code": "server_error", - "message": "message" - }, - "incomplete_details": { - "reason": "max_output_tokens" - }, - "instructions": "string", - "metadata": { - "foo": "string" - }, - "model": "gpt-5.1", - "object": "response", - "output": [ - { - "id": "id", - "content": [ - { - "annotations": [ - { - "file_id": "file_id", - "filename": "filename", - "index": 0, - "type": "file_citation" - } - ], - "text": "text", - "type": "output_text", - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ] - } - ], - "role": "assistant", - "status": "in_progress", - "type": "message", - "agent": { - "agent_name": "agent_name" - }, - "phase": "commentary" - } - ], - "parallel_tool_calls": true, - "temperature": 1, - "tool_choice": "none", - "tools": [ - { - "name": "name", - "parameters": { - "foo": "bar" - }, - "strict": true, - "type": "function", - "allowed_callers": [ - "direct" - ], - "defer_loading": true, - "description": "description", - "output_schema": { - "foo": "bar" - } - } - ], - "top_p": 1, - "background": true, - "completed_at": 0, - "conversation": { - "id": "id" - }, - "max_output_tokens": 0, - "max_tool_calls": 0, - "moderation": { - "input": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - }, - "output": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - } - }, - "output_text": "output_text", - "previous_response_id": "previous_response_id", - "prompt": { - "id": "id", - "variables": { - "foo": "string" - }, - "version": "version" - }, - "prompt_cache_key": "prompt-cache-key-1234", - "prompt_cache_options": { - "mode": "implicit", - "ttl": "30m" - }, - "prompt_cache_retention": "in_memory", - "reasoning": { - "context": "auto", - "effort": "none", - "generate_summary": "auto", - "mode": "standard", - "summary": "auto" - }, - "safety_identifier": "safety-identifier-1234", - "service_tier": "auto", - "status": "completed", - "text": { - "format": { - "type": "text" - }, - "verbosity": "low" - }, - "top_logprobs": 0, - "truncation": "auto", - "usage": { - "input_tokens": 0, - "input_tokens_details": { - "cache_write_tokens": 0, - "cached_tokens": 0 - }, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - }, - "user": "user-1234" -} -``` + Inline skill payload -### Text input + - `data: str` -```python -from openai import OpenAI + Base64-encoded skill zip bundle. -client = OpenAI() + - `media_type: Literal["application/zip"]` -response = client.responses.create( - model="gpt-5.4", - input="Tell me a three sentence bedtime story about a unicorn." -) + The media type of the inline skill payload. Must be `application/zip`. -print(response) -``` + - `"application/zip"` -#### Response + - `type: Literal["base64"]` -```json -{ - "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b", - "object": "response", - "created_at": 1741476542, - "status": "completed", - "completed_at": 1741476543, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-5.4", - "output": [ - { - "type": "message", - "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "In a peaceful grove beneath a silver moon, a unicorn named Lumina discovered a hidden pool that reflected the stars. As she dipped her horn into the water, the pool began to shimmer, revealing a pathway to a magical realm of endless night skies. Filled with wonder, Lumina whispered a wish for all who dream to find their own hidden magic, and as she glanced back, her hoofprints sparkled like stardust.", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 36, - "input_tokens_details": { - "cached_tokens": 0 - }, - "output_tokens": 87, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 123 - }, - "user": null, - "metadata": {} -} -``` + The type of the inline skill source. Must be `base64`. -### Image input + - `"base64"` -```python -from openai import OpenAI +### Beta Local Environment -client = OpenAI() +- `class BetaLocalEnvironment: …` -response = client.responses.create( - model="gpt-5.4", - input=[ - { - "role": "user", - "content": [ - { "type": "input_text", "text": "what is in this image?" }, - { - "type": "input_image", - "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" - } - ] - } - ] -) + - `type: Literal["local"]` -print(response) -``` + Use a local computer environment. -#### Response + - `"local"` -```json -{ - "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", - "object": "response", - "created_at": 1741476777, - "status": "completed", - "completed_at": 1741476778, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-5.4", - "output": [ - { - "type": "message", - "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 328, - "input_tokens_details": { - "cached_tokens": 0 - }, - "output_tokens": 52, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 380 - }, - "user": null, - "metadata": {} -} -``` + - `skills: Optional[List[BetaLocalSkill]]` -### File input + An optional list of skills. -```python -from openai import OpenAI + - `description: str` -client = OpenAI() + The description of the skill. -response = client.responses.create( - model="gpt-5.4", - input=[ - { - "role": "user", - "content": [ - { "type": "input_text", "text": "what is in this file?" }, - { - "type": "input_file", - "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf", - "detail": "auto" - } - ] - } - ] -) + - `name: str` -print(response) -``` + The name of the skill. -#### Response + - `path: str` -```json -{ - "id": "resp_686eef60237881a2bd1180bb8b13de430e34c516d176ff86", - "object": "response", - "created_at": 1752100704, - "status": "completed", - "completed_at": 1752100705, - "background": false, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "max_tool_calls": null, - "model": "gpt-5.4", - "output": [ - { - "id": "msg_686eef60d3e081a29283bdcbc4322fd90e34c516d176ff86", - "type": "message", - "status": "completed", - "content": [ - { - "type": "output_text", - "annotations": [], - "logprobs": [], - "text": "The file seems to contain excerpts from a letter to the shareholders of Berkshire Hathaway Inc., likely written by Warren Buffett. It covers several topics:\n\n1. **Communication Philosophy**: Buffett emphasizes the importance of transparency and candidness in reporting mistakes and successes to shareholders.\n\n2. **Mistakes and Learnings**: The letter acknowledges past mistakes in business assessments and management hires, highlighting the importance of correcting errors promptly.\n\n3. **CEO Succession**: Mention of Greg Abel stepping in as the new CEO and continuing the tradition of honest communication.\n\n4. **Pete Liegl Story**: A detailed account of acquiring Forest River and the relationship with its founder, highlighting trust and effective business decisions.\n\n5. **2024 Performance**: Overview of business performance, particularly in insurance and investment activities, with a focus on GEICO's improvement.\n\n6. **Tax Contributions**: Discussion of significant tax payments to the U.S. Treasury, credited to shareholders' reinvestments.\n\n7. **Investment Strategy**: A breakdown of Berkshire\u2019s investments in both controlled subsidiaries and marketable equities, along with a focus on long-term holding strategies.\n\n8. **American Capitalism**: Reflections on America\u2019s economic development and Berkshire\u2019s role within it.\n\n9. **Property-Casualty Insurance**: Insights into the P/C insurance business model and its challenges and benefits.\n\n10. **Japanese Investments**: Information about Berkshire\u2019s investments in Japanese companies and future plans.\n\n11. **Annual Meeting**: Details about the upcoming annual gathering in Omaha, including schedule changes and new book releases.\n\n12. **Personal Anecdotes**: Light-hearted stories about family and interactions, conveying Buffett's personable approach.\n\n13. **Financial Performance Data**: Tables comparing Berkshire\u2019s annual performance to the S&P 500, showing impressive long-term gains.\n\nOverall, the letter reinforces Berkshire Hathaway's commitment to transparency, investment in both its businesses and the wider economy, and emphasizes strong leadership and prudent financial management." - } - ], - "role": "assistant" - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "service_tier": "default", - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_logprobs": 0, - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 8438, - "input_tokens_details": { - "cached_tokens": 0 - }, - "output_tokens": 398, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 8836 - }, - "user": null, - "metadata": {} -} -``` + The path to the directory containing the skill. -### Web search +### Beta Local Skill -```python -from openai import OpenAI +- `class BetaLocalSkill: …` -client = OpenAI() + - `description: str` -response = client.responses.create( - model="gpt-5.4", - tools=[{ "type": "web_search_preview" }], - input="What was a positive news story from today?", -) + The description of the skill. -print(response) -``` + - `name: str` -#### Response + The name of the skill. -```json -{ - "id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c", - "object": "response", - "created_at": 1741484430, - "status": "completed", - "completed_at": 1741484431, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-5.4", - "output": [ - { - "type": "web_search_call", - "id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c", - "status": "completed" - }, - { - "type": "message", - "id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "As of today, March 9, 2025, one notable positive news story...", - "annotations": [ - { - "type": "url_citation", - "start_index": 442, - "end_index": 557, - "url": "https://.../?utm_source=chatgpt.com", - "title": "..." - }, - { - "type": "url_citation", - "start_index": 962, - "end_index": 1077, - "url": "https://.../?utm_source=chatgpt.com", - "title": "..." - }, - { - "type": "url_citation", - "start_index": 1336, - "end_index": 1451, - "url": "https://.../?utm_source=chatgpt.com", - "title": "..." - } - ] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [ - { - "type": "web_search_preview", - "domains": [], - "search_context_size": "medium", - "user_location": { - "type": "approximate", - "city": null, - "country": "US", - "region": null, - "timezone": null - } - } - ], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 328, - "input_tokens_details": { - "cached_tokens": 0 - }, - "output_tokens": 356, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 684 - }, - "user": null, - "metadata": {} -} -``` + - `path: str` -### File search + The path to the directory containing the skill. -```python -from openai import OpenAI +### Beta Namespace Tool -client = OpenAI() +- `class BetaNamespaceTool: …` -response = client.responses.create( - model="gpt-5.4", - tools=[{ - "type": "file_search", - "vector_store_ids": ["vs_1234567890"], - "max_num_results": 20 - }], - input="What are the attributes of an ancient brown dragon?", -) + Groups function/custom tools under a shared namespace. -print(response) -``` + - `description: str` -#### Response + A description of the namespace shown to the model. -```json -{ - "id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7", - "object": "response", - "created_at": 1741485253, - "status": "completed", - "completed_at": 1741485254, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-5.4", - "output": [ - { - "type": "file_search_call", - "id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7", - "status": "completed", - "queries": [ - "attributes of an ancient brown dragon" - ], - "results": null - }, - { - "type": "message", - "id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "The attributes of an ancient brown dragon include...", - "annotations": [ - { - "type": "file_citation", - "index": 320, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 576, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 815, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 815, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 1030, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 1030, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 1156, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 1225, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - } - ] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [ - { - "type": "file_search", - "filters": null, - "max_num_results": 20, - "ranking_options": { - "ranker": "auto", - "score_threshold": 0.0 - }, - "vector_store_ids": [ - "vs_1234567890" - ] - } - ], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 18307, - "input_tokens_details": { - "cached_tokens": 0 - }, - "output_tokens": 348, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 18655 - }, - "user": null, - "metadata": {} -} -``` + - `name: str` -### Streaming + The namespace name used in tool calls (for example, `crm`). -```python -from openai import OpenAI + - `tools: List[Tool]` -client = OpenAI() + The function/custom tools available inside this namespace. -response = client.responses.create( - model="gpt-5.4", - instructions="You are a helpful assistant.", - input="Hello!", - stream=True -) + - `class ToolFunction: …` -for event in response: - print(event) -``` + - `name: str` -#### Response + - `type: Literal["function"]` -```json -event: response.created -data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}} + - `"function"` -event: response.in_progress -data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}} + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` -event: response.output_item.added -data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}} + The tool invocation context(s). -event: response.content_part.added -data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}} + - `"direct"` -event: response.output_text.delta -data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hi"} + - `"programmatic"` -... + - `defer_loading: Optional[bool]` -event: response.output_text.done -data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"Hi there! How can I assist you today?"} + Whether this function should be deferred and discovered via tool search. -event: response.content_part.done -data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}} + - `description: Optional[str]` -event: response.output_item.done -data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}} + - `output_schema: Optional[Dict[str, object]]` -event: response.completed -data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}} -``` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. -### Functions + - `parameters: Optional[object]` -```python -from openai import OpenAI + - `strict: Optional[bool]` -client = OpenAI() + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. -tools = [ - { - "type": "function", - "name": "get_current_weather", - "description": "Get the current weather in a given location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA", - }, - "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, - }, - "required": ["location", "unit"], - } - } -] + - `class BetaCustomTool: …` -response = client.responses.create( - model="gpt-5.4", - tools=tools, - input="What is the weather like in Boston today?", - tool_choice="auto" -) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) -print(response) -``` + - `name: str` -#### Response + The name of the custom tool, used to identify it in tool calls. -```json -{ - "id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0", - "object": "response", - "created_at": 1741294021, - "status": "completed", - "completed_at": 1741294022, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-5.4", - "output": [ - { - "type": "function_call", - "id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0", - "call_id": "call_unLAR8MvFNptuiZK6K6HCy5k", - "name": "get_current_weather", - "arguments": "{\"location\":\"Boston, MA\",\"unit\":\"celsius\"}", - "status": "completed" - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [ - { - "type": "function", - "description": "Get the current weather in a given location", - "name": "get_current_weather", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA" - }, - "unit": { - "type": "string", - "enum": [ - "celsius", - "fahrenheit" - ] - } - }, - "required": [ - "location", - "unit" - ] - }, - "strict": true - } - ], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 291, - "output_tokens": 23, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 314 - }, - "user": null, - "metadata": {} -} -``` + - `type: Literal["custom"]` -### Reasoning + The type of the custom tool. Always `custom`. -```python -from openai import OpenAI -client = OpenAI() + - `"custom"` -response = client.responses.create( - model="o3-mini", - input="How much wood would a woodchuck chuck?", - reasoning={ - "effort": "high" - } -) + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` -print(response) -``` + The tool invocation context(s). -#### Response + - `"direct"` -```json -{ - "id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808", - "object": "response", - "created_at": 1741477868, - "status": "completed", - "completed_at": 1741477869, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "o1-2024-12-17", - "output": [ - { - "type": "message", - "id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "The classic tongue twister...", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": "high", - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 81, - "input_tokens_details": { - "cached_tokens": 0 - }, - "output_tokens": 1035, - "output_tokens_details": { - "reasoning_tokens": 832 - }, - "total_tokens": 1116 - }, - "user": null, - "metadata": {} -} -``` + - `"programmatic"` -## Get a model response + - `defer_loading: Optional[bool]` -`beta.responses.retrieve(strresponse_id, ResponseRetrieveParams**kwargs) -> BetaResponse` + Whether this tool should be deferred and discovered via tool search. -**get** `/responses/{response_id}?beta=true` + - `description: Optional[str]` -Get a model response + Optional description of the custom tool, used to provide more context. -### Parameters + - `format: Optional[Format]` -- `response_id: str` + The input format for the custom tool. Default is unconstrained text. -- `include: Optional[List[BetaResponseIncludable]]` + - `class FormatText: …` - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. + Unconstrained free-form text. - - `"file_search_call.results"` + - `type: Literal["text"]` - - `"web_search_call.results"` + Unconstrained text format. Always `text`. - - `"web_search_call.action.sources"` + - `"text"` - - `"message.input_image.image_url"` + - `class FormatGrammar: …` - - `"computer_call_output.output.image_url"` + A grammar defined by the user. - - `"code_interpreter_call.outputs"` + - `definition: str` - - `"reasoning.encrypted_content"` + The grammar definition. - - `"message.output_text.logprobs"` + - `syntax: Literal["lark", "regex"]` -- `include_obfuscation: Optional[bool]` + The syntax of the grammar definition. One of `lark` or `regex`. - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events - to normalize payload sizes as a mitigation to certain side-channel - attacks. These obfuscation fields are included by default, but add a - small amount of overhead to the data stream. You can set - `include_obfuscation` to false to optimize for bandwidth if you trust - the network links between your application and the OpenAI API. + - `"lark"` -- `starting_after: Optional[int]` + - `"regex"` - The sequence number of the event after which to start streaming. + - `type: Literal["grammar"]` -- `stream: Optional[Literal[false]]` + Grammar format. Always `grammar`. - If set to true, the model response data will be streamed to the client - as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). - See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) - for more information. + - `"grammar"` - - `false` + - `type: Literal["namespace"]` -- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` + The type of the tool. Always `namespace`. - - `"responses_multi_agent=v1"` + - `"namespace"` -### Returns +### Beta Response - `class BetaResponse: …` @@ -28113,7 +38977,7 @@ Get a model response - `"developer"` - - `phase: Optional[Literal["commentary"]]` + - `phase: Optional[Literal["commentary", "final_answer"]]` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -28121,6 +38985,8 @@ Get a model response - `"commentary"` + - `"final_answer"` + - `type: Optional[Literal["message"]]` The type of the message input. Always `message`. @@ -28372,7 +39238,7 @@ Get a model response The canonical name of the agent that produced this item. - - `phase: Optional[Literal["commentary"]]` + - `phase: Optional[Literal["commentary", "final_answer"]]` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -28380,6 +39246,8 @@ Get a model response - `"commentary"` + - `"final_answer"` + - `class BetaResponseFileSearchToolCall: …` The results of a file search tool call. See the @@ -29550,7 +40418,7 @@ Get a model response - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -29560,7 +40428,11 @@ Get a model response - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `class FiltersCompoundFilter: …` @@ -29607,7 +40479,7 @@ Get a model response - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -29617,7 +40489,11 @@ Get a model response - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `object` @@ -34303,337 +45179,604 @@ Get a model response A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). -### Example +### Beta Response Apply Patch Tool Call -```python -import os -from openai import OpenAI +- `class BetaResponseApplyPatchToolCall: …` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -for response in client.beta.responses.retrieve( - response_id="resp_677efb5139a88190b512bc3fef8e535d", -): - print(response) -``` + A tool call that applies file diffs by creating, deleting, or updating files. -#### Response + - `id: str` -```json -{ - "id": "id", - "created_at": 0, - "error": { - "code": "server_error", - "message": "message" - }, - "incomplete_details": { - "reason": "max_output_tokens" - }, - "instructions": "string", - "metadata": { - "foo": "string" - }, - "model": "gpt-5.1", - "object": "response", - "output": [ - { - "id": "id", - "content": [ - { - "annotations": [ - { - "file_id": "file_id", - "filename": "filename", - "index": 0, - "type": "file_citation" - } - ], - "text": "text", - "type": "output_text", - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ] - } - ], - "role": "assistant", - "status": "in_progress", - "type": "message", - "agent": { - "agent_name": "agent_name" - }, - "phase": "commentary" - } - ], - "parallel_tool_calls": true, - "temperature": 1, - "tool_choice": "none", - "tools": [ - { - "name": "name", - "parameters": { - "foo": "bar" - }, - "strict": true, - "type": "function", - "allowed_callers": [ - "direct" - ], - "defer_loading": true, - "description": "description", - "output_schema": { - "foo": "bar" - } - } - ], - "top_p": 1, - "background": true, - "completed_at": 0, - "conversation": { - "id": "id" - }, - "max_output_tokens": 0, - "max_tool_calls": 0, - "moderation": { - "input": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - }, - "output": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - } - }, - "output_text": "output_text", - "previous_response_id": "previous_response_id", - "prompt": { - "id": "id", - "variables": { - "foo": "string" - }, - "version": "version" - }, - "prompt_cache_key": "prompt-cache-key-1234", - "prompt_cache_options": { - "mode": "implicit", - "ttl": "30m" - }, - "prompt_cache_retention": "in_memory", - "reasoning": { - "context": "auto", - "effort": "none", - "generate_summary": "auto", - "mode": "standard", - "summary": "auto" - }, - "safety_identifier": "safety-identifier-1234", - "service_tier": "auto", - "status": "completed", - "text": { - "format": { - "type": "text" - }, - "verbosity": "low" - }, - "top_logprobs": 0, - "truncation": "auto", - "usage": { - "input_tokens": 0, - "input_tokens_details": { - "cache_write_tokens": 0, - "cached_tokens": 0 - }, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - }, - "user": "user-1234" -} -``` + The unique ID of the apply patch tool call. Populated when this item is returned via API. -### Example + - `call_id: str` -```python -from openai import OpenAI -client = OpenAI() + The unique ID of the apply patch tool call generated by the model. -response = client.responses.retrieve("resp_123") -print(response) -``` + - `operation: Operation` -#### Response + One of the create_file, delete_file, or update_file operations applied via apply_patch. -```json -{ - "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", - "object": "response", - "created_at": 1741386163, - "status": "completed", - "completed_at": 1741386164, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-4o-2024-08-06", - "output": [ - { - "type": "message", - "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 32, - "input_tokens_details": { - "cached_tokens": 0 - }, - "output_tokens": 18, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 50 - }, - "user": null, - "metadata": {} -} -``` + - `class OperationCreateFile: …` -## Delete a model response + Instruction describing how to create a file via the apply_patch tool. -`beta.responses.delete(strresponse_id, ResponseDeleteParams**kwargs)` + - `diff: str` -**delete** `/responses/{response_id}?beta=true` + Diff to apply. -Delete a model response + - `path: str` -### Parameters + Path of the file to create. -- `response_id: str` + - `type: Literal["create_file"]` -- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` + Create a new file with the provided diff. - - `"responses_multi_agent=v1"` + - `"create_file"` -### Example + - `class OperationDeleteFile: …` -```python -import os -from openai import OpenAI + Instruction describing how to delete a file via the apply_patch tool. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -client.beta.responses.delete( - response_id="resp_677efb5139a88190b512bc3fef8e535d", -) -``` + - `path: str` -### Example + Path of the file to delete. -```python -from openai import OpenAI -client = OpenAI() + - `type: Literal["delete_file"]` -response = client.responses.delete("resp_123") -print(response) -``` + Delete the specified file. -#### Response + - `"delete_file"` -```json -{ - "id": "resp_6786a1bec27481909a17d673315b29f6", - "object": "response", - "deleted": true -} -``` + - `class OperationUpdateFile: …` -## Cancel a response + Instruction describing how to update a file via the apply_patch tool. -`beta.responses.cancel(strresponse_id, ResponseCancelParams**kwargs) -> BetaResponse` + - `diff: str` -**post** `/responses/{response_id}/cancel?beta=true` + Diff to apply. -Cancel a response + - `path: str` -### Parameters + Path of the file to update. -- `response_id: str` + - `type: Literal["update_file"]` -- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` + Update an existing file with the provided diff. - - `"responses_multi_agent=v1"` + - `"update_file"` -### Returns + - `status: Literal["in_progress", "completed"]` -- `class BetaResponse: …` + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: Literal["apply_patch_call"]` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `created_by: Optional[str]` + + The ID of the entity that created this tool call. + +### Beta Response Apply Patch Tool Call Output + +- `class BetaResponseApplyPatchToolCallOutput: …` + + The output emitted by an apply patch tool call. + + - `id: str` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `call_id: str` + + The unique ID of the apply patch tool call generated by the model. + + - `status: Literal["completed", "failed"]` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: Literal["apply_patch_call_output"]` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `created_by: Optional[str]` + + The ID of the entity that created this tool call output. + + - `output: Optional[str]` + + Optional textual output returned by the apply patch tool. + +### Beta Response Audio Delta Event + +- `class BetaResponseAudioDeltaEvent: …` + + Emitted when there is a partial audio response. + + - `delta: str` + + A chunk of Base64 encoded response audio bytes. + + - `sequence_number: int` + + A sequence number for this chunk of the stream response. + + - `type: Literal["response.audio.delta"]` + + The type of the event. Always `response.audio.delta`. + + - `"response.audio.delta"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + +### Beta Response Audio Done Event + +- `class BetaResponseAudioDoneEvent: …` + + Emitted when the audio response is complete. + + - `sequence_number: int` + + The sequence number of the delta. + + - `type: Literal["response.audio.done"]` + + The type of the event. Always `response.audio.done`. + + - `"response.audio.done"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + +### Beta Response Audio Transcript Delta Event + +- `class BetaResponseAudioTranscriptDeltaEvent: …` + + Emitted when there is a partial transcript of audio. + + - `delta: str` + + The partial transcript of the audio response. + + - `sequence_number: int` + + The sequence number of this event. + + - `type: Literal["response.audio.transcript.delta"]` + + The type of the event. Always `response.audio.transcript.delta`. + + - `"response.audio.transcript.delta"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + +### Beta Response Audio Transcript Done Event + +- `class BetaResponseAudioTranscriptDoneEvent: …` + + Emitted when the full audio transcript is completed. + + - `sequence_number: int` + + The sequence number of this event. + + - `type: Literal["response.audio.transcript.done"]` + + The type of the event. Always `response.audio.transcript.done`. + + - `"response.audio.transcript.done"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + +### Beta Response Code Interpreter Call Code Delta Event + +- `class BetaResponseCodeInterpreterCallCodeDeltaEvent: …` + + Emitted when a partial code snippet is streamed by the code interpreter. + + - `delta: str` + + The partial code snippet being streamed by the code interpreter. + + - `item_id: str` + + The unique identifier of the code interpreter tool call item. + + - `output_index: int` + + The index of the output item in the response for which the code is being streamed. + + - `sequence_number: int` + + The sequence number of this event, used to order streaming events. + + - `type: Literal["response.code_interpreter_call_code.delta"]` + + The type of the event. Always `response.code_interpreter_call_code.delta`. + + - `"response.code_interpreter_call_code.delta"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + +### Beta Response Code Interpreter Call Code Done Event + +- `class BetaResponseCodeInterpreterCallCodeDoneEvent: …` + + Emitted when the code snippet is finalized by the code interpreter. + + - `code: str` + + The final code snippet output by the code interpreter. + + - `item_id: str` + + The unique identifier of the code interpreter tool call item. + + - `output_index: int` + + The index of the output item in the response for which the code is finalized. + + - `sequence_number: int` + + The sequence number of this event, used to order streaming events. + + - `type: Literal["response.code_interpreter_call_code.done"]` + + The type of the event. Always `response.code_interpreter_call_code.done`. + + - `"response.code_interpreter_call_code.done"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + +### Beta Response Code Interpreter Call Completed Event + +- `class BetaResponseCodeInterpreterCallCompletedEvent: …` + + Emitted when the code interpreter call is completed. + + - `item_id: str` + + The unique identifier of the code interpreter tool call item. + + - `output_index: int` + + The index of the output item in the response for which the code interpreter call is completed. + + - `sequence_number: int` + + The sequence number of this event, used to order streaming events. + + - `type: Literal["response.code_interpreter_call.completed"]` + + The type of the event. Always `response.code_interpreter_call.completed`. + + - `"response.code_interpreter_call.completed"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + +### Beta Response Code Interpreter Call In Progress Event + +- `class BetaResponseCodeInterpreterCallInProgressEvent: …` + + Emitted when a code interpreter call is in progress. + + - `item_id: str` + + The unique identifier of the code interpreter tool call item. + + - `output_index: int` + + The index of the output item in the response for which the code interpreter call is in progress. + + - `sequence_number: int` + + The sequence number of this event, used to order streaming events. + + - `type: Literal["response.code_interpreter_call.in_progress"]` + + The type of the event. Always `response.code_interpreter_call.in_progress`. + + - `"response.code_interpreter_call.in_progress"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + +### Beta Response Code Interpreter Call Interpreting Event + +- `class BetaResponseCodeInterpreterCallInterpretingEvent: …` + + Emitted when the code interpreter is actively interpreting the code snippet. + + - `item_id: str` + + The unique identifier of the code interpreter tool call item. + + - `output_index: int` + + The index of the output item in the response for which the code interpreter is interpreting code. + + - `sequence_number: int` + + The sequence number of this event, used to order streaming events. + + - `type: Literal["response.code_interpreter_call.interpreting"]` + + The type of the event. Always `response.code_interpreter_call.interpreting`. + + - `"response.code_interpreter_call.interpreting"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + +### Beta Response Code Interpreter Tool Call + +- `class BetaResponseCodeInterpreterToolCall: …` + + A tool call to run code. + + - `id: str` + + The unique ID of the code interpreter tool call. + + - `code: Optional[str]` + + The code to run, or null if not available. + + - `container_id: str` + + The ID of the container used to run the code. + + - `outputs: Optional[List[Output]]` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `class OutputLogs: …` + + The logs output from the code interpreter. + + - `logs: str` + + The logs output from the code interpreter. + + - `type: Literal["logs"]` + + The type of the output. Always `logs`. + + - `"logs"` + + - `class OutputImage: …` + + The image output from the code interpreter. + + - `type: Literal["image"]` + + The type of the output. Always `image`. + + - `"image"` + + - `url: str` + + The URL of the image output from the code interpreter. + + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: Literal["code_interpreter_call"]` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + +### Beta Response Compaction Item + +- `class BetaResponseCompactionItem: …` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `id: str` + + The unique ID of the compaction item. + + - `encrypted_content: str` + + The encrypted content that was produced by compaction. + + - `type: Literal["compaction"]` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + +### Beta Response Compaction Item Param + +- `class BetaResponseCompactionItemParam: …` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `encrypted_content: str` + + The encrypted content of the compaction summary. + + - `type: Literal["compaction"]` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `id: Optional[str]` + + The ID of the compaction item. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + +### Beta Response Completed Event + +- `class BetaResponseCompletedEvent: …` + + Emitted when the model response is complete. + + - `response: BetaResponse` + + Properties of the completed response. - `id: str` @@ -34865,7 +46008,7 @@ Cancel a response - `"developer"` - - `phase: Optional[Literal["commentary"]]` + - `phase: Optional[Literal["commentary", "final_answer"]]` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -34873,6 +46016,8 @@ Cancel a response - `"commentary"` + - `"final_answer"` + - `type: Optional[Literal["message"]]` The type of the message input. Always `message`. @@ -35124,7 +46269,7 @@ Cancel a response The canonical name of the agent that produced this item. - - `phase: Optional[Literal["commentary"]]` + - `phase: Optional[Literal["commentary", "final_answer"]]` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -35132,6 +46277,8 @@ Cancel a response - `"commentary"` + - `"final_answer"` + - `class BetaResponseFileSearchToolCall: …` The results of a file search tool call. See the @@ -36302,7 +47449,7 @@ Cancel a response - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -36312,7 +47459,11 @@ Cancel a response - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `class FiltersCompoundFilter: …` @@ -36359,7 +47510,7 @@ Cancel a response - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -36369,7 +47520,11 @@ Cancel a response - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `object` @@ -40388,1314 +51543,325 @@ Cancel a response For function calling, the type is always `function`. - - `"function"` - - - `class BetaToolChoiceMcp: …` - - Use this option to force the model to call a specific tool on a remote MCP server. - - - `server_label: str` - - The label of the MCP server to use. - - - `type: Literal["mcp"]` - - For MCP tools, the type is always `mcp`. - - - `"mcp"` - - - `name: Optional[str]` - - The name of the tool to call on the server. - - - `class BetaToolChoiceCustom: …` - - Use this option to force the model to call a specific custom tool. - - - `name: str` - - The name of the custom tool to call. - - - `type: Literal["custom"]` - - For custom tool calling, the type is always `custom`. - - - `"custom"` - - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` - - - `type: Literal["programmatic_tool_calling"]` - - The tool to call. Always `programmatic_tool_calling`. - - - `"programmatic_tool_calling"` - - - `class BetaToolChoiceApplyPatch: …` - - Forces the model to call the apply_patch tool when executing a tool call. - - - `type: Literal["apply_patch"]` - - The tool to call. Always `apply_patch`. - - - `"apply_patch"` - - - `class BetaToolChoiceShell: …` - - Forces the model to call the shell tool when a tool call is required. - - - `type: Literal["shell"]` - - The tool to call. Always `shell`. - - - `"shell"` - - - `tools: List[BetaTool]` - - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. - - We support the following categories of tools: - - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. - - - `class BetaFunctionTool: …` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `class BetaFileSearchTool: …` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - - `class BetaComputerTool: …` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaComputerUsePreviewTool: …` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaWebSearchTool: …` - - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `class Mcp: …` - - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - - `class CodeInterpreter: …` - - A tool that runs Python code to help generate a response to a prompt. - - - `class ProgrammaticToolCalling: …` - - - `class ImageGeneration: …` - - A tool that generates images using the GPT image models. - - - `class LocalShell: …` - - A tool that allows the model to execute shell commands in a local environment. - - - `class BetaFunctionShellTool: …` - - A tool that allows the model to execute shell commands. - - - `class BetaCustomTool: …` - - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - - `class BetaNamespaceTool: …` - - Groups function/custom tools under a shared namespace. - - - `class BetaToolSearchTool: …` - - Hosted or BYOT tool search configuration for deferred tools. - - - `class BetaWebSearchPreviewTool: …` - - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `class BetaApplyPatchTool: …` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `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. - - - `background: Optional[bool]` - - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). - - - `completed_at: Optional[float]` - - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. - - - `conversation: Optional[Conversation]` - - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - - `id: str` - - The unique ID of the conversation that this response was associated with. - - - `max_output_tokens: Optional[int]` - - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - - `max_tool_calls: Optional[int]` - - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - - `moderation: Optional[Moderation]` - - Moderation results for the response input and output, if moderated completions were requested. - - - `input: ModerationInput` - - Moderation for the response input. - - - `class ModerationInputModerationResult: …` - - A moderation result produced for the response input or output. - - - `categories: Dict[str, bool]` - - A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - - Which modalities of input are reflected by the score for each category. - - - `"text"` - - - `"image"` - - - `category_scores: Dict[str, float]` - - A dictionary of moderation categories to scores. - - - `flagged: bool` - - A boolean indicating whether the content was flagged by any category. - - - `model: str` - - The moderation model that produced this result. - - - `type: Literal["moderation_result"]` - - The object type, which was always `moderation_result` for successful moderation results. - - - `"moderation_result"` - - - `class ModerationInputError: …` - - An error produced while attempting moderation for the response input or output. - - - `code: str` - - The error code. - - - `message: str` - - The error message. - - - `type: Literal["error"]` - - The object type, which was always `error` for moderation failures. - - - `"error"` - - - `output: ModerationOutput` - - Moderation for the response output. - - - `class ModerationOutputModerationResult: …` - - A moderation result produced for the response input or output. - - - `categories: Dict[str, bool]` - - A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - - Which modalities of input are reflected by the score for each category. - - - `"text"` - - - `"image"` - - - `category_scores: Dict[str, float]` - - A dictionary of moderation categories to scores. - - - `flagged: bool` - - A boolean indicating whether the content was flagged by any category. - - - `model: str` - - The moderation model that produced this result. - - - `type: Literal["moderation_result"]` - - The object type, which was always `moderation_result` for successful moderation results. - - - `"moderation_result"` - - - `class ModerationOutputError: …` - - An error produced while attempting moderation for the response input or output. - - - `code: str` - - The error code. - - - `message: str` - - The error message. - - - `type: Literal["error"]` - - The object type, which was always `error` for moderation failures. - - - `"error"` - - - `previous_response_id: Optional[str]` - - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - - `prompt: Optional[BetaResponsePrompt]` - - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - - `id: str` - - The unique identifier of the prompt template to use. - - - `variables: Optional[Dict[str, Variables]]` - - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. - - - `str` - - - `class BetaResponseInputText: …` - - A text input to the model. - - - `class BetaResponseInputImage: …` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class BetaResponseInputFile: …` - - A file input to the model. - - - `version: Optional[str]` - - Optional version of the prompt template. - - - `prompt_cache_key: Optional[str]` - - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - - `prompt_cache_options: Optional[PromptCacheOptions]` - - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - - `mode: Literal["implicit", "explicit"]` - - Whether implicit prompt-cache breakpoints were enabled. - - - `"implicit"` - - - `"explicit"` - - - `ttl: Literal["30m"]` - - The minimum lifetime applied to each cache breakpoint. - - - `"30m"` - - - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` - - Deprecated. Use `prompt_cache_options.ttl` instead. - - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - - `"in_memory"` - - - `"24h"` - - - `reasoning: Optional[Reasoning]` - - **gpt-5 and o-series models only** - - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` - - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. - - - `"auto"` - - - `"current_turn"` - - - `"all_turns"` - - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` - - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. - - - `"none"` - - - `"minimal"` - - - `"low"` - - - `"medium"` - - - `"high"` - - - `"xhigh"` - - - `"max"` - - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` - - **Deprecated:** use `summary` instead. - - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. - - - `"auto"` - - - `"concise"` - - - `"detailed"` - - - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` - - Controls the reasoning execution mode for the request. - - When returned on a response, this is the effective execution mode. - - - `str` - - - `Literal["standard", "pro"]` - - Controls the reasoning execution mode for the request. - - When returned on a response, this is the effective execution mode. - - - `"standard"` - - - `"pro"` - - - `summary: Optional[Literal["auto", "concise", "detailed"]]` - - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. - - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - - `"auto"` - - - `"concise"` - - - `"detailed"` - - - `safety_identifier: Optional[str]` - - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` - - Specifies the processing type used for serving the request. - - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. - - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - - `"auto"` - - - `"default"` - - - `"flex"` - - - `"scale"` - - - `"priority"` - - - `status: Optional[BetaResponseStatus]` - - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. - - - `"completed"` - - - `"failed"` - - - `"in_progress"` - - - `"cancelled"` - - - `"queued"` - - - `"incomplete"` - - - `text: Optional[BetaResponseTextConfig]` - - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: - - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - - `format: Optional[BetaResponseFormatTextConfig]` - - An object specifying the format that the model must output. - - Configuring `{ "type": "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). - - The default format is `{ "type": "text" }` with no additional options. - - **Not recommended for gpt-4o and newer models:** - - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. - - - `class Text: …` - - Default response format. Used to generate text responses. - - - `type: Literal["text"]` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `class BetaResponseFormatTextJSONSchemaConfig: …` - - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - - `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. - - - `schema: 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/). - - - `type: Literal["json_schema"]` - - The type of response format being defined. Always `json_schema`. - - - `"json_schema"` - - - `description: Optional[str]` - - A description of what the response format is for, used by the model to - determine how to respond in the format. - - - `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). - - - `class JSONObject: …` - - 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"` - - - `verbosity: Optional[Literal["low", "medium", "high"]]` - - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. - - - `"low"` - - - `"medium"` - - - `"high"` - - - `top_logprobs: Optional[int]` - - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. - - - `truncation: Optional[Literal["auto", "disabled"]]` - - The truncation strategy to use for the model response. - - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. - - - `"auto"` - - - `"disabled"` - - - `usage: Optional[BetaResponseUsage]` - - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. - - - `input_tokens: int` - - The number of input tokens. - - - `input_tokens_details: InputTokensDetails` - - A detailed breakdown of the input tokens. - - - `cache_write_tokens: int` - - The number of input tokens that were written to the cache. - - - `cached_tokens: int` - - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - - `output_tokens: int` - - The number of output tokens. - - - `output_tokens_details: OutputTokensDetails` - - A detailed breakdown of the output tokens. - - - `reasoning_tokens: int` - - The number of reasoning tokens. - - - `total_tokens: int` - - The total number of tokens used. - - - `user: Optional[str]` - - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - -### 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 -) -beta_response = client.beta.responses.cancel( - response_id="resp_677efb5139a88190b512bc3fef8e535d", -) -print(beta_response.id) -``` - -#### Response - -```json -{ - "id": "id", - "created_at": 0, - "error": { - "code": "server_error", - "message": "message" - }, - "incomplete_details": { - "reason": "max_output_tokens" - }, - "instructions": "string", - "metadata": { - "foo": "string" - }, - "model": "gpt-5.1", - "object": "response", - "output": [ - { - "id": "id", - "content": [ - { - "annotations": [ - { - "file_id": "file_id", - "filename": "filename", - "index": 0, - "type": "file_citation" - } - ], - "text": "text", - "type": "output_text", - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ] - } - ], - "role": "assistant", - "status": "in_progress", - "type": "message", - "agent": { - "agent_name": "agent_name" - }, - "phase": "commentary" - } - ], - "parallel_tool_calls": true, - "temperature": 1, - "tool_choice": "none", - "tools": [ - { - "name": "name", - "parameters": { - "foo": "bar" - }, - "strict": true, - "type": "function", - "allowed_callers": [ - "direct" - ], - "defer_loading": true, - "description": "description", - "output_schema": { - "foo": "bar" - } - } - ], - "top_p": 1, - "background": true, - "completed_at": 0, - "conversation": { - "id": "id" - }, - "max_output_tokens": 0, - "max_tool_calls": 0, - "moderation": { - "input": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - }, - "output": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - } - }, - "output_text": "output_text", - "previous_response_id": "previous_response_id", - "prompt": { - "id": "id", - "variables": { - "foo": "string" - }, - "version": "version" - }, - "prompt_cache_key": "prompt-cache-key-1234", - "prompt_cache_options": { - "mode": "implicit", - "ttl": "30m" - }, - "prompt_cache_retention": "in_memory", - "reasoning": { - "context": "auto", - "effort": "none", - "generate_summary": "auto", - "mode": "standard", - "summary": "auto" - }, - "safety_identifier": "safety-identifier-1234", - "service_tier": "auto", - "status": "completed", - "text": { - "format": { - "type": "text" - }, - "verbosity": "low" - }, - "top_logprobs": 0, - "truncation": "auto", - "usage": { - "input_tokens": 0, - "input_tokens_details": { - "cache_write_tokens": 0, - "cached_tokens": 0 - }, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - }, - "user": "user-1234" -} -``` - -### Example - -```python -from openai import OpenAI -client = OpenAI() - -response = client.responses.cancel("resp_123") -print(response) -``` - -#### Response - -```json -{ - "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", - "object": "response", - "created_at": 1741386163, - "status": "cancelled", - "background": true, - "completed_at": null, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-4o-2024-08-06", - "output": [ - { - "type": "message", - "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", - "status": "in_progress", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} -} -``` - -## Compact a response - -`beta.responses.compact(ResponseCompactParams**kwargs) -> BetaCompactedResponse` - -**post** `/responses/compact?beta=true` - -Compact a response - -### Parameters - -- `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str, null]` - - Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` - - Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - - - `"gpt-5.6-sol"` - - - `"gpt-5.6-terra"` - - - `"gpt-5.6-luna"` - - - `"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"` + - `"function"` - - `"o4-mini-2025-04-16"` + - `class BetaToolChoiceMcp: …` - - `"o3"` + Use this option to force the model to call a specific tool on a remote MCP server. - - `"o3-2025-04-16"` + - `server_label: str` - - `"o3-mini"` + The label of the MCP server to use. - - `"o3-mini-2025-01-31"` + - `type: Literal["mcp"]` - - `"o1"` + For MCP tools, the type is always `mcp`. - - `"o1-2024-12-17"` + - `"mcp"` - - `"o1-preview"` + - `name: Optional[str]` - - `"o1-preview-2024-09-12"` + The name of the tool to call on the server. - - `"o1-mini"` + - `class BetaToolChoiceCustom: …` - - `"o1-mini-2024-09-12"` + Use this option to force the model to call a specific custom tool. - - `"gpt-4o"` + - `name: str` - - `"gpt-4o-2024-11-20"` + The name of the custom tool to call. - - `"gpt-4o-2024-08-06"` + - `type: Literal["custom"]` - - `"gpt-4o-2024-05-13"` + For custom tool calling, the type is always `custom`. - - `"gpt-4o-audio-preview"` + - `"custom"` - - `"gpt-4o-audio-preview-2024-10-01"` + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` - - `"gpt-4o-audio-preview-2024-12-17"` + - `type: Literal["programmatic_tool_calling"]` - - `"gpt-4o-audio-preview-2025-06-03"` + The tool to call. Always `programmatic_tool_calling`. - - `"gpt-4o-mini-audio-preview"` + - `"programmatic_tool_calling"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `class BetaToolChoiceApplyPatch: …` - - `"gpt-4o-search-preview"` + Forces the model to call the apply_patch tool when executing a tool call. - - `"gpt-4o-mini-search-preview"` + - `type: Literal["apply_patch"]` - - `"gpt-4o-search-preview-2025-03-11"` + The tool to call. Always `apply_patch`. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `"apply_patch"` - - `"chatgpt-4o-latest"` + - `class BetaToolChoiceShell: …` - - `"codex-mini-latest"` + Forces the model to call the shell tool when a tool call is required. - - `"gpt-4o-mini"` + - `type: Literal["shell"]` - - `"gpt-4o-mini-2024-07-18"` + The tool to call. Always `shell`. - - `"gpt-4-turbo"` + - `"shell"` - - `"gpt-4-turbo-2024-04-09"` + - `tools: List[BetaTool]` - - `"gpt-4-0125-preview"` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `"gpt-4-turbo-preview"` + We support the following categories of tools: - - `"gpt-4-1106-preview"` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `"gpt-4-vision-preview"` + - `class BetaFunctionTool: …` - - `"gpt-4"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"gpt-4-0314"` + - `class BetaFileSearchTool: …` - - `"gpt-4-0613"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `"gpt-4-32k"` + - `class BetaComputerTool: …` - - `"gpt-4-32k-0314"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-4-32k-0613"` + - `class BetaComputerUsePreviewTool: …` - - `"gpt-3.5-turbo"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-3.5-turbo-16k"` + - `class BetaWebSearchTool: …` - - `"gpt-3.5-turbo-0301"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"gpt-3.5-turbo-0613"` + - `class Mcp: …` - - `"gpt-3.5-turbo-1106"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"gpt-3.5-turbo-0125"` + - `class CodeInterpreter: …` - - `"gpt-3.5-turbo-16k-0613"` + A tool that runs Python code to help generate a response to a prompt. - - `"o1-pro"` + - `class ProgrammaticToolCalling: …` - - `"o1-pro-2025-03-19"` + - `class ImageGeneration: …` - - `"o3-pro"` + A tool that generates images using the GPT image models. - - `"o3-pro-2025-06-10"` + - `class LocalShell: …` - - `"o3-deep-research"` + A tool that allows the model to execute shell commands in a local environment. - - `"o3-deep-research-2025-06-26"` + - `class BetaFunctionShellTool: …` - - `"o4-mini-deep-research"` + A tool that allows the model to execute shell commands. - - `"o4-mini-deep-research-2025-06-26"` + - `class BetaCustomTool: …` - - `"computer-use-preview"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `"computer-use-preview-2025-03-11"` + - `class BetaNamespaceTool: …` - - `"gpt-5-codex"` + Groups function/custom tools under a shared namespace. - - `"gpt-5-pro"` + - `class BetaToolSearchTool: …` - - `"gpt-5-pro-2025-10-06"` + Hosted or BYOT tool search configuration for deferred tools. - - `"gpt-5.1-codex-max"` + - `class BetaWebSearchPreviewTool: …` - - `str` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). -- `input: Optional[Union[str, Iterable[BetaResponseInputItemParam], null]]` + - `class BetaApplyPatchTool: …` - Text, image, or file inputs to the model, used to generate a response + Allows the assistant to create, delete, or update files using unified diffs. - - `str` + - `top_p: Optional[float]` - A text input to the model, equivalent to a text input with the `user` role. + 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. - - `Iterable[BetaResponseInputItemParam]` + We generally recommend altering this or `temperature` but not both. - A list of one or many input items to the model, containing different content types. + - `background: Optional[bool]` - - `class BetaEasyInputMessage: …` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `completed_at: Optional[float]` - - `content: Union[str, BetaResponseInputMessageContentList]` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `conversation: Optional[Conversation]` - - `str` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - A text input to the model. + - `id: str` - - `List[BetaResponseInputContent]` + The unique ID of the conversation that this response was associated with. - - `class BetaResponseInputText: …` + - `max_output_tokens: Optional[int]` - A text input to the model. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `text: str` + - `max_tool_calls: Optional[int]` - The text input to the model. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `type: Literal["input_text"]` + - `moderation: Optional[Moderation]` - The type of the input item. Always `input_text`. + Moderation results for the response input and output, if moderated completions were requested. - - `"input_text"` + - `input: ModerationInput` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + Moderation for the response input. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class ModerationInputModerationResult: …` - - `mode: Literal["explicit"]` + A moderation result produced for the response input or output. - The breakpoint mode. Always `explicit`. + - `categories: Dict[str, bool]` - - `"explicit"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `class BetaResponseInputImage: …` + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Which modalities of input are reflected by the score for each category. - - `detail: Literal["low", "high", "auto", "original"]` + - `"text"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"image"` - - `"low"` + - `category_scores: Dict[str, float]` - - `"high"` + A dictionary of moderation categories to scores. - - `"auto"` + - `flagged: bool` - - `"original"` + A boolean indicating whether the content was flagged by any category. - - `type: Literal["input_image"]` + - `model: str` - The type of the input item. Always `input_image`. + The moderation model that produced this result. - - `"input_image"` + - `type: Literal["moderation_result"]` - - `file_id: Optional[str]` + The object type, which was always `moderation_result` for successful moderation results. - The ID of the file to be sent to the model. + - `"moderation_result"` - - `image_url: Optional[str]` + - `class ModerationInputError: …` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + An error produced while attempting moderation for the response input or output. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `code: str` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The error code. - - `mode: Literal["explicit"]` + - `message: str` - The breakpoint mode. Always `explicit`. + The error message. - - `"explicit"` + - `type: Literal["error"]` - - `class BetaResponseInputFile: …` + The object type, which was always `error` for moderation failures. - A file input to the model. + - `"error"` - - `type: Literal["input_file"]` + - `output: ModerationOutput` - The type of the input item. Always `input_file`. + Moderation for the response output. - - `"input_file"` + - `class ModerationOutputModerationResult: …` - - `detail: Optional[Literal["auto", "low", "high"]]` + A moderation result produced for the response input or output. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `categories: Dict[str, bool]` - - `"auto"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"low"` + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - - `"high"` + Which modalities of input are reflected by the score for each category. - - `file_data: Optional[str]` + - `"text"` - The content of the file to be sent to the model. + - `"image"` - - `file_id: Optional[str]` + - `category_scores: Dict[str, float]` - The ID of the file to be sent to the model. + A dictionary of moderation categories to scores. - - `file_url: Optional[str]` + - `flagged: bool` - The URL of the file to be sent to the model. + A boolean indicating whether the content was flagged by any category. - - `filename: Optional[str]` + - `model: str` - The name of the file to be sent to the model. + The moderation model that produced this result. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["moderation_result"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The object type, which was always `moderation_result` for successful moderation results. - - `mode: Literal["explicit"]` + - `"moderation_result"` - The breakpoint mode. Always `explicit`. + - `class ModerationOutputError: …` - - `"explicit"` + An error produced while attempting moderation for the response input or output. - - `role: Literal["user", "assistant", "system", "developer"]` + - `code: str` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The error code. - - `"user"` + - `message: str` - - `"assistant"` + The error message. - - `"system"` + - `type: Literal["error"]` - - `"developer"` + The object type, which was always `error` for moderation failures. - - `phase: Optional[Literal["commentary"]]` + - `"error"` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `previous_response_id: Optional[str]` - - `"commentary"` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `type: Optional[Literal["message"]]` + - `prompt: Optional[BetaResponsePrompt]` - The type of the message input. Always `message`. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `"message"` + - `id: str` - - `class Message: …` + The unique identifier of the prompt template to use. - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + - `variables: Optional[Dict[str, Variables]]` - - `content: BetaResponseInputMessageContentList` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - A list of one or many input items to the model, containing different content - types. + - `str` - `class BetaResponseInputText: …` @@ -41709,313 +51875,362 @@ Compact a response A file input to the model. - - `role: Literal["user", "system", "developer"]` + - `version: Optional[str]` - The role of the message input. One of `user`, `system`, or `developer`. + Optional version of the prompt template. - - `"user"` + - `prompt_cache_key: Optional[str]` - - `"system"` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `"developer"` + - `prompt_cache_options: Optional[PromptCacheOptions]` - - `agent: Optional[MessageAgent]` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The agent that produced this item. + - `mode: Literal["implicit", "explicit"]` - - `agent_name: str` + Whether implicit prompt-cache breakpoints were enabled. - The canonical name of the agent that produced this item. + - `"implicit"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"explicit"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `ttl: Literal["30m"]` - - `"in_progress"` + The minimum lifetime applied to each cache breakpoint. - - `"completed"` + - `"30m"` - - `"incomplete"` + - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` - - `type: Optional[Literal["message"]]` + Deprecated. Use `prompt_cache_options.ttl` instead. - The type of the message input. Always set to `message`. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `"message"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `class BetaResponseOutputMessage: …` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - An output message from the model. + - `"in_memory"` - - `id: str` + - `"24h"` - The unique ID of the output message. + - `reasoning: Optional[Reasoning]` - - `content: List[Content]` + **gpt-5 and o-series models only** - The content of the output message. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `class BetaResponseOutputText: …` + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` - A text output from the model. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `annotations: List[Annotation]` + - `"auto"` - The annotations of the text output. + - `"current_turn"` - - `class AnnotationFileCitation: …` + - `"all_turns"` - A citation to a file. + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` - - `file_id: str` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - The ID of the file. + - `"none"` - - `filename: str` + - `"minimal"` - The filename of the file cited. + - `"low"` - - `index: int` + - `"medium"` - The index of the file in the list of files. + - `"high"` - - `type: Literal["file_citation"]` + - `"xhigh"` - The type of the file citation. Always `file_citation`. + - `"max"` - - `"file_citation"` + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` - - `class AnnotationURLCitation: …` + **Deprecated:** use `summary` instead. - A citation for a web resource used to generate a model response. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `end_index: int` + - `"auto"` - The index of the last character of the URL citation in the message. + - `"concise"` - - `start_index: int` + - `"detailed"` - The index of the first character of the URL citation in the message. + - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` - - `title: str` + Controls the reasoning execution mode for the request. - The title of the web resource. + When returned on a response, this is the effective execution mode. - - `type: Literal["url_citation"]` + - `str` - The type of the URL citation. Always `url_citation`. + - `Literal["standard", "pro"]` - - `"url_citation"` + Controls the reasoning execution mode for the request. - - `url: str` + When returned on a response, this is the effective execution mode. - The URL of the web resource. + - `"standard"` - - `class AnnotationContainerFileCitation: …` + - `"pro"` - A citation for a container file used to generate a model response. + - `summary: Optional[Literal["auto", "concise", "detailed"]]` - - `container_id: str` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The ID of the container file. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `end_index: int` + - `"auto"` - The index of the last character of the container file citation in the message. + - `"concise"` - - `file_id: str` + - `"detailed"` - The ID of the file. + - `safety_identifier: Optional[str]` - - `filename: str` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The filename of the container file cited. + - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` - - `start_index: int` + Specifies the processing type used for serving the request. - The index of the first character of the container file citation in the message. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `type: Literal["container_file_citation"]` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The type of the container file citation. Always `container_file_citation`. + - `"auto"` - - `"container_file_citation"` + - `"default"` - - `class AnnotationFilePath: …` + - `"flex"` - A path to a file. + - `"scale"` - - `file_id: str` + - `"priority"` - The ID of the file. + - `status: Optional[BetaResponseStatus]` - - `index: int` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The index of the file in the list of files. + - `"completed"` - - `type: Literal["file_path"]` + - `"failed"` - The type of the file path. Always `file_path`. + - `"in_progress"` - - `"file_path"` + - `"cancelled"` - - `text: str` + - `"queued"` - The text output from the model. + - `"incomplete"` - - `type: Literal["output_text"]` + - `text: Optional[BetaResponseTextConfig]` - The type of the output text. Always `output_text`. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"output_text"` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `logprobs: Optional[List[Logprob]]` + - `format: Optional[BetaResponseFormatTextConfig]` - - `token: str` + An object specifying the format that the model must output. - - `bytes: List[int]` + Configuring `{ "type": "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). - - `logprob: float` + The default format is `{ "type": "text" }` with no additional options. - - `top_logprobs: List[LogprobTopLogprob]` + **Not recommended for gpt-4o and newer models:** - - `token: str` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `bytes: List[int]` + - `class Text: …` - - `logprob: float` + Default response format. Used to generate text responses. - - `class BetaResponseOutputRefusal: …` + - `type: Literal["text"]` - A refusal from the model. + The type of response format being defined. Always `text`. - - `refusal: str` + - `"text"` - The refusal explanation from the model. + - `class BetaResponseFormatTextJSONSchemaConfig: …` - - `type: Literal["refusal"]` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The type of the refusal. Always `refusal`. + - `name: str` - - `"refusal"` + 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. - - `role: Literal["assistant"]` + - `schema: Dict[str, object]` - The role of the output message. Always `assistant`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"assistant"` + - `type: Literal["json_schema"]` - - `status: Literal["in_progress", "completed", "incomplete"]` + The type of response format being defined. Always `json_schema`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"json_schema"` - - `"in_progress"` + - `description: Optional[str]` - - `"completed"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"incomplete"` + - `strict: Optional[bool]` - - `type: Literal["message"]` + 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). - The type of the output message. Always `message`. + - `class JSONObject: …` - - `"message"` + 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. - - `agent: Optional[Agent]` + - `type: Literal["json_object"]` - The agent that produced this item. + The type of response format being defined. Always `json_object`. - - `agent_name: str` + - `"json_object"` - The canonical name of the agent that produced this item. + - `verbosity: Optional[Literal["low", "medium", "high"]]` - - `phase: Optional[Literal["commentary"]]` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `"low"` - - `"commentary"` + - `"medium"` - - `class BetaResponseFileSearchToolCall: …` + - `"high"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `top_logprobs: Optional[int]` - - `id: str` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - The unique ID of the file search tool call. + - `truncation: Optional[Literal["auto", "disabled"]]` - - `queries: List[str]` + The truncation strategy to use for the model response. - The queries used to search for files. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `"auto"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"disabled"` - - `"in_progress"` + - `usage: Optional[BetaResponseUsage]` - - `"searching"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `"completed"` + - `input_tokens: int` - - `"incomplete"` + The number of input tokens. - - `"failed"` + - `input_tokens_details: InputTokensDetails` - - `type: Literal["file_search_call"]` + A detailed breakdown of the input tokens. - The type of the file search tool call. Always `file_search_call`. + - `cache_write_tokens: int` - - `"file_search_call"` + The number of input tokens that were written to the cache. - - `agent: Optional[Agent]` + - `cached_tokens: int` - The agent that produced this item. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `agent_name: str` + - `output_tokens: int` - The canonical name of the agent that produced this item. + The number of output tokens. - - `results: Optional[List[Result]]` + - `output_tokens_details: OutputTokensDetails` - The results of the file search tool call. + A detailed breakdown of the output tokens. - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + - `reasoning_tokens: int` - 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, booleans, or numbers. + The number of reasoning tokens. - - `str` + - `total_tokens: int` - - `float` + The total number of tokens used. - - `bool` + - `user: Optional[str]` - - `file_id: Optional[str]` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The unique ID of the file. + - `sequence_number: int` - - `filename: Optional[str]` + The sequence number for this event. - The name of the file. + - `type: Literal["response.completed"]` - - `score: Optional[float]` + The type of the event. Always `response.completed`. - The relevance score of the file - a value between 0 and 1. + - `"response.completed"` - - `text: Optional[str]` + - `agent: Optional[Agent]` - The text that was retrieved from the file. + The agent that owns this multi-agent streaming event. - - `class BetaResponseComputerToolCall: …` + - `agent_name: str` + + The canonical name of the agent that produced this item. + +### Beta Response Computer Tool Call + +- `class BetaResponseComputerToolCall: …` A tool call to a computer use tool. See the [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. @@ -42305,9 +52520,13 @@ Compact a response The canonical name of the agent that produced this item. - - `class ComputerCallOutput: …` +### Beta Response Computer Tool Call Output Item - The output of a computer tool call. +- `class BetaResponseComputerToolCallOutputItem: …` + + - `id: str` + + The unique ID of the computer call tool output. - `call_id: str` @@ -42332,180 +52551,41 @@ Compact a response The URL of the screenshot image. - - `type: Literal["computer_call_output"]` - - The type of the computer tool call output. Always `computer_call_output`. - - - `"computer_call_output"` - - - `id: Optional[str]` - - The ID of the computer tool call output. - - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - - The safety checks reported by the API that have been acknowledged by the developer. - - - `id: str` - - The ID of the pending safety check. - - - `code: Optional[str]` - - The type of the pending safety check. - - - `message: Optional[str]` - - Details about the pending safety check. - - - `agent: Optional[ComputerCallOutputAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - `"in_progress"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"completed"` - `"incomplete"` - - `class BetaResponseFunctionWebSearch: …` - - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - - `id: str` - - The unique ID of the web search tool call. - - - `action: Action` - - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). - - - `class ActionSearch: …` - - Action type "search" - Performs a web search query. - - - `type: Literal["search"]` - - The action type. - - - `"search"` - - - `queries: Optional[List[str]]` - - The search queries. - - - `query: Optional[str]` - - The search query. - - - `sources: Optional[List[ActionSearchSource]]` - - The sources used in the search. - - - `type: Literal["url"]` - - The type of source. Always `url`. - - - `"url"` - - - `url: str` - - The URL of the source. - - - `class ActionOpenPage: …` - - Action type "open_page" - Opens a specific URL from search results. - - - `type: Literal["open_page"]` - - The action type. - - - `"open_page"` - - - `url: Optional[str]` - - The URL opened by the model. - - - `class ActionFindInPage: …` - - Action type "find_in_page": Searches for a pattern within a loaded page. - - - `pattern: str` - - The pattern or text to search for within the page. - - - `type: Literal["find_in_page"]` - - The action type. - - - `"find_in_page"` - - - `url: str` - - The URL of the page searched for the pattern. - - - `status: Literal["in_progress", "searching", "completed", "failed"]` - - The status of the web search tool call. - - - `"in_progress"` - - - `"searching"` - - - `"completed"` - - `"failed"` - - `type: Literal["web_search_call"]` - - The type of the web search tool call. Always `web_search_call`. - - - `"web_search_call"` - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `class BetaResponseFunctionToolCall: …` - - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"in_progress"` - - `arguments: str` + - `type: Literal["computer_call_output"]` - A JSON string of the arguments to pass to the function. + The type of the computer tool call output. Always `computer_call_output`. - - `call_id: str` + - `"computer_call_output"` - The unique ID of the function tool call generated by the model. + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - - `name: str` + The safety checks reported by the API that have been acknowledged by the + developer. - The name of the function to run. + - `id: str` - - `type: Literal["function_call"]` + The ID of the pending safety check. - The type of the function tool call. Always `function_call`. + - `code: Optional[str]` - - `"function_call"` + The type of the pending safety check. - - `id: Optional[str]` + - `message: Optional[str]` - The unique ID of the function tool call. + Details about the pending safety check. - `agent: Optional[Agent]` @@ -42515,60 +52595,52 @@ Compact a response The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` - - - `type: Literal["direct"]` - - - `"direct"` + - `created_by: Optional[str]` - - `class CallerProgram: …` + The identifier of the actor that created the item. - - `caller_id: str` +### Beta Response Computer Tool Call Output Screenshot - The call ID of the program item that produced this tool call. +- `class BetaResponseComputerToolCallOutputScreenshot: …` - - `type: Literal["program"]` + A computer screenshot image used with the computer use tool. - - `"program"` + - `type: Literal["computer_screenshot"]` - - `namespace: Optional[str]` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The namespace of the function to run. + - `"computer_screenshot"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `file_id: Optional[str]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The identifier of an uploaded file that contains the screenshot. - - `"in_progress"` + - `image_url: Optional[str]` - - `"completed"` + The URL of the screenshot image. - - `"incomplete"` +### Beta Response Container Reference - - `class FunctionCallOutput: …` +- `class BetaResponseContainerReference: …` - The output of a function tool call. + Represents a container created with /v1/containers. - - `call_id: str` + - `container_id: str` - The unique ID of the function tool call generated by the model. + - `type: Literal["container_reference"]` - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + The environment type. Always `container_reference`. - Text, image, or file output of the function tool call. + - `"container_reference"` - - `str` +### Beta Response Content - A JSON string of the output of the function tool call. +- `BetaResponseContent` - - `List[BetaResponseFunctionCallOutputItem]` + Multi-modal input and output contents. - - `class BetaResponseInputTextContent: …` + - `class BetaResponseInputText: …` A text input to the model. @@ -42592,17 +52664,11 @@ Compact a response - `"explicit"` - - `class BetaResponseInputImageContent: …` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `type: Literal["input_image"]` - - The type of the input item. Always `input_image`. + - `class BetaResponseInputImage: …` - - `"input_image"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + - `detail: Literal["low", "high", "auto", "original"]` The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. @@ -42614,6 +52680,12 @@ Compact a response - `"original"` + - `type: Literal["input_image"]` + + The type of the input item. Always `input_image`. + + - `"input_image"` + - `file_id: Optional[str]` The ID of the file to be sent to the model. @@ -42632,7 +52704,7 @@ Compact a response - `"explicit"` - - `class BetaResponseInputFileContent: …` + - `class BetaResponseInputFile: …` A file input to the model. @@ -42654,7 +52726,7 @@ Compact a response - `file_data: Optional[str]` - The base64-encoded data of the file to be sent to the model. + The content of the file to be sent to the model. - `file_id: Optional[str]` @@ -42678,199 +52750,197 @@ Compact a response - `"explicit"` - - `type: Literal["function_call_output"]` - - The type of the function tool call output. Always `function_call_output`. + - `class BetaResponseOutputText: …` - - `"function_call_output"` + A text output from the model. - - `id: Optional[str]` + - `annotations: List[Annotation]` - The unique ID of the function tool call output. Populated when this item is returned via API. + The annotations of the text output. - - `agent: Optional[FunctionCallOutputAgent]` + - `class AnnotationFileCitation: …` - The agent that produced this item. + A citation to a file. - - `agent_name: str` + - `file_id: str` - The canonical name of the agent that produced this item. + The ID of the file. - - `caller: Optional[FunctionCallOutputCaller]` + - `filename: str` - The execution context that produced this tool call. + The filename of the file cited. - - `class FunctionCallOutputCallerDirect: …` + - `index: int` - - `type: Literal["direct"]` + The index of the file in the list of files. - The caller type. Always `direct`. + - `type: Literal["file_citation"]` - - `"direct"` + The type of the file citation. Always `file_citation`. - - `class FunctionCallOutputCallerProgram: …` + - `"file_citation"` - - `caller_id: str` + - `class AnnotationURLCitation: …` - The call ID of the program item that produced this tool call. + A citation for a web resource used to generate a model response. - - `type: Literal["program"]` + - `end_index: int` - The caller type. Always `program`. + The index of the last character of the URL citation in the message. - - `"program"` + - `start_index: int` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The index of the first character of the URL citation in the message. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `title: str` - - `"in_progress"` + The title of the web resource. - - `"completed"` + - `type: Literal["url_citation"]` - - `"incomplete"` + The type of the URL citation. Always `url_citation`. - - `class AgentMessage: …` + - `"url_citation"` - A message routed between agents. + - `url: str` - - `author: str` + The URL of the web resource. - The sending agent identity. + - `class AnnotationContainerFileCitation: …` - - `content: List[AgentMessageContent]` + A citation for a container file used to generate a model response. - Plaintext, image, or encrypted content sent between agents. + - `container_id: str` - - `class BetaResponseInputTextContent: …` + The ID of the container file. - A text input to the model. + - `end_index: int` - - `class BetaResponseInputImageContent: …` + The index of the last character of the container file citation in the message. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `file_id: str` - - `class AgentMessageContentEncryptedContent: …` + The ID of the file. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `filename: str` - - `encrypted_content: str` + The filename of the container file cited. - Opaque encrypted content. + - `start_index: int` - - `type: Literal["encrypted_content"]` + The index of the first character of the container file citation in the message. - The type of the input item. Always `encrypted_content`. + - `type: Literal["container_file_citation"]` - - `"encrypted_content"` + The type of the container file citation. Always `container_file_citation`. - - `recipient: str` + - `"container_file_citation"` - The destination agent identity. + - `class AnnotationFilePath: …` - - `type: Literal["agent_message"]` + A path to a file. - The item type. Always `agent_message`. + - `file_id: str` - - `"agent_message"` + The ID of the file. - - `id: Optional[str]` + - `index: int` - The unique ID of this agent message item. + The index of the file in the list of files. - - `agent: Optional[AgentMessageAgent]` + - `type: Literal["file_path"]` - The agent that produced this item. + The type of the file path. Always `file_path`. - - `agent_name: str` + - `"file_path"` - The canonical name of the agent that produced this item. + - `text: str` - - `class MultiAgentCall: …` + The text output from the model. - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `type: Literal["output_text"]` - The multi-agent action that was executed. + The type of the output text. Always `output_text`. - - `"spawn_agent"` + - `"output_text"` - - `"interrupt_agent"` + - `logprobs: Optional[List[Logprob]]` - - `"list_agents"` + - `token: str` - - `"send_message"` + - `bytes: List[int]` - - `"followup_task"` + - `logprob: float` - - `"wait_agent"` + - `top_logprobs: List[LogprobTopLogprob]` - - `arguments: str` + - `token: str` - The action arguments as a JSON string. + - `bytes: List[int]` - - `call_id: str` + - `logprob: float` - The unique ID linking this call to its output. + - `class BetaResponseOutputRefusal: …` - - `type: Literal["multi_agent_call"]` + A refusal from the model. - The item type. Always `multi_agent_call`. + - `refusal: str` - - `"multi_agent_call"` + The refusal explanation from the model. - - `id: Optional[str]` + - `type: Literal["refusal"]` - The unique ID of this multi-agent call. + The type of the refusal. Always `refusal`. - - `agent: Optional[MultiAgentCallAgent]` + - `"refusal"` - The agent that produced this item. + - `class ReasoningText: …` - - `agent_name: str` + Reasoning text from the model. - The canonical name of the agent that produced this item. + - `text: str` - - `class MultiAgentCallOutput: …` + The reasoning text from the model. - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `type: Literal["reasoning_text"]` - The multi-agent action that produced this result. + The type of the reasoning text. Always `reasoning_text`. - - `"spawn_agent"` + - `"reasoning_text"` - - `"interrupt_agent"` +### Beta Response Content Part Added Event - - `"list_agents"` +- `class BetaResponseContentPartAddedEvent: …` - - `"send_message"` + Emitted when a new content part is added. - - `"followup_task"` + - `content_index: int` - - `"wait_agent"` + The index of the content part that was added. - - `call_id: str` + - `item_id: str` - The unique ID of the multi-agent call. + The ID of the output item that the content part was added to. - - `output: List[MultiAgentCallOutputOutput]` + - `output_index: int` - Text output returned by the multi-agent action. + The index of the output item that the content part was added to. - - `text: str` + - `part: Part` - The text content. + The content part that was added. - - `type: Literal["output_text"]` + - `class BetaResponseOutputText: …` - The content type. Always `output_text`. + A text output from the model. - - `"output_text"` + - `annotations: List[Annotation]` - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + The annotations of the text output. - Citations associated with the text content. + - `class AnnotationFileCitation: …` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + A citation to a file. - `file_id: str` @@ -42886,47 +52956,51 @@ Compact a response - `type: Literal["file_citation"]` - The citation type. Always `file_citation`. + The type of the file citation. Always `file_citation`. - `"file_citation"` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + - `class AnnotationURLCitation: …` + + A citation for a web resource used to generate a model response. - `end_index: int` - The index of the last character of the citation in the message. + The index of the last character of the URL citation in the message. - `start_index: int` - The index of the first character of the citation in the message. + The index of the first character of the URL citation in the message. - `title: str` - The title of the cited resource. + The title of the web resource. - `type: Literal["url_citation"]` - The citation type. Always `url_citation`. + The type of the URL citation. Always `url_citation`. - `"url_citation"` - `url: str` - The URL of the cited resource. + The URL of the web resource. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `class AnnotationContainerFileCitation: …` + + A citation for a container file used to generate a model response. - `container_id: str` - The ID of the container. + The ID of the container file. - `end_index: int` - The index of the last character of the citation in the message. + The index of the last character of the container file citation in the message. - `file_id: str` - The ID of the container file. + The ID of the file. - `filename: str` @@ -42934,1181 +53008,1243 @@ Compact a response - `start_index: int` - The index of the first character of the citation in the message. + The index of the first character of the container file citation in the message. - `type: Literal["container_file_citation"]` - The citation type. Always `container_file_citation`. + The type of the container file citation. Always `container_file_citation`. - `"container_file_citation"` - - `type: Literal["multi_agent_call_output"]` + - `class AnnotationFilePath: …` - The item type. Always `multi_agent_call_output`. + A path to a file. - - `"multi_agent_call_output"` + - `file_id: str` - - `id: Optional[str]` + The ID of the file. - The unique ID of this multi-agent call output. + - `index: int` - - `agent: Optional[MultiAgentCallOutputAgent]` + The index of the file in the list of files. - The agent that produced this item. + - `type: Literal["file_path"]` - - `agent_name: str` + The type of the file path. Always `file_path`. - The canonical name of the agent that produced this item. + - `"file_path"` - - `class ToolSearchCall: …` + - `text: str` - - `arguments: object` + The text output from the model. - The arguments supplied to the tool search call. + - `type: Literal["output_text"]` - - `type: Literal["tool_search_call"]` + The type of the output text. Always `output_text`. - The item type. Always `tool_search_call`. + - `"output_text"` - - `"tool_search_call"` + - `logprobs: Optional[List[Logprob]]` - - `id: Optional[str]` + - `token: str` - The unique ID of this tool search call. + - `bytes: List[int]` - - `agent: Optional[ToolSearchCallAgent]` + - `logprob: float` - The agent that produced this item. + - `top_logprobs: List[LogprobTopLogprob]` + + - `token: str` + + - `bytes: List[int]` + + - `logprob: float` + + - `class BetaResponseOutputRefusal: …` + + A refusal from the model. + + - `refusal: str` + + The refusal explanation from the model. + + - `type: Literal["refusal"]` + + The type of the refusal. Always `refusal`. + + - `"refusal"` + + - `class PartReasoningText: …` + + Reasoning text from the model. + + - `text: str` + + The reasoning text from the model. + + - `type: Literal["reasoning_text"]` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `sequence_number: int` + + The sequence number of this event. + + - `type: Literal["response.content_part.added"]` + + The type of the event. Always `response.content_part.added`. + + - `"response.content_part.added"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `call_id: Optional[str]` +### Beta Response Content Part Done Event - The unique ID of the tool search call generated by the model. +- `class BetaResponseContentPartDoneEvent: …` - - `execution: Optional[Literal["server", "client"]]` + Emitted when a content part is done. - Whether tool search was executed by the server or by the client. + - `content_index: int` - - `"server"` + The index of the content part that is done. - - `"client"` + - `item_id: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The ID of the output item that the content part was added to. - The status of the tool search call. + - `output_index: int` - - `"in_progress"` + The index of the output item that the content part was added to. - - `"completed"` + - `part: Part` - - `"incomplete"` + The content part that is done. - - `class BetaResponseToolSearchOutputItemParam: …` + - `class BetaResponseOutputText: …` - - `tools: List[BetaTool]` + A text output from the model. - The loaded tool definitions returned by the tool search output. + - `annotations: List[Annotation]` - - `class BetaFunctionTool: …` + The annotations of the text output. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class AnnotationFileCitation: …` - - `name: str` + A citation to a file. - The name of the function to call. + - `file_id: str` - - `parameters: Optional[Dict[str, object]]` + The ID of the file. - A JSON schema object describing the parameters of the function. + - `filename: str` - - `strict: Optional[bool]` + The filename of the file cited. - Whether strict parameter validation is enforced for this function tool. + - `index: int` - - `type: Literal["function"]` + The index of the file in the list of files. - The type of the function tool. Always `function`. + - `type: Literal["file_citation"]` - - `"function"` + The type of the file citation. Always `file_citation`. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"file_citation"` - The tool invocation context(s). + - `class AnnotationURLCitation: …` - - `"direct"` + A citation for a web resource used to generate a model response. - - `"programmatic"` + - `end_index: int` - - `defer_loading: Optional[bool]` + The index of the last character of the URL citation in the message. - Whether this function is deferred and loaded via tool search. + - `start_index: int` - - `description: Optional[str]` + The index of the first character of the URL citation in the message. - A description of the function. Used by the model to determine whether or not to call the function. + - `title: str` - - `output_schema: Optional[Dict[str, object]]` + The title of the web resource. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `type: Literal["url_citation"]` - - `class BetaFileSearchTool: …` + The type of the URL citation. Always `url_citation`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `"url_citation"` - - `type: Literal["file_search"]` + - `url: str` - The type of the file search tool. Always `file_search`. + The URL of the web resource. - - `"file_search"` + - `class AnnotationContainerFileCitation: …` - - `vector_store_ids: List[str]` + A citation for a container file used to generate a model response. - The IDs of the vector stores to search. + - `container_id: str` - - `filters: Optional[Filters]` + The ID of the container file. - A filter to apply. + - `end_index: int` - - `class FiltersComparisonFilter: …` + The index of the last character of the container file citation in the message. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `file_id: str` - - `key: str` + The ID of the file. - The key to compare against the value. + - `filename: str` - - `type: Literal["eq", "ne", "gt", 5 more]` + The filename of the container file cited. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `start_index: int` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The index of the first character of the container file citation in the message. - - `"eq"` + - `type: Literal["container_file_citation"]` - - `"ne"` + The type of the container file citation. Always `container_file_citation`. - - `"gt"` + - `"container_file_citation"` - - `"gte"` + - `class AnnotationFilePath: …` - - `"lt"` + A path to a file. - - `"lte"` + - `file_id: str` - - `"in"` + The ID of the file. - - `"nin"` + - `index: int` - - `value: Union[str, float, bool, List[object]]` + The index of the file in the list of files. - The value to compare against the attribute key; supports string, number, or boolean types. + - `type: Literal["file_path"]` - - `str` + The type of the file path. Always `file_path`. - - `float` + - `"file_path"` - - `bool` + - `text: str` - - `List[object]` + The text output from the model. - - `class FiltersCompoundFilter: …` + - `type: Literal["output_text"]` - Combine multiple filters using `and` or `or`. + The type of the output text. Always `output_text`. - - `filters: List[FiltersCompoundFilterFilter]` + - `"output_text"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `logprobs: Optional[List[Logprob]]` - - `class FiltersCompoundFilterFilterComparisonFilter: …` + - `token: str` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `bytes: List[int]` - - `key: str` + - `logprob: float` - The key to compare against the value. + - `top_logprobs: List[LogprobTopLogprob]` - - `type: Literal["eq", "ne", "gt", 5 more]` + - `token: str` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `bytes: List[int]` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `logprob: float` - - `"eq"` + - `class BetaResponseOutputRefusal: …` - - `"ne"` + A refusal from the model. - - `"gt"` + - `refusal: str` - - `"gte"` + The refusal explanation from the model. - - `"lt"` + - `type: Literal["refusal"]` - - `"lte"` + The type of the refusal. Always `refusal`. - - `"in"` + - `"refusal"` - - `"nin"` + - `class PartReasoningText: …` - - `value: Union[str, float, bool, List[object]]` + Reasoning text from the model. - The value to compare against the attribute key; supports string, number, or boolean types. + - `text: str` - - `str` + The reasoning text from the model. - - `float` + - `type: Literal["reasoning_text"]` - - `bool` + The type of the reasoning text. Always `reasoning_text`. - - `List[object]` + - `"reasoning_text"` - - `object` + - `sequence_number: int` - - `type: Literal["and", "or"]` + The sequence number of this event. - Type of operation: `and` or `or`. + - `type: Literal["response.content_part.done"]` - - `"and"` + The type of the event. Always `response.content_part.done`. - - `"or"` + - `"response.content_part.done"` - - `max_num_results: Optional[int]` + - `agent: Optional[Agent]` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The agent that owns this multi-agent streaming event. - - `ranking_options: Optional[RankingOptions]` + - `agent_name: str` - Ranking options for search. + The canonical name of the agent that produced this item. - - `hybrid_search: Optional[RankingOptionsHybridSearch]` +### Beta Response Conversation Param - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. +- `class BetaResponseConversationParam: …` - - `embedding_weight: float` + The conversation that this response belongs to. - The weight of the embedding in the reciprocal ranking fusion. + - `id: str` - - `text_weight: float` + The unique ID of the conversation. - The weight of the text in the reciprocal ranking fusion. +### Beta Response Created Event - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` +- `class BetaResponseCreatedEvent: …` - The ranker to use for the file search. + An event that is emitted when a response is created. - - `"auto"` + - `response: BetaResponse` - - `"default-2024-11-15"` + The response that was created. - - `score_threshold: Optional[float]` + - `id: str` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + Unique identifier for this Response. - - `class BetaComputerTool: …` + - `created_at: float` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Unix timestamp (in seconds) of when this Response was created. - - `type: Literal["computer"]` + - `error: Optional[BetaResponseError]` - The type of the computer tool. Always `computer`. + An error object returned when the model fails to generate a Response. - - `"computer"` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` - - `class BetaComputerUsePreviewTool: …` + The error code for the response. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"server_error"` - - `display_height: int` + - `"rate_limit_exceeded"` - The height of the computer display. + - `"invalid_prompt"` - - `display_width: int` + - `"bio_policy"` - The width of the computer display. + - `"vector_store_timeout"` - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `"invalid_image"` - The type of computer environment to control. + - `"invalid_image_format"` - - `"windows"` + - `"invalid_base64_image"` - - `"mac"` + - `"invalid_image_url"` - - `"linux"` + - `"image_too_large"` - - `"ubuntu"` + - `"image_too_small"` - - `"browser"` + - `"image_parse_error"` - - `type: Literal["computer_use_preview"]` + - `"image_content_policy_violation"` - The type of the computer use tool. Always `computer_use_preview`. + - `"invalid_image_mode"` - - `"computer_use_preview"` + - `"image_file_too_large"` - - `class BetaWebSearchTool: …` + - `"unsupported_image_media_type"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"empty_image_file"` - - `type: Literal["web_search", "web_search_2025_08_26"]` + - `"failed_to_download_image"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"image_file_not_found"` - - `"web_search"` + - `message: str` - - `"web_search_2025_08_26"` + A human-readable description of the error. - - `filters: Optional[Filters]` + - `incomplete_details: Optional[IncompleteDetails]` - Filters for the search. + Details about why the response is incomplete. - - `allowed_domains: Optional[List[str]]` + - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The reason why the response is incomplete. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"max_output_tokens"` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `"content_filter"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `instructions: Union[str, List[BetaResponseInputItem], null]` - - `"low"` + A system (or developer) message inserted into the model's context. - - `"medium"` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `"high"` + - `str` - - `user_location: Optional[UserLocation]` + A text input to the model, equivalent to a text input with the + `developer` role. - The approximate location of the user. + - `List[BetaResponseInputItem]` - - `city: Optional[str]` + A list of one or many input items to the model, containing + different content types. - Free text input for the city of the user, e.g. `San Francisco`. + - `class BetaEasyInputMessage: …` - - `country: Optional[str]` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `content: Union[str, BetaResponseInputMessageContentList]` - - `region: Optional[str]` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - Free text input for the region of the user, e.g. `California`. + - `str` - - `timezone: Optional[str]` + A text input to the model. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `List[BetaResponseInputContent]` - - `type: Optional[Literal["approximate"]]` + - `class BetaResponseInputText: …` - The type of location approximation. Always `approximate`. + A text input to the model. - - `"approximate"` + - `text: str` - - `class Mcp: …` + The text input to the model. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: Literal["input_text"]` - - `server_label: str` + The type of the input item. Always `input_text`. - A label for this MCP server, used to identify it in tool calls. + - `"input_text"` - - `type: Literal["mcp"]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The type of the MCP tool. Always `mcp`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"mcp"` + - `mode: Literal["explicit"]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The breakpoint mode. Always `explicit`. - The tool invocation context(s). + - `"explicit"` - - `"direct"` + - `class BetaResponseInputImage: …` - - `"programmatic"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `allowed_tools: Optional[McpAllowedTools]` + - `detail: Literal["low", "high", "auto", "original"]` - List of allowed tool names or a filter object. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `List[str]` + - `"low"` - A string array of allowed tool names + - `"high"` - - `class McpAllowedToolsMcpToolFilter: …` + - `"auto"` - A filter object to specify which tools are allowed. + - `"original"` - - `read_only: Optional[bool]` + - `type: Literal["input_image"]` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The type of the input item. Always `input_image`. - - `tool_names: Optional[List[str]]` + - `"input_image"` - List of allowed tool names. + - `file_id: Optional[str]` - - `authorization: Optional[str]` + The ID of the file to be sent to the model. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `image_url: Optional[str]` - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Currently supported `connector_id` values are: + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `mode: Literal["explicit"]` - - `"connector_dropbox"` + The breakpoint mode. Always `explicit`. - - `"connector_gmail"` + - `"explicit"` - - `"connector_googlecalendar"` + - `class BetaResponseInputFile: …` - - `"connector_googledrive"` + A file input to the model. - - `"connector_microsoftteams"` + - `type: Literal["input_file"]` - - `"connector_outlookcalendar"` + The type of the input item. Always `input_file`. - - `"connector_outlookemail"` + - `"input_file"` - - `"connector_sharepoint"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `defer_loading: Optional[bool]` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - Whether this MCP tool is deferred and discovered via tool search. + - `"auto"` - - `headers: Optional[Dict[str, str]]` + - `"low"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"high"` - - `require_approval: Optional[McpRequireApproval]` + - `file_data: Optional[str]` - Specify which of the MCP server's tools require approval. + The content of the file to be sent to the model. - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `file_id: Optional[str]` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The ID of the file to be sent to the model. - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `file_url: Optional[str]` - A filter object to specify which tools are allowed. + The URL of the file to be sent to the model. - - `read_only: Optional[bool]` + - `filename: Optional[str]` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The name of the file to be sent to the model. - - `tool_names: Optional[List[str]]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - List of allowed tool names. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + - `mode: Literal["explicit"]` - A filter object to specify which tools are allowed. + The breakpoint mode. Always `explicit`. - - `read_only: Optional[bool]` + - `"explicit"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `role: Literal["user", "assistant", "system", "developer"]` - - `tool_names: Optional[List[str]]` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - List of allowed tool names. + - `"user"` - - `Literal["always", "never"]` + - `"assistant"` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `"system"` - - `"always"` + - `"developer"` - - `"never"` + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `server_description: Optional[str]` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - Optional description of the MCP server, used to provide more context. + - `"commentary"` - - `server_url: Optional[str]` + - `"final_answer"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `type: Optional[Literal["message"]]` - - `tunnel_id: Optional[str]` + The type of the message input. Always `message`. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `"message"` - - `class CodeInterpreter: …` + - `class Message: …` - A tool that runs Python code to help generate a response to a prompt. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `container: CodeInterpreterContainer` + - `content: BetaResponseInputMessageContentList` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + A list of one or many input items to the model, containing different content + types. - - `str` + - `class BetaResponseInputText: …` - The container ID. + A text input to the model. - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `class BetaResponseInputImage: …` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `type: Literal["auto"]` + - `class BetaResponseInputFile: …` - Always `auto`. + A file input to the model. - - `"auto"` + - `role: Literal["user", "system", "developer"]` - - `file_ids: Optional[List[str]]` + The role of the message input. One of `user`, `system`, or `developer`. - An optional list of uploaded files to make available to your code. + - `"user"` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `"system"` - The memory limit for the code interpreter container. + - `"developer"` - - `"1g"` + - `agent: Optional[MessageAgent]` - - `"4g"` + The agent that produced this item. - - `"16g"` + - `agent_name: str` - - `"64g"` + The canonical name of the agent that produced this item. - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Network access policy for the container. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class BetaContainerNetworkPolicyDisabled: …` + - `"in_progress"` - - `type: Literal["disabled"]` + - `"completed"` - Disable outbound network access. Always `disabled`. + - `"incomplete"` - - `"disabled"` + - `type: Optional[Literal["message"]]` - - `class BetaContainerNetworkPolicyAllowlist: …` + The type of the message input. Always set to `message`. - - `allowed_domains: List[str]` + - `"message"` - A list of allowed domains when type is `allowlist`. + - `class BetaResponseOutputMessage: …` - - `type: Literal["allowlist"]` + An output message from the model. - Allow outbound network access only to specified domains. Always `allowlist`. + - `id: str` - - `"allowlist"` + The unique ID of the output message. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `content: List[Content]` - Optional domain-scoped secrets for allowlisted domains. + The content of the output message. - - `domain: str` + - `class BetaResponseOutputText: …` - The domain associated with the secret. + A text output from the model. - - `name: str` + - `annotations: List[Annotation]` - The name of the secret to inject for the domain. + The annotations of the text output. - - `value: str` + - `class AnnotationFileCitation: …` - The secret value to inject for the domain. + A citation to a file. - - `type: Literal["code_interpreter"]` + - `file_id: str` - The type of the code interpreter tool. Always `code_interpreter`. + The ID of the file. - - `"code_interpreter"` + - `filename: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The filename of the file cited. - The tool invocation context(s). + - `index: int` - - `"direct"` + The index of the file in the list of files. - - `"programmatic"` + - `type: Literal["file_citation"]` - - `class ProgrammaticToolCalling: …` + The type of the file citation. Always `file_citation`. - - `type: Literal["programmatic_tool_calling"]` + - `"file_citation"` - The type of the tool. Always `programmatic_tool_calling`. + - `class AnnotationURLCitation: …` - - `"programmatic_tool_calling"` + A citation for a web resource used to generate a model response. - - `class ImageGeneration: …` + - `end_index: int` - A tool that generates images using the GPT image models. + The index of the last character of the URL citation in the message. - - `type: Literal["image_generation"]` + - `start_index: int` - The type of the image generation tool. Always `image_generation`. + The index of the first character of the URL citation in the message. - - `"image_generation"` + - `title: str` - - `action: Optional[Literal["generate", "edit", "auto"]]` + The title of the web resource. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `type: Literal["url_citation"]` - - `"generate"` + The type of the URL citation. Always `url_citation`. - - `"edit"` + - `"url_citation"` - - `"auto"` + - `url: str` - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + The URL of the web resource. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `class AnnotationContainerFileCitation: …` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + A citation for a container file used to generate a model response. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `container_id: str` - - `"transparent"` + The ID of the container file. - - `"opaque"` + - `end_index: int` - - `"auto"` + The index of the last character of the container file citation in the message. - - `input_fidelity: Optional[Literal["high", "low"]]` + - `file_id: str` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + The ID of the file. - - `"high"` + - `filename: str` - - `"low"` + The filename of the container file cited. - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + - `start_index: int` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The index of the first character of the container file citation in the message. - - `file_id: Optional[str]` + - `type: Literal["container_file_citation"]` - File ID for the mask image. + The type of the container file citation. Always `container_file_citation`. - - `image_url: Optional[str]` + - `"container_file_citation"` - Base64-encoded mask image. + - `class AnnotationFilePath: …` - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + A path to a file. - The image generation model to use. Default: `gpt-image-1`. + - `file_id: str` - - `str` + The ID of the file. - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `index: int` - The image generation model to use. Default: `gpt-image-1`. + The index of the file in the list of files. - - `"gpt-image-1"` + - `type: Literal["file_path"]` - - `"gpt-image-1-mini"` + The type of the file path. Always `file_path`. - - `"gpt-image-2"` + - `"file_path"` - - `"gpt-image-2-2026-04-21"` + - `text: str` - - `"gpt-image-1.5"` + The text output from the model. - - `"chatgpt-image-latest"` + - `type: Literal["output_text"]` - - `moderation: Optional[Literal["auto", "low"]]` + The type of the output text. Always `output_text`. - Moderation level for the generated image. Default: `auto`. + - `"output_text"` - - `"auto"` + - `logprobs: Optional[List[Logprob]]` - - `"low"` + - `token: str` - - `output_compression: Optional[int]` + - `bytes: List[int]` - Compression level for the output image. Default: 100. + - `logprob: float` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + - `top_logprobs: List[LogprobTopLogprob]` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `token: str` - - `"png"` + - `bytes: List[int]` - - `"webp"` + - `logprob: float` - - `"jpeg"` + - `class BetaResponseOutputRefusal: …` - - `partial_images: Optional[int]` + A refusal from the model. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `refusal: str` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + The refusal explanation from the model. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `type: Literal["refusal"]` - - `"low"` + The type of the refusal. Always `refusal`. - - `"medium"` + - `"refusal"` - - `"high"` + - `role: Literal["assistant"]` - - `"auto"` + The role of the output message. Always `assistant`. - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + - `"assistant"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `str` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `"in_progress"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"completed"` - - `"1024x1024"` + - `"incomplete"` - - `"1024x1536"` + - `type: Literal["message"]` - - `"1536x1024"` + The type of the output message. Always `message`. - - `"auto"` + - `"message"` - - `class LocalShell: …` + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `phase: Optional[Literal["commentary", "final_answer"]]` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `class BetaResponseFileSearchToolCall: …` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `id: str` + + The unique ID of the file search tool call. + + - `queries: List[str]` + + The queries used to search for files. + + - `status: Literal["in_progress", "searching", "completed", 2 more]` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` - A tool that allows the model to execute shell commands in a local environment. + - `"completed"` - - `type: Literal["local_shell"]` + - `"incomplete"` - The type of the local shell tool. Always `local_shell`. + - `"failed"` - - `"local_shell"` + - `type: Literal["file_search_call"]` - - `class BetaFunctionShellTool: …` + The type of the file search tool call. Always `file_search_call`. - A tool that allows the model to execute shell commands. + - `"file_search_call"` - - `type: Literal["shell"]` + - `agent: Optional[Agent]` - The type of the shell tool. Always `shell`. + The agent that produced this item. - - `"shell"` + - `agent_name: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `results: Optional[List[Result]]` - - `"direct"` + The results of the file search tool call. - - `"programmatic"` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - - `environment: Optional[Environment]` + 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, booleans, or numbers. - - `class BetaContainerAuto: …` + - `str` - - `type: Literal["container_auto"]` + - `float` - Automatically creates a container for this request + - `bool` - - `"container_auto"` + - `file_id: Optional[str]` - - `file_ids: Optional[List[str]]` + The unique ID of the file. - An optional list of uploaded files to make available to your code. + - `filename: Optional[str]` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + The name of the file. - The memory limit for the container. + - `score: Optional[float]` - - `"1g"` + The relevance score of the file - a value between 0 and 1. - - `"4g"` + - `text: Optional[str]` - - `"16g"` + The text that was retrieved from the file. - - `"64g"` + - `class BetaResponseComputerToolCall: …` - - `network_policy: Optional[NetworkPolicy]` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - Network access policy for the container. + - `id: str` - - `class BetaContainerNetworkPolicyDisabled: …` + The unique ID of the computer call. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `call_id: str` - - `skills: Optional[List[Skill]]` + An identifier used when responding to the tool call with output. - An optional list of skills referenced by id or inline data. + - `pending_safety_checks: List[PendingSafetyCheck]` - - `class BetaSkillReference: …` + The pending safety checks for the computer call. - - `skill_id: str` + - `id: str` - The ID of the referenced skill. + The ID of the pending safety check. - - `type: Literal["skill_reference"]` + - `code: Optional[str]` - References a skill created with the /v1/skills endpoint. + The type of the pending safety check. - - `"skill_reference"` + - `message: Optional[str]` - - `version: Optional[str]` + Details about the pending safety check. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `class BetaInlineSkill: …` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `description: str` + - `"in_progress"` - The description of the skill. + - `"completed"` - - `name: str` + - `"incomplete"` - The name of the skill. + - `type: Literal["computer_call"]` - - `source: BetaInlineSkillSource` + The type of the computer call. Always `computer_call`. - Inline skill payload + - `"computer_call"` - - `data: str` + - `action: Optional[BetaComputerAction]` - Base64-encoded skill zip bundle. + A click action. - - `media_type: Literal["application/zip"]` + - `class Click: …` - The media type of the inline skill payload. Must be `application/zip`. + A click action. - - `"application/zip"` + - `button: Literal["left", "right", "wheel", 2 more]` - - `type: Literal["base64"]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The type of the inline skill source. Must be `base64`. + - `"left"` - - `"base64"` + - `"right"` - - `type: Literal["inline"]` + - `"wheel"` - Defines an inline skill for this request. + - `"back"` - - `"inline"` + - `"forward"` - - `class BetaLocalEnvironment: …` + - `type: Literal["click"]` - - `type: Literal["local"]` + Specifies the event type. For a click action, this property is always `click`. - Use a local computer environment. + - `"click"` - - `"local"` + - `x: int` - - `skills: Optional[List[BetaLocalSkill]]` + The x-coordinate where the click occurred. - An optional list of skills. + - `y: int` - - `description: str` + The y-coordinate where the click occurred. - The description of the skill. + - `keys: Optional[List[str]]` - - `name: str` + The keys being held while clicking. - The name of the skill. + - `class DoubleClick: …` - - `path: str` + A double click action. - The path to the directory containing the skill. + - `keys: Optional[List[str]]` - - `class BetaContainerReference: …` + The keys being held while double-clicking. - - `container_id: str` + - `type: Literal["double_click"]` - The ID of the referenced container. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `type: Literal["container_reference"]` + - `"double_click"` - References a container created with the /v1/containers endpoint + - `x: int` - - `"container_reference"` + The x-coordinate where the double click occurred. - - `class BetaCustomTool: …` + - `y: int` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The y-coordinate where the double click occurred. - - `name: str` + - `class Drag: …` - The name of the custom tool, used to identify it in tool calls. + A drag action. - - `type: Literal["custom"]` + - `path: List[DragPath]` - The type of the custom tool. Always `custom`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"custom"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `x: int` - The tool invocation context(s). + The x-coordinate. - - `"direct"` + - `y: int` - - `"programmatic"` + The y-coordinate. - - `defer_loading: Optional[bool]` + - `type: Literal["drag"]` - Whether this tool should be deferred and discovered via tool search. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `description: Optional[str]` + - `"drag"` - Optional description of the custom tool, used to provide more context. + - `keys: Optional[List[str]]` - - `format: Optional[Format]` + The keys being held while dragging the mouse. - The input format for the custom tool. Default is unconstrained text. + - `class Keypress: …` - - `class FormatText: …` + A collection of keypresses the model would like to perform. - Unconstrained free-form text. + - `keys: List[str]` - - `type: Literal["text"]` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - Unconstrained text format. Always `text`. + - `type: Literal["keypress"]` - - `"text"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `class FormatGrammar: …` + - `"keypress"` - A grammar defined by the user. + - `class Move: …` - - `definition: str` + A mouse move action. - The grammar definition. + - `type: Literal["move"]` - - `syntax: Literal["lark", "regex"]` + Specifies the event type. For a move action, this property is always set to `move`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"move"` - - `"lark"` + - `x: int` - - `"regex"` + The x-coordinate to move to. - - `type: Literal["grammar"]` + - `y: int` - Grammar format. Always `grammar`. + The y-coordinate to move to. - - `"grammar"` + - `keys: Optional[List[str]]` - - `class BetaNamespaceTool: …` + The keys being held while moving the mouse. - Groups function/custom tools under a shared namespace. + - `class Screenshot: …` - - `description: str` + A screenshot action. - A description of the namespace shown to the model. + - `type: Literal["screenshot"]` - - `name: str` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The namespace name used in tool calls (for example, `crm`). + - `"screenshot"` - - `tools: List[Tool]` + - `class Scroll: …` - The function/custom tools available inside this namespace. + A scroll action. - - `class ToolFunction: …` + - `scroll_x: int` - - `name: str` + The horizontal scroll distance. - - `type: Literal["function"]` + - `scroll_y: int` - - `"function"` + The vertical scroll distance. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["scroll"]` - The tool invocation context(s). + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"direct"` + - `"scroll"` - - `"programmatic"` + - `x: int` - - `defer_loading: Optional[bool]` + The x-coordinate where the scroll occurred. - Whether this function should be deferred and discovered via tool search. + - `y: int` - - `description: Optional[str]` + The y-coordinate where the scroll occurred. - - `output_schema: Optional[Dict[str, object]]` + - `keys: Optional[List[str]]` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The keys being held while scrolling. - - `parameters: Optional[object]` + - `class Type: …` - - `strict: Optional[bool]` + An action to type in text. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `text: str` - - `class BetaCustomTool: …` + The text to type. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: Literal["type"]` - - `type: Literal["namespace"]` + Specifies the event type. For a type action, this property is always set to `type`. - The type of the tool. Always `namespace`. + - `"type"` - - `"namespace"` + - `class Wait: …` - - `class BetaToolSearchTool: …` + A wait action. - Hosted or BYOT tool search configuration for deferred tools. + - `type: Literal["wait"]` - - `type: Literal["tool_search"]` + Specifies the event type. For a wait action, this property is always set to `wait`. - The type of the tool. Always `tool_search`. + - `"wait"` - - `"tool_search"` + - `actions: Optional[BetaComputerActionList]` - - `description: Optional[str]` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - Description shown to the model for a client-executed tool search tool. + - `class Click: …` - - `execution: Optional[Literal["server", "client"]]` + A click action. - Whether tool search is executed by the server or by the client. + - `class DoubleClick: …` - - `"server"` + A double click action. - - `"client"` + - `class Drag: …` - - `parameters: Optional[object]` + A drag action. - Parameter schema for a client-executed tool search tool. + - `class Keypress: …` - - `class BetaWebSearchPreviewTool: …` + A collection of keypresses the model would like to perform. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class Move: …` - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + A mouse move action. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `class Screenshot: …` - - `"web_search_preview"` + A screenshot action. - - `"web_search_preview_2025_03_11"` + - `class Scroll: …` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + A scroll action. - - `"text"` + - `class Type: …` - - `"image"` + An action to type in text. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `class Wait: …` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + A wait action. - - `"low"` + - `agent: Optional[Agent]` - - `"medium"` + The agent that produced this item. - - `"high"` + - `agent_name: str` - - `user_location: Optional[UserLocation]` + The canonical name of the agent that produced this item. - The user's location. + - `class ComputerCallOutput: …` - - `type: Literal["approximate"]` + The output of a computer tool call. - The type of location approximation. Always `approximate`. + - `call_id: str` - - `"approximate"` + The ID of the computer tool call that produced the output. - - `city: Optional[str]` + - `output: BetaResponseComputerToolCallOutputScreenshot` - Free text input for the city of the user, e.g. `San Francisco`. + A computer screenshot image used with the computer use tool. - - `country: Optional[str]` + - `type: Literal["computer_screenshot"]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `region: Optional[str]` + - `"computer_screenshot"` - Free text input for the region of the user, e.g. `California`. + - `file_id: Optional[str]` - - `timezone: Optional[str]` + The identifier of an uploaded file that contains the screenshot. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `image_url: Optional[str]` - - `class BetaApplyPatchTool: …` + The URL of the screenshot image. - Allows the assistant to create, delete, or update files using unified diffs. + - `type: Literal["computer_call_output"]` - - `type: Literal["apply_patch"]` + The type of the computer tool call output. Always `computer_call_output`. - The type of the tool. Always `apply_patch`. + - `"computer_call_output"` - - `"apply_patch"` + - `id: Optional[str]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The ID of the computer tool call output. - The tool invocation context(s). + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - - `"direct"` + The safety checks reported by the API that have been acknowledged by the developer. - - `"programmatic"` + - `id: str` - - `type: Literal["tool_search_output"]` + The ID of the pending safety check. - The item type. Always `tool_search_output`. + - `code: Optional[str]` - - `"tool_search_output"` + The type of the pending safety check. - - `id: Optional[str]` + - `message: Optional[str]` - The unique ID of this tool search output. + Details about the pending safety check. - - `agent: Optional[Agent]` + - `agent: Optional[ComputerCallOutputAgent]` The agent that produced this item. @@ -44116,115 +54252,113 @@ Compact a response The canonical name of the agent that produced this item. - - `call_id: Optional[str]` - - The unique ID of the tool search call generated by the model. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `execution: Optional[Literal["server", "client"]]` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - Whether tool search was executed by the server or by the client. + - `"in_progress"` - - `"server"` + - `"completed"` - - `"client"` + - `"incomplete"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `class BetaResponseFunctionWebSearch: …` - The status of the tool search output. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `"in_progress"` + - `id: str` - - `"completed"` + The unique ID of the web search tool call. - - `"incomplete"` + - `action: Action` - - `class AdditionalTools: …` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `role: Literal["developer"]` + - `class ActionSearch: …` - The role that provided the additional tools. Only `developer` is supported. + Action type "search" - Performs a web search query. - - `"developer"` + - `type: Literal["search"]` - - `tools: List[BetaTool]` + The action type. - A list of additional tools made available at this item. + - `"search"` - - `class BetaFunctionTool: …` + - `queries: Optional[List[str]]` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The search queries. - - `class BetaFileSearchTool: …` + - `query: Optional[str]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The search query. - - `class BetaComputerTool: …` + - `sources: Optional[List[ActionSearchSource]]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The sources used in the search. - - `class BetaComputerUsePreviewTool: …` + - `type: Literal["url"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of source. Always `url`. - - `class BetaWebSearchTool: …` + - `"url"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `url: str` - - `class Mcp: …` + The URL of the source. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `class ActionOpenPage: …` - - `class CodeInterpreter: …` + Action type "open_page" - Opens a specific URL from search results. - A tool that runs Python code to help generate a response to a prompt. + - `type: Literal["open_page"]` - - `class ProgrammaticToolCalling: …` + The action type. - - `class ImageGeneration: …` + - `"open_page"` - A tool that generates images using the GPT image models. + - `url: Optional[str]` - - `class LocalShell: …` + The URL opened by the model. - A tool that allows the model to execute shell commands in a local environment. + - `class ActionFindInPage: …` - - `class BetaFunctionShellTool: …` + Action type "find_in_page": Searches for a pattern within a loaded page. - A tool that allows the model to execute shell commands. + - `pattern: str` - - `class BetaCustomTool: …` + The pattern or text to search for within the page. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: Literal["find_in_page"]` - - `class BetaNamespaceTool: …` + The action type. - Groups function/custom tools under a shared namespace. + - `"find_in_page"` - - `class BetaToolSearchTool: …` + - `url: str` - Hosted or BYOT tool search configuration for deferred tools. + The URL of the page searched for the pattern. - - `class BetaWebSearchPreviewTool: …` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The status of the web search tool call. - - `class BetaApplyPatchTool: …` + - `"in_progress"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"searching"` - - `type: Literal["additional_tools"]` + - `"completed"` - The item type. Always `additional_tools`. + - `"failed"` - - `"additional_tools"` + - `type: Literal["web_search_call"]` - - `id: Optional[str]` + The type of the web search tool call. Always `web_search_call`. - The unique ID of this additional tools item. + - `"web_search_call"` - - `agent: Optional[AdditionalToolsAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -44232,36 +54366,32 @@ Compact a response The canonical name of the agent that produced this item. - - `class BetaResponseReasoningItem: …` - - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class BetaResponseFunctionToolCall: …` - - `id: str` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The unique identifier of the reasoning content. + - `arguments: str` - - `summary: List[Summary]` + A JSON string of the arguments to pass to the function. - Reasoning summary content. + - `call_id: str` - - `text: str` + The unique ID of the function tool call generated by the model. - A summary of the reasoning output from the model so far. + - `name: str` - - `type: Literal["summary_text"]` + The name of the function to run. - The type of the object. Always `summary_text`. + - `type: Literal["function_call"]` - - `"summary_text"` + The type of the function tool call. Always `function_call`. - - `type: Literal["reasoning"]` + - `"function_call"` - The type of the object. Always `reasoning`. + - `id: Optional[str]` - - `"reasoning"` + The unique ID of the function tool call. - `agent: Optional[Agent]` @@ -44271,24 +54401,29 @@ Compact a response The canonical name of the agent that produced this item. - - `content: Optional[List[Content]]` + - `caller: Optional[Caller]` - Reasoning text content. + The execution context that produced this tool call. - - `text: str` + - `class CallerDirect: …` - The reasoning text from the model. + - `type: Literal["direct"]` - - `type: Literal["reasoning_text"]` + - `"direct"` - The type of the reasoning text. Always `reasoning_text`. + - `class CallerProgram: …` - - `"reasoning_text"` + - `caller_id: str` - - `encrypted_content: Optional[str]` + The call ID of the program item that produced this tool call. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `type: Literal["program"]` + + - `"program"` + + - `namespace: Optional[str]` + + The namespace of the function to run. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` @@ -44301,140 +54436,145 @@ Compact a response - `"incomplete"` - - `class BetaResponseCompactionItemParam: …` + - `class FunctionCallOutput: …` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The output of a function tool call. - - `encrypted_content: str` + - `call_id: str` - The encrypted content of the compaction summary. + The unique ID of the function tool call generated by the model. - - `type: Literal["compaction"]` + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - The type of the item. Always `compaction`. + Text, image, or file output of the function tool call. - - `"compaction"` + - `str` - - `id: Optional[str]` + A JSON string of the output of the function tool call. - The ID of the compaction item. + - `List[BetaResponseFunctionCallOutputItem]` - - `agent: Optional[Agent]` + - `class BetaResponseInputTextContent: …` - The agent that produced this item. + A text input to the model. - - `agent_name: str` + - `text: str` - The canonical name of the agent that produced this item. + The text input to the model. - - `class ImageGenerationCall: …` + - `type: Literal["input_text"]` - An image generation request made by the model. + The type of the input item. Always `input_text`. - - `id: str` + - `"input_text"` - The unique ID of the image generation call. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `result: Optional[str]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The generated image encoded in base64. + - `mode: Literal["explicit"]` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + The breakpoint mode. Always `explicit`. - The status of the image generation call. + - `"explicit"` - - `"in_progress"` + - `class BetaResponseInputImageContent: …` - - `"completed"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `"generating"` + - `type: Literal["input_image"]` - - `"failed"` + The type of the input item. Always `input_image`. - - `type: Literal["image_generation_call"]` + - `"input_image"` - The type of the image generation call. Always `image_generation_call`. + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - - `"image_generation_call"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `agent: Optional[ImageGenerationCallAgent]` + - `"low"` - The agent that produced this item. + - `"high"` - - `agent_name: str` + - `"auto"` - The canonical name of the agent that produced this item. + - `"original"` - - `class BetaResponseCodeInterpreterToolCall: …` + - `file_id: Optional[str]` - A tool call to run code. + The ID of the file to be sent to the model. - - `id: str` + - `image_url: Optional[str]` - The unique ID of the code interpreter tool call. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `code: Optional[str]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The code to run, or null if not available. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `container_id: str` + - `mode: Literal["explicit"]` - The ID of the container used to run the code. + The breakpoint mode. Always `explicit`. - - `outputs: Optional[List[Output]]` + - `"explicit"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `class BetaResponseInputFileContent: …` - - `class OutputLogs: …` + A file input to the model. - The logs output from the code interpreter. + - `type: Literal["input_file"]` - - `logs: str` + The type of the input item. Always `input_file`. - The logs output from the code interpreter. + - `"input_file"` - - `type: Literal["logs"]` + - `detail: Optional[Literal["auto", "low", "high"]]` - The type of the output. Always `logs`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `"logs"` + - `"auto"` - - `class OutputImage: …` + - `"low"` - The image output from the code interpreter. + - `"high"` - - `type: Literal["image"]` + - `file_data: Optional[str]` - The type of the output. Always `image`. + The base64-encoded data of the file to be sent to the model. - - `"image"` + - `file_id: Optional[str]` - - `url: str` + The ID of the file to be sent to the model. - The URL of the image output from the code interpreter. + - `file_url: Optional[str]` - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + The URL of the file to be sent to the model. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `filename: Optional[str]` - - `"in_progress"` + The name of the file to be sent to the model. - - `"completed"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"incomplete"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"interpreting"` + - `mode: Literal["explicit"]` - - `"failed"` + The breakpoint mode. Always `explicit`. - - `type: Literal["code_interpreter_call"]` + - `"explicit"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `type: Literal["function_call_output"]` - - `"code_interpreter_call"` + The type of the function tool call output. Always `function_call_output`. - - `agent: Optional[Agent]` + - `"function_call_output"` + + - `id: Optional[str]` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: Optional[FunctionCallOutputAgent]` The agent that produced this item. @@ -44442,91 +54582,89 @@ Compact a response The canonical name of the agent that produced this item. - - `class LocalShellCall: …` - - A tool call to run a command on the local shell. + - `caller: Optional[FunctionCallOutputCaller]` - - `id: str` + The execution context that produced this tool call. - The unique ID of the local shell call. + - `class FunctionCallOutputCallerDirect: …` - - `action: LocalShellCallAction` + - `type: Literal["direct"]` - Execute a shell command on the server. + The caller type. Always `direct`. - - `command: List[str]` + - `"direct"` - The command to run. + - `class FunctionCallOutputCallerProgram: …` - - `env: Dict[str, str]` + - `caller_id: str` - Environment variables to set for the command. + The call ID of the program item that produced this tool call. - - `type: Literal["exec"]` + - `type: Literal["program"]` - The type of the local shell action. Always `exec`. + The caller type. Always `program`. - - `"exec"` + - `"program"` - - `timeout_ms: Optional[int]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Optional timeout in milliseconds for the command. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `user: Optional[str]` + - `"in_progress"` - Optional user to run the command as. + - `"completed"` - - `working_directory: Optional[str]` + - `"incomplete"` - Optional working directory to run the command in. + - `class AgentMessage: …` - - `call_id: str` + A message routed between agents. - The unique ID of the local shell tool call generated by the model. + - `author: str` - - `status: Literal["in_progress", "completed", "incomplete"]` + The sending agent identity. - The status of the local shell call. + - `content: List[AgentMessageContent]` - - `"in_progress"` + Plaintext, image, or encrypted content sent between agents. - - `"completed"` + - `class BetaResponseInputTextContent: …` - - `"incomplete"` + A text input to the model. - - `type: Literal["local_shell_call"]` + - `class BetaResponseInputImageContent: …` - The type of the local shell call. Always `local_shell_call`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `"local_shell_call"` + - `class AgentMessageContentEncryptedContent: …` - - `agent: Optional[LocalShellCallAgent]` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The agent that produced this item. + - `encrypted_content: str` - - `agent_name: str` + Opaque encrypted content. - The canonical name of the agent that produced this item. + - `type: Literal["encrypted_content"]` - - `class LocalShellCallOutput: …` + The type of the input item. Always `encrypted_content`. - The output of a local shell tool call. + - `"encrypted_content"` - - `id: str` + - `recipient: str` - The unique ID of the local shell tool call generated by the model. + The destination agent identity. - - `output: str` + - `type: Literal["agent_message"]` - A JSON string of the output of the local shell tool call. + The item type. Always `agent_message`. - - `type: Literal["local_shell_call_output"]` + - `"agent_message"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `id: Optional[str]` - - `"local_shell_call_output"` + The unique ID of this agent message item. - - `agent: Optional[LocalShellCallOutputAgent]` + - `agent: Optional[AgentMessageAgent]` The agent that produced this item. @@ -44534,51 +54672,43 @@ Compact a response The canonical name of the agent that produced this item. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` + - `class MultiAgentCall: …` - - `class ShellCall: …` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - A tool representing a request to execute one or more shell commands. + The multi-agent action that was executed. - - `action: ShellCallAction` + - `"spawn_agent"` - The shell commands and limits that describe how to run the tool call. + - `"interrupt_agent"` - - `commands: List[str]` + - `"list_agents"` - Ordered shell commands for the execution environment to run. + - `"send_message"` - - `max_output_length: Optional[int]` + - `"followup_task"` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `"wait_agent"` - - `timeout_ms: Optional[int]` + - `arguments: str` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The action arguments as a JSON string. - `call_id: str` - The unique ID of the shell tool call generated by the model. + The unique ID linking this call to its output. - - `type: Literal["shell_call"]` + - `type: Literal["multi_agent_call"]` - The type of the item. Always `shell_call`. + The item type. Always `multi_agent_call`. - - `"shell_call"` + - `"multi_agent_call"` - `id: Optional[str]` - The unique ID of the shell tool call. Populated when this item is returned via API. + The unique ID of this multi-agent call. - - `agent: Optional[ShellCallAgent]` + - `agent: Optional[MultiAgentCallAgent]` The agent that produced this item. @@ -44586,1301 +54716,1315 @@ Compact a response The canonical name of the agent that produced this item. - - `caller: Optional[ShellCallCaller]` - - The execution context that produced this tool call. - - - `class ShellCallCallerDirect: …` - - - `type: Literal["direct"]` - - The caller type. Always `direct`. - - - `"direct"` - - - `class ShellCallCallerProgram: …` - - - `caller_id: str` - - The call ID of the program item that produced this tool call. - - - `type: Literal["program"]` - - The caller type. Always `program`. - - - `"program"` - - - `environment: Optional[ShellCallEnvironment]` + - `class MultiAgentCallOutput: …` - The environment to execute the shell commands in. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `class BetaLocalEnvironment: …` + The multi-agent action that produced this result. - - `class BetaContainerReference: …` + - `"spawn_agent"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"interrupt_agent"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"list_agents"` - - `"in_progress"` + - `"send_message"` - - `"completed"` + - `"followup_task"` - - `"incomplete"` + - `"wait_agent"` - - `class ShellCallOutput: …` + - `call_id: str` - The streamed output items emitted by a shell tool call. + The unique ID of the multi-agent call. - - `call_id: str` + - `output: List[MultiAgentCallOutputOutput]` - The unique ID of the shell tool call generated by the model. + Text output returned by the multi-agent action. - - `output: List[BetaResponseFunctionShellCallOutputContent]` + - `text: str` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The text content. - - `outcome: Outcome` + - `type: Literal["output_text"]` - The exit or timeout outcome associated with this shell call. + The content type. Always `output_text`. - - `class OutcomeTimeout: …` + - `"output_text"` - Indicates that the shell call exceeded its configured time limit. + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - - `type: Literal["timeout"]` + Citations associated with the text content. - The outcome type. Always `timeout`. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - - `"timeout"` + - `file_id: str` - - `class OutcomeExit: …` + The ID of the file. - Indicates that the shell commands finished and returned an exit code. + - `filename: str` - - `exit_code: int` + The filename of the file cited. - The exit code returned by the shell process. + - `index: int` - - `type: Literal["exit"]` + The index of the file in the list of files. - The outcome type. Always `exit`. + - `type: Literal["file_citation"]` - - `"exit"` + The citation type. Always `file_citation`. - - `stderr: str` + - `"file_citation"` - Captured stderr output for the shell call. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` - - `stdout: str` + - `end_index: int` - Captured stdout output for the shell call. + The index of the last character of the citation in the message. - - `type: Literal["shell_call_output"]` + - `start_index: int` - The type of the item. Always `shell_call_output`. + The index of the first character of the citation in the message. - - `"shell_call_output"` + - `title: str` - - `id: Optional[str]` + The title of the cited resource. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `type: Literal["url_citation"]` - - `agent: Optional[ShellCallOutputAgent]` + The citation type. Always `url_citation`. - The agent that produced this item. + - `"url_citation"` - - `agent_name: str` + - `url: str` - The canonical name of the agent that produced this item. + The URL of the cited resource. - - `caller: Optional[ShellCallOutputCaller]` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` - The execution context that produced this tool call. + - `container_id: str` - - `class ShellCallOutputCallerDirect: …` + The ID of the container. - - `type: Literal["direct"]` + - `end_index: int` - The caller type. Always `direct`. + The index of the last character of the citation in the message. - - `"direct"` + - `file_id: str` - - `class ShellCallOutputCallerProgram: …` + The ID of the container file. - - `caller_id: str` + - `filename: str` - The call ID of the program item that produced this tool call. + The filename of the container file cited. - - `type: Literal["program"]` + - `start_index: int` - The caller type. Always `program`. + The index of the first character of the citation in the message. - - `"program"` + - `type: Literal["container_file_citation"]` - - `max_output_length: Optional[int]` + The citation type. Always `container_file_citation`. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `"container_file_citation"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `type: Literal["multi_agent_call_output"]` - The status of the shell call output. + The item type. Always `multi_agent_call_output`. - - `"in_progress"` + - `"multi_agent_call_output"` - - `"completed"` + - `id: Optional[str]` - - `"incomplete"` + The unique ID of this multi-agent call output. - - `class ApplyPatchCall: …` + - `agent: Optional[MultiAgentCallOutputAgent]` - A tool call representing a request to create, delete, or update files using diff patches. + The agent that produced this item. - - `call_id: str` + - `agent_name: str` - The unique ID of the apply patch tool call generated by the model. + The canonical name of the agent that produced this item. - - `operation: ApplyPatchCallOperation` + - `class ToolSearchCall: …` - The specific create, delete, or update instruction for the apply_patch tool call. + - `arguments: object` - - `class ApplyPatchCallOperationCreateFile: …` + The arguments supplied to the tool search call. - Instruction for creating a new file via the apply_patch tool. + - `type: Literal["tool_search_call"]` - - `diff: str` + The item type. Always `tool_search_call`. - Unified diff content to apply when creating the file. + - `"tool_search_call"` - - `path: str` + - `id: Optional[str]` - Path of the file to create relative to the workspace root. + The unique ID of this tool search call. - - `type: Literal["create_file"]` + - `agent: Optional[ToolSearchCallAgent]` - The operation type. Always `create_file`. + The agent that produced this item. - - `"create_file"` + - `agent_name: str` - - `class ApplyPatchCallOperationDeleteFile: …` + The canonical name of the agent that produced this item. - Instruction for deleting an existing file via the apply_patch tool. + - `call_id: Optional[str]` - - `path: str` + The unique ID of the tool search call generated by the model. - Path of the file to delete relative to the workspace root. + - `execution: Optional[Literal["server", "client"]]` - - `type: Literal["delete_file"]` + Whether tool search was executed by the server or by the client. - The operation type. Always `delete_file`. + - `"server"` - - `"delete_file"` + - `"client"` - - `class ApplyPatchCallOperationUpdateFile: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Instruction for updating an existing file via the apply_patch tool. + The status of the tool search call. - - `diff: str` + - `"in_progress"` - Unified diff content to apply to the existing file. + - `"completed"` - - `path: str` + - `"incomplete"` - Path of the file to update relative to the workspace root. + - `class BetaResponseToolSearchOutputItemParam: …` - - `type: Literal["update_file"]` + - `tools: List[BetaTool]` - The operation type. Always `update_file`. + The loaded tool definitions returned by the tool search output. - - `"update_file"` + - `class BetaFunctionTool: …` - - `status: Literal["in_progress", "completed"]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `name: str` - - `"in_progress"` + The name of the function to call. - - `"completed"` + - `parameters: Optional[Dict[str, object]]` - - `type: Literal["apply_patch_call"]` + A JSON schema object describing the parameters of the function. - The type of the item. Always `apply_patch_call`. + - `strict: Optional[bool]` - - `"apply_patch_call"` + Whether strict parameter validation is enforced for this function tool. - - `id: Optional[str]` + - `type: Literal["function"]` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The type of the function tool. Always `function`. - - `agent: Optional[ApplyPatchCallAgent]` + - `"function"` - The agent that produced this item. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `agent_name: str` + The tool invocation context(s). - The canonical name of the agent that produced this item. + - `"direct"` - - `caller: Optional[ApplyPatchCallCaller]` + - `"programmatic"` - The execution context that produced this tool call. + - `defer_loading: Optional[bool]` - - `class ApplyPatchCallCallerDirect: …` + Whether this function is deferred and loaded via tool search. - - `type: Literal["direct"]` + - `description: Optional[str]` - The caller type. Always `direct`. + A description of the function. Used by the model to determine whether or not to call the function. - - `"direct"` + - `output_schema: Optional[Dict[str, object]]` - - `class ApplyPatchCallCallerProgram: …` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `caller_id: str` + - `class BetaFileSearchTool: …` - The call ID of the program item that produced this tool call. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: Literal["program"]` + - `type: Literal["file_search"]` - The caller type. Always `program`. + The type of the file search tool. Always `file_search`. - - `"program"` + - `"file_search"` - - `class ApplyPatchCallOutput: …` + - `vector_store_ids: List[str]` - The streamed output emitted by an apply patch tool call. + The IDs of the vector stores to search. - - `call_id: str` + - `filters: Optional[Filters]` - The unique ID of the apply patch tool call generated by the model. + A filter to apply. - - `status: Literal["completed", "failed"]` + - `class FiltersComparisonFilter: …` - The status of the apply patch tool call output. One of `completed` or `failed`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"completed"` + - `key: str` - - `"failed"` + The key to compare against the value. - - `type: Literal["apply_patch_call_output"]` + - `type: Literal["eq", "ne", "gt", 5 more]` - The type of the item. Always `apply_patch_call_output`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"apply_patch_call_output"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `id: Optional[str]` + - `"eq"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"ne"` - - `agent: Optional[ApplyPatchCallOutputAgent]` + - `"gt"` - The agent that produced this item. + - `"gte"` - - `agent_name: str` + - `"lt"` - The canonical name of the agent that produced this item. + - `"lte"` - - `caller: Optional[ApplyPatchCallOutputCaller]` + - `"in"` - The execution context that produced this tool call. + - `"nin"` - - `class ApplyPatchCallOutputCallerDirect: …` + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `type: Literal["direct"]` + The value to compare against the attribute key; supports string, number, or boolean types. - The caller type. Always `direct`. + - `str` - - `"direct"` + - `float` - - `class ApplyPatchCallOutputCallerProgram: …` + - `bool` - - `caller_id: str` + - `List[Union[str, float]]` - The call ID of the program item that produced this tool call. + - `str` - - `type: Literal["program"]` + - `float` - The caller type. Always `program`. + - `class FiltersCompoundFilter: …` - - `"program"` + Combine multiple filters using `and` or `or`. - - `output: Optional[str]` + - `filters: List[FiltersCompoundFilterFilter]` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `class McpListTools: …` + - `class FiltersCompoundFilterFilterComparisonFilter: …` - A list of tools available on an MCP server. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `id: str` + - `key: str` - The unique ID of the list. + The key to compare against the value. - - `server_label: str` + - `type: Literal["eq", "ne", "gt", 5 more]` - The label of the MCP server. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `tools: List[McpListToolsTool]` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The tools available on the server. + - `"eq"` - - `input_schema: object` + - `"ne"` - The JSON schema describing the tool's input. + - `"gt"` - - `name: str` + - `"gte"` - The name of the tool. + - `"lt"` - - `annotations: Optional[object]` + - `"lte"` - Additional annotations about the tool. + - `"in"` - - `description: Optional[str]` + - `"nin"` - The description of the tool. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `type: Literal["mcp_list_tools"]` + The value to compare against the attribute key; supports string, number, or boolean types. - The type of the item. Always `mcp_list_tools`. + - `str` - - `"mcp_list_tools"` + - `float` - - `agent: Optional[McpListToolsAgent]` + - `bool` - The agent that produced this item. + - `List[Union[str, float]]` - - `agent_name: str` + - `str` - The canonical name of the agent that produced this item. + - `float` - - `error: Optional[str]` + - `object` - Error message if the server could not list tools. + - `type: Literal["and", "or"]` - - `class McpApprovalRequest: …` + Type of operation: `and` or `or`. - A request for human approval of a tool invocation. + - `"and"` - - `id: str` + - `"or"` - The unique ID of the approval request. + - `max_num_results: Optional[int]` - - `arguments: str` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - A JSON string of arguments for the tool. + - `ranking_options: Optional[RankingOptions]` - - `name: str` + Ranking options for search. - The name of the tool to run. + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - `server_label: str` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The label of the MCP server making the request. + - `embedding_weight: float` - - `type: Literal["mcp_approval_request"]` + The weight of the embedding in the reciprocal ranking fusion. - The type of the item. Always `mcp_approval_request`. + - `text_weight: float` - - `"mcp_approval_request"` + The weight of the text in the reciprocal ranking fusion. - - `agent: Optional[McpApprovalRequestAgent]` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - The agent that produced this item. + The ranker to use for the file search. - - `agent_name: str` + - `"auto"` - The canonical name of the agent that produced this item. + - `"default-2024-11-15"` - - `class McpApprovalResponse: …` + - `score_threshold: Optional[float]` - A response to an MCP approval request. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `approval_request_id: str` + - `class BetaComputerTool: …` - The ID of the approval request being answered. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `approve: bool` + - `type: Literal["computer"]` - Whether the request was approved. + The type of the computer tool. Always `computer`. - - `type: Literal["mcp_approval_response"]` + - `"computer"` - The type of the item. Always `mcp_approval_response`. + - `class BetaComputerUsePreviewTool: …` - - `"mcp_approval_response"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `id: Optional[str]` + - `display_height: int` - The unique ID of the approval response + The height of the computer display. - - `agent: Optional[McpApprovalResponseAgent]` + - `display_width: int` - The agent that produced this item. + The width of the computer display. - - `agent_name: str` + - `environment: Literal["windows", "mac", "linux", 2 more]` - The canonical name of the agent that produced this item. + The type of computer environment to control. - - `reason: Optional[str]` + - `"windows"` - Optional reason for the decision. + - `"mac"` - - `class McpCall: …` + - `"linux"` - An invocation of a tool on an MCP server. + - `"ubuntu"` - - `id: str` + - `"browser"` - The unique ID of the tool call. + - `type: Literal["computer_use_preview"]` - - `arguments: str` + The type of the computer use tool. Always `computer_use_preview`. - A JSON string of the arguments passed to the tool. + - `"computer_use_preview"` - - `name: str` + - `class BetaWebSearchTool: …` - The name of the tool that was run. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `server_label: str` + - `type: Literal["web_search", "web_search_2025_08_26"]` - The label of the MCP server running the tool. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `type: Literal["mcp_call"]` + - `"web_search"` - The type of the item. Always `mcp_call`. + - `"web_search_2025_08_26"` - - `"mcp_call"` + - `filters: Optional[Filters]` - - `agent: Optional[McpCallAgent]` + Filters for the search. - The agent that produced this item. + - `allowed_domains: Optional[List[str]]` - - `agent_name: str` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The canonical name of the agent that produced this item. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `approval_request_id: Optional[str]` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `error: Optional[str]` + - `"low"` - The error from the tool call, if any. + - `"medium"` - - `output: Optional[str]` + - `"high"` - The output from the tool call. + - `user_location: Optional[UserLocation]` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + The approximate location of the user. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `city: Optional[str]` - - `"in_progress"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"completed"` + - `country: Optional[str]` - - `"incomplete"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"calling"` + - `region: Optional[str]` - - `"failed"` + Free text input for the region of the user, e.g. `California`. - - `class BetaResponseCustomToolCallOutput: …` + - `timezone: Optional[str]` - The output of a custom tool call from your code, being sent back to the model. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `call_id: str` + - `type: Optional[Literal["approximate"]]` - The call ID, used to map this custom tool call output to a custom tool call. + The type of location approximation. Always `approximate`. - - `output: Union[str, List[OutputOutputContentList]]` + - `"approximate"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `class Mcp: …` - - `str` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - A string of the output of the custom tool call. + - `server_label: str` - - `List[OutputOutputContentList]` + A label for this MCP server, used to identify it in tool calls. - Text, image, or file output of the custom tool call. + - `type: Literal["mcp"]` - - `class BetaResponseInputText: …` + The type of the MCP tool. Always `mcp`. - A text input to the model. + - `"mcp"` - - `class BetaResponseInputImage: …` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The tool invocation context(s). - - `class BetaResponseInputFile: …` + - `"direct"` - A file input to the model. + - `"programmatic"` - - `type: Literal["custom_tool_call_output"]` + - `allowed_tools: Optional[McpAllowedTools]` - The type of the custom tool call output. Always `custom_tool_call_output`. + List of allowed tool names or a filter object. - - `"custom_tool_call_output"` + - `List[str]` - - `id: Optional[str]` + A string array of allowed tool names - The unique ID of the custom tool call output in the OpenAI platform. + - `class McpAllowedToolsMcpToolFilter: …` - - `agent: Optional[Agent]` + A filter object to specify which tools are allowed. - The agent that produced this item. + - `read_only: Optional[bool]` - - `agent_name: str` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The canonical name of the agent that produced this item. + - `tool_names: Optional[List[str]]` - - `caller: Optional[Caller]` + List of allowed tool names. - The execution context that produced this tool call. + - `authorization: Optional[str]` - - `class CallerDirect: …` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `type: Literal["direct"]` + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - The caller type. Always `direct`. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `"direct"` + Currently supported `connector_id` values are: - - `class CallerProgram: …` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `caller_id: str` + - `"connector_dropbox"` - The call ID of the program item that produced this tool call. + - `"connector_gmail"` - - `type: Literal["program"]` + - `"connector_googlecalendar"` - The caller type. Always `program`. + - `"connector_googledrive"` - - `"program"` + - `"connector_microsoftteams"` - - `class BetaResponseCustomToolCall: …` + - `"connector_outlookcalendar"` - A call to a custom tool created by the model. + - `"connector_outlookemail"` - - `call_id: str` + - `"connector_sharepoint"` - An identifier used to map this custom tool call to a tool call output. + - `defer_loading: Optional[bool]` - - `input: str` + Whether this MCP tool is deferred and discovered via tool search. - The input for the custom tool call generated by the model. + - `headers: Optional[Dict[str, str]]` - - `name: str` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The name of the custom tool being called. + - `require_approval: Optional[McpRequireApproval]` - - `type: Literal["custom_tool_call"]` + Specify which of the MCP server's tools require approval. - The type of the custom tool call. Always `custom_tool_call`. + - `class McpRequireApprovalMcpToolApprovalFilter: …` - - `"custom_tool_call"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `id: Optional[str]` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - The unique ID of the custom tool call in the OpenAI platform. + A filter object to specify which tools are allowed. - - `agent: Optional[Agent]` + - `read_only: Optional[bool]` - The agent that produced this item. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `agent_name: str` + - `tool_names: Optional[List[str]]` - The canonical name of the agent that produced this item. + List of allowed tool names. - - `caller: Optional[Caller]` + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - The execution context that produced this tool call. + A filter object to specify which tools are allowed. - - `class CallerDirect: …` + - `read_only: Optional[bool]` - - `type: Literal["direct"]` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"direct"` + - `tool_names: Optional[List[str]]` - - `class CallerProgram: …` + List of allowed tool names. - - `caller_id: str` + - `Literal["always", "never"]` - The call ID of the program item that produced this tool call. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `type: Literal["program"]` + - `"always"` - - `"program"` + - `"never"` - - `namespace: Optional[str]` + - `server_description: Optional[str]` - The namespace of the custom tool being called. + Optional description of the MCP server, used to provide more context. - - `class CompactionTrigger: …` + - `server_url: Optional[str]` - Compacts the current context. Must be the final input item. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `type: Literal["compaction_trigger"]` + - `tunnel_id: Optional[str]` - The type of the item. Always `compaction_trigger`. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `"compaction_trigger"` + - `class CodeInterpreter: …` - - `agent: Optional[CompactionTriggerAgent]` + A tool that runs Python code to help generate a response to a prompt. - The agent that produced this item. + - `container: CodeInterpreterContainer` - - `agent_name: str` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The canonical name of the agent that produced this item. + - `str` - - `class ItemReference: …` + The container ID. - An internal identifier for an item to reference. + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `id: str` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The ID of the item to reference. + - `type: Literal["auto"]` - - `agent: Optional[ItemReferenceAgent]` + Always `auto`. - The agent that produced this item. + - `"auto"` - - `agent_name: str` + - `file_ids: Optional[List[str]]` - The canonical name of the agent that produced this item. + An optional list of uploaded files to make available to your code. - - `type: Optional[Literal["item_reference"]]` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The type of item to reference. Always `item_reference`. + The memory limit for the code interpreter container. - - `"item_reference"` + - `"1g"` - - `class Program: …` + - `"4g"` - - `id: str` + - `"16g"` - The unique ID of this program item. + - `"64g"` - - `call_id: str` + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - The stable call ID of the program item. + Network access policy for the container. - - `code: str` + - `class BetaContainerNetworkPolicyDisabled: …` - The JavaScript source executed by programmatic tool calling. + - `type: Literal["disabled"]` - - `fingerprint: str` + Disable outbound network access. Always `disabled`. - Opaque program replay fingerprint that must be round-tripped. + - `"disabled"` - - `type: Literal["program"]` + - `class BetaContainerNetworkPolicyAllowlist: …` - The item type. Always `program`. + - `allowed_domains: List[str]` - - `"program"` + A list of allowed domains when type is `allowlist`. - - `agent: Optional[ProgramAgent]` + - `type: Literal["allowlist"]` - The agent that produced this item. + Allow outbound network access only to specified domains. Always `allowlist`. - - `agent_name: str` + - `"allowlist"` - The canonical name of the agent that produced this item. + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `class ProgramOutput: …` + Optional domain-scoped secrets for allowlisted domains. - - `id: str` + - `domain: str` - The unique ID of this program output item. + The domain associated with the secret. - - `call_id: str` + - `name: str` - The call ID of the program item. + The name of the secret to inject for the domain. - - `result: str` + - `value: str` - The result produced by the program item. + The secret value to inject for the domain. - - `status: Literal["completed", "incomplete"]` + - `type: Literal["code_interpreter"]` - The terminal status of the program output. + The type of the code interpreter tool. Always `code_interpreter`. - - `"completed"` + - `"code_interpreter"` - - `"incomplete"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `type: Literal["program_output"]` + The tool invocation context(s). - The item type. Always `program_output`. + - `"direct"` - - `"program_output"` + - `"programmatic"` - - `agent: Optional[ProgramOutputAgent]` + - `class ProgrammaticToolCalling: …` - The agent that produced this item. + - `type: Literal["programmatic_tool_calling"]` - - `agent_name: str` + The type of the tool. Always `programmatic_tool_calling`. - The canonical name of the agent that produced this item. + - `"programmatic_tool_calling"` -- `instructions: Optional[str]` + - `class ImageGeneration: …` - A system (or developer) message inserted into the model's context. - When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + A tool that generates images using the GPT image models. -- `previous_response_id: Optional[str]` + - `type: Literal["image_generation"]` - The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + The type of the image generation tool. Always `image_generation`. -- `prompt_cache_key: Optional[str]` + - `"image_generation"` - A key to use when reading from or writing to the prompt cache. + - `action: Optional[Literal["generate", "edit", "auto"]]` -- `prompt_cache_options: Optional[PromptCacheOptions]` + Whether to generate a new image or edit an existing image. Default: `auto`. - Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. + - `"generate"` - - `mode: Optional[Literal["implicit", "explicit"]]` + - `"edit"` - Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + - `"auto"` - - `"implicit"` + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `"explicit"` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `ttl: Optional[Literal["30m"]]` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `"30m"` + - `"transparent"` -- `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + - `"opaque"` - How long to retain a prompt cache entry created by this request. + - `"auto"` - - `"in_memory"` + - `input_fidelity: Optional[Literal["high", "low"]]` - - `"24h"` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. -- `service_tier: Optional[Literal["auto", "default", "flex", "priority"]]` + - `"high"` - The service tier to use for this request. + - `"low"` - - `"auto"` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - - `"default"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"flex"` + - `file_id: Optional[str]` - - `"priority"` + File ID for the mask image. -- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` + - `image_url: Optional[str]` - - `"responses_multi_agent=v1"` + Base64-encoded mask image. -### Returns + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` -- `class BetaCompactedResponse: …` + The image generation model to use. Default: `gpt-image-1`. - - `id: str` + - `str` - The unique identifier for the compacted response. + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `created_at: int` + The image generation model to use. Default: `gpt-image-1`. - Unix timestamp (in seconds) when the compacted conversation was created. + - `"gpt-image-1"` - - `object: Literal["response.compaction"]` + - `"gpt-image-1-mini"` - The object type. Always `response.compaction`. + - `"gpt-image-2"` - - `"response.compaction"` + - `"gpt-image-2-2026-04-21"` - - `output: List[BetaResponseOutputItem]` + - `"gpt-image-1.5"` - The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + - `"chatgpt-image-latest"` - - `class BetaResponseOutputMessage: …` + - `moderation: Optional[Literal["auto", "low"]]` - An output message from the model. + Moderation level for the generated image. Default: `auto`. - - `id: str` + - `"auto"` - The unique ID of the output message. + - `"low"` - - `content: List[Content]` + - `output_compression: Optional[int]` - The content of the output message. + Compression level for the output image. Default: 100. - - `class BetaResponseOutputText: …` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - A text output from the model. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `annotations: List[Annotation]` + - `"png"` - The annotations of the text output. + - `"webp"` - - `class AnnotationFileCitation: …` + - `"jpeg"` - A citation to a file. + - `partial_images: Optional[int]` - - `file_id: str` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The ID of the file. + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - - `filename: str` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The filename of the file cited. + - `"low"` - - `index: int` + - `"medium"` - The index of the file in the list of files. + - `"high"` - - `type: Literal["file_citation"]` + - `"auto"` - The type of the file citation. Always `file_citation`. + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - - `"file_citation"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `class AnnotationURLCitation: …` + - `str` - A citation for a web resource used to generate a model response. + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `end_index: int` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The index of the last character of the URL citation in the message. + - `"1024x1024"` - - `start_index: int` + - `"1024x1536"` - The index of the first character of the URL citation in the message. + - `"1536x1024"` - - `title: str` + - `"auto"` - The title of the web resource. + - `class LocalShell: …` - - `type: Literal["url_citation"]` + A tool that allows the model to execute shell commands in a local environment. - The type of the URL citation. Always `url_citation`. + - `type: Literal["local_shell"]` - - `"url_citation"` + The type of the local shell tool. Always `local_shell`. - - `url: str` + - `"local_shell"` - The URL of the web resource. + - `class BetaFunctionShellTool: …` - - `class AnnotationContainerFileCitation: …` + A tool that allows the model to execute shell commands. - A citation for a container file used to generate a model response. + - `type: Literal["shell"]` - - `container_id: str` + The type of the shell tool. Always `shell`. - The ID of the container file. + - `"shell"` - - `end_index: int` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The index of the last character of the container file citation in the message. + The tool invocation context(s). - - `file_id: str` + - `"direct"` - The ID of the file. + - `"programmatic"` - - `filename: str` + - `environment: Optional[Environment]` - The filename of the container file cited. + - `class BetaContainerAuto: …` - - `start_index: int` + - `type: Literal["container_auto"]` - The index of the first character of the container file citation in the message. + Automatically creates a container for this request - - `type: Literal["container_file_citation"]` + - `"container_auto"` - The type of the container file citation. Always `container_file_citation`. + - `file_ids: Optional[List[str]]` - - `"container_file_citation"` + An optional list of uploaded files to make available to your code. - - `class AnnotationFilePath: …` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - A path to a file. + The memory limit for the container. - - `file_id: str` + - `"1g"` - The ID of the file. + - `"4g"` - - `index: int` + - `"16g"` - The index of the file in the list of files. + - `"64g"` - - `type: Literal["file_path"]` + - `network_policy: Optional[NetworkPolicy]` - The type of the file path. Always `file_path`. + Network access policy for the container. - - `"file_path"` + - `class BetaContainerNetworkPolicyDisabled: …` - - `text: str` + - `class BetaContainerNetworkPolicyAllowlist: …` - The text output from the model. + - `skills: Optional[List[Skill]]` - - `type: Literal["output_text"]` + An optional list of skills referenced by id or inline data. - The type of the output text. Always `output_text`. + - `class BetaSkillReference: …` - - `"output_text"` + - `skill_id: str` - - `logprobs: Optional[List[Logprob]]` + The ID of the referenced skill. - - `token: str` + - `type: Literal["skill_reference"]` - - `bytes: List[int]` + References a skill created with the /v1/skills endpoint. - - `logprob: float` + - `"skill_reference"` - - `top_logprobs: List[LogprobTopLogprob]` + - `version: Optional[str]` - - `token: str` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `bytes: List[int]` + - `class BetaInlineSkill: …` - - `logprob: float` + - `description: str` - - `class BetaResponseOutputRefusal: …` + The description of the skill. - A refusal from the model. + - `name: str` - - `refusal: str` + The name of the skill. - The refusal explanation from the model. + - `source: BetaInlineSkillSource` - - `type: Literal["refusal"]` + Inline skill payload - The type of the refusal. Always `refusal`. + - `data: str` - - `"refusal"` + Base64-encoded skill zip bundle. - - `role: Literal["assistant"]` + - `media_type: Literal["application/zip"]` - The role of the output message. Always `assistant`. + The media type of the inline skill payload. Must be `application/zip`. - - `"assistant"` + - `"application/zip"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `type: Literal["base64"]` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The type of the inline skill source. Must be `base64`. - - `"in_progress"` + - `"base64"` - - `"completed"` + - `type: Literal["inline"]` - - `"incomplete"` + Defines an inline skill for this request. - - `type: Literal["message"]` + - `"inline"` - The type of the output message. Always `message`. + - `class BetaLocalEnvironment: …` - - `"message"` + - `type: Literal["local"]` - - `agent: Optional[Agent]` + Use a local computer environment. - The agent that produced this item. + - `"local"` - - `agent_name: str` + - `skills: Optional[List[BetaLocalSkill]]` - The canonical name of the agent that produced this item. + An optional list of skills. - - `phase: Optional[Literal["commentary"]]` + - `description: str` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The description of the skill. - - `"commentary"` + - `name: str` - - `class BetaResponseFileSearchToolCall: …` + The name of the skill. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `path: str` - - `id: str` + The path to the directory containing the skill. - The unique ID of the file search tool call. + - `class BetaContainerReference: …` - - `queries: List[str]` + - `container_id: str` - The queries used to search for files. + The ID of the referenced container. - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `type: Literal["container_reference"]` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + References a container created with the /v1/containers endpoint - - `"in_progress"` + - `"container_reference"` - - `"searching"` + - `class BetaCustomTool: …` - - `"completed"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `"incomplete"` + - `name: str` - - `"failed"` + The name of the custom tool, used to identify it in tool calls. - - `type: Literal["file_search_call"]` + - `type: Literal["custom"]` - The type of the file search tool call. Always `file_search_call`. + The type of the custom tool. Always `custom`. - - `"file_search_call"` + - `"custom"` - - `agent: Optional[Agent]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The agent that produced this item. + The tool invocation context(s). - - `agent_name: str` + - `"direct"` - The canonical name of the agent that produced this item. + - `"programmatic"` - - `results: Optional[List[Result]]` + - `defer_loading: Optional[bool]` - The results of the file search tool call. + Whether this tool should be deferred and discovered via tool search. - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + - `description: Optional[str]` - 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, booleans, or numbers. + Optional description of the custom tool, used to provide more context. - - `str` + - `format: Optional[Format]` - - `float` + The input format for the custom tool. Default is unconstrained text. - - `bool` + - `class FormatText: …` - - `file_id: Optional[str]` + Unconstrained free-form text. - The unique ID of the file. + - `type: Literal["text"]` - - `filename: Optional[str]` + Unconstrained text format. Always `text`. - The name of the file. + - `"text"` - - `score: Optional[float]` + - `class FormatGrammar: …` - The relevance score of the file - a value between 0 and 1. + A grammar defined by the user. - - `text: Optional[str]` + - `definition: str` - The text that was retrieved from the file. + The grammar definition. - - `class BetaResponseFunctionToolCall: …` + - `syntax: Literal["lark", "regex"]` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The syntax of the grammar definition. One of `lark` or `regex`. - - `arguments: str` + - `"lark"` - A JSON string of the arguments to pass to the function. + - `"regex"` - - `call_id: str` + - `type: Literal["grammar"]` - The unique ID of the function tool call generated by the model. + Grammar format. Always `grammar`. - - `name: str` + - `"grammar"` - The name of the function to run. + - `class BetaNamespaceTool: …` - - `type: Literal["function_call"]` + Groups function/custom tools under a shared namespace. - The type of the function tool call. Always `function_call`. + - `description: str` - - `"function_call"` + A description of the namespace shown to the model. - - `id: Optional[str]` + - `name: str` - The unique ID of the function tool call. + The namespace name used in tool calls (for example, `crm`). - - `agent: Optional[Agent]` + - `tools: List[Tool]` - The agent that produced this item. + The function/custom tools available inside this namespace. - - `agent_name: str` + - `class ToolFunction: …` - The canonical name of the agent that produced this item. + - `name: str` - - `caller: Optional[Caller]` + - `type: Literal["function"]` - The execution context that produced this tool call. + - `"function"` - - `class CallerDirect: …` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `type: Literal["direct"]` + The tool invocation context(s). - `"direct"` - - `class CallerProgram: …` - - - `caller_id: str` + - `"programmatic"` - The call ID of the program item that produced this tool call. + - `defer_loading: Optional[bool]` - - `type: Literal["program"]` + Whether this function should be deferred and discovered via tool search. - - `"program"` + - `description: Optional[str]` - - `namespace: Optional[str]` + - `output_schema: Optional[Dict[str, object]]` - The namespace of the function to run. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `parameters: Optional[object]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `strict: Optional[bool]` - - `"in_progress"` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `"completed"` + - `class BetaCustomTool: …` - - `"incomplete"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `class BetaResponseFunctionToolCallOutputItem: …` + - `type: Literal["namespace"]` - - `id: str` + The type of the tool. Always `namespace`. - The unique ID of the function call tool output. + - `"namespace"` - - `call_id: str` + - `class BetaToolSearchTool: …` - The unique ID of the function tool call generated by the model. + Hosted or BYOT tool search configuration for deferred tools. - - `output: Union[str, List[OutputOutputContentList]]` + - `type: Literal["tool_search"]` - The output from the function call generated by your code. - Can be a string or an list of output content. + The type of the tool. Always `tool_search`. - - `str` + - `"tool_search"` - A string of the output of the function call. + - `description: Optional[str]` - - `List[OutputOutputContentList]` + Description shown to the model for a client-executed tool search tool. - Text, image, or file output of the function call. + - `execution: Optional[Literal["server", "client"]]` - - `class BetaResponseInputText: …` + Whether tool search is executed by the server or by the client. - A text input to the model. + - `"server"` - - `text: str` + - `"client"` - The text input to the model. + - `parameters: Optional[object]` - - `type: Literal["input_text"]` + Parameter schema for a client-executed tool search tool. - The type of the input item. Always `input_text`. + - `class BetaWebSearchPreviewTool: …` - - `"input_text"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `mode: Literal["explicit"]` + - `"web_search_preview"` - The breakpoint mode. Always `explicit`. + - `"web_search_preview_2025_03_11"` - - `"explicit"` + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `class BetaResponseInputImage: …` + - `"text"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"image"` - - `detail: Literal["low", "high", "auto", "original"]` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - `"low"` + - `"medium"` + - `"high"` - - `"auto"` + - `user_location: Optional[UserLocation]` - - `"original"` + The user's location. - - `type: Literal["input_image"]` + - `type: Literal["approximate"]` - The type of the input item. Always `input_image`. + The type of location approximation. Always `approximate`. - - `"input_image"` + - `"approximate"` - - `file_id: Optional[str]` + - `city: Optional[str]` - The ID of the file to be sent to the model. + Free text input for the city of the user, e.g. `San Francisco`. - - `image_url: Optional[str]` + - `country: Optional[str]` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `region: Optional[str]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Free text input for the region of the user, e.g. `California`. - - `mode: Literal["explicit"]` + - `timezone: Optional[str]` - The breakpoint mode. Always `explicit`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"explicit"` + - `class BetaApplyPatchTool: …` - - `class BetaResponseInputFile: …` + Allows the assistant to create, delete, or update files using unified diffs. - A file input to the model. + - `type: Literal["apply_patch"]` - - `type: Literal["input_file"]` + The type of the tool. Always `apply_patch`. - The type of the input item. Always `input_file`. + - `"apply_patch"` - - `"input_file"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `detail: Optional[Literal["auto", "low", "high"]]` + The tool invocation context(s). - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"direct"` - - `"auto"` + - `"programmatic"` - - `"low"` + - `type: Literal["tool_search_output"]` - - `"high"` + The item type. Always `tool_search_output`. - - `file_data: Optional[str]` + - `"tool_search_output"` - The content of the file to be sent to the model. + - `id: Optional[str]` - - `file_id: Optional[str]` + The unique ID of this tool search output. - The ID of the file to be sent to the model. + - `agent: Optional[Agent]` - - `file_url: Optional[str]` + The agent that produced this item. - The URL of the file to be sent to the model. + - `agent_name: str` - - `filename: Optional[str]` + The canonical name of the agent that produced this item. - The name of the file to be sent to the model. + - `call_id: Optional[str]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The unique ID of the tool search call generated by the model. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `execution: Optional[Literal["server", "client"]]` - - `mode: Literal["explicit"]` + Whether tool search was executed by the server or by the client. - The breakpoint mode. Always `explicit`. + - `"server"` - - `"explicit"` + - `"client"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the tool search output. - `"in_progress"` @@ -45888,185 +56032,188 @@ Compact a response - `"incomplete"` - - `type: Literal["function_call_output"]` - - The type of the function tool call output. Always `function_call_output`. - - - `"function_call_output"` + - `class AdditionalTools: …` - - `agent: Optional[Agent]` + - `role: Literal["developer"]` - The agent that produced this item. + The role that provided the additional tools. Only `developer` is supported. - - `agent_name: str` + - `"developer"` - The canonical name of the agent that produced this item. + - `tools: List[BetaTool]` - - `caller: Optional[Caller]` + A list of additional tools made available at this item. - The execution context that produced this tool call. + - `class BetaFunctionTool: …` - - `class CallerDirect: …` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `type: Literal["direct"]` + - `class BetaFileSearchTool: …` - The caller type. Always `direct`. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `"direct"` + - `class BetaComputerTool: …` - - `class CallerProgram: …` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `caller_id: str` + - `class BetaComputerUsePreviewTool: …` - The call ID of the program item that produced this tool call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: Literal["program"]` + - `class BetaWebSearchTool: …` - The caller type. Always `program`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"program"` + - `class Mcp: …` - - `created_by: Optional[str]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The identifier of the actor that created the item. + - `class CodeInterpreter: …` - - `class AgentMessage: …` + A tool that runs Python code to help generate a response to a prompt. - - `id: str` + - `class ProgrammaticToolCalling: …` - The unique ID of the agent message. + - `class ImageGeneration: …` - - `author: str` + A tool that generates images using the GPT image models. - The sending agent identity. + - `class LocalShell: …` - - `content: List[AgentMessageContent]` + A tool that allows the model to execute shell commands in a local environment. - Encrypted content sent between agents. + - `class BetaFunctionShellTool: …` - - `class BetaResponseInputText: …` + A tool that allows the model to execute shell commands. - A text input to the model. + - `class BetaCustomTool: …` - - `class BetaResponseOutputText: …` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - A text output from the model. + - `class BetaNamespaceTool: …` - - `class AgentMessageContentText: …` + Groups function/custom tools under a shared namespace. - A text content. + - `class BetaToolSearchTool: …` - - `text: str` + Hosted or BYOT tool search configuration for deferred tools. - - `type: Literal["text"]` + - `class BetaWebSearchPreviewTool: …` - - `"text"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class AgentMessageContentSummaryText: …` + - `class BetaApplyPatchTool: …` - A summary text from the model. + Allows the assistant to create, delete, or update files using unified diffs. - - `text: str` + - `type: Literal["additional_tools"]` - A summary of the reasoning output from the model so far. + The item type. Always `additional_tools`. - - `type: Literal["summary_text"]` + - `"additional_tools"` - The type of the object. Always `summary_text`. + - `id: Optional[str]` - - `"summary_text"` + The unique ID of this additional tools item. - - `class AgentMessageContentReasoningText: …` + - `agent: Optional[AdditionalToolsAgent]` - Reasoning text from the model. + The agent that produced this item. - - `text: str` + - `agent_name: str` - The reasoning text from the model. + The canonical name of the agent that produced this item. - - `type: Literal["reasoning_text"]` + - `class BetaResponseReasoningItem: …` - The type of the reasoning text. Always `reasoning_text`. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `"reasoning_text"` + - `id: str` - - `class BetaResponseOutputRefusal: …` + The unique identifier of the reasoning content. - A refusal from the model. + - `summary: List[Summary]` - - `class BetaResponseInputImage: …` + Reasoning summary content. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `text: str` - - `class AgentMessageContentComputerScreenshot: …` + A summary of the reasoning output from the model so far. - A screenshot of a computer. + - `type: Literal["summary_text"]` - - `detail: Literal["low", "high", "auto", "original"]` + The type of the object. Always `summary_text`. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"summary_text"` - - `"low"` + - `type: Literal["reasoning"]` - - `"high"` + The type of the object. Always `reasoning`. - - `"auto"` + - `"reasoning"` - - `"original"` + - `agent: Optional[Agent]` - - `file_id: Optional[str]` + The agent that produced this item. - The identifier of an uploaded file that contains the screenshot. + - `agent_name: str` - - `image_url: Optional[str]` + The canonical name of the agent that produced this item. - The URL of the screenshot image. + - `content: Optional[List[Content]]` - - `type: Literal["computer_screenshot"]` + Reasoning text content. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `text: str` - - `"computer_screenshot"` + The reasoning text from the model. - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `type: Literal["reasoning_text"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The type of the reasoning text. Always `reasoning_text`. - - `mode: Literal["explicit"]` + - `"reasoning_text"` - The breakpoint mode. Always `explicit`. + - `encrypted_content: Optional[str]` - - `"explicit"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `class BetaResponseInputFile: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A file input to the model. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class AgentMessageContentEncryptedContent: …` + - `"in_progress"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"completed"` - - `encrypted_content: str` + - `"incomplete"` - Opaque encrypted content. + - `class BetaResponseCompactionItemParam: …` - - `type: Literal["encrypted_content"]` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The type of the input item. Always `encrypted_content`. + - `encrypted_content: str` - - `"encrypted_content"` + The encrypted content of the compaction summary. - - `recipient: str` + - `type: Literal["compaction"]` - The destination agent identity. + The type of the item. Always `compaction`. - - `type: Literal["agent_message"]` + - `"compaction"` - The type of the item. Always `agent_message`. + - `id: Optional[str]` - - `"agent_message"` + The ID of the compaction item. - - `agent: Optional[AgentMessageAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -46074,43 +56221,37 @@ Compact a response The canonical name of the agent that produced this item. - - `class MultiAgentCall: …` - - - `id: str` - - The unique ID of the multi-agent call item. - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `class ImageGenerationCall: …` - The multi-agent action to execute. + An image generation request made by the model. - - `"spawn_agent"` + - `id: str` - - `"interrupt_agent"` + The unique ID of the image generation call. - - `"list_agents"` + - `result: Optional[str]` - - `"send_message"` + The generated image encoded in base64. - - `"followup_task"` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - - `"wait_agent"` + The status of the image generation call. - - `arguments: str` + - `"in_progress"` - The JSON string of arguments generated for the action. + - `"completed"` - - `call_id: str` + - `"generating"` - The unique ID linking this call to its output. + - `"failed"` - - `type: Literal["multi_agent_call"]` + - `type: Literal["image_generation_call"]` - The type of the multi-agent call. Always `multi_agent_call`. + The type of the image generation call. Always `image_generation_call`. - - `"multi_agent_call"` + - `"image_generation_call"` - - `agent: Optional[MultiAgentCallAgent]` + - `agent: Optional[ImageGenerationCallAgent]` The agent that produced this item. @@ -46118,161 +56259,168 @@ Compact a response The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput: …` + - `class BetaResponseCodeInterpreterToolCall: …` + + A tool call to run code. - `id: str` - The unique ID of the multi-agent call output item. + The unique ID of the code interpreter tool call. - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `code: Optional[str]` - The multi-agent action that produced this result. + The code to run, or null if not available. - - `"spawn_agent"` + - `container_id: str` - - `"interrupt_agent"` + The ID of the container used to run the code. - - `"list_agents"` + - `outputs: Optional[List[Output]]` - - `"send_message"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"followup_task"` + - `class OutputLogs: …` - - `"wait_agent"` + The logs output from the code interpreter. - - `call_id: str` + - `logs: str` - The unique ID of the multi-agent call. + The logs output from the code interpreter. - - `output: List[BetaResponseOutputText]` + - `type: Literal["logs"]` - Text output returned by the multi-agent action. + The type of the output. Always `logs`. - - `annotations: List[Annotation]` + - `"logs"` - The annotations of the text output. + - `class OutputImage: …` - - `text: str` + The image output from the code interpreter. - The text output from the model. + - `type: Literal["image"]` - - `type: Literal["output_text"]` + The type of the output. Always `image`. - The type of the output text. Always `output_text`. + - `"image"` - - `logprobs: Optional[List[Logprob]]` + - `url: str` - - `type: Literal["multi_agent_call_output"]` + The URL of the image output from the code interpreter. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - - `"multi_agent_call_output"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `agent: Optional[MultiAgentCallOutputAgent]` + - `"in_progress"` - The agent that produced this item. + - `"completed"` - - `agent_name: str` + - `"incomplete"` - The canonical name of the agent that produced this item. + - `"interpreting"` - - `class BetaResponseFunctionWebSearch: …` + - `"failed"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `type: Literal["code_interpreter_call"]` - - `id: str` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The unique ID of the web search tool call. + - `"code_interpreter_call"` - - `action: Action` + - `agent: Optional[Agent]` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + The agent that produced this item. - - `class ActionSearch: …` + - `agent_name: str` - Action type "search" - Performs a web search query. + The canonical name of the agent that produced this item. - - `type: Literal["search"]` + - `class LocalShellCall: …` - The action type. + A tool call to run a command on the local shell. - - `"search"` + - `id: str` - - `queries: Optional[List[str]]` + The unique ID of the local shell call. - The search queries. + - `action: LocalShellCallAction` - - `query: Optional[str]` + Execute a shell command on the server. - The search query. + - `command: List[str]` - - `sources: Optional[List[ActionSearchSource]]` + The command to run. - The sources used in the search. + - `env: Dict[str, str]` - - `type: Literal["url"]` + Environment variables to set for the command. - The type of source. Always `url`. + - `type: Literal["exec"]` - - `"url"` + The type of the local shell action. Always `exec`. - - `url: str` + - `"exec"` - The URL of the source. + - `timeout_ms: Optional[int]` - - `class ActionOpenPage: …` + Optional timeout in milliseconds for the command. - Action type "open_page" - Opens a specific URL from search results. + - `user: Optional[str]` - - `type: Literal["open_page"]` + Optional user to run the command as. - The action type. + - `working_directory: Optional[str]` - - `"open_page"` + Optional working directory to run the command in. - - `url: Optional[str]` + - `call_id: str` - The URL opened by the model. + The unique ID of the local shell tool call generated by the model. - - `class ActionFindInPage: …` + - `status: Literal["in_progress", "completed", "incomplete"]` - Action type "find_in_page": Searches for a pattern within a loaded page. + The status of the local shell call. - - `pattern: str` + - `"in_progress"` - The pattern or text to search for within the page. + - `"completed"` - - `type: Literal["find_in_page"]` + - `"incomplete"` - The action type. + - `type: Literal["local_shell_call"]` - - `"find_in_page"` + The type of the local shell call. Always `local_shell_call`. - - `url: str` + - `"local_shell_call"` - The URL of the page searched for the pattern. + - `agent: Optional[LocalShellCallAgent]` - - `status: Literal["in_progress", "searching", "completed", "failed"]` + The agent that produced this item. - The status of the web search tool call. + - `agent_name: str` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"searching"` + - `class LocalShellCallOutput: …` - - `"completed"` + The output of a local shell tool call. - - `"failed"` + - `id: str` - - `type: Literal["web_search_call"]` + The unique ID of the local shell tool call generated by the model. - The type of the web search tool call. Always `web_search_call`. + - `output: str` - - `"web_search_call"` + A JSON string of the output of the local shell tool call. - - `agent: Optional[Agent]` + - `type: Literal["local_shell_call_output"]` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `agent: Optional[LocalShellCallOutputAgent]` The agent that produced this item. @@ -46280,289 +56428,285 @@ Compact a response The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCall: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `id: str` + - `"in_progress"` - The unique ID of the computer call. + - `"completed"` - - `call_id: str` + - `"incomplete"` - An identifier used when responding to the tool call with output. + - `class ShellCall: …` - - `pending_safety_checks: List[PendingSafetyCheck]` + A tool representing a request to execute one or more shell commands. - The pending safety checks for the computer call. + - `action: ShellCallAction` - - `id: str` + The shell commands and limits that describe how to run the tool call. - The ID of the pending safety check. + - `commands: List[str]` - - `code: Optional[str]` + Ordered shell commands for the execution environment to run. - The type of the pending safety check. + - `max_output_length: Optional[int]` - - `message: Optional[str]` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Details about the pending safety check. + - `timeout_ms: Optional[int]` - - `status: Literal["in_progress", "completed", "incomplete"]` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `call_id: str` - - `"in_progress"` + The unique ID of the shell tool call generated by the model. - - `"completed"` + - `type: Literal["shell_call"]` - - `"incomplete"` + The type of the item. Always `shell_call`. - - `type: Literal["computer_call"]` + - `"shell_call"` - The type of the computer call. Always `computer_call`. + - `id: Optional[str]` - - `"computer_call"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `action: Optional[BetaComputerAction]` + - `agent: Optional[ShellCallAgent]` - A click action. + The agent that produced this item. - - `class Click: …` + - `agent_name: str` - A click action. + The canonical name of the agent that produced this item. - - `button: Literal["left", "right", "wheel", 2 more]` + - `caller: Optional[ShellCallCaller]` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The execution context that produced this tool call. - - `"left"` + - `class ShellCallCallerDirect: …` - - `"right"` + - `type: Literal["direct"]` - - `"wheel"` + The caller type. Always `direct`. - - `"back"` + - `"direct"` - - `"forward"` + - `class ShellCallCallerProgram: …` - - `type: Literal["click"]` + - `caller_id: str` - Specifies the event type. For a click action, this property is always `click`. + The call ID of the program item that produced this tool call. - - `"click"` + - `type: Literal["program"]` - - `x: int` + The caller type. Always `program`. - The x-coordinate where the click occurred. + - `"program"` - - `y: int` + - `environment: Optional[ShellCallEnvironment]` - The y-coordinate where the click occurred. + The environment to execute the shell commands in. - - `keys: Optional[List[str]]` + - `class BetaLocalEnvironment: …` - The keys being held while clicking. + - `class BetaContainerReference: …` - - `class DoubleClick: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A double click action. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `keys: Optional[List[str]]` + - `"in_progress"` - The keys being held while double-clicking. + - `"completed"` - - `type: Literal["double_click"]` + - `"incomplete"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `class ShellCallOutput: …` - - `"double_click"` + The streamed output items emitted by a shell tool call. - - `x: int` + - `call_id: str` - The x-coordinate where the double click occurred. + The unique ID of the shell tool call generated by the model. - - `y: int` + - `output: List[BetaResponseFunctionShellCallOutputContent]` - The y-coordinate where the double click occurred. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `class Drag: …` + - `outcome: Outcome` - A drag action. + The exit or timeout outcome associated with this shell call. - - `path: List[DragPath]` + - `class OutcomeTimeout: …` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Indicates that the shell call exceeded its configured time limit. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `type: Literal["timeout"]` - - `x: int` + The outcome type. Always `timeout`. - The x-coordinate. + - `"timeout"` - - `y: int` + - `class OutcomeExit: …` - The y-coordinate. + Indicates that the shell commands finished and returned an exit code. - - `type: Literal["drag"]` + - `exit_code: int` - Specifies the event type. For a drag action, this property is always set to `drag`. + The exit code returned by the shell process. - - `"drag"` + - `type: Literal["exit"]` - - `keys: Optional[List[str]]` + The outcome type. Always `exit`. - The keys being held while dragging the mouse. + - `"exit"` - - `class Keypress: …` + - `stderr: str` - A collection of keypresses the model would like to perform. + Captured stderr output for the shell call. - - `keys: List[str]` + - `stdout: str` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Captured stdout output for the shell call. - - `type: Literal["keypress"]` + - `type: Literal["shell_call_output"]` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The type of the item. Always `shell_call_output`. - - `"keypress"` + - `"shell_call_output"` - - `class Move: …` + - `id: Optional[str]` - A mouse move action. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `type: Literal["move"]` + - `agent: Optional[ShellCallOutputAgent]` - Specifies the event type. For a move action, this property is always set to `move`. + The agent that produced this item. - - `"move"` + - `agent_name: str` - - `x: int` + The canonical name of the agent that produced this item. - The x-coordinate to move to. + - `caller: Optional[ShellCallOutputCaller]` - - `y: int` + The execution context that produced this tool call. - The y-coordinate to move to. + - `class ShellCallOutputCallerDirect: …` - - `keys: Optional[List[str]]` + - `type: Literal["direct"]` - The keys being held while moving the mouse. + The caller type. Always `direct`. - - `class Screenshot: …` + - `"direct"` - A screenshot action. + - `class ShellCallOutputCallerProgram: …` - - `type: Literal["screenshot"]` + - `caller_id: str` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The call ID of the program item that produced this tool call. - - `"screenshot"` + - `type: Literal["program"]` - - `class Scroll: …` + The caller type. Always `program`. - A scroll action. + - `"program"` - - `scroll_x: int` + - `max_output_length: Optional[int]` - The horizontal scroll distance. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `scroll_y: int` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The vertical scroll distance. + The status of the shell call output. - - `type: Literal["scroll"]` + - `"in_progress"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"completed"` - - `"scroll"` + - `"incomplete"` - - `x: int` + - `class ApplyPatchCall: …` - The x-coordinate where the scroll occurred. + A tool call representing a request to create, delete, or update files using diff patches. - - `y: int` + - `call_id: str` - The y-coordinate where the scroll occurred. + The unique ID of the apply patch tool call generated by the model. - - `keys: Optional[List[str]]` + - `operation: ApplyPatchCallOperation` - The keys being held while scrolling. + The specific create, delete, or update instruction for the apply_patch tool call. - - `class Type: …` + - `class ApplyPatchCallOperationCreateFile: …` - An action to type in text. + Instruction for creating a new file via the apply_patch tool. - - `text: str` + - `diff: str` - The text to type. + Unified diff content to apply when creating the file. - - `type: Literal["type"]` + - `path: str` - Specifies the event type. For a type action, this property is always set to `type`. + Path of the file to create relative to the workspace root. - - `"type"` + - `type: Literal["create_file"]` - - `class Wait: …` + The operation type. Always `create_file`. - A wait action. + - `"create_file"` - - `type: Literal["wait"]` + - `class ApplyPatchCallOperationDeleteFile: …` - Specifies the event type. For a wait action, this property is always set to `wait`. + Instruction for deleting an existing file via the apply_patch tool. - - `"wait"` + - `path: str` - - `actions: Optional[BetaComputerActionList]` + Path of the file to delete relative to the workspace root. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `type: Literal["delete_file"]` - - `class Click: …` + The operation type. Always `delete_file`. - A click action. + - `"delete_file"` - - `class DoubleClick: …` + - `class ApplyPatchCallOperationUpdateFile: …` - A double click action. + Instruction for updating an existing file via the apply_patch tool. - - `class Drag: …` + - `diff: str` - A drag action. + Unified diff content to apply to the existing file. - - `class Keypress: …` + - `path: str` - A collection of keypresses the model would like to perform. + Path of the file to update relative to the workspace root. - - `class Move: …` + - `type: Literal["update_file"]` - A mouse move action. + The operation type. Always `update_file`. - - `class Screenshot: …` + - `"update_file"` - A screenshot action. + - `status: Literal["in_progress", "completed"]` - - `class Scroll: …` + The status of the apply patch tool call. One of `in_progress` or `completed`. - A scroll action. + - `"in_progress"` - - `class Type: …` + - `"completed"` - An action to type in text. + - `type: Literal["apply_patch_call"]` - - `class Wait: …` + The type of the item. Always `apply_patch_call`. - A wait action. + - `"apply_patch_call"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallAgent]` The agent that produced this item. @@ -46570,115 +56714,131 @@ Compact a response The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem: …` + - `caller: Optional[ApplyPatchCallCaller]` - - `id: str` + The execution context that produced this tool call. - The unique ID of the computer call tool output. + - `class ApplyPatchCallCallerDirect: …` - - `call_id: str` + - `type: Literal["direct"]` - The ID of the computer tool call that produced the output. + The caller type. Always `direct`. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"direct"` - A computer screenshot image used with the computer use tool. + - `class ApplyPatchCallCallerProgram: …` - - `type: Literal["computer_screenshot"]` + - `caller_id: str` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The call ID of the program item that produced this tool call. - - `"computer_screenshot"` + - `type: Literal["program"]` - - `file_id: Optional[str]` + The caller type. Always `program`. - The identifier of an uploaded file that contains the screenshot. + - `"program"` - - `image_url: Optional[str]` + - `class ApplyPatchCallOutput: …` - The URL of the screenshot image. + The streamed output emitted by an apply patch tool call. - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + - `call_id: str` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The unique ID of the apply patch tool call generated by the model. - - `"completed"` + - `status: Literal["completed", "failed"]` - - `"incomplete"` + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` - `"failed"` - - `"in_progress"` + - `type: Literal["apply_patch_call_output"]` - - `type: Literal["computer_call_output"]` + The type of the item. Always `apply_patch_call_output`. - The type of the computer tool call output. Always `computer_call_output`. + - `"apply_patch_call_output"` - - `"computer_call_output"` + - `id: Optional[str]` - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The safety checks reported by the API that have been acknowledged by the - developer. + - `agent: Optional[ApplyPatchCallOutputAgent]` - - `id: str` + The agent that produced this item. - The ID of the pending safety check. + - `agent_name: str` - - `code: Optional[str]` + The canonical name of the agent that produced this item. - The type of the pending safety check. + - `caller: Optional[ApplyPatchCallOutputCaller]` - - `message: Optional[str]` + The execution context that produced this tool call. - Details about the pending safety check. + - `class ApplyPatchCallOutputCallerDirect: …` - - `agent: Optional[Agent]` + - `type: Literal["direct"]` - The agent that produced this item. + The caller type. Always `direct`. - - `agent_name: str` + - `"direct"` - The canonical name of the agent that produced this item. + - `class ApplyPatchCallOutputCallerProgram: …` - - `created_by: Optional[str]` + - `caller_id: str` - The identifier of the actor that created the item. + The call ID of the program item that produced this tool call. - - `class BetaResponseReasoningItem: …` + - `type: Literal["program"]` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The caller type. Always `program`. + + - `"program"` + + - `output: Optional[str]` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `class McpListTools: …` + + A list of tools available on an MCP server. - `id: str` - The unique identifier of the reasoning content. + The unique ID of the list. - - `summary: List[Summary]` + - `server_label: str` - Reasoning summary content. + The label of the MCP server. - - `text: str` + - `tools: List[McpListToolsTool]` - A summary of the reasoning output from the model so far. + The tools available on the server. - - `type: Literal["summary_text"]` + - `input_schema: object` - The type of the object. Always `summary_text`. + The JSON schema describing the tool's input. - - `"summary_text"` + - `name: str` - - `type: Literal["reasoning"]` + The name of the tool. - The type of the object. Always `reasoning`. + - `annotations: Optional[object]` - - `"reasoning"` + Additional annotations about the tool. - - `agent: Optional[Agent]` + - `description: Optional[str]` + + The description of the tool. + + - `type: Literal["mcp_list_tools"]` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `agent: Optional[McpListToolsAgent]` The agent that produced this item. @@ -46686,61 +56846,67 @@ Compact a response The canonical name of the agent that produced this item. - - `content: Optional[List[Content]]` + - `error: Optional[str]` - Reasoning text content. + Error message if the server could not list tools. - - `text: str` + - `class McpApprovalRequest: …` - The reasoning text from the model. + A request for human approval of a tool invocation. - - `type: Literal["reasoning_text"]` + - `id: str` - The type of the reasoning text. Always `reasoning_text`. + The unique ID of the approval request. - - `"reasoning_text"` + - `arguments: str` - - `encrypted_content: Optional[str]` + A JSON string of arguments for the tool. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `name: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The name of the tool to run. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `server_label: str` - - `"in_progress"` + The label of the MCP server making the request. - - `"completed"` + - `type: Literal["mcp_approval_request"]` - - `"incomplete"` + The type of the item. Always `mcp_approval_request`. - - `class Program: …` + - `"mcp_approval_request"` - - `id: str` + - `agent: Optional[McpApprovalRequestAgent]` - The unique ID of the program item. + The agent that produced this item. - - `call_id: str` + - `agent_name: str` - The stable call ID of the program item. + The canonical name of the agent that produced this item. - - `code: str` + - `class McpApprovalResponse: …` - The JavaScript source executed by programmatic tool calling. + A response to an MCP approval request. - - `fingerprint: str` + - `approval_request_id: str` - Opaque program replay fingerprint that must be round-tripped. + The ID of the approval request being answered. - - `type: Literal["program"]` + - `approve: bool` - The type of the item. Always `program`. + Whether the request was approved. - - `"program"` + - `type: Literal["mcp_approval_response"]` - - `agent: Optional[ProgramAgent]` + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `id: Optional[str]` + + The unique ID of the approval response + + - `agent: Optional[McpApprovalResponseAgent]` The agent that produced this item. @@ -46748,35 +56914,37 @@ Compact a response The canonical name of the agent that produced this item. - - `class ProgramOutput: …` + - `reason: Optional[str]` - - `id: str` + Optional reason for the decision. - The unique ID of the program output item. + - `class McpCall: …` - - `call_id: str` + An invocation of a tool on an MCP server. - The call ID of the program item. + - `id: str` - - `result: str` + The unique ID of the tool call. - The result produced by the program item. + - `arguments: str` - - `status: Literal["completed", "incomplete"]` + A JSON string of the arguments passed to the tool. - The terminal status of the program output item. + - `name: str` - - `"completed"` + The name of the tool that was run. - - `"incomplete"` + - `server_label: str` - - `type: Literal["program_output"]` + The label of the MCP server running the tool. + + - `type: Literal["mcp_call"]` - The type of the item. Always `program_output`. + The type of the item. Always `mcp_call`. - - `"program_output"` + - `"mcp_call"` - - `agent: Optional[ProgramOutputAgent]` + - `agent: Optional[McpCallAgent]` The agent that produced this item. @@ -46784,31 +56952,22 @@ Compact a response The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall: …` - - - `id: str` - - The unique ID of the tool search call item. - - - `arguments: object` - - Arguments used for the tool search call. - - - `call_id: Optional[str]` + - `approval_request_id: Optional[str]` - The unique ID of the tool search call generated by the model. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `execution: Literal["server", "client"]` + - `error: Optional[str]` - Whether tool search was executed by the server or by the client. + The error from the tool call, if any. - - `"server"` + - `output: Optional[str]` - - `"client"` + The output from the tool call. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - The status of the tool search call item that was recorded. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `"in_progress"` @@ -46816,1141 +56975,1123 @@ Compact a response - `"incomplete"` - - `type: Literal["tool_search_call"]` + - `"calling"` - The type of the item. Always `tool_search_call`. + - `"failed"` - - `"tool_search_call"` + - `class BetaResponseCustomToolCallOutput: …` - - `agent: Optional[Agent]` + The output of a custom tool call from your code, being sent back to the model. - The agent that produced this item. + - `call_id: str` - - `agent_name: str` + The call ID, used to map this custom tool call output to a custom tool call. - The canonical name of the agent that produced this item. + - `output: Union[str, List[OutputOutputContentList]]` - - `created_by: Optional[str]` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The identifier of the actor that created the item. + - `str` - - `class BetaResponseToolSearchOutputItem: …` + A string of the output of the custom tool call. - - `id: str` + - `List[OutputOutputContentList]` - The unique ID of the tool search output item. + Text, image, or file output of the custom tool call. - - `call_id: Optional[str]` + - `class BetaResponseInputText: …` - The unique ID of the tool search call generated by the model. + A text input to the model. - - `execution: Literal["server", "client"]` + - `class BetaResponseInputImage: …` - Whether tool search was executed by the server or by the client. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"server"` + - `class BetaResponseInputFile: …` - - `"client"` + A file input to the model. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `type: Literal["custom_tool_call_output"]` - The status of the tool search output item that was recorded. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"in_progress"` + - `"custom_tool_call_output"` - - `"completed"` + - `id: Optional[str]` - - `"incomplete"` + The unique ID of the custom tool call output in the OpenAI platform. - - `tools: List[BetaTool]` + - `agent: Optional[Agent]` - The loaded tool definitions returned by tool search. + The agent that produced this item. - - `class BetaFunctionTool: …` + - `agent_name: str` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The canonical name of the agent that produced this item. - - `name: str` + - `caller: Optional[Caller]` - The name of the function to call. + The execution context that produced this tool call. - - `parameters: Optional[Dict[str, object]]` + - `class CallerDirect: …` - A JSON schema object describing the parameters of the function. + - `type: Literal["direct"]` - - `strict: Optional[bool]` + The caller type. Always `direct`. - Whether strict parameter validation is enforced for this function tool. + - `"direct"` - - `type: Literal["function"]` + - `class CallerProgram: …` - The type of the function tool. Always `function`. + - `caller_id: str` - - `"function"` + The call ID of the program item that produced this tool call. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["program"]` - The tool invocation context(s). + The caller type. Always `program`. - - `"direct"` + - `"program"` - - `"programmatic"` + - `class BetaResponseCustomToolCall: …` - - `defer_loading: Optional[bool]` + A call to a custom tool created by the model. - Whether this function is deferred and loaded via tool search. + - `call_id: str` - - `description: Optional[str]` + An identifier used to map this custom tool call to a tool call output. - A description of the function. Used by the model to determine whether or not to call the function. + - `input: str` - - `output_schema: Optional[Dict[str, object]]` + The input for the custom tool call generated by the model. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `name: str` - - `class BetaFileSearchTool: …` + The name of the custom tool being called. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `type: Literal["custom_tool_call"]` - - `type: Literal["file_search"]` + The type of the custom tool call. Always `custom_tool_call`. - The type of the file search tool. Always `file_search`. + - `"custom_tool_call"` - - `"file_search"` + - `id: Optional[str]` - - `vector_store_ids: List[str]` + The unique ID of the custom tool call in the OpenAI platform. - The IDs of the vector stores to search. + - `agent: Optional[Agent]` - - `filters: Optional[Filters]` + The agent that produced this item. - A filter to apply. + - `agent_name: str` - - `class FiltersComparisonFilter: …` + The canonical name of the agent that produced this item. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `caller: Optional[Caller]` - - `key: str` + The execution context that produced this tool call. - The key to compare against the value. + - `class CallerDirect: …` - - `type: Literal["eq", "ne", "gt", 5 more]` + - `type: Literal["direct"]` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"direct"` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `class CallerProgram: …` - - `"eq"` + - `caller_id: str` - - `"ne"` + The call ID of the program item that produced this tool call. - - `"gt"` + - `type: Literal["program"]` - - `"gte"` + - `"program"` - - `"lt"` + - `namespace: Optional[str]` - - `"lte"` + The namespace of the custom tool being called. - - `"in"` + - `class CompactionTrigger: …` - - `"nin"` + Compacts the current context. Must be the final input item. - - `value: Union[str, float, bool, List[object]]` + - `type: Literal["compaction_trigger"]` - The value to compare against the attribute key; supports string, number, or boolean types. + The type of the item. Always `compaction_trigger`. - - `str` + - `"compaction_trigger"` - - `float` + - `agent: Optional[CompactionTriggerAgent]` - - `bool` + The agent that produced this item. - - `List[object]` + - `agent_name: str` - - `class FiltersCompoundFilter: …` + The canonical name of the agent that produced this item. - Combine multiple filters using `and` or `or`. + - `class ItemReference: …` - - `filters: List[FiltersCompoundFilterFilter]` + An internal identifier for an item to reference. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `id: str` - - `class FiltersCompoundFilterFilterComparisonFilter: …` + The ID of the item to reference. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `agent: Optional[ItemReferenceAgent]` - - `key: str` + The agent that produced this item. - The key to compare against the value. + - `agent_name: str` - - `type: Literal["eq", "ne", "gt", 5 more]` + The canonical name of the agent that produced this item. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `type: Optional[Literal["item_reference"]]` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The type of item to reference. Always `item_reference`. - - `"eq"` + - `"item_reference"` - - `"ne"` + - `class Program: …` - - `"gt"` + - `id: str` - - `"gte"` + The unique ID of this program item. - - `"lt"` + - `call_id: str` - - `"lte"` + The stable call ID of the program item. - - `"in"` + - `code: str` - - `"nin"` + The JavaScript source executed by programmatic tool calling. - - `value: Union[str, float, bool, List[object]]` + - `fingerprint: str` - The value to compare against the attribute key; supports string, number, or boolean types. + Opaque program replay fingerprint that must be round-tripped. - - `str` + - `type: Literal["program"]` - - `float` + The item type. Always `program`. - - `bool` + - `"program"` - - `List[object]` + - `agent: Optional[ProgramAgent]` - - `object` + The agent that produced this item. - - `type: Literal["and", "or"]` + - `agent_name: str` - Type of operation: `and` or `or`. + The canonical name of the agent that produced this item. - - `"and"` + - `class ProgramOutput: …` - - `"or"` + - `id: str` - - `max_num_results: Optional[int]` + The unique ID of this program output item. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `call_id: str` - - `ranking_options: Optional[RankingOptions]` + The call ID of the program item. - Ranking options for search. + - `result: str` - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + The result produced by the program item. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `status: Literal["completed", "incomplete"]` - - `embedding_weight: float` + The terminal status of the program output. - The weight of the embedding in the reciprocal ranking fusion. + - `"completed"` - - `text_weight: float` + - `"incomplete"` - The weight of the text in the reciprocal ranking fusion. + - `type: Literal["program_output"]` - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + The item type. Always `program_output`. - The ranker to use for the file search. + - `"program_output"` - - `"auto"` + - `agent: Optional[ProgramOutputAgent]` - - `"default-2024-11-15"` + The agent that produced this item. - - `score_threshold: Optional[float]` + - `agent_name: str` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The canonical name of the agent that produced this item. - - `class BetaComputerTool: …` + - `metadata: Optional[Dict[str, str]]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + 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. - - `type: Literal["computer"]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of the computer tool. Always `computer`. + - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` - - `"computer"` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `class BetaComputerUsePreviewTool: …` + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `display_height: int` + - `"gpt-5.6-sol"` - The height of the computer display. + - `"gpt-5.6-terra"` - - `display_width: int` + - `"gpt-5.6-luna"` - The width of the computer display. + - `"gpt-5.4"` - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `"gpt-5.4-mini"` - The type of computer environment to control. + - `"gpt-5.4-nano"` - - `"windows"` + - `"gpt-5.4-mini-2026-03-17"` - - `"mac"` + - `"gpt-5.4-nano-2026-03-17"` - - `"linux"` + - `"gpt-5.3-chat-latest"` - - `"ubuntu"` + - `"gpt-5.2"` - - `"browser"` + - `"gpt-5.2-2025-12-11"` - - `type: Literal["computer_use_preview"]` + - `"gpt-5.2-chat-latest"` - The type of the computer use tool. Always `computer_use_preview`. + - `"gpt-5.2-pro"` - - `"computer_use_preview"` + - `"gpt-5.2-pro-2025-12-11"` - - `class BetaWebSearchTool: …` + - `"gpt-5.1"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"gpt-5.1-2025-11-13"` - - `type: Literal["web_search", "web_search_2025_08_26"]` + - `"gpt-5.1-codex"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"gpt-5.1-mini"` - - `"web_search"` + - `"gpt-5.1-chat-latest"` - - `"web_search_2025_08_26"` + - `"gpt-5"` - - `filters: Optional[Filters]` + - `"gpt-5-mini"` - Filters for the search. + - `"gpt-5-nano"` - - `allowed_domains: Optional[List[str]]` + - `"gpt-5-2025-08-07"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"gpt-5-mini-2025-08-07"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"gpt-5-nano-2025-08-07"` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `"gpt-5-chat-latest"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"gpt-4.1"` - - `"low"` + - `"gpt-4.1-mini"` - - `"medium"` + - `"gpt-4.1-nano"` - - `"high"` + - `"gpt-4.1-2025-04-14"` - - `user_location: Optional[UserLocation]` + - `"gpt-4.1-mini-2025-04-14"` - The approximate location of the user. + - `"gpt-4.1-nano-2025-04-14"` - - `city: Optional[str]` + - `"o4-mini"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"o4-mini-2025-04-16"` - - `country: Optional[str]` + - `"o3"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"o3-2025-04-16"` - - `region: Optional[str]` + - `"o3-mini"` - Free text input for the region of the user, e.g. `California`. + - `"o3-mini-2025-01-31"` - - `timezone: Optional[str]` + - `"o1"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"o1-2024-12-17"` - - `type: Optional[Literal["approximate"]]` + - `"o1-preview"` - The type of location approximation. Always `approximate`. + - `"o1-preview-2024-09-12"` - - `"approximate"` + - `"o1-mini"` - - `class Mcp: …` + - `"o1-mini-2024-09-12"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"gpt-4o"` - - `server_label: str` + - `"gpt-4o-2024-11-20"` - A label for this MCP server, used to identify it in tool calls. + - `"gpt-4o-2024-08-06"` - - `type: Literal["mcp"]` + - `"gpt-4o-2024-05-13"` - The type of the MCP tool. Always `mcp`. + - `"gpt-4o-audio-preview"` - - `"mcp"` + - `"gpt-4o-audio-preview-2024-10-01"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"gpt-4o-audio-preview-2024-12-17"` - The tool invocation context(s). + - `"gpt-4o-audio-preview-2025-06-03"` - - `"direct"` + - `"gpt-4o-mini-audio-preview"` - - `"programmatic"` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `allowed_tools: Optional[McpAllowedTools]` + - `"gpt-4o-search-preview"` - List of allowed tool names or a filter object. + - `"gpt-4o-mini-search-preview"` - - `List[str]` + - `"gpt-4o-search-preview-2025-03-11"` - A string array of allowed tool names + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `class McpAllowedToolsMcpToolFilter: …` + - `"chatgpt-4o-latest"` - A filter object to specify which tools are allowed. + - `"codex-mini-latest"` - - `read_only: Optional[bool]` + - `"gpt-4o-mini"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"gpt-4o-mini-2024-07-18"` - - `tool_names: Optional[List[str]]` + - `"gpt-4-turbo"` - List of allowed tool names. + - `"gpt-4-turbo-2024-04-09"` - - `authorization: Optional[str]` + - `"gpt-4-0125-preview"` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `"gpt-4-turbo-preview"` - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + - `"gpt-4-1106-preview"` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `"gpt-4-vision-preview"` - Currently supported `connector_id` values are: + - `"gpt-4"` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `"gpt-4-0314"` - - `"connector_dropbox"` + - `"gpt-4-0613"` - - `"connector_gmail"` + - `"gpt-4-32k"` - - `"connector_googlecalendar"` + - `"gpt-4-32k-0314"` - - `"connector_googledrive"` + - `"gpt-4-32k-0613"` - - `"connector_microsoftteams"` + - `"gpt-3.5-turbo"` - - `"connector_outlookcalendar"` + - `"gpt-3.5-turbo-16k"` - - `"connector_outlookemail"` + - `"gpt-3.5-turbo-0301"` - - `"connector_sharepoint"` + - `"gpt-3.5-turbo-0613"` - - `defer_loading: Optional[bool]` + - `"gpt-3.5-turbo-1106"` - Whether this MCP tool is deferred and discovered via tool search. + - `"gpt-3.5-turbo-0125"` - - `headers: Optional[Dict[str, str]]` + - `"gpt-3.5-turbo-16k-0613"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"o1-pro"` - - `require_approval: Optional[McpRequireApproval]` + - `"o1-pro-2025-03-19"` - Specify which of the MCP server's tools require approval. + - `"o3-pro"` - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `"o3-pro-2025-06-10"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"o3-deep-research"` - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `"o3-deep-research-2025-06-26"` - A filter object to specify which tools are allowed. + - `"o4-mini-deep-research"` - - `read_only: Optional[bool]` + - `"o4-mini-deep-research-2025-06-26"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"computer-use-preview"` - - `tool_names: Optional[List[str]]` + - `"computer-use-preview-2025-03-11"` - List of allowed tool names. + - `"gpt-5-codex"` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + - `"gpt-5-pro"` - A filter object to specify which tools are allowed. + - `"gpt-5-pro-2025-10-06"` - - `read_only: Optional[bool]` + - `"gpt-5.1-codex-max"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `str` - - `tool_names: Optional[List[str]]` + - `object: Literal["response"]` - List of allowed tool names. + The object type of this resource - always set to `response`. - - `Literal["always", "never"]` + - `"response"` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `output: List[BetaResponseOutputItem]` - - `"always"` + An array of content items generated by the model. - - `"never"` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `server_description: Optional[str]` + - `class BetaResponseOutputMessage: …` - Optional description of the MCP server, used to provide more context. + An output message from the model. - - `server_url: Optional[str]` + - `class BetaResponseFileSearchToolCall: …` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `tunnel_id: Optional[str]` + - `class BetaResponseFunctionToolCall: …` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `class CodeInterpreter: …` + - `class BetaResponseFunctionToolCallOutputItem: …` - A tool that runs Python code to help generate a response to a prompt. + - `id: str` - - `container: CodeInterpreterContainer` + The unique ID of the function call tool output. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `call_id: str` + + The unique ID of the function tool call generated by the model. + + - `output: Union[str, List[OutputOutputContentList]]` + + The output from the function call generated by your code. + Can be a string or an list of output content. - `str` - The container ID. + A string of the output of the function call. - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `List[OutputOutputContentList]` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Text, image, or file output of the function call. - - `type: Literal["auto"]` + - `class BetaResponseInputText: …` - Always `auto`. + A text input to the model. - - `"auto"` + - `class BetaResponseInputImage: …` - - `file_ids: Optional[List[str]]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - An optional list of uploaded files to make available to your code. + - `class BetaResponseInputFile: …` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + A file input to the model. - The memory limit for the code interpreter container. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"1g"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"4g"` + - `"in_progress"` - - `"16g"` + - `"completed"` - - `"64g"` + - `"incomplete"` - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `type: Literal["function_call_output"]` - Network access policy for the container. + The type of the function tool call output. Always `function_call_output`. - - `class BetaContainerNetworkPolicyDisabled: …` + - `"function_call_output"` - - `type: Literal["disabled"]` + - `agent: Optional[Agent]` - Disable outbound network access. Always `disabled`. + The agent that produced this item. - - `"disabled"` + - `agent_name: str` - - `class BetaContainerNetworkPolicyAllowlist: …` + The canonical name of the agent that produced this item. - - `allowed_domains: List[str]` + - `caller: Optional[Caller]` - A list of allowed domains when type is `allowlist`. + The execution context that produced this tool call. - - `type: Literal["allowlist"]` + - `class CallerDirect: …` - Allow outbound network access only to specified domains. Always `allowlist`. + - `type: Literal["direct"]` - - `"allowlist"` + The caller type. Always `direct`. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `"direct"` - Optional domain-scoped secrets for allowlisted domains. + - `class CallerProgram: …` - - `domain: str` + - `caller_id: str` - The domain associated with the secret. + The call ID of the program item that produced this tool call. - - `name: str` + - `type: Literal["program"]` - The name of the secret to inject for the domain. + The caller type. Always `program`. - - `value: str` + - `"program"` - The secret value to inject for the domain. + - `created_by: Optional[str]` - - `type: Literal["code_interpreter"]` + The identifier of the actor that created the item. - The type of the code interpreter tool. Always `code_interpreter`. + - `class AgentMessage: …` - - `"code_interpreter"` + - `id: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The unique ID of the agent message. - The tool invocation context(s). + - `author: str` - - `"direct"` + The sending agent identity. - - `"programmatic"` + - `content: List[AgentMessageContent]` - - `class ProgrammaticToolCalling: …` + Encrypted content sent between agents. - - `type: Literal["programmatic_tool_calling"]` + - `class BetaResponseInputText: …` - The type of the tool. Always `programmatic_tool_calling`. + A text input to the model. - - `"programmatic_tool_calling"` + - `class BetaResponseOutputText: …` - - `class ImageGeneration: …` + A text output from the model. - A tool that generates images using the GPT image models. + - `class AgentMessageContentText: …` - - `type: Literal["image_generation"]` + A text content. - The type of the image generation tool. Always `image_generation`. + - `text: str` - - `"image_generation"` + - `type: Literal["text"]` - - `action: Optional[Literal["generate", "edit", "auto"]]` + - `"text"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `class AgentMessageContentSummaryText: …` - - `"generate"` + A summary text from the model. - - `"edit"` + - `text: str` - - `"auto"` + A summary of the reasoning output from the model so far. - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + - `type: Literal["summary_text"]` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The type of the object. Always `summary_text`. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `"summary_text"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `class AgentMessageContentReasoningText: …` - - `"transparent"` + Reasoning text from the model. - - `"opaque"` + - `text: str` - - `"auto"` + The reasoning text from the model. - - `input_fidelity: Optional[Literal["high", "low"]]` + - `type: Literal["reasoning_text"]` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + The type of the reasoning text. Always `reasoning_text`. - - `"high"` + - `"reasoning_text"` - - `"low"` + - `class BetaResponseOutputRefusal: …` - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + A refusal from the model. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `class BetaResponseInputImage: …` - - `file_id: Optional[str]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - File ID for the mask image. + - `class AgentMessageContentComputerScreenshot: …` - - `image_url: Optional[str]` + A screenshot of a computer. - Base64-encoded mask image. + - `detail: Literal["low", "high", "auto", "original"]` - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The image generation model to use. Default: `gpt-image-1`. + - `"low"` - - `str` + - `"high"` - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `"auto"` - The image generation model to use. Default: `gpt-image-1`. + - `"original"` - - `"gpt-image-1"` + - `file_id: Optional[str]` - - `"gpt-image-1-mini"` + The identifier of an uploaded file that contains the screenshot. - - `"gpt-image-2"` + - `image_url: Optional[str]` - - `"gpt-image-2-2026-04-21"` + The URL of the screenshot image. - - `"gpt-image-1.5"` + - `type: Literal["computer_screenshot"]` - - `"chatgpt-image-latest"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `moderation: Optional[Literal["auto", "low"]]` + - `"computer_screenshot"` - Moderation level for the generated image. Default: `auto`. + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - - `"auto"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"low"` + - `mode: Literal["explicit"]` - - `output_compression: Optional[int]` + The breakpoint mode. Always `explicit`. - Compression level for the output image. Default: 100. + - `"explicit"` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + - `class BetaResponseInputFile: …` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + A file input to the model. - - `"png"` + - `class AgentMessageContentEncryptedContent: …` - - `"webp"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"jpeg"` + - `encrypted_content: str` - - `partial_images: Optional[int]` + Opaque encrypted content. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `type: Literal["encrypted_content"]` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + The type of the input item. Always `encrypted_content`. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"encrypted_content"` - - `"low"` + - `recipient: str` - - `"medium"` + The destination agent identity. - - `"high"` + - `type: Literal["agent_message"]` - - `"auto"` + The type of the item. Always `agent_message`. - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + - `"agent_message"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `agent: Optional[AgentMessageAgent]` - - `str` + The agent that produced this item. - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `agent_name: str` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The canonical name of the agent that produced this item. - - `"1024x1024"` + - `class MultiAgentCall: …` - - `"1024x1536"` + - `id: str` - - `"1536x1024"` + The unique ID of the multi-agent call item. - - `"auto"` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `class LocalShell: …` + The multi-agent action to execute. - A tool that allows the model to execute shell commands in a local environment. + - `"spawn_agent"` - - `type: Literal["local_shell"]` + - `"interrupt_agent"` - The type of the local shell tool. Always `local_shell`. + - `"list_agents"` - - `"local_shell"` + - `"send_message"` - - `class BetaFunctionShellTool: …` + - `"followup_task"` - A tool that allows the model to execute shell commands. + - `"wait_agent"` - - `type: Literal["shell"]` + - `arguments: str` - The type of the shell tool. Always `shell`. + The JSON string of arguments generated for the action. - - `"shell"` + - `call_id: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The unique ID linking this call to its output. - The tool invocation context(s). + - `type: Literal["multi_agent_call"]` - - `"direct"` + The type of the multi-agent call. Always `multi_agent_call`. - - `"programmatic"` + - `"multi_agent_call"` - - `environment: Optional[Environment]` + - `agent: Optional[MultiAgentCallAgent]` - - `class BetaContainerAuto: …` + The agent that produced this item. - - `type: Literal["container_auto"]` + - `agent_name: str` - Automatically creates a container for this request + The canonical name of the agent that produced this item. - - `"container_auto"` + - `class MultiAgentCallOutput: …` - - `file_ids: Optional[List[str]]` + - `id: str` - An optional list of uploaded files to make available to your code. + The unique ID of the multi-agent call output item. - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - The memory limit for the container. + The multi-agent action that produced this result. - - `"1g"` + - `"spawn_agent"` - - `"4g"` + - `"interrupt_agent"` - - `"16g"` + - `"list_agents"` - - `"64g"` + - `"send_message"` - - `network_policy: Optional[NetworkPolicy]` + - `"followup_task"` - Network access policy for the container. + - `"wait_agent"` - - `class BetaContainerNetworkPolicyDisabled: …` + - `call_id: str` - - `class BetaContainerNetworkPolicyAllowlist: …` + The unique ID of the multi-agent call. - - `skills: Optional[List[Skill]]` + - `output: List[BetaResponseOutputText]` - An optional list of skills referenced by id or inline data. + Text output returned by the multi-agent action. - - `class BetaSkillReference: …` + - `annotations: List[Annotation]` - - `skill_id: str` + The annotations of the text output. - The ID of the referenced skill. + - `text: str` - - `type: Literal["skill_reference"]` + The text output from the model. - References a skill created with the /v1/skills endpoint. + - `type: Literal["output_text"]` - - `"skill_reference"` + The type of the output text. Always `output_text`. - - `version: Optional[str]` + - `logprobs: Optional[List[Logprob]]` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `type: Literal["multi_agent_call_output"]` - - `class BetaInlineSkill: …` + The type of the multi-agent result. Always `multi_agent_call_output`. - - `description: str` + - `"multi_agent_call_output"` - The description of the skill. + - `agent: Optional[MultiAgentCallOutputAgent]` - - `name: str` + The agent that produced this item. - The name of the skill. + - `agent_name: str` - - `source: BetaInlineSkillSource` + The canonical name of the agent that produced this item. - Inline skill payload + - `class BetaResponseFunctionWebSearch: …` - - `data: str` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - Base64-encoded skill zip bundle. + - `class BetaResponseComputerToolCall: …` - - `media_type: Literal["application/zip"]` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The media type of the inline skill payload. Must be `application/zip`. + - `class BetaResponseComputerToolCallOutputItem: …` - - `"application/zip"` + - `id: str` - - `type: Literal["base64"]` + The unique ID of the computer call tool output. - The type of the inline skill source. Must be `base64`. + - `call_id: str` - - `"base64"` + The ID of the computer tool call that produced the output. - - `type: Literal["inline"]` + - `output: BetaResponseComputerToolCallOutputScreenshot` - Defines an inline skill for this request. + A computer screenshot image used with the computer use tool. - - `"inline"` + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - `class BetaLocalEnvironment: …` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `type: Literal["local"]` + - `"completed"` - Use a local computer environment. + - `"incomplete"` - - `"local"` + - `"failed"` - - `skills: Optional[List[BetaLocalSkill]]` + - `"in_progress"` - An optional list of skills. + - `type: Literal["computer_call_output"]` - - `description: str` + The type of the computer tool call output. Always `computer_call_output`. - The description of the skill. + - `"computer_call_output"` - - `name: str` + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - The name of the skill. + The safety checks reported by the API that have been acknowledged by the + developer. - - `path: str` + - `id: str` - The path to the directory containing the skill. + The ID of the pending safety check. - - `class BetaContainerReference: …` + - `code: Optional[str]` - - `container_id: str` + The type of the pending safety check. - The ID of the referenced container. + - `message: Optional[str]` - - `type: Literal["container_reference"]` + Details about the pending safety check. - References a container created with the /v1/containers endpoint + - `agent: Optional[Agent]` - - `"container_reference"` + The agent that produced this item. - - `class BetaCustomTool: …` + - `agent_name: str` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The canonical name of the agent that produced this item. - - `name: str` + - `created_by: Optional[str]` - The name of the custom tool, used to identify it in tool calls. + The identifier of the actor that created the item. - - `type: Literal["custom"]` + - `class BetaResponseReasoningItem: …` - The type of the custom tool. Always `custom`. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `"custom"` + - `class Program: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `id: str` - The tool invocation context(s). + The unique ID of the program item. - - `"direct"` + - `call_id: str` - - `"programmatic"` + The stable call ID of the program item. - - `defer_loading: Optional[bool]` + - `code: str` - Whether this tool should be deferred and discovered via tool search. + The JavaScript source executed by programmatic tool calling. - - `description: Optional[str]` + - `fingerprint: str` - Optional description of the custom tool, used to provide more context. + Opaque program replay fingerprint that must be round-tripped. - - `format: Optional[Format]` + - `type: Literal["program"]` - The input format for the custom tool. Default is unconstrained text. + The type of the item. Always `program`. - - `class FormatText: …` + - `"program"` - Unconstrained free-form text. + - `agent: Optional[ProgramAgent]` - - `type: Literal["text"]` + The agent that produced this item. - Unconstrained text format. Always `text`. + - `agent_name: str` - - `"text"` + The canonical name of the agent that produced this item. - - `class FormatGrammar: …` + - `class ProgramOutput: …` - A grammar defined by the user. + - `id: str` + + The unique ID of the program output item. - - `definition: str` + - `call_id: str` - The grammar definition. + The call ID of the program item. - - `syntax: Literal["lark", "regex"]` + - `result: str` - The syntax of the grammar definition. One of `lark` or `regex`. + The result produced by the program item. - - `"lark"` + - `status: Literal["completed", "incomplete"]` - - `"regex"` + The terminal status of the program output item. - - `type: Literal["grammar"]` + - `"completed"` - Grammar format. Always `grammar`. + - `"incomplete"` - - `"grammar"` + - `type: Literal["program_output"]` - - `class BetaNamespaceTool: …` + The type of the item. Always `program_output`. - Groups function/custom tools under a shared namespace. + - `"program_output"` - - `description: str` + - `agent: Optional[ProgramOutputAgent]` - A description of the namespace shown to the model. + The agent that produced this item. - - `name: str` + - `agent_name: str` - The namespace name used in tool calls (for example, `crm`). + The canonical name of the agent that produced this item. - - `tools: List[Tool]` + - `class BetaResponseToolSearchCall: …` - The function/custom tools available inside this namespace. + - `id: str` - - `class ToolFunction: …` + The unique ID of the tool search call item. - - `name: str` + - `arguments: object` - - `type: Literal["function"]` + Arguments used for the tool search call. - - `"function"` + - `call_id: Optional[str]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The unique ID of the tool search call generated by the model. - The tool invocation context(s). + - `execution: Literal["server", "client"]` - - `"direct"` + Whether tool search was executed by the server or by the client. - - `"programmatic"` + - `"server"` - - `defer_loading: Optional[bool]` + - `"client"` - Whether this function should be deferred and discovered via tool search. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `description: Optional[str]` + The status of the tool search call item that was recorded. - - `output_schema: Optional[Dict[str, object]]` + - `"in_progress"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `"completed"` - - `parameters: Optional[object]` + - `"incomplete"` - - `strict: Optional[bool]` + - `type: Literal["tool_search_call"]` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The type of the item. Always `tool_search_call`. - - `class BetaCustomTool: …` + - `"tool_search_call"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `agent: Optional[Agent]` - - `type: Literal["namespace"]` + The agent that produced this item. - The type of the tool. Always `namespace`. + - `agent_name: str` - - `"namespace"` + The canonical name of the agent that produced this item. - - `class BetaToolSearchTool: …` + - `created_by: Optional[str]` - Hosted or BYOT tool search configuration for deferred tools. + The identifier of the actor that created the item. - - `type: Literal["tool_search"]` + - `class BetaResponseToolSearchOutputItem: …` - The type of the tool. Always `tool_search`. + - `id: str` - - `"tool_search"` + The unique ID of the tool search output item. - - `description: Optional[str]` + - `call_id: Optional[str]` - Description shown to the model for a client-executed tool search tool. + The unique ID of the tool search call generated by the model. - - `execution: Optional[Literal["server", "client"]]` + - `execution: Literal["server", "client"]` - Whether tool search is executed by the server or by the client. + Whether tool search was executed by the server or by the client. - `"server"` - `"client"` - - `parameters: Optional[object]` + - `status: Literal["in_progress", "completed", "incomplete"]` - Parameter schema for a client-executed tool search tool. + The status of the tool search output item that was recorded. - - `class BetaWebSearchPreviewTool: …` + - `"in_progress"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"completed"` - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + - `"incomplete"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `tools: List[BetaTool]` - - `"web_search_preview"` + The loaded tool definitions returned by tool search. - - `"web_search_preview_2025_03_11"` + - `class BetaFunctionTool: …` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"text"` + - `class BetaFileSearchTool: …` - - `"image"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `class BetaComputerTool: …` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"low"` + - `class BetaComputerUsePreviewTool: …` - - `"medium"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"high"` + - `class BetaWebSearchTool: …` - - `user_location: Optional[UserLocation]` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The user's location. + - `class Mcp: …` - - `type: Literal["approximate"]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The type of location approximation. Always `approximate`. + - `class CodeInterpreter: …` - - `"approximate"` + A tool that runs Python code to help generate a response to a prompt. - - `city: Optional[str]` + - `class ProgrammaticToolCalling: …` - Free text input for the city of the user, e.g. `San Francisco`. + - `class ImageGeneration: …` - - `country: Optional[str]` + A tool that generates images using the GPT image models. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `class LocalShell: …` - - `region: Optional[str]` + A tool that allows the model to execute shell commands in a local environment. - Free text input for the region of the user, e.g. `California`. + - `class BetaFunctionShellTool: …` - - `timezone: Optional[str]` + A tool that allows the model to execute shell commands. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `class BetaCustomTool: …` - - `class BetaApplyPatchTool: …` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - Allows the assistant to create, delete, or update files using unified diffs. + - `class BetaNamespaceTool: …` - - `type: Literal["apply_patch"]` + Groups function/custom tools under a shared namespace. - The type of the tool. Always `apply_patch`. + - `class BetaToolSearchTool: …` - - `"apply_patch"` + Hosted or BYOT tool search configuration for deferred tools. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `class BetaWebSearchPreviewTool: …` - The tool invocation context(s). + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"direct"` + - `class BetaApplyPatchTool: …` - - `"programmatic"` + Allows the assistant to create, delete, or update files using unified diffs. - `type: Literal["tool_search_output"]` @@ -48150,79 +58291,6 @@ Compact a response A tool call to run code. - - `id: str` - - The unique ID of the code interpreter tool call. - - - `code: Optional[str]` - - The code to run, or null if not available. - - - `container_id: str` - - The ID of the container used to run the code. - - - `outputs: Optional[List[Output]]` - - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. - - - `class OutputLogs: …` - - The logs output from the code interpreter. - - - `logs: str` - - The logs output from the code interpreter. - - - `type: Literal["logs"]` - - The type of the output. Always `logs`. - - - `"logs"` - - - `class OutputImage: …` - - The image output from the code interpreter. - - - `type: Literal["image"]` - - The type of the output. Always `image`. - - - `"image"` - - - `url: str` - - The URL of the image output from the code interpreter. - - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"interpreting"` - - - `"failed"` - - - `type: Literal["code_interpreter_call"]` - - The type of the code interpreter tool call. Always `code_interpreter_call`. - - - `"code_interpreter_call"` - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - `class LocalShellCall: …` A tool call to run a command on the local shell. @@ -48631,262 +58699,1084 @@ Compact a response - `"direct"` - - `class CallerProgram: …` + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `created_by: Optional[str]` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput: …` + + The output emitted by an apply patch tool call. + + - `id: str` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `call_id: str` + + The unique ID of the apply patch tool call generated by the model. + + - `status: Literal["completed", "failed"]` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: Literal["apply_patch_call_output"]` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `created_by: Optional[str]` + + The ID of the entity that created this tool call output. + + - `output: Optional[str]` + + Optional textual output returned by the apply patch tool. + + - `class McpCall: …` + + An invocation of a tool on an MCP server. + + - `id: str` + + The unique ID of the tool call. + + - `arguments: str` + + A JSON string of the arguments passed to the tool. + + - `name: str` + + The name of the tool that was run. + + - `server_label: str` + + The label of the MCP server running the tool. + + - `type: Literal["mcp_call"]` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `agent: Optional[McpCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `approval_request_id: Optional[str]` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: Optional[str]` + + The error from the tool call, if any. + + - `output: Optional[str]` + + The output from the tool call. + + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `class McpListTools: …` + + A list of tools available on an MCP server. + + - `id: str` + + The unique ID of the list. + + - `server_label: str` + + The label of the MCP server. + + - `tools: List[McpListToolsTool]` + + The tools available on the server. + + - `input_schema: object` + + The JSON schema describing the tool's input. + + - `name: str` + + The name of the tool. + + - `annotations: Optional[object]` + + Additional annotations about the tool. + + - `description: Optional[str]` + + The description of the tool. + + - `type: Literal["mcp_list_tools"]` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `agent: Optional[McpListToolsAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `error: Optional[str]` + + Error message if the server could not list tools. + + - `class McpApprovalRequest: …` + + A request for human approval of a tool invocation. + + - `id: str` + + The unique ID of the approval request. + + - `arguments: str` + + A JSON string of arguments for the tool. + + - `name: str` + + The name of the tool to run. + + - `server_label: str` + + The label of the MCP server making the request. + + - `type: Literal["mcp_approval_request"]` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `agent: Optional[McpApprovalRequestAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse: …` + + A response to an MCP approval request. + + - `id: str` + + The unique ID of the approval response + + - `approval_request_id: str` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: Literal["mcp_approval_response"]` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `agent: Optional[McpApprovalResponseAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `reason: Optional[str]` + + Optional reason for the decision. + + - `class BetaResponseCustomToolCall: …` + + A call to a custom tool created by the model. + + - `class BetaResponseCustomToolCallOutputItem: …` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: str` + + The unique ID of the custom tool call output item. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `parallel_tool_calls: bool` + + Whether to allow the model to run tool calls in parallel. + + - `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. + We generally recommend altering this or `top_p` but not both. + + - `tool_choice: ToolChoice` + + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. + + - `Literal["none", "auto", "required"]` + + - `"none"` + + - `"auto"` + + - `"required"` + + - `class BetaToolChoiceAllowed: …` + + Constrains the tools available to the model to a pre-defined set. + + - `mode: Literal["auto", "required"]` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `"auto"` + + - `"required"` + + - `tools: List[Dict[str, object]]` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `type: Literal["allowed_tools"]` + + Allowed tool configuration type. Always `allowed_tools`. + + - `"allowed_tools"` + + - `class BetaToolChoiceTypes: …` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `"file_search"` + + - `"web_search_preview"` + + - `"computer"` + + - `"computer_use_preview"` + + - `"computer_use"` + + - `"web_search_preview_2025_03_11"` + + - `"image_generation"` + + - `"code_interpreter"` + + - `class BetaToolChoiceFunction: …` + + Use this option to force the model to call a specific function. + + - `name: str` + + The name of the function to call. + + - `type: Literal["function"]` + + For function calling, the type is always `function`. + + - `"function"` + + - `class BetaToolChoiceMcp: …` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `server_label: str` + + The label of the MCP server to use. + + - `type: Literal["mcp"]` + + For MCP tools, the type is always `mcp`. + + - `"mcp"` + + - `name: Optional[str]` + + The name of the tool to call on the server. + + - `class BetaToolChoiceCustom: …` + + Use this option to force the model to call a specific custom tool. + + - `name: str` + + The name of the custom tool to call. + + - `type: Literal["custom"]` + + For custom tool calling, the type is always `custom`. + + - `"custom"` + + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + + - `type: Literal["programmatic_tool_calling"]` + + The tool to call. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + + - `class BetaToolChoiceApplyPatch: …` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `type: Literal["apply_patch"]` + + The tool to call. Always `apply_patch`. + + - `"apply_patch"` + + - `class BetaToolChoiceShell: …` + + Forces the model to call the shell tool when a tool call is required. + + - `type: Literal["shell"]` + + The tool to call. Always `shell`. + + - `"shell"` + + - `tools: List[BetaTool]` + + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. + + - `class BetaFunctionTool: …` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool: …` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool: …` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class Mcp: …` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `class CodeInterpreter: …` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling: …` + + - `class ImageGeneration: …` + + A tool that generates images using the GPT image models. + + - `class LocalShell: …` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool: …` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool: …` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool: …` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool: …` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool: …` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `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. + + - `background: Optional[bool]` + + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + + - `completed_at: Optional[float]` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `conversation: Optional[Conversation]` + + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + + - `id: str` + + The unique ID of the conversation that this response was associated with. + + - `max_output_tokens: Optional[int]` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + + - `max_tool_calls: Optional[int]` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `moderation: Optional[Moderation]` + + Moderation results for the response input and output, if moderated completions were requested. + + - `input: ModerationInput` + + Moderation for the response input. + + - `class ModerationInputModerationResult: …` + + A moderation result produced for the response input or output. + + - `categories: Dict[str, bool]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: Dict[str, float]` + + A dictionary of moderation categories to scores. + + - `flagged: bool` + + A boolean indicating whether the content was flagged by any category. + + - `model: str` + + The moderation model that produced this result. + + - `type: Literal["moderation_result"]` + + The object type, which was always `moderation_result` for successful moderation results. + + - `"moderation_result"` + + - `class ModerationInputError: …` + + An error produced while attempting moderation for the response input or output. + + - `code: str` + + The error code. + + - `message: str` + + The error message. + + - `type: Literal["error"]` + + The object type, which was always `error` for moderation failures. + + - `"error"` + + - `output: ModerationOutput` + + Moderation for the response output. + + - `class ModerationOutputModerationResult: …` + + A moderation result produced for the response input or output. + + - `categories: Dict[str, bool]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: Dict[str, float]` + + A dictionary of moderation categories to scores. + + - `flagged: bool` + + A boolean indicating whether the content was flagged by any category. + + - `model: str` + + The moderation model that produced this result. + + - `type: Literal["moderation_result"]` + + The object type, which was always `moderation_result` for successful moderation results. + + - `"moderation_result"` + + - `class ModerationOutputError: …` + + An error produced while attempting moderation for the response input or output. + + - `code: str` + + The error code. + + - `message: str` + + The error message. + + - `type: Literal["error"]` + + The object type, which was always `error` for moderation failures. + + - `"error"` + + - `previous_response_id: Optional[str]` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `prompt: Optional[BetaResponsePrompt]` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `id: str` + + The unique identifier of the prompt template to use. + + - `variables: Optional[Dict[str, Variables]]` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `str` + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `version: Optional[str]` + + Optional version of the prompt template. + + - `prompt_cache_key: Optional[str]` + + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + + - `prompt_cache_options: Optional[PromptCacheOptions]` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: Literal["implicit", "explicit"]` + + Whether implicit prompt-cache breakpoints were enabled. + + - `"implicit"` + + - `"explicit"` + + - `ttl: Literal["30m"]` + + The minimum lifetime applied to each cache breakpoint. + + - `"30m"` + + - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + + - `"in_memory"` + + - `"24h"` + + - `reasoning: Optional[Reasoning]` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. + + - `"auto"` - - `caller_id: str` + - `"current_turn"` - The call ID of the program item that produced this tool call. + - `"all_turns"` - - `type: Literal["program"]` + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` - - `"program"` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `created_by: Optional[str]` + - `"none"` - The ID of the entity that created this tool call. + - `"minimal"` - - `class BetaResponseApplyPatchToolCallOutput: …` + - `"low"` - The output emitted by an apply patch tool call. + - `"medium"` - - `id: str` + - `"high"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"xhigh"` - - `call_id: str` + - `"max"` - The unique ID of the apply patch tool call generated by the model. + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` - - `status: Literal["completed", "failed"]` + **Deprecated:** use `summary` instead. - The status of the apply patch tool call output. One of `completed` or `failed`. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `"completed"` + - `"auto"` - - `"failed"` + - `"concise"` - - `type: Literal["apply_patch_call_output"]` + - `"detailed"` - The type of the item. Always `apply_patch_call_output`. + - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` - - `"apply_patch_call_output"` + Controls the reasoning execution mode for the request. - - `agent: Optional[Agent]` + When returned on a response, this is the effective execution mode. - The agent that produced this item. + - `str` - - `agent_name: str` + - `Literal["standard", "pro"]` - The canonical name of the agent that produced this item. + Controls the reasoning execution mode for the request. - - `caller: Optional[Caller]` + When returned on a response, this is the effective execution mode. - The execution context that produced this tool call. + - `"standard"` - - `class CallerDirect: …` + - `"pro"` - - `type: Literal["direct"]` + - `summary: Optional[Literal["auto", "concise", "detailed"]]` - - `"direct"` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `class CallerProgram: …` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `caller_id: str` + - `"auto"` - The call ID of the program item that produced this tool call. + - `"concise"` - - `type: Literal["program"]` + - `"detailed"` - - `"program"` + - `safety_identifier: Optional[str]` - - `created_by: Optional[str]` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The ID of the entity that created this tool call output. + - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` - - `output: Optional[str]` + Specifies the processing type used for serving the request. - Optional textual output returned by the apply patch tool. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `class McpCall: …` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - An invocation of a tool on an MCP server. + - `"auto"` - - `id: str` + - `"default"` - The unique ID of the tool call. + - `"flex"` - - `arguments: str` + - `"scale"` - A JSON string of the arguments passed to the tool. + - `"priority"` - - `name: str` + - `status: Optional[BetaResponseStatus]` - The name of the tool that was run. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `server_label: str` + - `"completed"` - The label of the MCP server running the tool. + - `"failed"` - - `type: Literal["mcp_call"]` + - `"in_progress"` - The type of the item. Always `mcp_call`. + - `"cancelled"` - - `"mcp_call"` + - `"queued"` - - `agent: Optional[McpCallAgent]` + - `"incomplete"` - The agent that produced this item. + - `text: Optional[BetaResponseTextConfig]` - - `agent_name: str` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The canonical name of the agent that produced this item. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `approval_request_id: Optional[str]` + - `format: Optional[BetaResponseFormatTextConfig]` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + An object specifying the format that the model must output. - - `error: Optional[str]` + Configuring `{ "type": "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). - The error from the tool call, if any. + The default format is `{ "type": "text" }` with no additional options. - - `output: Optional[str]` + **Not recommended for gpt-4o and newer models:** - The output from the tool call. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `class Text: …` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + Default response format. Used to generate text responses. - - `"in_progress"` + - `type: Literal["text"]` - - `"completed"` + The type of response format being defined. Always `text`. - - `"incomplete"` + - `"text"` - - `"calling"` + - `class BetaResponseFormatTextJSONSchemaConfig: …` - - `"failed"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `class McpListTools: …` + - `name: str` - A list of tools available on an MCP server. + 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. - - `id: str` + - `schema: Dict[str, object]` - The unique ID of the list. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `server_label: str` + - `type: Literal["json_schema"]` - The label of the MCP server. + The type of response format being defined. Always `json_schema`. - - `tools: List[McpListToolsTool]` + - `"json_schema"` - The tools available on the server. + - `description: Optional[str]` - - `input_schema: object` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The JSON schema describing the tool's input. + - `strict: Optional[bool]` - - `name: str` + 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). - The name of the tool. + - `class JSONObject: …` - - `annotations: Optional[object]` + 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. - Additional annotations about the tool. + - `type: Literal["json_object"]` - - `description: Optional[str]` + The type of response format being defined. Always `json_object`. - The description of the tool. + - `"json_object"` - - `type: Literal["mcp_list_tools"]` + - `verbosity: Optional[Literal["low", "medium", "high"]]` - The type of the item. Always `mcp_list_tools`. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `"mcp_list_tools"` + - `"low"` - - `agent: Optional[McpListToolsAgent]` + - `"medium"` - The agent that produced this item. + - `"high"` - - `agent_name: str` + - `top_logprobs: Optional[int]` - The canonical name of the agent that produced this item. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `error: Optional[str]` + - `truncation: Optional[Literal["auto", "disabled"]]` - Error message if the server could not list tools. + The truncation strategy to use for the model response. - - `class McpApprovalRequest: …` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - A request for human approval of a tool invocation. + - `"auto"` - - `id: str` + - `"disabled"` - The unique ID of the approval request. + - `usage: Optional[BetaResponseUsage]` - - `arguments: str` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - A JSON string of arguments for the tool. + - `input_tokens: int` - - `name: str` + The number of input tokens. - The name of the tool to run. + - `input_tokens_details: InputTokensDetails` - - `server_label: str` + A detailed breakdown of the input tokens. - The label of the MCP server making the request. + - `cache_write_tokens: int` - - `type: Literal["mcp_approval_request"]` + The number of input tokens that were written to the cache. - The type of the item. Always `mcp_approval_request`. + - `cached_tokens: int` - - `"mcp_approval_request"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `agent: Optional[McpApprovalRequestAgent]` + - `output_tokens: int` - The agent that produced this item. + The number of output tokens. - - `agent_name: str` + - `output_tokens_details: OutputTokensDetails` - The canonical name of the agent that produced this item. + A detailed breakdown of the output tokens. - - `class McpApprovalResponse: …` + - `reasoning_tokens: int` - A response to an MCP approval request. + The number of reasoning tokens. - - `id: str` + - `total_tokens: int` - The unique ID of the approval response + The total number of tokens used. - - `approval_request_id: str` + - `user: Optional[str]` - The ID of the approval request being answered. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `approve: bool` + - `sequence_number: int` - Whether the request was approved. + The sequence number for this event. - - `type: Literal["mcp_approval_response"]` + - `type: Literal["response.created"]` - The type of the item. Always `mcp_approval_response`. + The type of the event. Always `response.created`. - - `"mcp_approval_response"` + - `"response.created"` - - `agent: Optional[McpApprovalResponseAgent]` + - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `reason: Optional[str]` - - Optional reason for the decision. +### Beta Response Custom Tool Call - - `class BetaResponseCustomToolCall: …` +- `class BetaResponseCustomToolCall: …` A call to a custom tool created by the model. @@ -48944,432 +59834,292 @@ Compact a response The namespace of the custom tool being called. - - `class BetaResponseCustomToolCallOutputItem: …` - - The output of a custom tool call from your code, being sent back to the model. - - - `id: str` - - The unique ID of the custom tool call output item. +### Beta Response Custom Tool Call Input Delta Event - - `status: Literal["in_progress", "completed", "incomplete"]` +- `class BetaResponseCustomToolCallInputDeltaEvent: …` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Event representing a delta (partial update) to the input of a custom tool call. - - `"in_progress"` + - `delta: str` - - `"completed"` + The incremental input data (delta) for the custom tool call. - - `"incomplete"` + - `item_id: str` - - `created_by: Optional[str]` + Unique identifier for the API item associated with this event. - The identifier of the actor that created the item. + - `output_index: int` - - `usage: BetaResponseUsage` + The index of the output this delta applies to. - Token accounting for the compaction pass, including cached, reasoning, and total tokens. + - `sequence_number: int` - - `input_tokens: int` + The sequence number of this event. - The number of input tokens. + - `type: Literal["response.custom_tool_call_input.delta"]` - - `input_tokens_details: InputTokensDetails` + The event type identifier. - A detailed breakdown of the input tokens. + - `"response.custom_tool_call_input.delta"` - - `cache_write_tokens: int` + - `agent: Optional[Agent]` - The number of input tokens that were written to the cache. + The agent that owns this multi-agent streaming event. - - `cached_tokens: int` + - `agent_name: str` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The canonical name of the agent that produced this item. - - `output_tokens: int` +### Beta Response Custom Tool Call Input Done Event - The number of output tokens. +- `class BetaResponseCustomToolCallInputDoneEvent: …` - - `output_tokens_details: OutputTokensDetails` + Event indicating that input for a custom tool call is complete. - A detailed breakdown of the output tokens. + - `input: str` - - `reasoning_tokens: int` + The complete input data for the custom tool call. - The number of reasoning tokens. + - `item_id: str` - - `total_tokens: int` + Unique identifier for the API item associated with this event. - The total number of tokens used. + - `output_index: int` -### Example + The index of the output this event applies to. -```python -import os -from openai import OpenAI + - `sequence_number: int` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -beta_compacted_response = client.beta.responses.compact( - model="gpt-5.6-sol", -) -print(beta_compacted_response.id) -``` + The sequence number of this event. -#### Response + - `type: Literal["response.custom_tool_call_input.done"]` -```json -{ - "id": "id", - "created_at": 0, - "object": "response.compaction", - "output": [ - { - "id": "id", - "content": [ - { - "annotations": [ - { - "file_id": "file_id", - "filename": "filename", - "index": 0, - "type": "file_citation" - } - ], - "text": "text", - "type": "output_text", - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ] - } - ], - "role": "assistant", - "status": "in_progress", - "type": "message", - "agent": { - "agent_name": "agent_name" - }, - "phase": "commentary" - } - ], - "usage": { - "input_tokens": 0, - "input_tokens_details": { - "cache_write_tokens": 0, - "cached_tokens": 0 - }, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - } -} -``` + The event type identifier. -### Example + - `"response.custom_tool_call_input.done"` -```python -from openai import OpenAI + - `agent: Optional[Agent]` -client = OpenAI() + The agent that owns this multi-agent streaming event. -compacted_response = client.responses.compact( - model="gpt-5.1-codex-max", - input=[ - { - "role": "user", - "content": "Create a simple landing page for a dog petting cafe.", - }, - # All items returned from previous requests are included here, like reasoning, message, function call, etc. - { - "id": "msg_001", - "type": "message", - "status": "completed", - "content": [ - { - "type": "output_text", - "annotations": [], - "logprobs": [], - "text": "Below is a single file, ready-to-use landing page for a dog petting café:...", - }, - ], - "role": "assistant", - }, - ] -) -# Pass the compacted_response.output as input to the next request -print(compacted_response) -``` + - `agent_name: str` -#### Response + The canonical name of the agent that produced this item. -```json -{ - "id": "resp_001", - "object": "response.compaction", - "created_at": 1764967971, - "output": [ - { - "id": "msg_000", - "type": "message", - "status": "completed", - "content": [ - { - "type": "input_text", - "text": "Create a simple landing page for a dog petting cafe." - } - ], - "role": "user" - }, - { - "id": "cmp_001", - "type": "compaction", - "encrypted_content": "gAAAAABpM0Yj-...=" - } - ], - "usage": { - "input_tokens": 139, - "input_tokens_details": { - "cached_tokens": 0 - }, - "output_tokens": 438, - "output_tokens_details": { - "reasoning_tokens": 64 - }, - "total_tokens": 577 - } -} -``` +### Beta Response Custom Tool Call Item -## Domain Types +- `class BetaResponseCustomToolCallItem: …` -### Beta Apply Patch Tool + A call to a custom tool created by the model. -- `class BetaApplyPatchTool: …` + - `id: str` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of the custom tool call item. - - `type: Literal["apply_patch"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The type of the tool. Always `apply_patch`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"apply_patch"` + - `"in_progress"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"completed"` - The tool invocation context(s). + - `"incomplete"` - - `"direct"` + - `created_by: Optional[str]` - - `"programmatic"` + The identifier of the actor that created the item. -### Beta Compacted Response +### Beta Response Custom Tool Call Output -- `class BetaCompactedResponse: …` +- `class BetaResponseCustomToolCallOutput: …` - - `id: str` + The output of a custom tool call from your code, being sent back to the model. - The unique identifier for the compacted response. + - `call_id: str` - - `created_at: int` + The call ID, used to map this custom tool call output to a custom tool call. - Unix timestamp (in seconds) when the compacted conversation was created. + - `output: Union[str, List[OutputOutputContentList]]` - - `object: Literal["response.compaction"]` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The object type. Always `response.compaction`. + - `str` - - `"response.compaction"` + A string of the output of the custom tool call. - - `output: List[BetaResponseOutputItem]` + - `List[OutputOutputContentList]` - The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + Text, image, or file output of the custom tool call. - - `class BetaResponseOutputMessage: …` + - `class BetaResponseInputText: …` - An output message from the model. + A text input to the model. - - `id: str` + - `text: str` - The unique ID of the output message. + The text input to the model. - - `content: List[Content]` + - `type: Literal["input_text"]` - The content of the output message. + The type of the input item. Always `input_text`. - - `class BetaResponseOutputText: …` + - `"input_text"` - A text output from the model. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `annotations: List[Annotation]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The annotations of the text output. + - `mode: Literal["explicit"]` - - `class AnnotationFileCitation: …` + The breakpoint mode. Always `explicit`. - A citation to a file. + - `"explicit"` - - `file_id: str` + - `class BetaResponseInputImage: …` - The ID of the file. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `filename: str` + - `detail: Literal["low", "high", "auto", "original"]` - The filename of the file cited. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `index: int` + - `"low"` - The index of the file in the list of files. + - `"high"` - - `type: Literal["file_citation"]` + - `"auto"` - The type of the file citation. Always `file_citation`. + - `"original"` - - `"file_citation"` + - `type: Literal["input_image"]` - - `class AnnotationURLCitation: …` + The type of the input item. Always `input_image`. - A citation for a web resource used to generate a model response. + - `"input_image"` - - `end_index: int` + - `file_id: Optional[str]` - The index of the last character of the URL citation in the message. + The ID of the file to be sent to the model. - - `start_index: int` + - `image_url: Optional[str]` - The index of the first character of the URL citation in the message. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `title: str` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The title of the web resource. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `type: Literal["url_citation"]` + - `mode: Literal["explicit"]` - The type of the URL citation. Always `url_citation`. + The breakpoint mode. Always `explicit`. - - `"url_citation"` + - `"explicit"` - - `url: str` + - `class BetaResponseInputFile: …` - The URL of the web resource. + A file input to the model. - - `class AnnotationContainerFileCitation: …` + - `type: Literal["input_file"]` - A citation for a container file used to generate a model response. + The type of the input item. Always `input_file`. - - `container_id: str` + - `"input_file"` - The ID of the container file. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `end_index: int` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The index of the last character of the container file citation in the message. + - `"auto"` - - `file_id: str` + - `"low"` - The ID of the file. + - `"high"` - - `filename: str` + - `file_data: Optional[str]` - The filename of the container file cited. + The content of the file to be sent to the model. - - `start_index: int` + - `file_id: Optional[str]` - The index of the first character of the container file citation in the message. + The ID of the file to be sent to the model. - - `type: Literal["container_file_citation"]` + - `file_url: Optional[str]` - The type of the container file citation. Always `container_file_citation`. + The URL of the file to be sent to the model. - - `"container_file_citation"` + - `filename: Optional[str]` - - `class AnnotationFilePath: …` + The name of the file to be sent to the model. - A path to a file. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `file_id: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The ID of the file. + - `mode: Literal["explicit"]` - - `index: int` + The breakpoint mode. Always `explicit`. - The index of the file in the list of files. + - `"explicit"` - - `type: Literal["file_path"]` + - `type: Literal["custom_tool_call_output"]` - The type of the file path. Always `file_path`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"file_path"` + - `"custom_tool_call_output"` - - `text: str` + - `id: Optional[str]` - The text output from the model. + The unique ID of the custom tool call output in the OpenAI platform. - - `type: Literal["output_text"]` + - `agent: Optional[Agent]` - The type of the output text. Always `output_text`. + The agent that produced this item. - - `"output_text"` + - `agent_name: str` - - `logprobs: Optional[List[Logprob]]` + The canonical name of the agent that produced this item. - - `token: str` + - `caller: Optional[Caller]` - - `bytes: List[int]` + The execution context that produced this tool call. - - `logprob: float` + - `class CallerDirect: …` - - `top_logprobs: List[LogprobTopLogprob]` + - `type: Literal["direct"]` - - `token: str` + The caller type. Always `direct`. - - `bytes: List[int]` + - `"direct"` - - `logprob: float` + - `class CallerProgram: …` - - `class BetaResponseOutputRefusal: …` + - `caller_id: str` - A refusal from the model. + The call ID of the program item that produced this tool call. - - `refusal: str` + - `type: Literal["program"]` - The refusal explanation from the model. + The caller type. Always `program`. - - `type: Literal["refusal"]` + - `"program"` - The type of the refusal. Always `refusal`. +### Beta Response Custom Tool Call Output Item - - `"refusal"` +- `class BetaResponseCustomToolCallOutputItem: …` - - `role: Literal["assistant"]` + The output of a custom tool call from your code, being sent back to the model. - The role of the output message. Always `assistant`. + - `id: str` - - `"assistant"` + The unique ID of the custom tool call output item. - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -49377,196 +60127,214 @@ print(compacted_response) - `"incomplete"` - - `type: Literal["message"]` + - `created_by: Optional[str]` - The type of the output message. Always `message`. + The identifier of the actor that created the item. - - `"message"` +### Beta Response Error - - `agent: Optional[Agent]` +- `class BetaResponseError: …` - The agent that produced this item. + An error object returned when the model fails to generate a Response. - - `agent_name: str` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` - The canonical name of the agent that produced this item. + The error code for the response. - - `phase: Optional[Literal["commentary"]]` + - `"server_error"` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `"rate_limit_exceeded"` - - `"commentary"` + - `"invalid_prompt"` - - `class BetaResponseFileSearchToolCall: …` + - `"bio_policy"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"vector_store_timeout"` - - `id: str` + - `"invalid_image"` - The unique ID of the file search tool call. + - `"invalid_image_format"` - - `queries: List[str]` + - `"invalid_base64_image"` - The queries used to search for files. + - `"invalid_image_url"` - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `"image_too_large"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"image_too_small"` - - `"in_progress"` + - `"image_parse_error"` - - `"searching"` + - `"image_content_policy_violation"` - - `"completed"` + - `"invalid_image_mode"` - - `"incomplete"` + - `"image_file_too_large"` - - `"failed"` + - `"unsupported_image_media_type"` - - `type: Literal["file_search_call"]` + - `"empty_image_file"` - The type of the file search tool call. Always `file_search_call`. + - `"failed_to_download_image"` - - `"file_search_call"` + - `"image_file_not_found"` - - `agent: Optional[Agent]` + - `message: str` - The agent that produced this item. + A human-readable description of the error. - - `agent_name: str` +### Beta Response Error Event - The canonical name of the agent that produced this item. +- `class BetaResponseErrorEvent: …` - - `results: Optional[List[Result]]` + Emitted when an error occurs. - The results of the file search tool call. + - `code: Optional[str]` - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + The error code. - 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, booleans, or numbers. + - `message: str` - - `str` + The error message. - - `float` + - `param: Optional[str]` - - `bool` + The error parameter. - - `file_id: Optional[str]` + - `sequence_number: int` - The unique ID of the file. + The sequence number of this event. - - `filename: Optional[str]` + - `type: Literal["error"]` - The name of the file. + The type of the event. Always `error`. - - `score: Optional[float]` + - `"error"` - The relevance score of the file - a value between 0 and 1. + - `agent: Optional[Agent]` - - `text: Optional[str]` + The agent that owns this multi-agent streaming event. - The text that was retrieved from the file. + - `agent_name: str` - - `class BetaResponseFunctionToolCall: …` + The canonical name of the agent that produced this item. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. +### Beta Response Failed Event - - `arguments: str` +- `class BetaResponseFailedEvent: …` - A JSON string of the arguments to pass to the function. + An event that is emitted when a response fails. - - `call_id: str` + - `response: BetaResponse` - The unique ID of the function tool call generated by the model. + The response that failed. - - `name: str` + - `id: str` - The name of the function to run. + Unique identifier for this Response. - - `type: Literal["function_call"]` + - `created_at: float` - The type of the function tool call. Always `function_call`. + Unix timestamp (in seconds) of when this Response was created. - - `"function_call"` + - `error: Optional[BetaResponseError]` - - `id: Optional[str]` + An error object returned when the model fails to generate a Response. - The unique ID of the function tool call. + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` - - `agent: Optional[Agent]` + The error code for the response. - The agent that produced this item. + - `"server_error"` - - `agent_name: str` + - `"rate_limit_exceeded"` - The canonical name of the agent that produced this item. + - `"invalid_prompt"` - - `caller: Optional[Caller]` + - `"bio_policy"` - The execution context that produced this tool call. + - `"vector_store_timeout"` - - `class CallerDirect: …` + - `"invalid_image"` - - `type: Literal["direct"]` + - `"invalid_image_format"` - - `"direct"` + - `"invalid_base64_image"` - - `class CallerProgram: …` + - `"invalid_image_url"` - - `caller_id: str` + - `"image_too_large"` - The call ID of the program item that produced this tool call. + - `"image_too_small"` - - `type: Literal["program"]` + - `"image_parse_error"` - - `"program"` + - `"image_content_policy_violation"` - - `namespace: Optional[str]` + - `"invalid_image_mode"` - The namespace of the function to run. + - `"image_file_too_large"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"unsupported_image_media_type"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"empty_image_file"` - - `"in_progress"` + - `"failed_to_download_image"` - - `"completed"` + - `"image_file_not_found"` - - `"incomplete"` + - `message: str` - - `class BetaResponseFunctionToolCallOutputItem: …` + A human-readable description of the error. - - `id: str` + - `incomplete_details: Optional[IncompleteDetails]` - The unique ID of the function call tool output. + Details about why the response is incomplete. - - `call_id: str` + - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` - The unique ID of the function tool call generated by the model. + The reason why the response is incomplete. - - `output: Union[str, List[OutputOutputContentList]]` + - `"max_output_tokens"` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `"content_filter"` + + - `instructions: Union[str, List[BetaResponseInputItem], null]` + + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - `str` - A string of the output of the function call. + A text input to the model, equivalent to a text input with the + `developer` role. - - `List[OutputOutputContentList]` + - `List[BetaResponseInputItem]` - Text, image, or file output of the function call. + A list of one or many input items to the model, containing + different content types. + + - `class BetaEasyInputMessage: …` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: Union[str, BetaResponseInputMessageContentList]` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `str` + + A text input to the model. + + - `List[BetaResponseInputContent]` - `class BetaResponseInputText: …` @@ -49620,338 +60388,266 @@ print(compacted_response) - `image_url: Optional[str]` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: Literal["explicit"]` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `class BetaResponseInputFile: …` - - A file input to the model. - - - `type: Literal["input_file"]` - - The type of the input item. Always `input_file`. - - - `"input_file"` - - - `detail: Optional[Literal["auto", "low", "high"]]` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: Optional[str]` - - The content of the file to be sent to the model. - - - `file_id: Optional[str]` - - The ID of the file to be sent to the model. - - - `file_url: Optional[str]` - - The URL of the file to be sent to the model. - - - `filename: Optional[str]` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: Literal["explicit"]` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `type: Literal["function_call_output"]` - - The type of the function tool call output. Always `function_call_output`. - - - `"function_call_output"` - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The canonical name of the agent that produced this item. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `caller: Optional[Caller]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The execution context that produced this tool call. + - `mode: Literal["explicit"]` - - `class CallerDirect: …` + The breakpoint mode. Always `explicit`. - - `type: Literal["direct"]` + - `"explicit"` - The caller type. Always `direct`. + - `class BetaResponseInputFile: …` - - `"direct"` + A file input to the model. - - `class CallerProgram: …` + - `type: Literal["input_file"]` - - `caller_id: str` + The type of the input item. Always `input_file`. - The call ID of the program item that produced this tool call. + - `"input_file"` - - `type: Literal["program"]` + - `detail: Optional[Literal["auto", "low", "high"]]` - The caller type. Always `program`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `"program"` + - `"auto"` - - `created_by: Optional[str]` + - `"low"` - The identifier of the actor that created the item. + - `"high"` - - `class AgentMessage: …` + - `file_data: Optional[str]` - - `id: str` + The content of the file to be sent to the model. - The unique ID of the agent message. + - `file_id: Optional[str]` - - `author: str` + The ID of the file to be sent to the model. - The sending agent identity. + - `file_url: Optional[str]` - - `content: List[AgentMessageContent]` + The URL of the file to be sent to the model. - Encrypted content sent between agents. + - `filename: Optional[str]` - - `class BetaResponseInputText: …` + The name of the file to be sent to the model. - A text input to the model. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `class BetaResponseOutputText: …` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - A text output from the model. + - `mode: Literal["explicit"]` - - `class AgentMessageContentText: …` + The breakpoint mode. Always `explicit`. - A text content. + - `"explicit"` - - `text: str` + - `role: Literal["user", "assistant", "system", "developer"]` - - `type: Literal["text"]` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `"text"` + - `"user"` - - `class AgentMessageContentSummaryText: …` + - `"assistant"` - A summary text from the model. + - `"system"` - - `text: str` + - `"developer"` - A summary of the reasoning output from the model so far. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `type: Literal["summary_text"]` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - The type of the object. Always `summary_text`. + - `"commentary"` - - `"summary_text"` + - `"final_answer"` - - `class AgentMessageContentReasoningText: …` + - `type: Optional[Literal["message"]]` - Reasoning text from the model. + The type of the message input. Always `message`. - - `text: str` + - `"message"` - The reasoning text from the model. + - `class Message: …` - - `type: Literal["reasoning_text"]` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - The type of the reasoning text. Always `reasoning_text`. + - `content: BetaResponseInputMessageContentList` - - `"reasoning_text"` + A list of one or many input items to the model, containing different content + types. - - `class BetaResponseOutputRefusal: …` + - `class BetaResponseInputText: …` - A refusal from the model. + A text input to the model. - `class BetaResponseInputImage: …` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class AgentMessageContentComputerScreenshot: …` + - `class BetaResponseInputFile: …` - A screenshot of a computer. + A file input to the model. - - `detail: Literal["low", "high", "auto", "original"]` + - `role: Literal["user", "system", "developer"]` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The role of the message input. One of `user`, `system`, or `developer`. - - `"low"` + - `"user"` - - `"high"` + - `"system"` - - `"auto"` + - `"developer"` - - `"original"` + - `agent: Optional[MessageAgent]` - - `file_id: Optional[str]` + The agent that produced this item. - The identifier of an uploaded file that contains the screenshot. + - `agent_name: str` - - `image_url: Optional[str]` + The canonical name of the agent that produced this item. - The URL of the screenshot image. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `type: Literal["computer_screenshot"]` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"in_progress"` - - `"computer_screenshot"` + - `"completed"` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `"incomplete"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: Optional[Literal["message"]]` - - `mode: Literal["explicit"]` + The type of the message input. Always set to `message`. - The breakpoint mode. Always `explicit`. + - `"message"` - - `"explicit"` + - `class BetaResponseOutputMessage: …` - - `class BetaResponseInputFile: …` + An output message from the model. - A file input to the model. + - `id: str` - - `class AgentMessageContentEncryptedContent: …` + The unique ID of the output message. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `content: List[Content]` - - `encrypted_content: str` + The content of the output message. - Opaque encrypted content. + - `class BetaResponseOutputText: …` - - `type: Literal["encrypted_content"]` + A text output from the model. - The type of the input item. Always `encrypted_content`. + - `annotations: List[Annotation]` - - `"encrypted_content"` + The annotations of the text output. - - `recipient: str` + - `class AnnotationFileCitation: …` - The destination agent identity. + A citation to a file. - - `type: Literal["agent_message"]` + - `file_id: str` - The type of the item. Always `agent_message`. + The ID of the file. - - `"agent_message"` + - `filename: str` - - `agent: Optional[AgentMessageAgent]` + The filename of the file cited. - The agent that produced this item. + - `index: int` - - `agent_name: str` + The index of the file in the list of files. - The canonical name of the agent that produced this item. + - `type: Literal["file_citation"]` - - `class MultiAgentCall: …` + The type of the file citation. Always `file_citation`. - - `id: str` + - `"file_citation"` - The unique ID of the multi-agent call item. + - `class AnnotationURLCitation: …` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + A citation for a web resource used to generate a model response. - The multi-agent action to execute. + - `end_index: int` - - `"spawn_agent"` + The index of the last character of the URL citation in the message. - - `"interrupt_agent"` + - `start_index: int` - - `"list_agents"` + The index of the first character of the URL citation in the message. - - `"send_message"` + - `title: str` - - `"followup_task"` + The title of the web resource. - - `"wait_agent"` + - `type: Literal["url_citation"]` - - `arguments: str` + The type of the URL citation. Always `url_citation`. - The JSON string of arguments generated for the action. + - `"url_citation"` - - `call_id: str` + - `url: str` - The unique ID linking this call to its output. + The URL of the web resource. - - `type: Literal["multi_agent_call"]` + - `class AnnotationContainerFileCitation: …` - The type of the multi-agent call. Always `multi_agent_call`. + A citation for a container file used to generate a model response. - - `"multi_agent_call"` + - `container_id: str` - - `agent: Optional[MultiAgentCallAgent]` + The ID of the container file. - The agent that produced this item. + - `end_index: int` - - `agent_name: str` + The index of the last character of the container file citation in the message. - The canonical name of the agent that produced this item. + - `file_id: str` - - `class MultiAgentCallOutput: …` + The ID of the file. - - `id: str` + - `filename: str` - The unique ID of the multi-agent call output item. + The filename of the container file cited. - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `start_index: int` - The multi-agent action that produced this result. + The index of the first character of the container file citation in the message. - - `"spawn_agent"` + - `type: Literal["container_file_citation"]` - - `"interrupt_agent"` + The type of the container file citation. Always `container_file_citation`. - - `"list_agents"` + - `"container_file_citation"` - - `"send_message"` + - `class AnnotationFilePath: …` - - `"followup_task"` + A path to a file. - - `"wait_agent"` + - `file_id: str` - - `call_id: str` + The ID of the file. - The unique ID of the multi-agent call. + - `index: int` - - `output: List[BetaResponseOutputText]` + The index of the file in the list of files. - Text output returned by the multi-agent action. + - `type: Literal["file_path"]` - - `annotations: List[Annotation]` + The type of the file path. Always `file_path`. - The annotations of the text output. + - `"file_path"` - `text: str` @@ -49961,103 +60657,96 @@ print(compacted_response) The type of the output text. Always `output_text`. - - `logprobs: Optional[List[Logprob]]` - - - `type: Literal["multi_agent_call_output"]` - - The type of the multi-agent result. Always `multi_agent_call_output`. - - - `"multi_agent_call_output"` - - - `agent: Optional[MultiAgentCallOutputAgent]` - - The agent that produced this item. + - `"output_text"` - - `agent_name: str` + - `logprobs: Optional[List[Logprob]]` - The canonical name of the agent that produced this item. + - `token: str` - - `class BetaResponseFunctionWebSearch: …` + - `bytes: List[int]` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `logprob: float` - - `id: str` + - `top_logprobs: List[LogprobTopLogprob]` - The unique ID of the web search tool call. + - `token: str` - - `action: Action` + - `bytes: List[int]` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `logprob: float` - - `class ActionSearch: …` + - `class BetaResponseOutputRefusal: …` - Action type "search" - Performs a web search query. + A refusal from the model. - - `type: Literal["search"]` + - `refusal: str` - The action type. + The refusal explanation from the model. - - `"search"` + - `type: Literal["refusal"]` - - `queries: Optional[List[str]]` + The type of the refusal. Always `refusal`. - The search queries. + - `"refusal"` - - `query: Optional[str]` + - `role: Literal["assistant"]` - The search query. + The role of the output message. Always `assistant`. - - `sources: Optional[List[ActionSearchSource]]` + - `"assistant"` - The sources used in the search. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["url"]` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The type of source. Always `url`. + - `"in_progress"` - - `"url"` + - `"completed"` - - `url: str` + - `"incomplete"` - The URL of the source. + - `type: Literal["message"]` - - `class ActionOpenPage: …` + The type of the output message. Always `message`. - Action type "open_page" - Opens a specific URL from search results. + - `"message"` - - `type: Literal["open_page"]` + - `agent: Optional[Agent]` - The action type. + The agent that produced this item. - - `"open_page"` + - `agent_name: str` - - `url: Optional[str]` + The canonical name of the agent that produced this item. - The URL opened by the model. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `class ActionFindInPage: …` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"commentary"` - - `pattern: str` + - `"final_answer"` - The pattern or text to search for within the page. + - `class BetaResponseFileSearchToolCall: …` - - `type: Literal["find_in_page"]` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The action type. + - `id: str` - - `"find_in_page"` + The unique ID of the file search tool call. - - `url: str` + - `queries: List[str]` - The URL of the page searched for the pattern. + The queries used to search for files. - - `status: Literal["in_progress", "searching", "completed", "failed"]` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - The status of the web search tool call. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `"in_progress"` @@ -50065,13 +60754,15 @@ print(compacted_response) - `"completed"` + - `"incomplete"` + - `"failed"` - - `type: Literal["web_search_call"]` + - `type: Literal["file_search_call"]` - The type of the web search tool call. Always `web_search_call`. + The type of the file search tool call. Always `file_search_call`. - - `"web_search_call"` + - `"file_search_call"` - `agent: Optional[Agent]` @@ -50081,6 +60772,40 @@ print(compacted_response) The canonical name of the agent that produced this item. + - `results: Optional[List[Result]]` + + The results of the file search tool call. + + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + + 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, booleans, or numbers. + + - `str` + + - `float` + + - `bool` + + - `file_id: Optional[str]` + + The unique ID of the file. + + - `filename: Optional[str]` + + The name of the file. + + - `score: Optional[float]` + + The relevance score of the file - a value between 0 and 1. + + - `text: Optional[str]` + + The text that was retrieved from the file. + - `class BetaResponseComputerToolCall: …` A tool call to a computer use tool. See the @@ -50371,11 +61096,9 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem: …` - - - `id: str` + - `class ComputerCallOutput: …` - The unique ID of the computer call tool output. + The output of a computer tool call. - `call_id: str` @@ -50400,29 +61123,19 @@ print(compacted_response) The URL of the screenshot image. - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - - - `"completed"` - - - `"incomplete"` - - - `"failed"` - - - `"in_progress"` - - `type: Literal["computer_call_output"]` The type of the computer tool call output. Always `computer_call_output`. - `"computer_call_output"` - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + - `id: Optional[str]` - The safety checks reported by the API that have been acknowledged by the - developer. + The ID of the computer tool call output. + + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + + The safety checks reported by the API that have been acknowledged by the developer. - `id: str` @@ -50436,7 +61149,7 @@ print(compacted_response) Details about the pending safety check. - - `agent: Optional[Agent]` + - `agent: Optional[ComputerCallOutputAgent]` The agent that produced this item. @@ -50444,40 +61157,111 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The identifier of the actor that created the item. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `class BetaResponseReasoningItem: …` + - `"in_progress"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `"completed"` + + - `"incomplete"` + + - `class BetaResponseFunctionWebSearch: …` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: str` - The unique identifier of the reasoning content. + The unique ID of the web search tool call. - - `summary: List[Summary]` + - `action: Action` - Reasoning summary content. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `text: str` + - `class ActionSearch: …` - A summary of the reasoning output from the model so far. + Action type "search" - Performs a web search query. - - `type: Literal["summary_text"]` + - `type: Literal["search"]` - The type of the object. Always `summary_text`. + The action type. - - `"summary_text"` + - `"search"` - - `type: Literal["reasoning"]` + - `queries: Optional[List[str]]` - The type of the object. Always `reasoning`. + The search queries. - - `"reasoning"` + - `query: Optional[str]` + + The search query. + + - `sources: Optional[List[ActionSearchSource]]` + + The sources used in the search. + + - `type: Literal["url"]` + + The type of source. Always `url`. + + - `"url"` + + - `url: str` + + The URL of the source. + + - `class ActionOpenPage: …` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: Literal["open_page"]` + + The action type. + + - `"open_page"` + + - `url: Optional[str]` + + The URL opened by the model. + + - `class ActionFindInPage: …` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: str` + + The pattern or text to search for within the page. + + - `type: Literal["find_in_page"]` + + The action type. + + - `"find_in_page"` + + - `url: str` + + The URL of the page searched for the pattern. + + - `status: Literal["in_progress", "searching", "completed", "failed"]` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: Literal["web_search_call"]` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` - `agent: Optional[Agent]` @@ -50487,24 +61271,64 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `content: Optional[List[Content]]` + - `class BetaResponseFunctionToolCall: …` - Reasoning text content. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `text: str` + - `arguments: str` - The reasoning text from the model. + A JSON string of the arguments to pass to the function. - - `type: Literal["reasoning_text"]` + - `call_id: str` - The type of the reasoning text. Always `reasoning_text`. + The unique ID of the function tool call generated by the model. - - `"reasoning_text"` + - `name: str` - - `encrypted_content: Optional[str]` + The name of the function to run. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `type: Literal["function_call"]` + + The type of the function tool call. Always `function_call`. + + - `"function_call"` + + - `id: Optional[str]` + + The unique ID of the function tool call. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `namespace: Optional[str]` + + The namespace of the function to run. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` @@ -50517,31 +61341,145 @@ print(compacted_response) - `"incomplete"` - - `class Program: …` - - - `id: str` + - `class FunctionCallOutput: …` - The unique ID of the program item. + The output of a function tool call. - `call_id: str` - The stable call ID of the program item. + The unique ID of the function tool call generated by the model. - - `code: str` + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - The JavaScript source executed by programmatic tool calling. + Text, image, or file output of the function tool call. - - `fingerprint: str` + - `str` - Opaque program replay fingerprint that must be round-tripped. + A JSON string of the output of the function tool call. - - `type: Literal["program"]` + - `List[BetaResponseFunctionCallOutputItem]` - The type of the item. Always `program`. + - `class BetaResponseInputTextContent: …` - - `"program"` + A text input to the model. - - `agent: Optional[ProgramAgent]` + - `text: str` + + The text input to the model. + + - `type: Literal["input_text"]` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputImageContent: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: Literal["input_image"]` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `detail: Optional[Literal["low", "high", "auto", "original"]]` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `image_url: Optional[str]` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputFileContent: …` + + A file input to the model. + + - `type: Literal["input_file"]` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: Optional[Literal["auto", "low", "high"]]` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: Optional[str]` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `file_url: Optional[str]` + + The URL of the file to be sent to the model. + + - `filename: Optional[str]` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `type: Literal["function_call_output"]` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: Optional[str]` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: Optional[FunctionCallOutputAgent]` The agent that produced this item. @@ -50549,35 +61487,89 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ProgramOutput: …` + - `caller: Optional[FunctionCallOutputCaller]` - - `id: str` + The execution context that produced this tool call. - The unique ID of the program output item. + - `class FunctionCallOutputCallerDirect: …` - - `call_id: str` + - `type: Literal["direct"]` - The call ID of the program item. + The caller type. Always `direct`. - - `result: str` + - `"direct"` - The result produced by the program item. + - `class FunctionCallOutputCallerProgram: …` - - `status: Literal["completed", "incomplete"]` + - `caller_id: str` - The terminal status of the program output item. + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"in_progress"` - `"completed"` - `"incomplete"` - - `type: Literal["program_output"]` + - `class AgentMessage: …` - The type of the item. Always `program_output`. + A message routed between agents. - - `"program_output"` + - `author: str` - - `agent: Optional[ProgramOutputAgent]` + The sending agent identity. + + - `content: List[AgentMessageContent]` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent: …` + + A text input to the model. + + - `class BetaResponseInputImageContent: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `class AgentMessageContentEncryptedContent: …` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: str` + + Opaque encrypted content. + + - `type: Literal["encrypted_content"]` + + The type of the input item. Always `encrypted_content`. + + - `"encrypted_content"` + + - `recipient: str` + + The destination agent identity. + + - `type: Literal["agent_message"]` + + The item type. Always `agent_message`. + + - `"agent_message"` + + - `id: Optional[str]` + + The unique ID of this agent message item. + + - `agent: Optional[AgentMessageAgent]` The agent that produced this item. @@ -50585,45 +61577,173 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall: …` + - `class MultiAgentCall: …` - - `id: str` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - The unique ID of the tool search call item. + The multi-agent action that was executed. - - `arguments: object` + - `"spawn_agent"` - Arguments used for the tool search call. + - `"interrupt_agent"` - - `call_id: Optional[str]` + - `"list_agents"` - The unique ID of the tool search call generated by the model. + - `"send_message"` - - `execution: Literal["server", "client"]` + - `"followup_task"` - Whether tool search was executed by the server or by the client. + - `"wait_agent"` - - `"server"` + - `arguments: str` - - `"client"` + The action arguments as a JSON string. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `call_id: str` - The status of the tool search call item that was recorded. + The unique ID linking this call to its output. - - `"in_progress"` + - `type: Literal["multi_agent_call"]` - - `"completed"` + The item type. Always `multi_agent_call`. - - `"incomplete"` + - `"multi_agent_call"` - - `type: Literal["tool_search_call"]` + - `id: Optional[str]` - The type of the item. Always `tool_search_call`. + The unique ID of this multi-agent call. - - `"tool_search_call"` + - `agent: Optional[MultiAgentCallAgent]` - - `agent: Optional[Agent]` + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCallOutput: …` + + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: str` + + The unique ID of the multi-agent call. + + - `output: List[MultiAgentCallOutputOutput]` + + Text output returned by the multi-agent action. + + - `text: str` + + The text content. + + - `type: Literal["output_text"]` + + The content type. Always `output_text`. + + - `"output_text"` + + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + + Citations associated with the text content. + + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + + - `file_id: str` + + The ID of the file. + + - `filename: str` + + The filename of the file cited. + + - `index: int` + + The index of the file in the list of files. + + - `type: Literal["file_citation"]` + + The citation type. Always `file_citation`. + + - `"file_citation"` + + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + + - `end_index: int` + + The index of the last character of the citation in the message. + + - `start_index: int` + + The index of the first character of the citation in the message. + + - `title: str` + + The title of the cited resource. + + - `type: Literal["url_citation"]` + + The citation type. Always `url_citation`. + + - `"url_citation"` + + - `url: str` + + The URL of the cited resource. + + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + + - `container_id: str` + + The ID of the container. + + - `end_index: int` + + The index of the last character of the citation in the message. + + - `file_id: str` + + The ID of the container file. + + - `filename: str` + + The filename of the container file cited. + + - `start_index: int` + + The index of the first character of the citation in the message. + + - `type: Literal["container_file_citation"]` + + The citation type. Always `container_file_citation`. + + - `"container_file_citation"` + + - `type: Literal["multi_agent_call_output"]` + + The item type. Always `multi_agent_call_output`. + + - `"multi_agent_call_output"` + + - `id: Optional[str]` + + The unique ID of this multi-agent call output. + + - `agent: Optional[MultiAgentCallOutputAgent]` The agent that produced this item. @@ -50631,21 +61751,35 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` + - `class ToolSearchCall: …` - The identifier of the actor that created the item. + - `arguments: object` - - `class BetaResponseToolSearchOutputItem: …` + The arguments supplied to the tool search call. - - `id: str` + - `type: Literal["tool_search_call"]` - The unique ID of the tool search output item. + The item type. Always `tool_search_call`. + + - `"tool_search_call"` + + - `id: Optional[str]` + + The unique ID of this tool search call. + + - `agent: Optional[ToolSearchCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. - `call_id: Optional[str]` The unique ID of the tool search call generated by the model. - - `execution: Literal["server", "client"]` + - `execution: Optional[Literal["server", "client"]]` Whether tool search was executed by the server or by the client. @@ -50653,9 +61787,9 @@ print(compacted_response) - `"client"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the tool search output item that was recorded. + The status of the tool search call. - `"in_progress"` @@ -50663,9 +61797,11 @@ print(compacted_response) - `"incomplete"` + - `class BetaResponseToolSearchOutputItemParam: …` + - `tools: List[BetaTool]` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool: …` @@ -50764,7 +61900,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -50774,7 +61910,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `class FiltersCompoundFilter: …` @@ -50821,7 +61961,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -50831,7 +61971,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `object` @@ -51755,10 +62899,14 @@ print(compacted_response) - `type: Literal["tool_search_output"]` - The type of the item. Always `tool_search_output`. + The item type. Always `tool_search_output`. - `"tool_search_output"` + - `id: Optional[str]` + + The unique ID of this tool search output. + - `agent: Optional[Agent]` The agent that produced this item. @@ -51767,39 +62915,39 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` + - `call_id: Optional[str]` - The identifier of the actor that created the item. + The unique ID of the tool search call generated by the model. - - `class AdditionalTools: …` + - `execution: Optional[Literal["server", "client"]]` - - `id: str` + Whether tool search was executed by the server or by the client. - The unique ID of the additional tools item. + - `"server"` - - `role: Literal["unknown", "user", "assistant", 5 more]` + - `"client"` - The role that provided the additional tools. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"unknown"` + The status of the tool search output. - - `"user"` + - `"in_progress"` - - `"assistant"` + - `"completed"` - - `"system"` + - `"incomplete"` - - `"critic"` + - `class AdditionalTools: …` - - `"discriminator"` + - `role: Literal["developer"]` - - `"developer"` + The role that provided the additional tools. Only `developer` is supported. - - `"tool"` + - `"developer"` - `tools: List[BetaTool]` - The additional tool definitions made available at this item. + A list of additional tools made available at this item. - `class BetaFunctionTool: …` @@ -51867,10 +63015,14 @@ print(compacted_response) - `type: Literal["additional_tools"]` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. - `"additional_tools"` + - `id: Optional[str]` + + The unique ID of this additional tools item. + - `agent: Optional[AdditionalToolsAgent]` The agent that produced this item. @@ -51879,17 +63031,82 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem: …` + - `class BetaResponseReasoningItem: …` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: str` - The unique ID of the compaction item. + The unique identifier of the reasoning content. + + - `summary: List[Summary]` + + Reasoning summary content. + + - `text: str` + + A summary of the reasoning output from the model so far. + + - `type: Literal["summary_text"]` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `type: Literal["reasoning"]` + + The type of the object. Always `reasoning`. + + - `"reasoning"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `content: Optional[List[Content]]` + + Reasoning text content. + + - `text: str` + + The reasoning text from the model. + + - `type: Literal["reasoning_text"]` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: Optional[str]` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class BetaResponseCompactionItemParam: …` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `encrypted_content: str` - The encrypted content that was produced by compaction. + The encrypted content of the compaction summary. - `type: Literal["compaction"]` @@ -51897,6 +63114,10 @@ print(compacted_response) - `"compaction"` + - `id: Optional[str]` + + The ID of the compaction item. + - `agent: Optional[Agent]` The agent that produced this item. @@ -51905,10 +63126,6 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - `class ImageGenerationCall: …` An image generation request made by the model. @@ -52126,75 +63343,41 @@ print(compacted_response) - `"incomplete"` - - `class BetaResponseFunctionShellToolCall: …` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: str` + - `class ShellCall: …` - The unique ID of the shell tool call. Populated when this item is returned via API. + A tool representing a request to execute one or more shell commands. - - `action: Action` + - `action: ShellCallAction` The shell commands and limits that describe how to run the tool call. - `commands: List[str]` + Ordered shell commands for the execution environment to run. + - `max_output_length: Optional[int]` - Optional maximum number of characters to return from each command. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `timeout_ms: Optional[int]` - Optional timeout in milliseconds for the commands. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - `call_id: str` The unique ID of the shell tool call generated by the model. - - `environment: Optional[Environment]` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment: …` - - Represents the use of a local environment to perform shell actions. - - - `type: Literal["local"]` - - The environment type. Always `local`. - - - `"local"` - - - `class BetaResponseContainerReference: …` - - Represents a container created with /v1/containers. - - - `container_id: str` - - - `type: Literal["container_reference"]` - - The environment type. Always `container_reference`. - - - `"container_reference"` - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `type: Literal["shell_call"]` The type of the item. Always `shell_call`. - `"shell_call"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: Optional[ShellCallAgent]` The agent that produced this item. @@ -52202,17 +63385,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ShellCallCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ShellCallCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ShellCallCallerProgram: …` - `caller_id: str` @@ -52220,37 +63405,45 @@ print(compacted_response) - `type: Literal["program"]` + The caller type. Always `program`. + - `"program"` - - `created_by: Optional[str]` + - `environment: Optional[ShellCallEnvironment]` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `class BetaResponseFunctionShellToolCallOutput: …` + - `class BetaLocalEnvironment: …` - The output of a shell tool call that was emitted. + - `class BetaContainerReference: …` - - `id: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The unique ID of the shell call output. Populated when this item is returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `call_id: str` + - `"in_progress"` - The unique ID of the shell tool call generated by the model. + - `"completed"` - - `max_output_length: Optional[int]` + - `"incomplete"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `class ShellCallOutput: …` - - `output: List[Output]` + The streamed output items emitted by a shell tool call. - An array of shell call output contents + - `call_id: str` - - `outcome: OutputOutcome` + The unique ID of the shell tool call generated by the model. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `output: List[BetaResponseFunctionShellCallOutputContent]` - - `class OutputOutcomeTimeout: …` + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: Outcome` + + The exit or timeout outcome associated with this shell call. + + - `class OutcomeTimeout: …` Indicates that the shell call exceeded its configured time limit. @@ -52260,13 +63453,13 @@ print(compacted_response) - `"timeout"` - - `class OutputOutcomeExit: …` + - `class OutcomeExit: …` Indicates that the shell commands finished and returned an exit code. - `exit_code: int` - Exit code from the shell process. + The exit code returned by the shell process. - `type: Literal["exit"]` @@ -52276,33 +63469,23 @@ print(compacted_response) - `stderr: str` - The standard error output that was captured. + Captured stderr output for the shell call. - `stdout: str` - The standard output that was captured. - - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` + Captured stdout output for the shell call. - `type: Literal["shell_call_output"]` - The type of the shell call output. Always `shell_call_output`. + The type of the item. Always `shell_call_output`. - `"shell_call_output"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: Optional[ShellCallOutputAgent]` The agent that produced this item. @@ -52310,17 +63493,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ShellCallOutputCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ShellCallOutputCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ShellCallOutputCallerProgram: …` - `caller_id: str` @@ -52328,75 +63513,83 @@ print(compacted_response) - `type: Literal["program"]` + The caller type. Always `program`. + - `"program"` - - `created_by: Optional[str]` + - `max_output_length: Optional[int]` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseApplyPatchToolCall: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A tool call that applies file diffs by creating, deleting, or updating files. + The status of the shell call output. - - `id: str` + - `"in_progress"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"completed"` + + - `"incomplete"` + + - `class ApplyPatchCall: …` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: str` The unique ID of the apply patch tool call generated by the model. - - `operation: Operation` + - `operation: ApplyPatchCallOperation` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - - `class OperationCreateFile: …` + - `class ApplyPatchCallOperationCreateFile: …` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `diff: str` - Diff to apply. + Unified diff content to apply when creating the file. - `path: str` - Path of the file to create. + Path of the file to create relative to the workspace root. - `type: Literal["create_file"]` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `"create_file"` - - `class OperationDeleteFile: …` + - `class ApplyPatchCallOperationDeleteFile: …` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `path: str` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `type: Literal["delete_file"]` - Delete the specified file. + The operation type. Always `delete_file`. - `"delete_file"` - - `class OperationUpdateFile: …` + - `class ApplyPatchCallOperationUpdateFile: …` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `diff: str` - Diff to apply. + Unified diff content to apply to the existing file. - `path: str` - Path of the file to update. + Path of the file to update relative to the workspace root. - `type: Literal["update_file"]` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `"update_file"` @@ -52414,7 +63607,11 @@ print(compacted_response) - `"apply_patch_call"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallAgent]` The agent that produced this item. @@ -52422,17 +63619,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ApplyPatchCallCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ApplyPatchCallCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ApplyPatchCallCallerProgram: …` - `caller_id: str` @@ -52440,19 +63639,13 @@ print(compacted_response) - `type: Literal["program"]` - - `"program"` - - - `created_by: Optional[str]` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput: …` + The caller type. Always `program`. - The output emitted by an apply patch tool call. + - `"program"` - - `id: str` + - `class ApplyPatchCallOutput: …` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The streamed output emitted by an apply patch tool call. - `call_id: str` @@ -52472,7 +63665,11 @@ print(compacted_response) - `"apply_patch_call_output"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallOutputAgent]` The agent that produced this item. @@ -52480,17 +63677,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ApplyPatchCallOutputCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ApplyPatchCallOutputCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ApplyPatchCallOutputCallerProgram: …` - `caller_id: str` @@ -52498,76 +63697,13 @@ print(compacted_response) - `type: Literal["program"]` - - `"program"` - - - `created_by: Optional[str]` - - The ID of the entity that created this tool call output. - - - `output: Optional[str]` - - Optional textual output returned by the apply patch tool. - - - `class McpCall: …` - - An invocation of a tool on an MCP server. - - - `id: str` - - The unique ID of the tool call. - - - `arguments: str` - - A JSON string of the arguments passed to the tool. - - - `name: str` - - The name of the tool that was run. - - - `server_label: str` - - The label of the MCP server running the tool. - - - `type: Literal["mcp_call"]` - - The type of the item. Always `mcp_call`. - - - `"mcp_call"` - - - `agent: Optional[McpCallAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `approval_request_id: Optional[str]` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: Optional[str]` + The caller type. Always `program`. - The error from the tool call, if any. + - `"program"` - `output: Optional[str]` - The output from the tool call. - - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"calling"` - - - `"failed"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `class McpListTools: …` @@ -52657,10 +63793,6 @@ print(compacted_response) A response to an MCP approval request. - - `id: str` - - The unique ID of the approval response - - `approval_request_id: str` The ID of the approval request being answered. @@ -52675,6 +63807,10 @@ print(compacted_response) - `"mcp_approval_response"` + - `id: Optional[str]` + + The unique ID of the approval response + - `agent: Optional[McpApprovalResponseAgent]` The agent that produced this item. @@ -52687,33 +63823,33 @@ print(compacted_response) Optional reason for the decision. - - `class BetaResponseCustomToolCall: …` + - `class McpCall: …` - A call to a custom tool created by the model. + An invocation of a tool on an MCP server. - - `call_id: str` + - `id: str` - An identifier used to map this custom tool call to a tool call output. + The unique ID of the tool call. - - `input: str` + - `arguments: str` - The input for the custom tool call generated by the model. + A JSON string of the arguments passed to the tool. - `name: str` - The name of the custom tool being called. + The name of the tool that was run. - - `type: Literal["custom_tool_call"]` + - `server_label: str` - The type of the custom tool call. Always `custom_tool_call`. + The label of the MCP server running the tool. - - `"custom_tool_call"` + - `type: Literal["mcp_call"]` - - `id: Optional[str]` + The type of the item. Always `mcp_call`. - The unique ID of the custom tool call in the OpenAI platform. + - `"mcp_call"` - - `agent: Optional[Agent]` + - `agent: Optional[McpCallAgent]` The agent that produced this item. @@ -52721,1845 +63857,1856 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `approval_request_id: Optional[str]` - The execution context that produced this tool call. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `class CallerDirect: …` + - `error: Optional[str]` - - `type: Literal["direct"]` + The error from the tool call, if any. - - `"direct"` + - `output: Optional[str]` - - `class CallerProgram: …` + The output from the tool call. - - `caller_id: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - The call ID of the program item that produced this tool call. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `type: Literal["program"]` + - `"in_progress"` - - `"program"` + - `"completed"` - - `namespace: Optional[str]` + - `"incomplete"` - The namespace of the custom tool being called. + - `"calling"` - - `class BetaResponseCustomToolCallOutputItem: …` + - `"failed"` + + - `class BetaResponseCustomToolCallOutput: …` The output of a custom tool call from your code, being sent back to the model. - - `id: str` + - `call_id: str` - The unique ID of the custom tool call output item. + The call ID, used to map this custom tool call output to a custom tool call. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `output: Union[str, List[OutputOutputContentList]]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"in_progress"` + - `str` - - `"completed"` + A string of the output of the custom tool call. - - `"incomplete"` + - `List[OutputOutputContentList]` - - `created_by: Optional[str]` + Text, image, or file output of the custom tool call. - The identifier of the actor that created the item. + - `class BetaResponseInputText: …` - - `usage: BetaResponseUsage` + A text input to the model. - Token accounting for the compaction pass, including cached, reasoning, and total tokens. + - `class BetaResponseInputImage: …` - - `input_tokens: int` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The number of input tokens. + - `class BetaResponseInputFile: …` - - `input_tokens_details: InputTokensDetails` + A file input to the model. - A detailed breakdown of the input tokens. + - `type: Literal["custom_tool_call_output"]` - - `cache_write_tokens: int` + The type of the custom tool call output. Always `custom_tool_call_output`. - The number of input tokens that were written to the cache. + - `"custom_tool_call_output"` - - `cached_tokens: int` + - `id: Optional[str]` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The unique ID of the custom tool call output in the OpenAI platform. - - `output_tokens: int` + - `agent: Optional[Agent]` - The number of output tokens. + The agent that produced this item. - - `output_tokens_details: OutputTokensDetails` + - `agent_name: str` - A detailed breakdown of the output tokens. + The canonical name of the agent that produced this item. - - `reasoning_tokens: int` + - `caller: Optional[Caller]` - The number of reasoning tokens. + The execution context that produced this tool call. - - `total_tokens: int` + - `class CallerDirect: …` - The total number of tokens used. + - `type: Literal["direct"]` -### Beta Computer Action + The caller type. Always `direct`. -- `BetaComputerAction` + - `"direct"` - A click action. + - `class CallerProgram: …` - - `class Click: …` + - `caller_id: str` - A click action. + The call ID of the program item that produced this tool call. - - `button: Literal["left", "right", "wheel", 2 more]` + - `type: Literal["program"]` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The caller type. Always `program`. - - `"left"` + - `"program"` - - `"right"` + - `class BetaResponseCustomToolCall: …` - - `"wheel"` + A call to a custom tool created by the model. - - `"back"` + - `call_id: str` - - `"forward"` + An identifier used to map this custom tool call to a tool call output. - - `type: Literal["click"]` + - `input: str` - Specifies the event type. For a click action, this property is always `click`. + The input for the custom tool call generated by the model. - - `"click"` + - `name: str` - - `x: int` + The name of the custom tool being called. - The x-coordinate where the click occurred. + - `type: Literal["custom_tool_call"]` - - `y: int` + The type of the custom tool call. Always `custom_tool_call`. - The y-coordinate where the click occurred. + - `"custom_tool_call"` - - `keys: Optional[List[str]]` + - `id: Optional[str]` - The keys being held while clicking. + The unique ID of the custom tool call in the OpenAI platform. - - `class DoubleClick: …` + - `agent: Optional[Agent]` - A double click action. + The agent that produced this item. - - `keys: Optional[List[str]]` + - `agent_name: str` - The keys being held while double-clicking. + The canonical name of the agent that produced this item. - - `type: Literal["double_click"]` + - `caller: Optional[Caller]` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The execution context that produced this tool call. - - `"double_click"` + - `class CallerDirect: …` - - `x: int` + - `type: Literal["direct"]` - The x-coordinate where the double click occurred. + - `"direct"` - - `y: int` + - `class CallerProgram: …` - The y-coordinate where the double click occurred. + - `caller_id: str` - - `class Drag: …` + The call ID of the program item that produced this tool call. - A drag action. + - `type: Literal["program"]` - - `path: List[DragPath]` + - `"program"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `namespace: Optional[str]` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The namespace of the custom tool being called. - - `x: int` + - `class CompactionTrigger: …` - The x-coordinate. + Compacts the current context. Must be the final input item. - - `y: int` + - `type: Literal["compaction_trigger"]` - The y-coordinate. + The type of the item. Always `compaction_trigger`. - - `type: Literal["drag"]` + - `"compaction_trigger"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `agent: Optional[CompactionTriggerAgent]` - - `"drag"` + The agent that produced this item. - - `keys: Optional[List[str]]` + - `agent_name: str` - The keys being held while dragging the mouse. + The canonical name of the agent that produced this item. - - `class Keypress: …` + - `class ItemReference: …` - A collection of keypresses the model would like to perform. + An internal identifier for an item to reference. - - `keys: List[str]` + - `id: str` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The ID of the item to reference. - - `type: Literal["keypress"]` + - `agent: Optional[ItemReferenceAgent]` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The agent that produced this item. - - `"keypress"` + - `agent_name: str` - - `class Move: …` + The canonical name of the agent that produced this item. - A mouse move action. + - `type: Optional[Literal["item_reference"]]` - - `type: Literal["move"]` + The type of item to reference. Always `item_reference`. - Specifies the event type. For a move action, this property is always set to `move`. + - `"item_reference"` - - `"move"` + - `class Program: …` - - `x: int` + - `id: str` - The x-coordinate to move to. + The unique ID of this program item. - - `y: int` + - `call_id: str` - The y-coordinate to move to. + The stable call ID of the program item. - - `keys: Optional[List[str]]` + - `code: str` - The keys being held while moving the mouse. + The JavaScript source executed by programmatic tool calling. - - `class Screenshot: …` + - `fingerprint: str` - A screenshot action. + Opaque program replay fingerprint that must be round-tripped. - - `type: Literal["screenshot"]` + - `type: Literal["program"]` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The item type. Always `program`. - - `"screenshot"` + - `"program"` - - `class Scroll: …` + - `agent: Optional[ProgramAgent]` - A scroll action. + The agent that produced this item. - - `scroll_x: int` + - `agent_name: str` - The horizontal scroll distance. + The canonical name of the agent that produced this item. - - `scroll_y: int` + - `class ProgramOutput: …` - The vertical scroll distance. + - `id: str` - - `type: Literal["scroll"]` + The unique ID of this program output item. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `call_id: str` - - `"scroll"` + The call ID of the program item. - - `x: int` + - `result: str` - The x-coordinate where the scroll occurred. + The result produced by the program item. - - `y: int` + - `status: Literal["completed", "incomplete"]` - The y-coordinate where the scroll occurred. + The terminal status of the program output. - - `keys: Optional[List[str]]` + - `"completed"` - The keys being held while scrolling. + - `"incomplete"` - - `class Type: …` + - `type: Literal["program_output"]` - An action to type in text. + The item type. Always `program_output`. - - `text: str` + - `"program_output"` - The text to type. + - `agent: Optional[ProgramOutputAgent]` - - `type: Literal["type"]` + The agent that produced this item. - Specifies the event type. For a type action, this property is always set to `type`. + - `agent_name: str` - - `"type"` + The canonical name of the agent that produced this item. - - `class Wait: …` + - `metadata: Optional[Dict[str, str]]` - A wait action. + 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. - - `type: Literal["wait"]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` - - `"wait"` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. -### Beta Computer Action List + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` -- `List[BetaComputerAction]` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"gpt-5.6-sol"` - - `class Click: …` + - `"gpt-5.6-terra"` - A click action. + - `"gpt-5.6-luna"` - - `button: Literal["left", "right", "wheel", 2 more]` + - `"gpt-5.4"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"gpt-5.4-mini"` - - `"left"` + - `"gpt-5.4-nano"` - - `"right"` + - `"gpt-5.4-mini-2026-03-17"` - - `"wheel"` + - `"gpt-5.4-nano-2026-03-17"` - - `"back"` + - `"gpt-5.3-chat-latest"` - - `"forward"` + - `"gpt-5.2"` - - `type: Literal["click"]` + - `"gpt-5.2-2025-12-11"` - Specifies the event type. For a click action, this property is always `click`. + - `"gpt-5.2-chat-latest"` - - `"click"` + - `"gpt-5.2-pro"` - - `x: int` + - `"gpt-5.2-pro-2025-12-11"` - The x-coordinate where the click occurred. + - `"gpt-5.1"` - - `y: int` + - `"gpt-5.1-2025-11-13"` - The y-coordinate where the click occurred. + - `"gpt-5.1-codex"` - - `keys: Optional[List[str]]` + - `"gpt-5.1-mini"` - The keys being held while clicking. + - `"gpt-5.1-chat-latest"` - - `class DoubleClick: …` + - `"gpt-5"` - A double click action. + - `"gpt-5-mini"` - - `keys: Optional[List[str]]` + - `"gpt-5-nano"` - The keys being held while double-clicking. + - `"gpt-5-2025-08-07"` - - `type: Literal["double_click"]` + - `"gpt-5-mini-2025-08-07"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"gpt-5-nano-2025-08-07"` - - `"double_click"` + - `"gpt-5-chat-latest"` - - `x: int` + - `"gpt-4.1"` - The x-coordinate where the double click occurred. + - `"gpt-4.1-mini"` - - `y: int` + - `"gpt-4.1-nano"` - The y-coordinate where the double click occurred. + - `"gpt-4.1-2025-04-14"` - - `class Drag: …` + - `"gpt-4.1-mini-2025-04-14"` - A drag action. + - `"gpt-4.1-nano-2025-04-14"` - - `path: List[DragPath]` + - `"o4-mini"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"o4-mini-2025-04-16"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"o3"` - - `x: int` + - `"o3-2025-04-16"` - The x-coordinate. + - `"o3-mini"` - - `y: int` + - `"o3-mini-2025-01-31"` - The y-coordinate. + - `"o1"` - - `type: Literal["drag"]` + - `"o1-2024-12-17"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `"o1-preview"` - - `"drag"` + - `"o1-preview-2024-09-12"` - - `keys: Optional[List[str]]` + - `"o1-mini"` - The keys being held while dragging the mouse. + - `"o1-mini-2024-09-12"` - - `class Keypress: …` + - `"gpt-4o"` - A collection of keypresses the model would like to perform. + - `"gpt-4o-2024-11-20"` - - `keys: List[str]` + - `"gpt-4o-2024-08-06"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"gpt-4o-2024-05-13"` - - `type: Literal["keypress"]` + - `"gpt-4o-audio-preview"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"gpt-4o-audio-preview-2024-10-01"` - - `"keypress"` + - `"gpt-4o-audio-preview-2024-12-17"` - - `class Move: …` + - `"gpt-4o-audio-preview-2025-06-03"` - A mouse move action. + - `"gpt-4o-mini-audio-preview"` - - `type: Literal["move"]` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - Specifies the event type. For a move action, this property is always set to `move`. + - `"gpt-4o-search-preview"` - - `"move"` + - `"gpt-4o-mini-search-preview"` - - `x: int` + - `"gpt-4o-search-preview-2025-03-11"` - The x-coordinate to move to. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `y: int` + - `"chatgpt-4o-latest"` - The y-coordinate to move to. + - `"codex-mini-latest"` - - `keys: Optional[List[str]]` + - `"gpt-4o-mini"` - The keys being held while moving the mouse. + - `"gpt-4o-mini-2024-07-18"` - - `class Screenshot: …` + - `"gpt-4-turbo"` - A screenshot action. + - `"gpt-4-turbo-2024-04-09"` - - `type: Literal["screenshot"]` + - `"gpt-4-0125-preview"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"gpt-4-turbo-preview"` - - `"screenshot"` + - `"gpt-4-1106-preview"` - - `class Scroll: …` + - `"gpt-4-vision-preview"` - A scroll action. + - `"gpt-4"` - - `scroll_x: int` + - `"gpt-4-0314"` - The horizontal scroll distance. + - `"gpt-4-0613"` - - `scroll_y: int` + - `"gpt-4-32k"` - The vertical scroll distance. + - `"gpt-4-32k-0314"` - - `type: Literal["scroll"]` + - `"gpt-4-32k-0613"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"gpt-3.5-turbo"` - - `"scroll"` + - `"gpt-3.5-turbo-16k"` - - `x: int` + - `"gpt-3.5-turbo-0301"` - The x-coordinate where the scroll occurred. + - `"gpt-3.5-turbo-0613"` - - `y: int` + - `"gpt-3.5-turbo-1106"` - The y-coordinate where the scroll occurred. + - `"gpt-3.5-turbo-0125"` - - `keys: Optional[List[str]]` + - `"gpt-3.5-turbo-16k-0613"` - The keys being held while scrolling. + - `"o1-pro"` - - `class Type: …` + - `"o1-pro-2025-03-19"` - An action to type in text. + - `"o3-pro"` - - `text: str` + - `"o3-pro-2025-06-10"` - The text to type. + - `"o3-deep-research"` - - `type: Literal["type"]` + - `"o3-deep-research-2025-06-26"` - Specifies the event type. For a type action, this property is always set to `type`. + - `"o4-mini-deep-research"` - - `"type"` + - `"o4-mini-deep-research-2025-06-26"` - - `class Wait: …` + - `"computer-use-preview"` - A wait action. + - `"computer-use-preview-2025-03-11"` - - `type: Literal["wait"]` + - `"gpt-5-codex"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"gpt-5-pro"` - - `"wait"` + - `"gpt-5-pro-2025-10-06"` -### Beta Computer Tool + - `"gpt-5.1-codex-max"` -- `class BetaComputerTool: …` + - `str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `object: Literal["response"]` - - `type: Literal["computer"]` + The object type of this resource - always set to `response`. - The type of the computer tool. Always `computer`. + - `"response"` - - `"computer"` + - `output: List[BetaResponseOutputItem]` -### Beta Computer Use Preview Tool + An array of content items generated by the model. -- `class BetaComputerUsePreviewTool: …` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. + + - `class BetaResponseOutputMessage: …` + + An output message from the model. + + - `class BetaResponseFileSearchToolCall: …` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `class BetaResponseFunctionToolCall: …` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `class BetaResponseFunctionToolCallOutputItem: …` + + - `id: str` + + The unique ID of the function call tool output. + + - `call_id: str` + + The unique ID of the function tool call generated by the model. + + - `output: Union[str, List[OutputOutputContentList]]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The output from the function call generated by your code. + Can be a string or an list of output content. - - `display_height: int` + - `str` - The height of the computer display. + A string of the output of the function call. - - `display_width: int` + - `List[OutputOutputContentList]` - The width of the computer display. + Text, image, or file output of the function call. - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `class BetaResponseInputText: …` - The type of computer environment to control. + A text input to the model. - - `"windows"` + - `class BetaResponseInputImage: …` - - `"mac"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"linux"` + - `class BetaResponseInputFile: …` - - `"ubuntu"` + A file input to the model. - - `"browser"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["computer_use_preview"]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the computer use tool. Always `computer_use_preview`. + - `"in_progress"` - - `"computer_use_preview"` + - `"completed"` -### Beta Container Auto + - `"incomplete"` -- `class BetaContainerAuto: …` + - `type: Literal["function_call_output"]` - - `type: Literal["container_auto"]` + The type of the function tool call output. Always `function_call_output`. - Automatically creates a container for this request + - `"function_call_output"` - - `"container_auto"` + - `agent: Optional[Agent]` - - `file_ids: Optional[List[str]]` + The agent that produced this item. - An optional list of uploaded files to make available to your code. + - `agent_name: str` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + The canonical name of the agent that produced this item. - The memory limit for the container. + - `caller: Optional[Caller]` - - `"1g"` + The execution context that produced this tool call. - - `"4g"` + - `class CallerDirect: …` - - `"16g"` + - `type: Literal["direct"]` - - `"64g"` + The caller type. Always `direct`. - - `network_policy: Optional[NetworkPolicy]` + - `"direct"` - Network access policy for the container. + - `class CallerProgram: …` - - `class BetaContainerNetworkPolicyDisabled: …` + - `caller_id: str` - - `type: Literal["disabled"]` + The call ID of the program item that produced this tool call. - Disable outbound network access. Always `disabled`. + - `type: Literal["program"]` - - `"disabled"` + The caller type. Always `program`. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `"program"` - - `allowed_domains: List[str]` + - `created_by: Optional[str]` - A list of allowed domains when type is `allowlist`. + The identifier of the actor that created the item. - - `type: Literal["allowlist"]` + - `class AgentMessage: …` - Allow outbound network access only to specified domains. Always `allowlist`. + - `id: str` - - `"allowlist"` + The unique ID of the agent message. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `author: str` - Optional domain-scoped secrets for allowlisted domains. + The sending agent identity. - - `domain: str` + - `content: List[AgentMessageContent]` - The domain associated with the secret. + Encrypted content sent between agents. - - `name: str` + - `class BetaResponseInputText: …` - The name of the secret to inject for the domain. + A text input to the model. - - `value: str` + - `class BetaResponseOutputText: …` - The secret value to inject for the domain. + A text output from the model. - - `skills: Optional[List[Skill]]` + - `class AgentMessageContentText: …` - An optional list of skills referenced by id or inline data. + A text content. - - `class BetaSkillReference: …` + - `text: str` - - `skill_id: str` + - `type: Literal["text"]` - The ID of the referenced skill. + - `"text"` - - `type: Literal["skill_reference"]` + - `class AgentMessageContentSummaryText: …` - References a skill created with the /v1/skills endpoint. + A summary text from the model. - - `"skill_reference"` + - `text: str` - - `version: Optional[str]` + A summary of the reasoning output from the model so far. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `type: Literal["summary_text"]` - - `class BetaInlineSkill: …` + The type of the object. Always `summary_text`. - - `description: str` + - `"summary_text"` - The description of the skill. + - `class AgentMessageContentReasoningText: …` - - `name: str` + Reasoning text from the model. - The name of the skill. + - `text: str` - - `source: BetaInlineSkillSource` + The reasoning text from the model. - Inline skill payload + - `type: Literal["reasoning_text"]` - - `data: str` + The type of the reasoning text. Always `reasoning_text`. - Base64-encoded skill zip bundle. + - `"reasoning_text"` - - `media_type: Literal["application/zip"]` + - `class BetaResponseOutputRefusal: …` - The media type of the inline skill payload. Must be `application/zip`. + A refusal from the model. - - `"application/zip"` + - `class BetaResponseInputImage: …` - - `type: Literal["base64"]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The type of the inline skill source. Must be `base64`. + - `class AgentMessageContentComputerScreenshot: …` - - `"base64"` + A screenshot of a computer. - - `type: Literal["inline"]` + - `detail: Literal["low", "high", "auto", "original"]` - Defines an inline skill for this request. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"inline"` + - `"low"` -### Beta Container Network Policy Allowlist + - `"high"` -- `class BetaContainerNetworkPolicyAllowlist: …` + - `"auto"` - - `allowed_domains: List[str]` + - `"original"` - A list of allowed domains when type is `allowlist`. + - `file_id: Optional[str]` - - `type: Literal["allowlist"]` + The identifier of an uploaded file that contains the screenshot. - Allow outbound network access only to specified domains. Always `allowlist`. + - `image_url: Optional[str]` - - `"allowlist"` + The URL of the screenshot image. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `type: Literal["computer_screenshot"]` - Optional domain-scoped secrets for allowlisted domains. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `domain: str` + - `"computer_screenshot"` - The domain associated with the secret. + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - - `name: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The name of the secret to inject for the domain. + - `mode: Literal["explicit"]` - - `value: str` + The breakpoint mode. Always `explicit`. - The secret value to inject for the domain. + - `"explicit"` -### Beta Container Network Policy Disabled + - `class BetaResponseInputFile: …` -- `class BetaContainerNetworkPolicyDisabled: …` + A file input to the model. - - `type: Literal["disabled"]` + - `class AgentMessageContentEncryptedContent: …` - Disable outbound network access. Always `disabled`. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"disabled"` + - `encrypted_content: str` -### Beta Container Network Policy Domain Secret + Opaque encrypted content. -- `class BetaContainerNetworkPolicyDomainSecret: …` + - `type: Literal["encrypted_content"]` - - `domain: str` + The type of the input item. Always `encrypted_content`. - The domain associated with the secret. + - `"encrypted_content"` - - `name: str` + - `recipient: str` - The name of the secret to inject for the domain. + The destination agent identity. - - `value: str` + - `type: Literal["agent_message"]` - The secret value to inject for the domain. + The type of the item. Always `agent_message`. -### Beta Container Reference + - `"agent_message"` -- `class BetaContainerReference: …` + - `agent: Optional[AgentMessageAgent]` - - `container_id: str` + The agent that produced this item. - The ID of the referenced container. + - `agent_name: str` - - `type: Literal["container_reference"]` + The canonical name of the agent that produced this item. - References a container created with the /v1/containers endpoint + - `class MultiAgentCall: …` - - `"container_reference"` + - `id: str` -### Beta Custom Tool + The unique ID of the multi-agent call item. -- `class BetaCustomTool: …` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The multi-agent action to execute. - - `name: str` + - `"spawn_agent"` - The name of the custom tool, used to identify it in tool calls. + - `"interrupt_agent"` - - `type: Literal["custom"]` + - `"list_agents"` - The type of the custom tool. Always `custom`. + - `"send_message"` - - `"custom"` + - `"followup_task"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"wait_agent"` - The tool invocation context(s). + - `arguments: str` - - `"direct"` + The JSON string of arguments generated for the action. - - `"programmatic"` + - `call_id: str` - - `defer_loading: Optional[bool]` + The unique ID linking this call to its output. - Whether this tool should be deferred and discovered via tool search. + - `type: Literal["multi_agent_call"]` - - `description: Optional[str]` + The type of the multi-agent call. Always `multi_agent_call`. - Optional description of the custom tool, used to provide more context. + - `"multi_agent_call"` - - `format: Optional[Format]` + - `agent: Optional[MultiAgentCallAgent]` - The input format for the custom tool. Default is unconstrained text. + The agent that produced this item. - - `class FormatText: …` + - `agent_name: str` - Unconstrained free-form text. + The canonical name of the agent that produced this item. - - `type: Literal["text"]` + - `class MultiAgentCallOutput: …` - Unconstrained text format. Always `text`. + - `id: str` - - `"text"` + The unique ID of the multi-agent call output item. - - `class FormatGrammar: …` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - A grammar defined by the user. + The multi-agent action that produced this result. - - `definition: str` + - `"spawn_agent"` - The grammar definition. + - `"interrupt_agent"` - - `syntax: Literal["lark", "regex"]` + - `"list_agents"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"send_message"` - - `"lark"` + - `"followup_task"` - - `"regex"` + - `"wait_agent"` - - `type: Literal["grammar"]` + - `call_id: str` - Grammar format. Always `grammar`. + The unique ID of the multi-agent call. - - `"grammar"` + - `output: List[BetaResponseOutputText]` -### Beta Easy Input Message + Text output returned by the multi-agent action. -- `class BetaEasyInputMessage: …` + - `annotations: List[Annotation]` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The annotations of the text output. - - `content: Union[str, BetaResponseInputMessageContentList]` + - `text: str` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The text output from the model. - - `str` + - `type: Literal["output_text"]` - A text input to the model. + The type of the output text. Always `output_text`. - - `List[BetaResponseInputContent]` + - `logprobs: Optional[List[Logprob]]` - - `class BetaResponseInputText: …` + - `type: Literal["multi_agent_call_output"]` - A text input to the model. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `text: str` + - `"multi_agent_call_output"` - The text input to the model. + - `agent: Optional[MultiAgentCallOutputAgent]` - - `type: Literal["input_text"]` + The agent that produced this item. - The type of the input item. Always `input_text`. + - `agent_name: str` - - `"input_text"` + The canonical name of the agent that produced this item. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `class BetaResponseFunctionWebSearch: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `mode: Literal["explicit"]` + - `class BetaResponseComputerToolCall: …` - The breakpoint mode. Always `explicit`. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `"explicit"` + - `class BetaResponseComputerToolCallOutputItem: …` - - `class BetaResponseInputImage: …` + - `id: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The unique ID of the computer call tool output. - - `detail: Literal["low", "high", "auto", "original"]` + - `call_id: str` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The ID of the computer tool call that produced the output. - - `"low"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `"high"` + A computer screenshot image used with the computer use tool. - - `"auto"` + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - `"original"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `type: Literal["input_image"]` + - `"completed"` - The type of the input item. Always `input_image`. + - `"incomplete"` - - `"input_image"` + - `"failed"` - - `file_id: Optional[str]` + - `"in_progress"` - The ID of the file to be sent to the model. + - `type: Literal["computer_call_output"]` - - `image_url: Optional[str]` + The type of the computer tool call output. Always `computer_call_output`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"computer_call_output"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The safety checks reported by the API that have been acknowledged by the + developer. - - `mode: Literal["explicit"]` + - `id: str` - The breakpoint mode. Always `explicit`. + The ID of the pending safety check. - - `"explicit"` + - `code: Optional[str]` - - `class BetaResponseInputFile: …` + The type of the pending safety check. - A file input to the model. + - `message: Optional[str]` - - `type: Literal["input_file"]` + Details about the pending safety check. - The type of the input item. Always `input_file`. + - `agent: Optional[Agent]` - - `"input_file"` + The agent that produced this item. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `agent_name: str` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The canonical name of the agent that produced this item. - - `"auto"` + - `created_by: Optional[str]` - - `"low"` + The identifier of the actor that created the item. - - `"high"` + - `class BetaResponseReasoningItem: …` - - `file_data: Optional[str]` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - The content of the file to be sent to the model. + - `class Program: …` - - `file_id: Optional[str]` + - `id: str` - The ID of the file to be sent to the model. + The unique ID of the program item. - - `file_url: Optional[str]` + - `call_id: str` - The URL of the file to be sent to the model. + The stable call ID of the program item. - - `filename: Optional[str]` + - `code: str` - The name of the file to be sent to the model. + The JavaScript source executed by programmatic tool calling. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `fingerprint: str` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Opaque program replay fingerprint that must be round-tripped. - - `mode: Literal["explicit"]` + - `type: Literal["program"]` - The breakpoint mode. Always `explicit`. + The type of the item. Always `program`. - - `"explicit"` + - `"program"` - - `role: Literal["user", "assistant", "system", "developer"]` + - `agent: Optional[ProgramAgent]` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The agent that produced this item. - - `"user"` + - `agent_name: str` - - `"assistant"` + The canonical name of the agent that produced this item. - - `"system"` + - `class ProgramOutput: …` - - `"developer"` + - `id: str` - - `phase: Optional[Literal["commentary"]]` + The unique ID of the program output item. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `call_id: str` - - `"commentary"` + The call ID of the program item. - - `type: Optional[Literal["message"]]` + - `result: str` - The type of the message input. Always `message`. + The result produced by the program item. - - `"message"` + - `status: Literal["completed", "incomplete"]` -### Beta File Search Tool + The terminal status of the program output item. -- `class BetaFileSearchTool: …` + - `"completed"` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `"incomplete"` - - `type: Literal["file_search"]` + - `type: Literal["program_output"]` - The type of the file search tool. Always `file_search`. + The type of the item. Always `program_output`. - - `"file_search"` + - `"program_output"` - - `vector_store_ids: List[str]` + - `agent: Optional[ProgramOutputAgent]` - The IDs of the vector stores to search. + The agent that produced this item. - - `filters: Optional[Filters]` + - `agent_name: str` - A filter to apply. + The canonical name of the agent that produced this item. - - `class FiltersComparisonFilter: …` + - `class BetaResponseToolSearchCall: …` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `id: str` - - `key: str` + The unique ID of the tool search call item. - The key to compare against the value. + - `arguments: object` - - `type: Literal["eq", "ne", "gt", 5 more]` + Arguments used for the tool search call. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `call_id: Optional[str]` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The unique ID of the tool search call generated by the model. - - `"eq"` + - `execution: Literal["server", "client"]` - - `"ne"` + Whether tool search was executed by the server or by the client. - - `"gt"` + - `"server"` - - `"gte"` + - `"client"` - - `"lt"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"lte"` + The status of the tool search call item that was recorded. - - `"in"` + - `"in_progress"` - - `"nin"` + - `"completed"` - - `value: Union[str, float, bool, List[object]]` + - `"incomplete"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `type: Literal["tool_search_call"]` - - `str` + The type of the item. Always `tool_search_call`. - - `float` + - `"tool_search_call"` - - `bool` + - `agent: Optional[Agent]` - - `List[object]` + The agent that produced this item. - - `class FiltersCompoundFilter: …` + - `agent_name: str` - Combine multiple filters using `and` or `or`. + The canonical name of the agent that produced this item. - - `filters: List[FiltersCompoundFilterFilter]` + - `created_by: Optional[str]` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The identifier of the actor that created the item. - - `class FiltersCompoundFilterFilterComparisonFilter: …` + - `class BetaResponseToolSearchOutputItem: …` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `id: str` - - `key: str` + The unique ID of the tool search output item. - The key to compare against the value. + - `call_id: Optional[str]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The unique ID of the tool search call generated by the model. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `execution: Literal["server", "client"]` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + Whether tool search was executed by the server or by the client. - - `"eq"` + - `"server"` - - `"ne"` + - `"client"` - - `"gt"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"gte"` + The status of the tool search output item that was recorded. - - `"lt"` + - `"in_progress"` - - `"lte"` + - `"completed"` - - `"in"` + - `"incomplete"` - - `"nin"` + - `tools: List[BetaTool]` - - `value: Union[str, float, bool, List[object]]` + The loaded tool definitions returned by tool search. - The value to compare against the attribute key; supports string, number, or boolean types. + - `class BetaFunctionTool: …` - - `str` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `float` + - `class BetaFileSearchTool: …` - - `bool` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `List[object]` + - `class BetaComputerTool: …` - - `object` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: Literal["and", "or"]` + - `class BetaComputerUsePreviewTool: …` - Type of operation: `and` or `or`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"and"` + - `class BetaWebSearchTool: …` - - `"or"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `max_num_results: Optional[int]` + - `class Mcp: …` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `ranking_options: Optional[RankingOptions]` + - `class CodeInterpreter: …` - Ranking options for search. + A tool that runs Python code to help generate a response to a prompt. - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + - `class ProgrammaticToolCalling: …` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `class ImageGeneration: …` - - `embedding_weight: float` + A tool that generates images using the GPT image models. - The weight of the embedding in the reciprocal ranking fusion. + - `class LocalShell: …` - - `text_weight: float` + A tool that allows the model to execute shell commands in a local environment. - The weight of the text in the reciprocal ranking fusion. + - `class BetaFunctionShellTool: …` - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + A tool that allows the model to execute shell commands. - The ranker to use for the file search. + - `class BetaCustomTool: …` - - `"auto"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `"default-2024-11-15"` + - `class BetaNamespaceTool: …` - - `score_threshold: Optional[float]` + Groups function/custom tools under a shared namespace. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `class BetaToolSearchTool: …` -### Beta Function Shell Tool + Hosted or BYOT tool search configuration for deferred tools. -- `class BetaFunctionShellTool: …` + - `class BetaWebSearchPreviewTool: …` - A tool that allows the model to execute shell commands. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `type: Literal["shell"]` + - `class BetaApplyPatchTool: …` - The type of the shell tool. Always `shell`. + Allows the assistant to create, delete, or update files using unified diffs. - - `"shell"` + - `type: Literal["tool_search_output"]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The type of the item. Always `tool_search_output`. - The tool invocation context(s). + - `"tool_search_output"` - - `"direct"` + - `agent: Optional[Agent]` - - `"programmatic"` + The agent that produced this item. - - `environment: Optional[Environment]` + - `agent_name: str` - - `class BetaContainerAuto: …` + The canonical name of the agent that produced this item. - - `type: Literal["container_auto"]` + - `created_by: Optional[str]` - Automatically creates a container for this request + The identifier of the actor that created the item. - - `"container_auto"` + - `class AdditionalTools: …` - - `file_ids: Optional[List[str]]` + - `id: str` - An optional list of uploaded files to make available to your code. + The unique ID of the additional tools item. - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `role: Literal["unknown", "user", "assistant", 5 more]` - The memory limit for the container. + The role that provided the additional tools. - - `"1g"` + - `"unknown"` - - `"4g"` + - `"user"` - - `"16g"` + - `"assistant"` - - `"64g"` + - `"system"` - - `network_policy: Optional[NetworkPolicy]` + - `"critic"` - Network access policy for the container. + - `"discriminator"` - - `class BetaContainerNetworkPolicyDisabled: …` + - `"developer"` - - `type: Literal["disabled"]` + - `"tool"` - Disable outbound network access. Always `disabled`. + - `tools: List[BetaTool]` - - `"disabled"` + The additional tool definitions made available at this item. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `class BetaFunctionTool: …` - - `allowed_domains: List[str]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - A list of allowed domains when type is `allowlist`. + - `class BetaFileSearchTool: …` - - `type: Literal["allowlist"]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - Allow outbound network access only to specified domains. Always `allowlist`. + - `class BetaComputerTool: …` - - `"allowlist"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `class BetaComputerUsePreviewTool: …` - Optional domain-scoped secrets for allowlisted domains. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `domain: str` + - `class BetaWebSearchTool: …` - The domain associated with the secret. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `name: str` + - `class Mcp: …` - The name of the secret to inject for the domain. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `value: str` + - `class CodeInterpreter: …` - The secret value to inject for the domain. + A tool that runs Python code to help generate a response to a prompt. - - `skills: Optional[List[Skill]]` + - `class ProgrammaticToolCalling: …` - An optional list of skills referenced by id or inline data. + - `class ImageGeneration: …` - - `class BetaSkillReference: …` + A tool that generates images using the GPT image models. - - `skill_id: str` + - `class LocalShell: …` - The ID of the referenced skill. + A tool that allows the model to execute shell commands in a local environment. - - `type: Literal["skill_reference"]` + - `class BetaFunctionShellTool: …` - References a skill created with the /v1/skills endpoint. + A tool that allows the model to execute shell commands. - - `"skill_reference"` + - `class BetaCustomTool: …` - - `version: Optional[str]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `class BetaNamespaceTool: …` - - `class BetaInlineSkill: …` + Groups function/custom tools under a shared namespace. - - `description: str` + - `class BetaToolSearchTool: …` - The description of the skill. + Hosted or BYOT tool search configuration for deferred tools. - - `name: str` + - `class BetaWebSearchPreviewTool: …` - The name of the skill. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `source: BetaInlineSkillSource` + - `class BetaApplyPatchTool: …` - Inline skill payload + Allows the assistant to create, delete, or update files using unified diffs. - - `data: str` + - `type: Literal["additional_tools"]` - Base64-encoded skill zip bundle. + The type of the item. Always `additional_tools`. - - `media_type: Literal["application/zip"]` + - `"additional_tools"` - The media type of the inline skill payload. Must be `application/zip`. + - `agent: Optional[AdditionalToolsAgent]` - - `"application/zip"` + The agent that produced this item. - - `type: Literal["base64"]` + - `agent_name: str` - The type of the inline skill source. Must be `base64`. + The canonical name of the agent that produced this item. - - `"base64"` + - `class BetaResponseCompactionItem: …` - - `type: Literal["inline"]` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - Defines an inline skill for this request. + - `id: str` - - `"inline"` + The unique ID of the compaction item. - - `class BetaLocalEnvironment: …` + - `encrypted_content: str` - - `type: Literal["local"]` + The encrypted content that was produced by compaction. - Use a local computer environment. + - `type: Literal["compaction"]` - - `"local"` + The type of the item. Always `compaction`. - - `skills: Optional[List[BetaLocalSkill]]` + - `"compaction"` - An optional list of skills. + - `agent: Optional[Agent]` - - `description: str` + The agent that produced this item. - The description of the skill. + - `agent_name: str` - - `name: str` + The canonical name of the agent that produced this item. - The name of the skill. + - `created_by: Optional[str]` - - `path: str` + The identifier of the actor that created the item. - The path to the directory containing the skill. + - `class ImageGenerationCall: …` - - `class BetaContainerReference: …` + An image generation request made by the model. - - `container_id: str` + - `id: str` - The ID of the referenced container. + The unique ID of the image generation call. - - `type: Literal["container_reference"]` + - `result: Optional[str]` - References a container created with the /v1/containers endpoint + The generated image encoded in base64. - - `"container_reference"` + - `status: Literal["in_progress", "completed", "generating", "failed"]` -### Beta Function Tool + The status of the image generation call. -- `class BetaFunctionTool: …` + - `"in_progress"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `"completed"` - - `name: str` + - `"generating"` - The name of the function to call. + - `"failed"` - - `parameters: Optional[Dict[str, object]]` + - `type: Literal["image_generation_call"]` - A JSON schema object describing the parameters of the function. + The type of the image generation call. Always `image_generation_call`. - - `strict: Optional[bool]` + - `"image_generation_call"` - Whether strict parameter validation is enforced for this function tool. + - `agent: Optional[ImageGenerationCallAgent]` - - `type: Literal["function"]` + The agent that produced this item. - The type of the function tool. Always `function`. + - `agent_name: str` - - `"function"` + The canonical name of the agent that produced this item. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `class BetaResponseCodeInterpreterToolCall: …` - The tool invocation context(s). + A tool call to run code. - - `"direct"` + - `class LocalShellCall: …` - - `"programmatic"` + A tool call to run a command on the local shell. - - `defer_loading: Optional[bool]` + - `id: str` - Whether this function is deferred and loaded via tool search. + The unique ID of the local shell call. - - `description: Optional[str]` + - `action: LocalShellCallAction` - A description of the function. Used by the model to determine whether or not to call the function. + Execute a shell command on the server. - - `output_schema: Optional[Dict[str, object]]` + - `command: List[str]` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The command to run. -### Beta Inline Skill + - `env: Dict[str, str]` -- `class BetaInlineSkill: …` + Environment variables to set for the command. - - `description: str` + - `type: Literal["exec"]` - The description of the skill. + The type of the local shell action. Always `exec`. - - `name: str` + - `"exec"` - The name of the skill. + - `timeout_ms: Optional[int]` - - `source: BetaInlineSkillSource` + Optional timeout in milliseconds for the command. - Inline skill payload + - `user: Optional[str]` - - `data: str` + Optional user to run the command as. - Base64-encoded skill zip bundle. + - `working_directory: Optional[str]` - - `media_type: Literal["application/zip"]` + Optional working directory to run the command in. - The media type of the inline skill payload. Must be `application/zip`. + - `call_id: str` - - `"application/zip"` + The unique ID of the local shell tool call generated by the model. - - `type: Literal["base64"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The type of the inline skill source. Must be `base64`. + The status of the local shell call. - - `"base64"` + - `"in_progress"` - - `type: Literal["inline"]` + - `"completed"` - Defines an inline skill for this request. + - `"incomplete"` - - `"inline"` + - `type: Literal["local_shell_call"]` -### Beta Inline Skill Source + The type of the local shell call. Always `local_shell_call`. -- `class BetaInlineSkillSource: …` + - `"local_shell_call"` - Inline skill payload + - `agent: Optional[LocalShellCallAgent]` - - `data: str` + The agent that produced this item. - Base64-encoded skill zip bundle. + - `agent_name: str` - - `media_type: Literal["application/zip"]` + The canonical name of the agent that produced this item. - The media type of the inline skill payload. Must be `application/zip`. + - `class LocalShellCallOutput: …` - - `"application/zip"` + The output of a local shell tool call. - - `type: Literal["base64"]` + - `id: str` - The type of the inline skill source. Must be `base64`. + The unique ID of the local shell tool call generated by the model. - - `"base64"` + - `output: str` -### Beta Local Environment + A JSON string of the output of the local shell tool call. -- `class BetaLocalEnvironment: …` + - `type: Literal["local_shell_call_output"]` - - `type: Literal["local"]` + The type of the local shell tool call output. Always `local_shell_call_output`. - Use a local computer environment. + - `"local_shell_call_output"` - - `"local"` + - `agent: Optional[LocalShellCallOutputAgent]` - - `skills: Optional[List[BetaLocalSkill]]` + The agent that produced this item. - An optional list of skills. + - `agent_name: str` - - `description: str` + The canonical name of the agent that produced this item. - The description of the skill. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `name: str` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The name of the skill. + - `"in_progress"` - - `path: str` + - `"completed"` - The path to the directory containing the skill. + - `"incomplete"` -### Beta Local Skill + - `class BetaResponseFunctionShellToolCall: …` -- `class BetaLocalSkill: …` + A tool call that executes one or more shell commands in a managed environment. - - `description: str` + - `id: str` - The description of the skill. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `name: str` + - `action: Action` - The name of the skill. + The shell commands and limits that describe how to run the tool call. - - `path: str` + - `commands: List[str]` - The path to the directory containing the skill. + - `max_output_length: Optional[int]` -### Beta Namespace Tool + Optional maximum number of characters to return from each command. -- `class BetaNamespaceTool: …` + - `timeout_ms: Optional[int]` - Groups function/custom tools under a shared namespace. + Optional timeout in milliseconds for the commands. - - `description: str` + - `call_id: str` - A description of the namespace shown to the model. + The unique ID of the shell tool call generated by the model. - - `name: str` + - `environment: Optional[Environment]` - The namespace name used in tool calls (for example, `crm`). + Represents the use of a local environment to perform shell actions. - - `tools: List[Tool]` + - `class BetaResponseLocalEnvironment: …` - The function/custom tools available inside this namespace. + Represents the use of a local environment to perform shell actions. - - `class ToolFunction: …` + - `type: Literal["local"]` - - `name: str` + The environment type. Always `local`. - - `type: Literal["function"]` + - `"local"` - - `"function"` + - `class BetaResponseContainerReference: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + Represents a container created with /v1/containers. - The tool invocation context(s). + - `container_id: str` - - `"direct"` + - `type: Literal["container_reference"]` - - `"programmatic"` + The environment type. Always `container_reference`. - - `defer_loading: Optional[bool]` + - `"container_reference"` - Whether this function should be deferred and discovered via tool search. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `description: Optional[str]` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `output_schema: Optional[Dict[str, object]]` + - `"in_progress"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `"completed"` - - `parameters: Optional[object]` + - `"incomplete"` - - `strict: Optional[bool]` + - `type: Literal["shell_call"]` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The type of the item. Always `shell_call`. - - `class BetaCustomTool: …` + - `"shell_call"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `agent: Optional[Agent]` - - `name: str` + The agent that produced this item. - The name of the custom tool, used to identify it in tool calls. + - `agent_name: str` - - `type: Literal["custom"]` + The canonical name of the agent that produced this item. - The type of the custom tool. Always `custom`. + - `caller: Optional[Caller]` - - `"custom"` + The execution context that produced this tool call. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `class CallerDirect: …` - The tool invocation context(s). + - `type: Literal["direct"]` - `"direct"` - - `"programmatic"` + - `class CallerProgram: …` - - `defer_loading: Optional[bool]` + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` - Whether this tool should be deferred and discovered via tool search. + - `"program"` - - `description: Optional[str]` + - `created_by: Optional[str]` - Optional description of the custom tool, used to provide more context. + The ID of the entity that created this tool call. - - `format: Optional[Format]` + - `class BetaResponseFunctionShellToolCallOutput: …` - The input format for the custom tool. Default is unconstrained text. + The output of a shell tool call that was emitted. - - `class FormatText: …` + - `id: str` - Unconstrained free-form text. + The unique ID of the shell call output. Populated when this item is returned via API. - - `type: Literal["text"]` + - `call_id: str` - Unconstrained text format. Always `text`. + The unique ID of the shell tool call generated by the model. - - `"text"` + - `max_output_length: Optional[int]` - - `class FormatGrammar: …` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - A grammar defined by the user. + - `output: List[Output]` - - `definition: str` + An array of shell call output contents - The grammar definition. + - `outcome: OutputOutcome` - - `syntax: Literal["lark", "regex"]` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The syntax of the grammar definition. One of `lark` or `regex`. + - `class OutputOutcomeTimeout: …` - - `"lark"` + Indicates that the shell call exceeded its configured time limit. - - `"regex"` + - `type: Literal["timeout"]` - - `type: Literal["grammar"]` + The outcome type. Always `timeout`. - Grammar format. Always `grammar`. + - `"timeout"` - - `"grammar"` + - `class OutputOutcomeExit: …` - - `type: Literal["namespace"]` + Indicates that the shell commands finished and returned an exit code. - The type of the tool. Always `namespace`. + - `exit_code: int` - - `"namespace"` + Exit code from the shell process. -### Beta Response + - `type: Literal["exit"]` -- `class BetaResponse: …` + The outcome type. Always `exit`. - - `id: str` + - `"exit"` - Unique identifier for this Response. + - `stderr: str` - - `created_at: float` + The standard error output that was captured. - Unix timestamp (in seconds) of when this Response was created. + - `stdout: str` - - `error: Optional[BetaResponseError]` + The standard output that was captured. - An error object returned when the model fails to generate a Response. + - `created_by: Optional[str]` - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + The identifier of the actor that created the item. - The error code for the response. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"server_error"` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `"rate_limit_exceeded"` + - `"in_progress"` - - `"invalid_prompt"` + - `"completed"` - - `"bio_policy"` + - `"incomplete"` - - `"vector_store_timeout"` + - `type: Literal["shell_call_output"]` - - `"invalid_image"` + The type of the shell call output. Always `shell_call_output`. - - `"invalid_image_format"` + - `"shell_call_output"` - - `"invalid_base64_image"` + - `agent: Optional[Agent]` - - `"invalid_image_url"` + The agent that produced this item. - - `"image_too_large"` + - `agent_name: str` - - `"image_too_small"` + The canonical name of the agent that produced this item. - - `"image_parse_error"` + - `caller: Optional[Caller]` - - `"image_content_policy_violation"` + The execution context that produced this tool call. - - `"invalid_image_mode"` + - `class CallerDirect: …` - - `"image_file_too_large"` + - `type: Literal["direct"]` - - `"unsupported_image_media_type"` + - `"direct"` - - `"empty_image_file"` + - `class CallerProgram: …` - - `"failed_to_download_image"` + - `caller_id: str` - - `"image_file_not_found"` + The call ID of the program item that produced this tool call. - - `message: str` + - `type: Literal["program"]` - A human-readable description of the error. + - `"program"` - - `incomplete_details: Optional[IncompleteDetails]` + - `created_by: Optional[str]` - Details about why the response is incomplete. + The identifier of the actor that created the item. - - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` + - `class BetaResponseApplyPatchToolCall: …` - The reason why the response is incomplete. + A tool call that applies file diffs by creating, deleting, or updating files. - - `"max_output_tokens"` + - `id: str` - - `"content_filter"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `instructions: Union[str, List[BetaResponseInputItem], null]` + - `call_id: str` - A system (or developer) message inserted into the model's context. + The unique ID of the apply patch tool call generated by the model. - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `operation: Operation` - - `str` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - A text input to the model, equivalent to a text input with the - `developer` role. + - `class OperationCreateFile: …` - - `List[BetaResponseInputItem]` + Instruction describing how to create a file via the apply_patch tool. - A list of one or many input items to the model, containing - different content types. + - `diff: str` - - `class BetaEasyInputMessage: …` + Diff to apply. - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `path: str` - - `content: Union[str, BetaResponseInputMessageContentList]` + Path of the file to create. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `type: Literal["create_file"]` - - `str` + Create a new file with the provided diff. - A text input to the model. + - `"create_file"` - - `List[BetaResponseInputContent]` + - `class OperationDeleteFile: …` - - `class BetaResponseInputText: …` + Instruction describing how to delete a file via the apply_patch tool. - A text input to the model. + - `path: str` - - `text: str` + Path of the file to delete. - The text input to the model. + - `type: Literal["delete_file"]` - - `type: Literal["input_text"]` + Delete the specified file. - The type of the input item. Always `input_text`. + - `"delete_file"` - - `"input_text"` + - `class OperationUpdateFile: …` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + Instruction describing how to update a file via the apply_patch tool. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `diff: str` - - `mode: Literal["explicit"]` + Diff to apply. - The breakpoint mode. Always `explicit`. + - `path: str` - - `"explicit"` + Path of the file to update. - - `class BetaResponseInputImage: …` + - `type: Literal["update_file"]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Update an existing file with the provided diff. - - `detail: Literal["low", "high", "auto", "original"]` + - `"update_file"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `status: Literal["in_progress", "completed"]` - - `"low"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"high"` + - `"in_progress"` - - `"auto"` + - `"completed"` - - `"original"` + - `type: Literal["apply_patch_call"]` - - `type: Literal["input_image"]` + The type of the item. Always `apply_patch_call`. - The type of the input item. Always `input_image`. + - `"apply_patch_call"` - - `"input_image"` + - `agent: Optional[Agent]` - - `file_id: Optional[str]` + The agent that produced this item. - The ID of the file to be sent to the model. + - `agent_name: str` - - `image_url: Optional[str]` + The canonical name of the agent that produced this item. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `caller: Optional[Caller]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The execution context that produced this tool call. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class CallerDirect: …` - - `mode: Literal["explicit"]` + - `type: Literal["direct"]` - The breakpoint mode. Always `explicit`. + - `"direct"` - - `"explicit"` + - `class CallerProgram: …` - - `class BetaResponseInputFile: …` + - `caller_id: str` - A file input to the model. + The call ID of the program item that produced this tool call. - - `type: Literal["input_file"]` + - `type: Literal["program"]` - The type of the input item. Always `input_file`. + - `"program"` - - `"input_file"` + - `created_by: Optional[str]` - - `detail: Optional[Literal["auto", "low", "high"]]` + The ID of the entity that created this tool call. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `class BetaResponseApplyPatchToolCallOutput: …` - - `"auto"` + The output emitted by an apply patch tool call. - - `"low"` + - `id: str` - - `"high"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `file_data: Optional[str]` + - `call_id: str` - The content of the file to be sent to the model. + The unique ID of the apply patch tool call generated by the model. - - `file_id: Optional[str]` + - `status: Literal["completed", "failed"]` - The ID of the file to be sent to the model. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `file_url: Optional[str]` + - `"completed"` - The URL of the file to be sent to the model. + - `"failed"` - - `filename: Optional[str]` + - `type: Literal["apply_patch_call_output"]` - The name of the file to be sent to the model. + The type of the item. Always `apply_patch_call_output`. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"apply_patch_call_output"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `agent: Optional[Agent]` - - `mode: Literal["explicit"]` + The agent that produced this item. - The breakpoint mode. Always `explicit`. + - `agent_name: str` - - `"explicit"` + The canonical name of the agent that produced this item. - - `role: Literal["user", "assistant", "system", "developer"]` + - `caller: Optional[Caller]` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The execution context that produced this tool call. - - `"user"` + - `class CallerDirect: …` - - `"assistant"` + - `type: Literal["direct"]` - - `"system"` + - `"direct"` - - `"developer"` + - `class CallerProgram: …` - - `phase: Optional[Literal["commentary"]]` + - `caller_id: str` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The call ID of the program item that produced this tool call. - - `"commentary"` + - `type: Literal["program"]` - - `type: Optional[Literal["message"]]` + - `"program"` - The type of the message input. Always `message`. + - `created_by: Optional[str]` - - `"message"` + The ID of the entity that created this tool call output. - - `class Message: …` + - `output: Optional[str]` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + Optional textual output returned by the apply patch tool. - - `content: BetaResponseInputMessageContentList` + - `class McpCall: …` - A list of one or many input items to the model, containing different content - types. + An invocation of a tool on an MCP server. - - `class BetaResponseInputText: …` + - `id: str` - A text input to the model. + The unique ID of the tool call. - - `class BetaResponseInputImage: …` + - `arguments: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A JSON string of the arguments passed to the tool. - - `class BetaResponseInputFile: …` + - `name: str` - A file input to the model. + The name of the tool that was run. - - `role: Literal["user", "system", "developer"]` + - `server_label: str` - The role of the message input. One of `user`, `system`, or `developer`. + The label of the MCP server running the tool. - - `"user"` + - `type: Literal["mcp_call"]` - - `"system"` + The type of the item. Always `mcp_call`. - - `"developer"` + - `"mcp_call"` - - `agent: Optional[MessageAgent]` + - `agent: Optional[McpCallAgent]` The agent that produced this item. @@ -54567,10 +65714,22 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `approval_request_id: Optional[str]` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: Optional[str]` + + The error from the tool call, if any. + + - `output: Optional[str]` + + The output from the tool call. + + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `"in_progress"` @@ -54578,2561 +65737,2621 @@ print(compacted_response) - `"incomplete"` - - `type: Optional[Literal["message"]]` - - The type of the message input. Always set to `message`. + - `"calling"` - - `"message"` + - `"failed"` - - `class BetaResponseOutputMessage: …` + - `class McpListTools: …` - An output message from the model. + A list of tools available on an MCP server. - `id: str` - The unique ID of the output message. + The unique ID of the list. - - `content: List[Content]` + - `server_label: str` - The content of the output message. + The label of the MCP server. - - `class BetaResponseOutputText: …` + - `tools: List[McpListToolsTool]` - A text output from the model. + The tools available on the server. - - `annotations: List[Annotation]` + - `input_schema: object` - The annotations of the text output. + The JSON schema describing the tool's input. - - `class AnnotationFileCitation: …` + - `name: str` - A citation to a file. + The name of the tool. - - `file_id: str` + - `annotations: Optional[object]` - The ID of the file. + Additional annotations about the tool. - - `filename: str` + - `description: Optional[str]` - The filename of the file cited. + The description of the tool. - - `index: int` + - `type: Literal["mcp_list_tools"]` - The index of the file in the list of files. + The type of the item. Always `mcp_list_tools`. - - `type: Literal["file_citation"]` + - `"mcp_list_tools"` - The type of the file citation. Always `file_citation`. + - `agent: Optional[McpListToolsAgent]` - - `"file_citation"` + The agent that produced this item. - - `class AnnotationURLCitation: …` + - `agent_name: str` - A citation for a web resource used to generate a model response. + The canonical name of the agent that produced this item. - - `end_index: int` + - `error: Optional[str]` - The index of the last character of the URL citation in the message. + Error message if the server could not list tools. - - `start_index: int` + - `class McpApprovalRequest: …` - The index of the first character of the URL citation in the message. + A request for human approval of a tool invocation. - - `title: str` + - `id: str` - The title of the web resource. + The unique ID of the approval request. - - `type: Literal["url_citation"]` + - `arguments: str` - The type of the URL citation. Always `url_citation`. + A JSON string of arguments for the tool. - - `"url_citation"` + - `name: str` - - `url: str` + The name of the tool to run. - The URL of the web resource. + - `server_label: str` - - `class AnnotationContainerFileCitation: …` + The label of the MCP server making the request. - A citation for a container file used to generate a model response. + - `type: Literal["mcp_approval_request"]` - - `container_id: str` + The type of the item. Always `mcp_approval_request`. - The ID of the container file. + - `"mcp_approval_request"` - - `end_index: int` + - `agent: Optional[McpApprovalRequestAgent]` - The index of the last character of the container file citation in the message. + The agent that produced this item. - - `file_id: str` + - `agent_name: str` - The ID of the file. + The canonical name of the agent that produced this item. - - `filename: str` + - `class McpApprovalResponse: …` - The filename of the container file cited. + A response to an MCP approval request. - - `start_index: int` + - `id: str` - The index of the first character of the container file citation in the message. + The unique ID of the approval response - - `type: Literal["container_file_citation"]` + - `approval_request_id: str` - The type of the container file citation. Always `container_file_citation`. + The ID of the approval request being answered. - - `"container_file_citation"` + - `approve: bool` - - `class AnnotationFilePath: …` + Whether the request was approved. - A path to a file. + - `type: Literal["mcp_approval_response"]` - - `file_id: str` + The type of the item. Always `mcp_approval_response`. - The ID of the file. + - `"mcp_approval_response"` - - `index: int` + - `agent: Optional[McpApprovalResponseAgent]` - The index of the file in the list of files. + The agent that produced this item. - - `type: Literal["file_path"]` + - `agent_name: str` - The type of the file path. Always `file_path`. + The canonical name of the agent that produced this item. - - `"file_path"` + - `reason: Optional[str]` - - `text: str` + Optional reason for the decision. - The text output from the model. + - `class BetaResponseCustomToolCall: …` - - `type: Literal["output_text"]` + A call to a custom tool created by the model. - The type of the output text. Always `output_text`. + - `class BetaResponseCustomToolCallOutputItem: …` - - `"output_text"` + The output of a custom tool call from your code, being sent back to the model. - - `logprobs: Optional[List[Logprob]]` + - `id: str` - - `token: str` + The unique ID of the custom tool call output item. - - `bytes: List[int]` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `logprob: float` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `top_logprobs: List[LogprobTopLogprob]` + - `"in_progress"` - - `token: str` + - `"completed"` - - `bytes: List[int]` + - `"incomplete"` - - `logprob: float` + - `created_by: Optional[str]` - - `class BetaResponseOutputRefusal: …` + The identifier of the actor that created the item. - A refusal from the model. + - `parallel_tool_calls: bool` - - `refusal: str` + Whether to allow the model to run tool calls in parallel. - The refusal explanation from the model. + - `temperature: Optional[float]` - - `type: Literal["refusal"]` + 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. + We generally recommend altering this or `top_p` but not both. - The type of the refusal. Always `refusal`. + - `tool_choice: ToolChoice` - - `"refusal"` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `role: Literal["assistant"]` + - `Literal["none", "auto", "required"]` - The role of the output message. Always `assistant`. + - `"none"` - - `"assistant"` + - `"auto"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"required"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `class BetaToolChoiceAllowed: …` - - `"in_progress"` + Constrains the tools available to the model to a pre-defined set. - - `"completed"` + - `mode: Literal["auto", "required"]` - - `"incomplete"` + Constrains the tools available to the model to a pre-defined set. - - `type: Literal["message"]` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The type of the output message. Always `message`. + `required` requires the model to call one or more of the allowed tools. - - `"message"` + - `"auto"` - - `agent: Optional[Agent]` + - `"required"` - The agent that produced this item. + - `tools: List[Dict[str, object]]` - - `agent_name: str` + A list of tool definitions that the model should be allowed to call. - The canonical name of the agent that produced this item. + For the Responses API, the list of tool definitions might look like: - - `phase: Optional[Literal["commentary"]]` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `type: Literal["allowed_tools"]` - - `"commentary"` + Allowed tool configuration type. Always `allowed_tools`. - - `class BetaResponseFileSearchToolCall: …` + - `"allowed_tools"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `class BetaToolChoiceTypes: …` - - `id: str` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - The unique ID of the file search tool call. + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` - - `queries: List[str]` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - The queries used to search for files. + Allowed values are: - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"file_search"` - - `"in_progress"` + - `"web_search_preview"` - - `"searching"` + - `"computer"` - - `"completed"` + - `"computer_use_preview"` - - `"incomplete"` + - `"computer_use"` - - `"failed"` + - `"web_search_preview_2025_03_11"` - - `type: Literal["file_search_call"]` + - `"image_generation"` - The type of the file search tool call. Always `file_search_call`. + - `"code_interpreter"` - - `"file_search_call"` + - `class BetaToolChoiceFunction: …` - - `agent: Optional[Agent]` + Use this option to force the model to call a specific function. - The agent that produced this item. + - `name: str` - - `agent_name: str` + The name of the function to call. - The canonical name of the agent that produced this item. + - `type: Literal["function"]` - - `results: Optional[List[Result]]` + For function calling, the type is always `function`. - The results of the file search tool call. + - `"function"` - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + - `class BetaToolChoiceMcp: …` - 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, booleans, or numbers. + Use this option to force the model to call a specific tool on a remote MCP server. - - `str` + - `server_label: str` - - `float` + The label of the MCP server to use. - - `bool` + - `type: Literal["mcp"]` - - `file_id: Optional[str]` + For MCP tools, the type is always `mcp`. - The unique ID of the file. + - `"mcp"` - - `filename: Optional[str]` + - `name: Optional[str]` - The name of the file. + The name of the tool to call on the server. - - `score: Optional[float]` + - `class BetaToolChoiceCustom: …` - The relevance score of the file - a value between 0 and 1. + Use this option to force the model to call a specific custom tool. - - `text: Optional[str]` + - `name: str` - The text that was retrieved from the file. + The name of the custom tool to call. - - `class BetaResponseComputerToolCall: …` + - `type: Literal["custom"]` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + For custom tool calling, the type is always `custom`. - - `id: str` + - `"custom"` - The unique ID of the computer call. + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` - - `call_id: str` + - `type: Literal["programmatic_tool_calling"]` - An identifier used when responding to the tool call with output. + The tool to call. Always `programmatic_tool_calling`. - - `pending_safety_checks: List[PendingSafetyCheck]` + - `"programmatic_tool_calling"` - The pending safety checks for the computer call. + - `class BetaToolChoiceApplyPatch: …` - - `id: str` + Forces the model to call the apply_patch tool when executing a tool call. - The ID of the pending safety check. + - `type: Literal["apply_patch"]` - - `code: Optional[str]` + The tool to call. Always `apply_patch`. - The type of the pending safety check. + - `"apply_patch"` - - `message: Optional[str]` + - `class BetaToolChoiceShell: …` - Details about the pending safety check. + Forces the model to call the shell tool when a tool call is required. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `type: Literal["shell"]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The tool to call. Always `shell`. - - `"in_progress"` + - `"shell"` - - `"completed"` + - `tools: List[BetaTool]` - - `"incomplete"` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `type: Literal["computer_call"]` + We support the following categories of tools: - The type of the computer call. Always `computer_call`. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `"computer_call"` + - `class BetaFunctionTool: …` - - `action: Optional[BetaComputerAction]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - A click action. + - `class BetaFileSearchTool: …` - - `class Click: …` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - A click action. + - `class BetaComputerTool: …` - - `button: Literal["left", "right", "wheel", 2 more]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `class BetaComputerUsePreviewTool: …` - - `"left"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"right"` + - `class BetaWebSearchTool: …` - - `"wheel"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"back"` + - `class Mcp: …` - - `"forward"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `type: Literal["click"]` + - `class CodeInterpreter: …` - Specifies the event type. For a click action, this property is always `click`. + A tool that runs Python code to help generate a response to a prompt. - - `"click"` + - `class ProgrammaticToolCalling: …` - - `x: int` + - `class ImageGeneration: …` - The x-coordinate where the click occurred. + A tool that generates images using the GPT image models. - - `y: int` + - `class LocalShell: …` - The y-coordinate where the click occurred. + A tool that allows the model to execute shell commands in a local environment. - - `keys: Optional[List[str]]` + - `class BetaFunctionShellTool: …` - The keys being held while clicking. + A tool that allows the model to execute shell commands. - - `class DoubleClick: …` + - `class BetaCustomTool: …` - A double click action. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `keys: Optional[List[str]]` + - `class BetaNamespaceTool: …` - The keys being held while double-clicking. + Groups function/custom tools under a shared namespace. - - `type: Literal["double_click"]` + - `class BetaToolSearchTool: …` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Hosted or BYOT tool search configuration for deferred tools. - - `"double_click"` + - `class BetaWebSearchPreviewTool: …` - - `x: int` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The x-coordinate where the double click occurred. + - `class BetaApplyPatchTool: …` - - `y: int` + Allows the assistant to create, delete, or update files using unified diffs. - The y-coordinate where the double click occurred. + - `top_p: Optional[float]` - - `class Drag: …` + 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. - A drag action. + We generally recommend altering this or `temperature` but not both. - - `path: List[DragPath]` + - `background: Optional[bool]` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `completed_at: Optional[float]` - - `x: int` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The x-coordinate. + - `conversation: Optional[Conversation]` - - `y: int` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The y-coordinate. + - `id: str` - - `type: Literal["drag"]` + The unique ID of the conversation that this response was associated with. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `max_output_tokens: Optional[int]` - - `"drag"` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `keys: Optional[List[str]]` + - `max_tool_calls: Optional[int]` - The keys being held while dragging the mouse. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `class Keypress: …` + - `moderation: Optional[Moderation]` - A collection of keypresses the model would like to perform. + Moderation results for the response input and output, if moderated completions were requested. - - `keys: List[str]` + - `input: ModerationInput` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Moderation for the response input. - - `type: Literal["keypress"]` + - `class ModerationInputModerationResult: …` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + A moderation result produced for the response input or output. - - `"keypress"` + - `categories: Dict[str, bool]` - - `class Move: …` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - A mouse move action. + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - - `type: Literal["move"]` + Which modalities of input are reflected by the score for each category. - Specifies the event type. For a move action, this property is always set to `move`. + - `"text"` - - `"move"` + - `"image"` - - `x: int` + - `category_scores: Dict[str, float]` - The x-coordinate to move to. + A dictionary of moderation categories to scores. - - `y: int` + - `flagged: bool` - The y-coordinate to move to. + A boolean indicating whether the content was flagged by any category. - - `keys: Optional[List[str]]` + - `model: str` - The keys being held while moving the mouse. + The moderation model that produced this result. - - `class Screenshot: …` + - `type: Literal["moderation_result"]` - A screenshot action. + The object type, which was always `moderation_result` for successful moderation results. - - `type: Literal["screenshot"]` + - `"moderation_result"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `class ModerationInputError: …` - - `"screenshot"` + An error produced while attempting moderation for the response input or output. - - `class Scroll: …` + - `code: str` - A scroll action. + The error code. - - `scroll_x: int` + - `message: str` - The horizontal scroll distance. + The error message. - - `scroll_y: int` + - `type: Literal["error"]` - The vertical scroll distance. + The object type, which was always `error` for moderation failures. - - `type: Literal["scroll"]` + - `"error"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `output: ModerationOutput` - - `"scroll"` + Moderation for the response output. - - `x: int` + - `class ModerationOutputModerationResult: …` - The x-coordinate where the scroll occurred. + A moderation result produced for the response input or output. - - `y: int` + - `categories: Dict[str, bool]` - The y-coordinate where the scroll occurred. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `keys: Optional[List[str]]` + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - The keys being held while scrolling. + Which modalities of input are reflected by the score for each category. - - `class Type: …` + - `"text"` - An action to type in text. + - `"image"` - - `text: str` + - `category_scores: Dict[str, float]` - The text to type. + A dictionary of moderation categories to scores. - - `type: Literal["type"]` + - `flagged: bool` - Specifies the event type. For a type action, this property is always set to `type`. + A boolean indicating whether the content was flagged by any category. - - `"type"` + - `model: str` - - `class Wait: …` + The moderation model that produced this result. - A wait action. + - `type: Literal["moderation_result"]` - - `type: Literal["wait"]` + The object type, which was always `moderation_result` for successful moderation results. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"moderation_result"` - - `"wait"` + - `class ModerationOutputError: …` - - `actions: Optional[BetaComputerActionList]` + An error produced while attempting moderation for the response input or output. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `code: str` - - `class Click: …` + The error code. - A click action. + - `message: str` - - `class DoubleClick: …` + The error message. - A double click action. + - `type: Literal["error"]` - - `class Drag: …` + The object type, which was always `error` for moderation failures. - A drag action. + - `"error"` - - `class Keypress: …` + - `previous_response_id: Optional[str]` - A collection of keypresses the model would like to perform. + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `class Move: …` + - `prompt: Optional[BetaResponsePrompt]` - A mouse move action. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `class Screenshot: …` + - `id: str` - A screenshot action. + The unique identifier of the prompt template to use. - - `class Scroll: …` + - `variables: Optional[Dict[str, Variables]]` - A scroll action. + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `class Type: …` + - `str` - An action to type in text. + - `class BetaResponseInputText: …` - - `class Wait: …` + A text input to the model. - A wait action. + - `class BetaResponseInputImage: …` - - `agent: Optional[Agent]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The agent that produced this item. + - `class BetaResponseInputFile: …` - - `agent_name: str` + A file input to the model. - The canonical name of the agent that produced this item. + - `version: Optional[str]` - - `class ComputerCallOutput: …` + Optional version of the prompt template. - The output of a computer tool call. + - `prompt_cache_key: Optional[str]` - - `call_id: str` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - The ID of the computer tool call that produced the output. + - `prompt_cache_options: Optional[PromptCacheOptions]` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - A computer screenshot image used with the computer use tool. + - `mode: Literal["implicit", "explicit"]` - - `type: Literal["computer_screenshot"]` + Whether implicit prompt-cache breakpoints were enabled. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"implicit"` - - `"computer_screenshot"` + - `"explicit"` - - `file_id: Optional[str]` + - `ttl: Literal["30m"]` - The identifier of an uploaded file that contains the screenshot. + The minimum lifetime applied to each cache breakpoint. - - `image_url: Optional[str]` + - `"30m"` - The URL of the screenshot image. + - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` - - `type: Literal["computer_call_output"]` + Deprecated. Use `prompt_cache_options.ttl` instead. - The type of the computer tool call output. Always `computer_call_output`. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `"computer_call_output"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `id: Optional[str]` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The ID of the computer tool call output. + - `"in_memory"` - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + - `"24h"` - The safety checks reported by the API that have been acknowledged by the developer. + - `reasoning: Optional[Reasoning]` - - `id: str` + **gpt-5 and o-series models only** - The ID of the pending safety check. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `code: Optional[str]` + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` - The type of the pending safety check. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `message: Optional[str]` + - `"auto"` - Details about the pending safety check. + - `"current_turn"` - - `agent: Optional[ComputerCallOutputAgent]` + - `"all_turns"` - The agent that produced this item. + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` - - `agent_name: str` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - The canonical name of the agent that produced this item. + - `"none"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"minimal"` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `"low"` - - `"in_progress"` + - `"medium"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `"xhigh"` - - `class BetaResponseFunctionWebSearch: …` + - `"max"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` - - `id: str` + **Deprecated:** use `summary` instead. - The unique ID of the web search tool call. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `action: Action` + - `"auto"` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `"concise"` - - `class ActionSearch: …` + - `"detailed"` - Action type "search" - Performs a web search query. + - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` - - `type: Literal["search"]` + Controls the reasoning execution mode for the request. - The action type. + When returned on a response, this is the effective execution mode. - - `"search"` + - `str` - - `queries: Optional[List[str]]` + - `Literal["standard", "pro"]` - The search queries. + Controls the reasoning execution mode for the request. - - `query: Optional[str]` + When returned on a response, this is the effective execution mode. - The search query. + - `"standard"` - - `sources: Optional[List[ActionSearchSource]]` + - `"pro"` - The sources used in the search. + - `summary: Optional[Literal["auto", "concise", "detailed"]]` - - `type: Literal["url"]` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The type of source. Always `url`. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `"url"` + - `"auto"` - - `url: str` + - `"concise"` - The URL of the source. + - `"detailed"` - - `class ActionOpenPage: …` + - `safety_identifier: Optional[str]` - Action type "open_page" - Opens a specific URL from search results. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `type: Literal["open_page"]` + - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` - The action type. + Specifies the processing type used for serving the request. - - `"open_page"` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `url: Optional[str]` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The URL opened by the model. + - `"auto"` - - `class ActionFindInPage: …` + - `"default"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"flex"` - - `pattern: str` + - `"scale"` - The pattern or text to search for within the page. + - `"priority"` - - `type: Literal["find_in_page"]` + - `status: Optional[BetaResponseStatus]` - The action type. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `"find_in_page"` + - `"completed"` - - `url: str` + - `"failed"` - The URL of the page searched for the pattern. + - `"in_progress"` - - `status: Literal["in_progress", "searching", "completed", "failed"]` + - `"cancelled"` - The status of the web search tool call. + - `"queued"` - - `"in_progress"` + - `"incomplete"` - - `"searching"` + - `text: Optional[BetaResponseTextConfig]` - - `"completed"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"failed"` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `type: Literal["web_search_call"]` + - `format: Optional[BetaResponseFormatTextConfig]` - The type of the web search tool call. Always `web_search_call`. + An object specifying the format that the model must output. - - `"web_search_call"` + Configuring `{ "type": "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). - - `agent: Optional[Agent]` + The default format is `{ "type": "text" }` with no additional options. - The agent that produced this item. + **Not recommended for gpt-4o and newer models:** - - `agent_name: str` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - The canonical name of the agent that produced this item. + - `class Text: …` - - `class BetaResponseFunctionToolCall: …` + Default response format. Used to generate text responses. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `type: Literal["text"]` - - `arguments: str` + The type of response format being defined. Always `text`. - A JSON string of the arguments to pass to the function. + - `"text"` - - `call_id: str` + - `class BetaResponseFormatTextJSONSchemaConfig: …` - The unique ID of the function tool call generated by the model. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - `name: str` - The name of the function to run. - - - `type: Literal["function_call"]` + 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. - The type of the function tool call. Always `function_call`. + - `schema: Dict[str, object]` - - `"function_call"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `id: Optional[str]` + - `type: Literal["json_schema"]` - The unique ID of the function tool call. + The type of response format being defined. Always `json_schema`. - - `agent: Optional[Agent]` + - `"json_schema"` - The agent that produced this item. + - `description: Optional[str]` - - `agent_name: str` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The canonical name of the agent that produced this item. + - `strict: Optional[bool]` - - `caller: Optional[Caller]` + 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). - The execution context that produced this tool call. + - `class JSONObject: …` - - `class CallerDirect: …` + 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["direct"]` + - `type: Literal["json_object"]` - - `"direct"` + The type of response format being defined. Always `json_object`. - - `class CallerProgram: …` + - `"json_object"` - - `caller_id: str` + - `verbosity: Optional[Literal["low", "medium", "high"]]` - The call ID of the program item that produced this tool call. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `type: Literal["program"]` + - `"low"` - - `"program"` + - `"medium"` - - `namespace: Optional[str]` + - `"high"` - The namespace of the function to run. + - `top_logprobs: Optional[int]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `truncation: Optional[Literal["auto", "disabled"]]` - - `"in_progress"` + The truncation strategy to use for the model response. - - `"completed"` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `"incomplete"` + - `"auto"` - - `class FunctionCallOutput: …` + - `"disabled"` - The output of a function tool call. + - `usage: Optional[BetaResponseUsage]` - - `call_id: str` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The unique ID of the function tool call generated by the model. + - `input_tokens: int` - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + The number of input tokens. - Text, image, or file output of the function tool call. + - `input_tokens_details: InputTokensDetails` - - `str` + A detailed breakdown of the input tokens. - A JSON string of the output of the function tool call. + - `cache_write_tokens: int` - - `List[BetaResponseFunctionCallOutputItem]` + The number of input tokens that were written to the cache. - - `class BetaResponseInputTextContent: …` + - `cached_tokens: int` - A text input to the model. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `text: str` + - `output_tokens: int` - The text input to the model. + The number of output tokens. - - `type: Literal["input_text"]` + - `output_tokens_details: OutputTokensDetails` - The type of the input item. Always `input_text`. + A detailed breakdown of the output tokens. - - `"input_text"` + - `reasoning_tokens: int` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The number of reasoning tokens. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `total_tokens: int` - - `mode: Literal["explicit"]` + The total number of tokens used. - The breakpoint mode. Always `explicit`. + - `user: Optional[str]` - - `"explicit"` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `class BetaResponseInputImageContent: …` + - `sequence_number: int` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The sequence number of this event. - - `type: Literal["input_image"]` + - `type: Literal["response.failed"]` - The type of the input item. Always `input_image`. + The type of the event. Always `response.failed`. - - `"input_image"` + - `"response.failed"` - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + - `agent: Optional[Agent]` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The agent that owns this multi-agent streaming event. - - `"low"` + - `agent_name: str` - - `"high"` + The canonical name of the agent that produced this item. - - `"auto"` +### Beta Response File Search Call Completed Event - - `"original"` +- `class BetaResponseFileSearchCallCompletedEvent: …` - - `file_id: Optional[str]` + Emitted when a file search call is completed (results found). - The ID of the file to be sent to the model. + - `item_id: str` - - `image_url: Optional[str]` + The ID of the output item that the file search call is initiated. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `output_index: int` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The index of the output item that the file search call is initiated. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `sequence_number: int` - - `mode: Literal["explicit"]` + The sequence number of this event. - The breakpoint mode. Always `explicit`. + - `type: Literal["response.file_search_call.completed"]` - - `"explicit"` + The type of the event. Always `response.file_search_call.completed`. - - `class BetaResponseInputFileContent: …` + - `"response.file_search_call.completed"` - A file input to the model. + - `agent: Optional[Agent]` - - `type: Literal["input_file"]` + The agent that owns this multi-agent streaming event. - The type of the input item. Always `input_file`. + - `agent_name: str` - - `"input_file"` + The canonical name of the agent that produced this item. - - `detail: Optional[Literal["auto", "low", "high"]]` +### Beta Response File Search Call In Progress Event - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. +- `class BetaResponseFileSearchCallInProgressEvent: …` - - `"auto"` + Emitted when a file search call is initiated. - - `"low"` + - `item_id: str` - - `"high"` + The ID of the output item that the file search call is initiated. - - `file_data: Optional[str]` + - `output_index: int` - The base64-encoded data of the file to be sent to the model. + The index of the output item that the file search call is initiated. - - `file_id: Optional[str]` + - `sequence_number: int` - The ID of the file to be sent to the model. + The sequence number of this event. - - `file_url: Optional[str]` + - `type: Literal["response.file_search_call.in_progress"]` - The URL of the file to be sent to the model. + The type of the event. Always `response.file_search_call.in_progress`. - - `filename: Optional[str]` + - `"response.file_search_call.in_progress"` - The name of the file to be sent to the model. + - `agent: Optional[Agent]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The agent that owns this multi-agent streaming event. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `agent_name: str` - - `mode: Literal["explicit"]` + The canonical name of the agent that produced this item. - The breakpoint mode. Always `explicit`. +### Beta Response File Search Call Searching Event - - `"explicit"` +- `class BetaResponseFileSearchCallSearchingEvent: …` - - `type: Literal["function_call_output"]` + Emitted when a file search is currently searching. - The type of the function tool call output. Always `function_call_output`. + - `item_id: str` - - `"function_call_output"` + The ID of the output item that the file search call is initiated. - - `id: Optional[str]` + - `output_index: int` - The unique ID of the function tool call output. Populated when this item is returned via API. + The index of the output item that the file search call is searching. - - `agent: Optional[FunctionCallOutputAgent]` + - `sequence_number: int` - The agent that produced this item. + The sequence number of this event. - - `agent_name: str` + - `type: Literal["response.file_search_call.searching"]` - The canonical name of the agent that produced this item. + The type of the event. Always `response.file_search_call.searching`. - - `caller: Optional[FunctionCallOutputCaller]` + - `"response.file_search_call.searching"` - The execution context that produced this tool call. + - `agent: Optional[Agent]` - - `class FunctionCallOutputCallerDirect: …` + The agent that owns this multi-agent streaming event. - - `type: Literal["direct"]` + - `agent_name: str` - The caller type. Always `direct`. + The canonical name of the agent that produced this item. - - `"direct"` +### Beta Response File Search Tool Call - - `class FunctionCallOutputCallerProgram: …` +- `class BetaResponseFileSearchToolCall: …` - - `caller_id: str` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The call ID of the program item that produced this tool call. + - `id: str` - - `type: Literal["program"]` + The unique ID of the file search tool call. - The caller type. Always `program`. + - `queries: List[str]` - - `"program"` + The queries used to search for files. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `"in_progress"` + - `"searching"` + - `"completed"` - `"incomplete"` - - `class AgentMessage: …` + - `"failed"` - A message routed between agents. + - `type: Literal["file_search_call"]` - - `author: str` + The type of the file search tool call. Always `file_search_call`. - The sending agent identity. + - `"file_search_call"` - - `content: List[AgentMessageContent]` + - `agent: Optional[Agent]` - Plaintext, image, or encrypted content sent between agents. + The agent that produced this item. - - `class BetaResponseInputTextContent: …` + - `agent_name: str` - A text input to the model. + The canonical name of the agent that produced this item. - - `class BetaResponseInputImageContent: …` + - `results: Optional[List[Result]]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The results of the file search tool call. - - `class AgentMessageContentEncryptedContent: …` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + 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, booleans, or numbers. - - `encrypted_content: str` + - `str` - Opaque encrypted content. + - `float` - - `type: Literal["encrypted_content"]` + - `bool` - The type of the input item. Always `encrypted_content`. + - `file_id: Optional[str]` - - `"encrypted_content"` + The unique ID of the file. - - `recipient: str` + - `filename: Optional[str]` - The destination agent identity. + The name of the file. - - `type: Literal["agent_message"]` + - `score: Optional[float]` - The item type. Always `agent_message`. + The relevance score of the file - a value between 0 and 1. - - `"agent_message"` + - `text: Optional[str]` - - `id: Optional[str]` + The text that was retrieved from the file. - The unique ID of this agent message item. +### Beta Response Format Text Config - - `agent: Optional[AgentMessageAgent]` +- `BetaResponseFormatTextConfig` - The agent that produced this item. + An object specifying the format that the model must output. - - `agent_name: str` + Configuring `{ "type": "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). - The canonical name of the agent that produced this item. + The default format is `{ "type": "text" }` with no additional options. - - `class MultiAgentCall: …` + **Not recommended for gpt-4o and newer models:** - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - The multi-agent action that was executed. + - `class Text: …` - - `"spawn_agent"` + Default response format. Used to generate text responses. - - `"interrupt_agent"` + - `type: Literal["text"]` - - `"list_agents"` + The type of response format being defined. Always `text`. - - `"send_message"` + - `"text"` - - `"followup_task"` + - `class BetaResponseFormatTextJSONSchemaConfig: …` - - `"wait_agent"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `arguments: str` + - `name: str` - The action arguments as a JSON string. + 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. - - `call_id: str` + - `schema: Dict[str, object]` - The unique ID linking this call to its output. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `type: Literal["multi_agent_call"]` + - `type: Literal["json_schema"]` - The item type. Always `multi_agent_call`. + The type of response format being defined. Always `json_schema`. - - `"multi_agent_call"` + - `"json_schema"` - - `id: Optional[str]` + - `description: Optional[str]` - The unique ID of this multi-agent call. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `agent: Optional[MultiAgentCallAgent]` + - `strict: Optional[bool]` - The agent that produced this item. + 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). - - `agent_name: str` + - `class JSONObject: …` - The canonical name of the agent that produced this item. + 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. - - `class MultiAgentCallOutput: …` + - `type: Literal["json_object"]` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The type of response format being defined. Always `json_object`. - The multi-agent action that produced this result. + - `"json_object"` - - `"spawn_agent"` +### Beta Response Format Text JSON Schema Config - - `"interrupt_agent"` +- `class BetaResponseFormatTextJSONSchemaConfig: …` - - `"list_agents"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `"send_message"` + - `name: str` - - `"followup_task"` + 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. - - `"wait_agent"` + - `schema: Dict[str, object]` - - `call_id: str` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The unique ID of the multi-agent call. + - `type: Literal["json_schema"]` - - `output: List[MultiAgentCallOutputOutput]` + The type of response format being defined. Always `json_schema`. - Text output returned by the multi-agent action. + - `"json_schema"` - - `text: str` + - `description: Optional[str]` - The text content. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: Literal["output_text"]` + - `strict: Optional[bool]` - The content type. Always `output_text`. + 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). - - `"output_text"` +### Beta Response Function Call Arguments Delta Event - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` +- `class BetaResponseFunctionCallArgumentsDeltaEvent: …` - Citations associated with the text content. + Emitted when there is a partial function-call arguments delta. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + - `delta: str` - - `file_id: str` + The function-call arguments delta that is added. - The ID of the file. + - `item_id: str` - - `filename: str` + The ID of the output item that the function-call arguments delta is added to. - The filename of the file cited. + - `output_index: int` - - `index: int` + The index of the output item that the function-call arguments delta is added to. - The index of the file in the list of files. + - `sequence_number: int` - - `type: Literal["file_citation"]` + The sequence number of this event. - The citation type. Always `file_citation`. + - `type: Literal["response.function_call_arguments.delta"]` - - `"file_citation"` + The type of the event. Always `response.function_call_arguments.delta`. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + - `"response.function_call_arguments.delta"` - - `end_index: int` + - `agent: Optional[Agent]` - The index of the last character of the citation in the message. + The agent that owns this multi-agent streaming event. - - `start_index: int` + - `agent_name: str` - The index of the first character of the citation in the message. + The canonical name of the agent that produced this item. - - `title: str` +### Beta Response Function Call Arguments Done Event - The title of the cited resource. +- `class BetaResponseFunctionCallArgumentsDoneEvent: …` - - `type: Literal["url_citation"]` + Emitted when function-call arguments are finalized. - The citation type. Always `url_citation`. + - `arguments: str` - - `"url_citation"` + The function-call arguments. - - `url: str` + - `item_id: str` - The URL of the cited resource. + The ID of the item. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `name: str` - - `container_id: str` + The name of the function that was called. - The ID of the container. + - `output_index: int` - - `end_index: int` + The index of the output item. - The index of the last character of the citation in the message. + - `sequence_number: int` - - `file_id: str` + The sequence number of this event. - The ID of the container file. + - `type: Literal["response.function_call_arguments.done"]` - - `filename: str` + - `"response.function_call_arguments.done"` - The filename of the container file cited. + - `agent: Optional[Agent]` - - `start_index: int` + The agent that owns this multi-agent streaming event. - The index of the first character of the citation in the message. + - `agent_name: str` - - `type: Literal["container_file_citation"]` + The canonical name of the agent that produced this item. - The citation type. Always `container_file_citation`. +### Beta Response Function Call Output Item - - `"container_file_citation"` +- `BetaResponseFunctionCallOutputItem` - - `type: Literal["multi_agent_call_output"]` + A piece of message content, such as text, an image, or a file. - The item type. Always `multi_agent_call_output`. + - `class BetaResponseInputTextContent: …` - - `"multi_agent_call_output"` + A text input to the model. - - `id: Optional[str]` + - `text: str` - The unique ID of this multi-agent call output. + The text input to the model. - - `agent: Optional[MultiAgentCallOutputAgent]` + - `type: Literal["input_text"]` - The agent that produced this item. + The type of the input item. Always `input_text`. - - `agent_name: str` + - `"input_text"` - The canonical name of the agent that produced this item. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `class ToolSearchCall: …` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `arguments: object` + - `mode: Literal["explicit"]` - The arguments supplied to the tool search call. + The breakpoint mode. Always `explicit`. - - `type: Literal["tool_search_call"]` + - `"explicit"` - The item type. Always `tool_search_call`. + - `class BetaResponseInputImageContent: …` - - `"tool_search_call"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `id: Optional[str]` + - `type: Literal["input_image"]` - The unique ID of this tool search call. + The type of the input item. Always `input_image`. - - `agent: Optional[ToolSearchCallAgent]` + - `"input_image"` - The agent that produced this item. + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - - `agent_name: str` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The canonical name of the agent that produced this item. + - `"low"` - - `call_id: Optional[str]` + - `"high"` - The unique ID of the tool search call generated by the model. + - `"auto"` - - `execution: Optional[Literal["server", "client"]]` + - `"original"` - Whether tool search was executed by the server or by the client. + - `file_id: Optional[str]` - - `"server"` + The ID of the file to be sent to the model. - - `"client"` + - `image_url: Optional[str]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The status of the tool search call. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"in_progress"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"completed"` + - `mode: Literal["explicit"]` - - `"incomplete"` + The breakpoint mode. Always `explicit`. - - `class BetaResponseToolSearchOutputItemParam: …` + - `"explicit"` - - `tools: List[BetaTool]` + - `class BetaResponseInputFileContent: …` - The loaded tool definitions returned by the tool search output. + A file input to the model. - - `class BetaFunctionTool: …` + - `type: Literal["input_file"]` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The type of the input item. Always `input_file`. - - `name: str` + - `"input_file"` - The name of the function to call. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `parameters: Optional[Dict[str, object]]` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - A JSON schema object describing the parameters of the function. + - `"auto"` - - `strict: Optional[bool]` + - `"low"` - Whether strict parameter validation is enforced for this function tool. + - `"high"` - - `type: Literal["function"]` + - `file_data: Optional[str]` - The type of the function tool. Always `function`. + The base64-encoded data of the file to be sent to the model. - - `"function"` + - `file_id: Optional[str]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The ID of the file to be sent to the model. - The tool invocation context(s). + - `file_url: Optional[str]` - - `"direct"` + The URL of the file to be sent to the model. - - `"programmatic"` + - `filename: Optional[str]` - - `defer_loading: Optional[bool]` + The name of the file to be sent to the model. - Whether this function is deferred and loaded via tool search. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `description: Optional[str]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - A description of the function. Used by the model to determine whether or not to call the function. + - `mode: Literal["explicit"]` - - `output_schema: Optional[Dict[str, object]]` + The breakpoint mode. Always `explicit`. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"explicit"` - - `class BetaFileSearchTool: …` +### Beta Response Function Call Output Item List - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). +- `List[BetaResponseFunctionCallOutputItem]` - - `type: Literal["file_search"]` + An array of content outputs (text, image, file) for the function tool call. - The type of the file search tool. Always `file_search`. + - `class BetaResponseInputTextContent: …` - - `"file_search"` + A text input to the model. - - `vector_store_ids: List[str]` + - `text: str` - The IDs of the vector stores to search. + The text input to the model. - - `filters: Optional[Filters]` + - `type: Literal["input_text"]` - A filter to apply. + The type of the input item. Always `input_text`. - - `class FiltersComparisonFilter: …` + - `"input_text"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `key: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The key to compare against the value. + - `mode: Literal["explicit"]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The breakpoint mode. Always `explicit`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"explicit"` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `class BetaResponseInputImageContent: …` - - `"eq"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `"ne"` + - `type: Literal["input_image"]` - - `"gt"` + The type of the input item. Always `input_image`. - - `"gte"` + - `"input_image"` - - `"lt"` + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - - `"lte"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"in"` + - `"low"` - - `"nin"` + - `"high"` - - `value: Union[str, float, bool, List[object]]` + - `"auto"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"original"` - - `str` + - `file_id: Optional[str]` - - `float` + The ID of the file to be sent to the model. - - `bool` + - `image_url: Optional[str]` - - `List[object]` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `class FiltersCompoundFilter: …` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Combine multiple filters using `and` or `or`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `filters: List[FiltersCompoundFilterFilter]` + - `mode: Literal["explicit"]` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The breakpoint mode. Always `explicit`. - - `class FiltersCompoundFilterFilterComparisonFilter: …` + - `"explicit"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `class BetaResponseInputFileContent: …` - - `key: str` + A file input to the model. - The key to compare against the value. + - `type: Literal["input_file"]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The type of the input item. Always `input_file`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"input_file"` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"eq"` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `"ne"` + - `"auto"` - - `"gt"` + - `"low"` - - `"gte"` + - `"high"` - - `"lt"` + - `file_data: Optional[str]` - - `"lte"` + The base64-encoded data of the file to be sent to the model. - - `"in"` + - `file_id: Optional[str]` - - `"nin"` + The ID of the file to be sent to the model. - - `value: Union[str, float, bool, List[object]]` + - `file_url: Optional[str]` - The value to compare against the attribute key; supports string, number, or boolean types. + The URL of the file to be sent to the model. - - `str` + - `filename: Optional[str]` - - `float` + The name of the file to be sent to the model. - - `bool` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `List[object]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `object` + - `mode: Literal["explicit"]` - - `type: Literal["and", "or"]` + The breakpoint mode. Always `explicit`. - Type of operation: `and` or `or`. + - `"explicit"` - - `"and"` +### Beta Response Function Shell Call Output Content - - `"or"` +- `class BetaResponseFunctionShellCallOutputContent: …` - - `max_num_results: Optional[int]` + Captured stdout and stderr for a portion of a shell tool call output. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `outcome: Outcome` - - `ranking_options: Optional[RankingOptions]` + The exit or timeout outcome associated with this shell call. - Ranking options for search. + - `class OutcomeTimeout: …` - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + Indicates that the shell call exceeded its configured time limit. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `type: Literal["timeout"]` - - `embedding_weight: float` + The outcome type. Always `timeout`. - The weight of the embedding in the reciprocal ranking fusion. + - `"timeout"` - - `text_weight: float` + - `class OutcomeExit: …` - The weight of the text in the reciprocal ranking fusion. + Indicates that the shell commands finished and returned an exit code. - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + - `exit_code: int` - The ranker to use for the file search. + The exit code returned by the shell process. - - `"auto"` + - `type: Literal["exit"]` - - `"default-2024-11-15"` + The outcome type. Always `exit`. - - `score_threshold: Optional[float]` + - `"exit"` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `stderr: str` - - `class BetaComputerTool: …` + Captured stderr output for the shell call. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `stdout: str` - - `type: Literal["computer"]` + Captured stdout output for the shell call. - The type of the computer tool. Always `computer`. +### Beta Response Function Shell Tool Call - - `"computer"` +- `class BetaResponseFunctionShellToolCall: …` - - `class BetaComputerUsePreviewTool: …` + A tool call that executes one or more shell commands in a managed environment. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `id: str` - - `display_height: int` + The unique ID of the shell tool call. Populated when this item is returned via API. - The height of the computer display. + - `action: Action` - - `display_width: int` + The shell commands and limits that describe how to run the tool call. - The width of the computer display. + - `commands: List[str]` - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `max_output_length: Optional[int]` - The type of computer environment to control. + Optional maximum number of characters to return from each command. - - `"windows"` + - `timeout_ms: Optional[int]` - - `"mac"` + Optional timeout in milliseconds for the commands. - - `"linux"` + - `call_id: str` - - `"ubuntu"` + The unique ID of the shell tool call generated by the model. - - `"browser"` + - `environment: Optional[Environment]` - - `type: Literal["computer_use_preview"]` + Represents the use of a local environment to perform shell actions. - The type of the computer use tool. Always `computer_use_preview`. + - `class BetaResponseLocalEnvironment: …` - - `"computer_use_preview"` + Represents the use of a local environment to perform shell actions. - - `class BetaWebSearchTool: …` + - `type: Literal["local"]` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The environment type. Always `local`. - - `type: Literal["web_search", "web_search_2025_08_26"]` + - `"local"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `class BetaResponseContainerReference: …` - - `"web_search"` + Represents a container created with /v1/containers. - - `"web_search_2025_08_26"` + - `container_id: str` - - `filters: Optional[Filters]` + - `type: Literal["container_reference"]` - Filters for the search. + The environment type. Always `container_reference`. - - `allowed_domains: Optional[List[str]]` + - `"container_reference"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `status: Literal["in_progress", "completed", "incomplete"]` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `"in_progress"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"completed"` - - `"low"` + - `"incomplete"` - - `"medium"` + - `type: Literal["shell_call"]` - - `"high"` + The type of the item. Always `shell_call`. - - `user_location: Optional[UserLocation]` + - `"shell_call"` - The approximate location of the user. + - `agent: Optional[Agent]` - - `city: Optional[str]` + The agent that produced this item. - Free text input for the city of the user, e.g. `San Francisco`. + - `agent_name: str` - - `country: Optional[str]` + The canonical name of the agent that produced this item. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `caller: Optional[Caller]` - - `region: Optional[str]` + The execution context that produced this tool call. - Free text input for the region of the user, e.g. `California`. + - `class CallerDirect: …` - - `timezone: Optional[str]` + - `type: Literal["direct"]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"direct"` - - `type: Optional[Literal["approximate"]]` + - `class CallerProgram: …` - The type of location approximation. Always `approximate`. + - `caller_id: str` - - `"approximate"` + The call ID of the program item that produced this tool call. - - `class Mcp: …` + - `type: Literal["program"]` + + - `"program"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `created_by: Optional[str]` - - `server_label: str` + The ID of the entity that created this tool call. - A label for this MCP server, used to identify it in tool calls. +### Beta Response Function Shell Tool Call Output - - `type: Literal["mcp"]` +- `class BetaResponseFunctionShellToolCallOutput: …` - The type of the MCP tool. Always `mcp`. + The output of a shell tool call that was emitted. - - `"mcp"` + - `id: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The unique ID of the shell call output. Populated when this item is returned via API. - The tool invocation context(s). + - `call_id: str` - - `"direct"` + The unique ID of the shell tool call generated by the model. - - `"programmatic"` + - `max_output_length: Optional[int]` - - `allowed_tools: Optional[McpAllowedTools]` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - List of allowed tool names or a filter object. + - `output: List[Output]` - - `List[str]` + An array of shell call output contents - A string array of allowed tool names + - `outcome: OutputOutcome` - - `class McpAllowedToolsMcpToolFilter: …` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - A filter object to specify which tools are allowed. + - `class OutputOutcomeTimeout: …` - - `read_only: Optional[bool]` + Indicates that the shell call exceeded its configured time limit. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `type: Literal["timeout"]` - - `tool_names: Optional[List[str]]` + The outcome type. Always `timeout`. - List of allowed tool names. + - `"timeout"` - - `authorization: Optional[str]` + - `class OutputOutcomeExit: …` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + Indicates that the shell commands finished and returned an exit code. - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + - `exit_code: int` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + Exit code from the shell process. - Currently supported `connector_id` values are: + - `type: Literal["exit"]` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The outcome type. Always `exit`. - - `"connector_dropbox"` + - `"exit"` - - `"connector_gmail"` + - `stderr: str` - - `"connector_googlecalendar"` + The standard error output that was captured. - - `"connector_googledrive"` + - `stdout: str` - - `"connector_microsoftteams"` + The standard output that was captured. - - `"connector_outlookcalendar"` + - `created_by: Optional[str]` - - `"connector_outlookemail"` + The identifier of the actor that created the item. - - `"connector_sharepoint"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `defer_loading: Optional[bool]` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - Whether this MCP tool is deferred and discovered via tool search. + - `"in_progress"` - - `headers: Optional[Dict[str, str]]` + - `"completed"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"incomplete"` - - `require_approval: Optional[McpRequireApproval]` + - `type: Literal["shell_call_output"]` - Specify which of the MCP server's tools require approval. + The type of the shell call output. Always `shell_call_output`. - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `"shell_call_output"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `agent: Optional[Agent]` - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + The agent that produced this item. - A filter object to specify which tools are allowed. + - `agent_name: str` - - `read_only: Optional[bool]` + The canonical name of the agent that produced this item. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `caller: Optional[Caller]` - - `tool_names: Optional[List[str]]` + The execution context that produced this tool call. - List of allowed tool names. + - `class CallerDirect: …` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + - `type: Literal["direct"]` - A filter object to specify which tools are allowed. + - `"direct"` - - `read_only: Optional[bool]` + - `class CallerProgram: …` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `caller_id: str` - - `tool_names: Optional[List[str]]` + The call ID of the program item that produced this tool call. - List of allowed tool names. + - `type: Literal["program"]` - - `Literal["always", "never"]` + - `"program"` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `created_by: Optional[str]` - - `"always"` + The identifier of the actor that created the item. - - `"never"` +### Beta Response Function Tool Call - - `server_description: Optional[str]` +- `class BetaResponseFunctionToolCall: …` - Optional description of the MCP server, used to provide more context. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `server_url: Optional[str]` + - `arguments: str` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + A JSON string of the arguments to pass to the function. - - `tunnel_id: Optional[str]` + - `call_id: str` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + The unique ID of the function tool call generated by the model. - - `class CodeInterpreter: …` + - `name: str` - A tool that runs Python code to help generate a response to a prompt. + The name of the function to run. - - `container: CodeInterpreterContainer` + - `type: Literal["function_call"]` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The type of the function tool call. Always `function_call`. - - `str` + - `"function_call"` - The container ID. + - `id: Optional[str]` - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + The unique ID of the function tool call. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `agent: Optional[Agent]` - - `type: Literal["auto"]` + The agent that produced this item. - Always `auto`. + - `agent_name: str` - - `"auto"` + The canonical name of the agent that produced this item. - - `file_ids: Optional[List[str]]` + - `caller: Optional[Caller]` - An optional list of uploaded files to make available to your code. + The execution context that produced this tool call. - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `class CallerDirect: …` - The memory limit for the code interpreter container. + - `type: Literal["direct"]` - - `"1g"` + - `"direct"` - - `"4g"` + - `class CallerProgram: …` - - `"16g"` + - `caller_id: str` - - `"64g"` + The call ID of the program item that produced this tool call. - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `type: Literal["program"]` - Network access policy for the container. + - `"program"` - - `class BetaContainerNetworkPolicyDisabled: …` + - `namespace: Optional[str]` - - `type: Literal["disabled"]` + The namespace of the function to run. - Disable outbound network access. Always `disabled`. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"disabled"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `"in_progress"` - - `allowed_domains: List[str]` + - `"completed"` - A list of allowed domains when type is `allowlist`. + - `"incomplete"` - - `type: Literal["allowlist"]` +### Beta Response Function Tool Call Item - Allow outbound network access only to specified domains. Always `allowlist`. +- `class BetaResponseFunctionToolCallItem: …` - - `"allowlist"` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `id: str` - Optional domain-scoped secrets for allowlisted domains. + The unique ID of the function tool call. - - `domain: str` + - `status: Literal["in_progress", "completed", "incomplete"]` - The domain associated with the secret. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `name: str` + - `"in_progress"` - The name of the secret to inject for the domain. + - `"completed"` - - `value: str` + - `"incomplete"` - The secret value to inject for the domain. + - `created_by: Optional[str]` - - `type: Literal["code_interpreter"]` + The identifier of the actor that created the item. - The type of the code interpreter tool. Always `code_interpreter`. +### Beta Response Function Tool Call Output Item - - `"code_interpreter"` +- `class BetaResponseFunctionToolCallOutputItem: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `id: str` - The tool invocation context(s). + The unique ID of the function call tool output. - - `"direct"` + - `call_id: str` - - `"programmatic"` + The unique ID of the function tool call generated by the model. - - `class ProgrammaticToolCalling: …` + - `output: Union[str, List[OutputOutputContentList]]` - - `type: Literal["programmatic_tool_calling"]` + The output from the function call generated by your code. + Can be a string or an list of output content. - The type of the tool. Always `programmatic_tool_calling`. + - `str` - - `"programmatic_tool_calling"` + A string of the output of the function call. - - `class ImageGeneration: …` + - `List[OutputOutputContentList]` - A tool that generates images using the GPT image models. + Text, image, or file output of the function call. - - `type: Literal["image_generation"]` + - `class BetaResponseInputText: …` - The type of the image generation tool. Always `image_generation`. + A text input to the model. - - `"image_generation"` + - `text: str` - - `action: Optional[Literal["generate", "edit", "auto"]]` + The text input to the model. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `type: Literal["input_text"]` - - `"generate"` + The type of the input item. Always `input_text`. - - `"edit"` + - `"input_text"` - - `"auto"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `mode: Literal["explicit"]` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The breakpoint mode. Always `explicit`. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"explicit"` - - `"transparent"` + - `class BetaResponseInputImage: …` - - `"opaque"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"auto"` + - `detail: Literal["low", "high", "auto", "original"]` - - `input_fidelity: Optional[Literal["high", "low"]]` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `"low"` - `"high"` - - `"low"` + - `"auto"` - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + - `"original"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `type: Literal["input_image"]` + + The type of the input item. Always `input_image`. + + - `"input_image"` - `file_id: Optional[str]` - File ID for the mask image. + The ID of the file to be sent to the model. - `image_url: Optional[str]` - Base64-encoded mask image. - - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The image generation model to use. Default: `gpt-image-1`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `mode: Literal["explicit"]` - The image generation model to use. Default: `gpt-image-1`. + The breakpoint mode. Always `explicit`. - - `"gpt-image-1"` + - `"explicit"` - - `"gpt-image-1-mini"` + - `class BetaResponseInputFile: …` - - `"gpt-image-2"` + A file input to the model. - - `"gpt-image-2-2026-04-21"` + - `type: Literal["input_file"]` - - `"gpt-image-1.5"` + The type of the input item. Always `input_file`. - - `"chatgpt-image-latest"` + - `"input_file"` - - `moderation: Optional[Literal["auto", "low"]]` + - `detail: Optional[Literal["auto", "low", "high"]]` - Moderation level for the generated image. Default: `auto`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - `"auto"` - `"low"` - - `output_compression: Optional[int]` - - Compression level for the output image. Default: 100. - - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. - - - `"png"` - - - `"webp"` + - `"high"` - - `"jpeg"` + - `file_data: Optional[str]` - - `partial_images: Optional[int]` + The content of the file to be sent to the model. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `file_id: Optional[str]` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + The ID of the file to be sent to the model. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `file_url: Optional[str]` - - `"low"` + The URL of the file to be sent to the model. - - `"medium"` + - `filename: Optional[str]` - - `"high"` + The name of the file to be sent to the model. - - `"auto"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `mode: Literal["explicit"]` - - `str` + The breakpoint mode. Always `explicit`. - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `"explicit"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"1024x1024"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"1024x1536"` + - `"in_progress"` - - `"1536x1024"` + - `"completed"` - - `"auto"` + - `"incomplete"` - - `class LocalShell: …` + - `type: Literal["function_call_output"]` - A tool that allows the model to execute shell commands in a local environment. + The type of the function tool call output. Always `function_call_output`. - - `type: Literal["local_shell"]` + - `"function_call_output"` - The type of the local shell tool. Always `local_shell`. + - `agent: Optional[Agent]` - - `"local_shell"` + The agent that produced this item. - - `class BetaFunctionShellTool: …` + - `agent_name: str` - A tool that allows the model to execute shell commands. + The canonical name of the agent that produced this item. - - `type: Literal["shell"]` + - `caller: Optional[Caller]` - The type of the shell tool. Always `shell`. + The execution context that produced this tool call. - - `"shell"` + - `class CallerDirect: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["direct"]` - The tool invocation context(s). + The caller type. Always `direct`. - `"direct"` - - `"programmatic"` + - `class CallerProgram: …` - - `environment: Optional[Environment]` + - `caller_id: str` - - `class BetaContainerAuto: …` + The call ID of the program item that produced this tool call. - - `type: Literal["container_auto"]` + - `type: Literal["program"]` - Automatically creates a container for this request + The caller type. Always `program`. - - `"container_auto"` + - `"program"` - - `file_ids: Optional[List[str]]` + - `created_by: Optional[str]` - An optional list of uploaded files to make available to your code. + The identifier of the actor that created the item. - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` +### Beta Response Function Web Search - The memory limit for the container. +- `class BetaResponseFunctionWebSearch: …` - - `"1g"` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `"4g"` + - `id: str` - - `"16g"` + The unique ID of the web search tool call. - - `"64g"` + - `action: Action` - - `network_policy: Optional[NetworkPolicy]` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - Network access policy for the container. + - `class ActionSearch: …` - - `class BetaContainerNetworkPolicyDisabled: …` + Action type "search" - Performs a web search query. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `type: Literal["search"]` - - `skills: Optional[List[Skill]]` + The action type. - An optional list of skills referenced by id or inline data. + - `"search"` - - `class BetaSkillReference: …` + - `queries: Optional[List[str]]` - - `skill_id: str` + The search queries. - The ID of the referenced skill. + - `query: Optional[str]` - - `type: Literal["skill_reference"]` + The search query. - References a skill created with the /v1/skills endpoint. + - `sources: Optional[List[ActionSearchSource]]` - - `"skill_reference"` + The sources used in the search. - - `version: Optional[str]` + - `type: Literal["url"]` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The type of source. Always `url`. - - `class BetaInlineSkill: …` + - `"url"` - - `description: str` + - `url: str` - The description of the skill. + The URL of the source. - - `name: str` + - `class ActionOpenPage: …` - The name of the skill. + Action type "open_page" - Opens a specific URL from search results. - - `source: BetaInlineSkillSource` + - `type: Literal["open_page"]` - Inline skill payload + The action type. - - `data: str` + - `"open_page"` - Base64-encoded skill zip bundle. + - `url: Optional[str]` - - `media_type: Literal["application/zip"]` + The URL opened by the model. - The media type of the inline skill payload. Must be `application/zip`. + - `class ActionFindInPage: …` - - `"application/zip"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `type: Literal["base64"]` + - `pattern: str` - The type of the inline skill source. Must be `base64`. + The pattern or text to search for within the page. - - `"base64"` + - `type: Literal["find_in_page"]` - - `type: Literal["inline"]` + The action type. - Defines an inline skill for this request. + - `"find_in_page"` - - `"inline"` + - `url: str` - - `class BetaLocalEnvironment: …` + The URL of the page searched for the pattern. - - `type: Literal["local"]` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - Use a local computer environment. + The status of the web search tool call. - - `"local"` + - `"in_progress"` - - `skills: Optional[List[BetaLocalSkill]]` + - `"searching"` - An optional list of skills. + - `"completed"` - - `description: str` + - `"failed"` - The description of the skill. + - `type: Literal["web_search_call"]` - - `name: str` + The type of the web search tool call. Always `web_search_call`. - The name of the skill. + - `"web_search_call"` - - `path: str` + - `agent: Optional[Agent]` - The path to the directory containing the skill. + The agent that produced this item. - - `class BetaContainerReference: …` + - `agent_name: str` - - `container_id: str` + The canonical name of the agent that produced this item. - The ID of the referenced container. +### Beta Response Image Gen Call Completed Event - - `type: Literal["container_reference"]` +- `class BetaResponseImageGenCallCompletedEvent: …` - References a container created with the /v1/containers endpoint + Emitted when an image generation tool call has completed and the final image is available. - - `"container_reference"` + - `item_id: str` - - `class BetaCustomTool: …` + The unique identifier of the image generation item being processed. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `output_index: int` - - `name: str` + The index of the output item in the response's output array. - The name of the custom tool, used to identify it in tool calls. + - `sequence_number: int` - - `type: Literal["custom"]` + The sequence number of this event. - The type of the custom tool. Always `custom`. + - `type: Literal["response.image_generation_call.completed"]` - - `"custom"` + The type of the event. Always 'response.image_generation_call.completed'. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"response.image_generation_call.completed"` - The tool invocation context(s). + - `agent: Optional[Agent]` - - `"direct"` + The agent that owns this multi-agent streaming event. - - `"programmatic"` + - `agent_name: str` - - `defer_loading: Optional[bool]` + The canonical name of the agent that produced this item. - Whether this tool should be deferred and discovered via tool search. +### Beta Response Image Gen Call Generating Event - - `description: Optional[str]` +- `class BetaResponseImageGenCallGeneratingEvent: …` - Optional description of the custom tool, used to provide more context. + Emitted when an image generation tool call is actively generating an image (intermediate state). - - `format: Optional[Format]` + - `item_id: str` - The input format for the custom tool. Default is unconstrained text. + The unique identifier of the image generation item being processed. - - `class FormatText: …` + - `output_index: int` - Unconstrained free-form text. + The index of the output item in the response's output array. - - `type: Literal["text"]` + - `sequence_number: int` - Unconstrained text format. Always `text`. + The sequence number of the image generation item being processed. - - `"text"` + - `type: Literal["response.image_generation_call.generating"]` - - `class FormatGrammar: …` + The type of the event. Always 'response.image_generation_call.generating'. - A grammar defined by the user. + - `"response.image_generation_call.generating"` - - `definition: str` + - `agent: Optional[Agent]` - The grammar definition. + The agent that owns this multi-agent streaming event. - - `syntax: Literal["lark", "regex"]` + - `agent_name: str` - The syntax of the grammar definition. One of `lark` or `regex`. + The canonical name of the agent that produced this item. - - `"lark"` +### Beta Response Image Gen Call In Progress Event - - `"regex"` +- `class BetaResponseImageGenCallInProgressEvent: …` - - `type: Literal["grammar"]` + Emitted when an image generation tool call is in progress. - Grammar format. Always `grammar`. + - `item_id: str` - - `"grammar"` + The unique identifier of the image generation item being processed. - - `class BetaNamespaceTool: …` + - `output_index: int` - Groups function/custom tools under a shared namespace. + The index of the output item in the response's output array. - - `description: str` + - `sequence_number: int` - A description of the namespace shown to the model. + The sequence number of the image generation item being processed. - - `name: str` + - `type: Literal["response.image_generation_call.in_progress"]` - The namespace name used in tool calls (for example, `crm`). + The type of the event. Always 'response.image_generation_call.in_progress'. - - `tools: List[Tool]` + - `"response.image_generation_call.in_progress"` - The function/custom tools available inside this namespace. + - `agent: Optional[Agent]` - - `class ToolFunction: …` + The agent that owns this multi-agent streaming event. - - `name: str` + - `agent_name: str` - - `type: Literal["function"]` + The canonical name of the agent that produced this item. - - `"function"` +### Beta Response Image Gen Call Partial Image Event - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` +- `class BetaResponseImageGenCallPartialImageEvent: …` - The tool invocation context(s). + Emitted when a partial image is available during image generation streaming. - - `"direct"` + - `item_id: str` - - `"programmatic"` + The unique identifier of the image generation item being processed. - - `defer_loading: Optional[bool]` + - `output_index: int` - Whether this function should be deferred and discovered via tool search. + The index of the output item in the response's output array. - - `description: Optional[str]` + - `partial_image_b64: str` - - `output_schema: Optional[Dict[str, object]]` + Base64-encoded partial image data, suitable for rendering as an image. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `partial_image_index: int` - - `parameters: Optional[object]` + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - - `strict: Optional[bool]` + - `sequence_number: int` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The sequence number of the image generation item being processed. - - `class BetaCustomTool: …` + - `type: Literal["response.image_generation_call.partial_image"]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The type of the event. Always 'response.image_generation_call.partial_image'. - - `type: Literal["namespace"]` + - `"response.image_generation_call.partial_image"` - The type of the tool. Always `namespace`. + - `agent: Optional[Agent]` - - `"namespace"` + The agent that owns this multi-agent streaming event. - - `class BetaToolSearchTool: …` + - `agent_name: str` - Hosted or BYOT tool search configuration for deferred tools. + The canonical name of the agent that produced this item. - - `type: Literal["tool_search"]` +### Beta Response In Progress Event - The type of the tool. Always `tool_search`. +- `class BetaResponseInProgressEvent: …` - - `"tool_search"` + Emitted when the response is in progress. - - `description: Optional[str]` + - `response: BetaResponse` - Description shown to the model for a client-executed tool search tool. + The response that is in progress. - - `execution: Optional[Literal["server", "client"]]` + - `id: str` - Whether tool search is executed by the server or by the client. + Unique identifier for this Response. - - `"server"` + - `created_at: float` - - `"client"` + Unix timestamp (in seconds) of when this Response was created. - - `parameters: Optional[object]` + - `error: Optional[BetaResponseError]` - Parameter schema for a client-executed tool search tool. + An error object returned when the model fails to generate a Response. - - `class BetaWebSearchPreviewTool: …` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The error code for the response. - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + - `"server_error"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `"rate_limit_exceeded"` - - `"web_search_preview"` + - `"invalid_prompt"` - - `"web_search_preview_2025_03_11"` + - `"bio_policy"` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + - `"vector_store_timeout"` - - `"text"` + - `"invalid_image"` - - `"image"` + - `"invalid_image_format"` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `"invalid_base64_image"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"invalid_image_url"` - - `"low"` + - `"image_too_large"` - - `"medium"` + - `"image_too_small"` - - `"high"` + - `"image_parse_error"` - - `user_location: Optional[UserLocation]` + - `"image_content_policy_violation"` - The user's location. + - `"invalid_image_mode"` - - `type: Literal["approximate"]` + - `"image_file_too_large"` - The type of location approximation. Always `approximate`. + - `"unsupported_image_media_type"` - - `"approximate"` + - `"empty_image_file"` - - `city: Optional[str]` + - `"failed_to_download_image"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"image_file_not_found"` - - `country: Optional[str]` + - `message: str` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + A human-readable description of the error. - - `region: Optional[str]` + - `incomplete_details: Optional[IncompleteDetails]` - Free text input for the region of the user, e.g. `California`. + Details about why the response is incomplete. - - `timezone: Optional[str]` + - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The reason why the response is incomplete. - - `class BetaApplyPatchTool: …` + - `"max_output_tokens"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"content_filter"` - - `type: Literal["apply_patch"]` + - `instructions: Union[str, List[BetaResponseInputItem], null]` - The type of the tool. Always `apply_patch`. + A system (or developer) message inserted into the model's context. - - `"apply_patch"` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `str` - The tool invocation context(s). + A text input to the model, equivalent to a text input with the + `developer` role. - - `"direct"` + - `List[BetaResponseInputItem]` - - `"programmatic"` + A list of one or many input items to the model, containing + different content types. - - `type: Literal["tool_search_output"]` + - `class BetaEasyInputMessage: …` - The item type. Always `tool_search_output`. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `"tool_search_output"` + - `content: Union[str, BetaResponseInputMessageContentList]` - - `id: Optional[str]` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The unique ID of this tool search output. + - `str` - - `agent: Optional[Agent]` + A text input to the model. - The agent that produced this item. + - `List[BetaResponseInputContent]` - - `agent_name: str` + - `class BetaResponseInputText: …` - The canonical name of the agent that produced this item. + A text input to the model. - - `call_id: Optional[str]` + - `text: str` - The unique ID of the tool search call generated by the model. + The text input to the model. - - `execution: Optional[Literal["server", "client"]]` + - `type: Literal["input_text"]` - Whether tool search was executed by the server or by the client. + The type of the input item. Always `input_text`. - - `"server"` + - `"input_text"` - - `"client"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The status of the tool search output. + - `mode: Literal["explicit"]` - - `"in_progress"` + The breakpoint mode. Always `explicit`. - - `"completed"` + - `"explicit"` - - `"incomplete"` + - `class BetaResponseInputImage: …` - - `class AdditionalTools: …` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `role: Literal["developer"]` + - `detail: Literal["low", "high", "auto", "original"]` - The role that provided the additional tools. Only `developer` is supported. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"developer"` + - `"low"` - - `tools: List[BetaTool]` + - `"high"` - A list of additional tools made available at this item. + - `"auto"` - - `class BetaFunctionTool: …` + - `"original"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `type: Literal["input_image"]` - - `class BetaFileSearchTool: …` + The type of the input item. Always `input_image`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `"input_image"` - - `class BetaComputerTool: …` + - `file_id: Optional[str]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The ID of the file to be sent to the model. - - `class BetaComputerUsePreviewTool: …` + - `image_url: Optional[str]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `class BetaWebSearchTool: …` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class Mcp: …` + - `mode: Literal["explicit"]` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The breakpoint mode. Always `explicit`. - - `class CodeInterpreter: …` + - `"explicit"` - A tool that runs Python code to help generate a response to a prompt. + - `class BetaResponseInputFile: …` - - `class ProgrammaticToolCalling: …` + A file input to the model. - - `class ImageGeneration: …` + - `type: Literal["input_file"]` - A tool that generates images using the GPT image models. + The type of the input item. Always `input_file`. - - `class LocalShell: …` + - `"input_file"` - A tool that allows the model to execute shell commands in a local environment. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `class BetaFunctionShellTool: …` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - A tool that allows the model to execute shell commands. + - `"auto"` - - `class BetaCustomTool: …` + - `"low"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"high"` - - `class BetaNamespaceTool: …` + - `file_data: Optional[str]` - Groups function/custom tools under a shared namespace. + The content of the file to be sent to the model. - - `class BetaToolSearchTool: …` + - `file_id: Optional[str]` - Hosted or BYOT tool search configuration for deferred tools. + The ID of the file to be sent to the model. - - `class BetaWebSearchPreviewTool: …` + - `file_url: Optional[str]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The URL of the file to be sent to the model. - - `class BetaApplyPatchTool: …` + - `filename: Optional[str]` - Allows the assistant to create, delete, or update files using unified diffs. + The name of the file to be sent to the model. - - `type: Literal["additional_tools"]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The item type. Always `additional_tools`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"additional_tools"` + - `mode: Literal["explicit"]` - - `id: Optional[str]` + The breakpoint mode. Always `explicit`. - The unique ID of this additional tools item. + - `"explicit"` - - `agent: Optional[AdditionalToolsAgent]` + - `role: Literal["user", "assistant", "system", "developer"]` - The agent that produced this item. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `agent_name: str` + - `"user"` - The canonical name of the agent that produced this item. + - `"assistant"` - - `class BetaResponseReasoningItem: …` + - `"system"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `"developer"` - - `id: str` + - `phase: Optional[Literal["commentary", "final_answer"]]` - The unique identifier of the reasoning content. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `summary: List[Summary]` + - `"commentary"` - Reasoning summary content. + - `"final_answer"` - - `text: str` + - `type: Optional[Literal["message"]]` - A summary of the reasoning output from the model so far. + The type of the message input. Always `message`. - - `type: Literal["summary_text"]` + - `"message"` - The type of the object. Always `summary_text`. + - `class Message: …` - - `"summary_text"` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `type: Literal["reasoning"]` + - `content: BetaResponseInputMessageContentList` - The type of the object. Always `reasoning`. + A list of one or many input items to the model, containing different content + types. - - `"reasoning"` + - `class BetaResponseInputText: …` - - `agent: Optional[Agent]` + A text input to the model. - The agent that produced this item. + - `class BetaResponseInputImage: …` - - `agent_name: str` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The canonical name of the agent that produced this item. + - `class BetaResponseInputFile: …` - - `content: Optional[List[Content]]` + A file input to the model. - Reasoning text content. + - `role: Literal["user", "system", "developer"]` - - `text: str` + The role of the message input. One of `user`, `system`, or `developer`. - The reasoning text from the model. + - `"user"` - - `type: Literal["reasoning_text"]` + - `"system"` - The type of the reasoning text. Always `reasoning_text`. + - `"developer"` - - `"reasoning_text"` + - `agent: Optional[MessageAgent]` - - `encrypted_content: Optional[str]` + The agent that produced this item. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `agent_name: str` + + The canonical name of the agent that produced this item. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -57141,192 +68360,178 @@ print(compacted_response) - `"incomplete"` - - `class BetaResponseCompactionItemParam: …` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - - `encrypted_content: str` - - The encrypted content of the compaction summary. - - - `type: Literal["compaction"]` - - The type of the item. Always `compaction`. - - - `"compaction"` - - - `id: Optional[str]` + - `type: Optional[Literal["message"]]` - The ID of the compaction item. + The type of the message input. Always set to `message`. - - `agent: Optional[Agent]` + - `"message"` - The agent that produced this item. + - `class BetaResponseOutputMessage: …` - - `agent_name: str` + An output message from the model. - The canonical name of the agent that produced this item. + - `id: str` - - `class ImageGenerationCall: …` + The unique ID of the output message. - An image generation request made by the model. + - `content: List[Content]` - - `id: str` + The content of the output message. - The unique ID of the image generation call. + - `class BetaResponseOutputText: …` - - `result: Optional[str]` + A text output from the model. - The generated image encoded in base64. + - `annotations: List[Annotation]` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + The annotations of the text output. - The status of the image generation call. + - `class AnnotationFileCitation: …` - - `"in_progress"` + A citation to a file. - - `"completed"` + - `file_id: str` - - `"generating"` + The ID of the file. - - `"failed"` + - `filename: str` - - `type: Literal["image_generation_call"]` + The filename of the file cited. - The type of the image generation call. Always `image_generation_call`. + - `index: int` - - `"image_generation_call"` + The index of the file in the list of files. - - `agent: Optional[ImageGenerationCallAgent]` + - `type: Literal["file_citation"]` - The agent that produced this item. + The type of the file citation. Always `file_citation`. - - `agent_name: str` + - `"file_citation"` - The canonical name of the agent that produced this item. + - `class AnnotationURLCitation: …` - - `class BetaResponseCodeInterpreterToolCall: …` + A citation for a web resource used to generate a model response. - A tool call to run code. + - `end_index: int` - - `id: str` + The index of the last character of the URL citation in the message. - The unique ID of the code interpreter tool call. + - `start_index: int` - - `code: Optional[str]` + The index of the first character of the URL citation in the message. - The code to run, or null if not available. + - `title: str` - - `container_id: str` + The title of the web resource. - The ID of the container used to run the code. + - `type: Literal["url_citation"]` - - `outputs: Optional[List[Output]]` + The type of the URL citation. Always `url_citation`. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"url_citation"` - - `class OutputLogs: …` + - `url: str` - The logs output from the code interpreter. + The URL of the web resource. - - `logs: str` + - `class AnnotationContainerFileCitation: …` - The logs output from the code interpreter. + A citation for a container file used to generate a model response. - - `type: Literal["logs"]` + - `container_id: str` - The type of the output. Always `logs`. + The ID of the container file. - - `"logs"` + - `end_index: int` - - `class OutputImage: …` + The index of the last character of the container file citation in the message. - The image output from the code interpreter. + - `file_id: str` - - `type: Literal["image"]` + The ID of the file. - The type of the output. Always `image`. + - `filename: str` - - `"image"` + The filename of the container file cited. - - `url: str` + - `start_index: int` - The URL of the image output from the code interpreter. + The index of the first character of the container file citation in the message. - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + - `type: Literal["container_file_citation"]` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The type of the container file citation. Always `container_file_citation`. - - `"in_progress"` + - `"container_file_citation"` - - `"completed"` + - `class AnnotationFilePath: …` - - `"incomplete"` + A path to a file. - - `"interpreting"` + - `file_id: str` - - `"failed"` + The ID of the file. - - `type: Literal["code_interpreter_call"]` + - `index: int` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The index of the file in the list of files. - - `"code_interpreter_call"` + - `type: Literal["file_path"]` - - `agent: Optional[Agent]` + The type of the file path. Always `file_path`. - The agent that produced this item. + - `"file_path"` - - `agent_name: str` + - `text: str` - The canonical name of the agent that produced this item. + The text output from the model. - - `class LocalShellCall: …` + - `type: Literal["output_text"]` - A tool call to run a command on the local shell. + The type of the output text. Always `output_text`. - - `id: str` + - `"output_text"` - The unique ID of the local shell call. + - `logprobs: Optional[List[Logprob]]` - - `action: LocalShellCallAction` + - `token: str` - Execute a shell command on the server. + - `bytes: List[int]` - - `command: List[str]` + - `logprob: float` - The command to run. + - `top_logprobs: List[LogprobTopLogprob]` - - `env: Dict[str, str]` + - `token: str` - Environment variables to set for the command. + - `bytes: List[int]` - - `type: Literal["exec"]` + - `logprob: float` - The type of the local shell action. Always `exec`. + - `class BetaResponseOutputRefusal: …` - - `"exec"` + A refusal from the model. - - `timeout_ms: Optional[int]` + - `refusal: str` - Optional timeout in milliseconds for the command. + The refusal explanation from the model. - - `user: Optional[str]` + - `type: Literal["refusal"]` - Optional user to run the command as. + The type of the refusal. Always `refusal`. - - `working_directory: Optional[str]` + - `"refusal"` - Optional working directory to run the command in. + - `role: Literal["assistant"]` - - `call_id: str` + The role of the output message. Always `assistant`. - The unique ID of the local shell tool call generated by the model. + - `"assistant"` - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the local shell call. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"in_progress"` @@ -57334,13 +68539,13 @@ print(compacted_response) - `"incomplete"` - - `type: Literal["local_shell_call"]` + - `type: Literal["message"]` - The type of the local shell call. Always `local_shell_call`. + The type of the output message. Always `message`. - - `"local_shell_call"` + - `"message"` - - `agent: Optional[LocalShellCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -57348,119 +68553,125 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCallOutput: …` - - The output of a local shell tool call. - - - `id: str` - - The unique ID of the local shell tool call generated by the model. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `output: str` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - A JSON string of the output of the local shell tool call. + - `"commentary"` - - `type: Literal["local_shell_call_output"]` + - `"final_answer"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `class BetaResponseFileSearchToolCall: …` - - `"local_shell_call_output"` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `agent: Optional[LocalShellCallOutputAgent]` + - `id: str` - The agent that produced this item. + The unique ID of the file search tool call. - - `agent_name: str` + - `queries: List[str]` - The canonical name of the agent that produced this item. + The queries used to search for files. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `"in_progress"` + - `"searching"` + - `"completed"` - `"incomplete"` - - `class ShellCall: …` + - `"failed"` - A tool representing a request to execute one or more shell commands. + - `type: Literal["file_search_call"]` - - `action: ShellCallAction` + The type of the file search tool call. Always `file_search_call`. - The shell commands and limits that describe how to run the tool call. + - `"file_search_call"` - - `commands: List[str]` + - `agent: Optional[Agent]` - Ordered shell commands for the execution environment to run. + The agent that produced this item. - - `max_output_length: Optional[int]` + - `agent_name: str` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + The canonical name of the agent that produced this item. - - `timeout_ms: Optional[int]` + - `results: Optional[List[Result]]` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The results of the file search tool call. - - `call_id: str` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - The unique ID of the shell tool call generated by the model. + 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, booleans, or numbers. - - `type: Literal["shell_call"]` + - `str` - The type of the item. Always `shell_call`. + - `float` - - `"shell_call"` + - `bool` - - `id: Optional[str]` + - `file_id: Optional[str]` - The unique ID of the shell tool call. Populated when this item is returned via API. + The unique ID of the file. - - `agent: Optional[ShellCallAgent]` + - `filename: Optional[str]` - The agent that produced this item. + The name of the file. - - `agent_name: str` + - `score: Optional[float]` - The canonical name of the agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `caller: Optional[ShellCallCaller]` + - `text: Optional[str]` - The execution context that produced this tool call. + The text that was retrieved from the file. - - `class ShellCallCallerDirect: …` + - `class BetaResponseComputerToolCall: …` - - `type: Literal["direct"]` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The caller type. Always `direct`. + - `id: str` - - `"direct"` + The unique ID of the computer call. - - `class ShellCallCallerProgram: …` + - `call_id: str` - - `caller_id: str` + An identifier used when responding to the tool call with output. - The call ID of the program item that produced this tool call. + - `pending_safety_checks: List[PendingSafetyCheck]` - - `type: Literal["program"]` + The pending safety checks for the computer call. - The caller type. Always `program`. + - `id: str` - - `"program"` + The ID of the pending safety check. - - `environment: Optional[ShellCallEnvironment]` + - `code: Optional[str]` - The environment to execute the shell commands in. + The type of the pending safety check. - - `class BetaLocalEnvironment: …` + - `message: Optional[str]` - - `class BetaContainerReference: …` + Details about the pending safety check. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -57468,249 +68679,249 @@ print(compacted_response) - `"incomplete"` - - `class ShellCallOutput: …` - - The streamed output items emitted by a shell tool call. - - - `call_id: str` - - The unique ID of the shell tool call generated by the model. + - `type: Literal["computer_call"]` - - `output: List[BetaResponseFunctionShellCallOutputContent]` + The type of the computer call. Always `computer_call`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"computer_call"` - - `outcome: Outcome` + - `action: Optional[BetaComputerAction]` - The exit or timeout outcome associated with this shell call. + A click action. - - `class OutcomeTimeout: …` + - `class Click: …` - Indicates that the shell call exceeded its configured time limit. + A click action. - - `type: Literal["timeout"]` + - `button: Literal["left", "right", "wheel", 2 more]` - The outcome type. Always `timeout`. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"timeout"` + - `"left"` - - `class OutcomeExit: …` + - `"right"` - Indicates that the shell commands finished and returned an exit code. + - `"wheel"` - - `exit_code: int` + - `"back"` - The exit code returned by the shell process. + - `"forward"` - - `type: Literal["exit"]` + - `type: Literal["click"]` - The outcome type. Always `exit`. + Specifies the event type. For a click action, this property is always `click`. - - `"exit"` + - `"click"` - - `stderr: str` + - `x: int` - Captured stderr output for the shell call. + The x-coordinate where the click occurred. - - `stdout: str` + - `y: int` - Captured stdout output for the shell call. + The y-coordinate where the click occurred. - - `type: Literal["shell_call_output"]` + - `keys: Optional[List[str]]` - The type of the item. Always `shell_call_output`. + The keys being held while clicking. - - `"shell_call_output"` + - `class DoubleClick: …` - - `id: Optional[str]` + A double click action. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `keys: Optional[List[str]]` - - `agent: Optional[ShellCallOutputAgent]` + The keys being held while double-clicking. - The agent that produced this item. + - `type: Literal["double_click"]` - - `agent_name: str` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The canonical name of the agent that produced this item. + - `"double_click"` - - `caller: Optional[ShellCallOutputCaller]` + - `x: int` - The execution context that produced this tool call. + The x-coordinate where the double click occurred. - - `class ShellCallOutputCallerDirect: …` + - `y: int` - - `type: Literal["direct"]` + The y-coordinate where the double click occurred. - The caller type. Always `direct`. + - `class Drag: …` - - `"direct"` + A drag action. - - `class ShellCallOutputCallerProgram: …` + - `path: List[DragPath]` - - `caller_id: str` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The call ID of the program item that produced this tool call. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `type: Literal["program"]` + - `x: int` - The caller type. Always `program`. + The x-coordinate. - - `"program"` + - `y: int` - - `max_output_length: Optional[int]` + The y-coordinate. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `type: Literal["drag"]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + Specifies the event type. For a drag action, this property is always set to `drag`. - The status of the shell call output. + - `"drag"` - - `"in_progress"` + - `keys: Optional[List[str]]` - - `"completed"` + The keys being held while dragging the mouse. - - `"incomplete"` + - `class Keypress: …` - - `class ApplyPatchCall: …` + A collection of keypresses the model would like to perform. - A tool call representing a request to create, delete, or update files using diff patches. + - `keys: List[str]` - - `call_id: str` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The unique ID of the apply patch tool call generated by the model. + - `type: Literal["keypress"]` - - `operation: ApplyPatchCallOperation` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The specific create, delete, or update instruction for the apply_patch tool call. + - `"keypress"` - - `class ApplyPatchCallOperationCreateFile: …` + - `class Move: …` - Instruction for creating a new file via the apply_patch tool. + A mouse move action. - - `diff: str` + - `type: Literal["move"]` - Unified diff content to apply when creating the file. + Specifies the event type. For a move action, this property is always set to `move`. - - `path: str` + - `"move"` - Path of the file to create relative to the workspace root. + - `x: int` - - `type: Literal["create_file"]` + The x-coordinate to move to. - The operation type. Always `create_file`. + - `y: int` - - `"create_file"` + The y-coordinate to move to. - - `class ApplyPatchCallOperationDeleteFile: …` + - `keys: Optional[List[str]]` - Instruction for deleting an existing file via the apply_patch tool. + The keys being held while moving the mouse. - - `path: str` + - `class Screenshot: …` - Path of the file to delete relative to the workspace root. + A screenshot action. - - `type: Literal["delete_file"]` + - `type: Literal["screenshot"]` - The operation type. Always `delete_file`. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"delete_file"` + - `"screenshot"` - - `class ApplyPatchCallOperationUpdateFile: …` + - `class Scroll: …` - Instruction for updating an existing file via the apply_patch tool. + A scroll action. - - `diff: str` + - `scroll_x: int` - Unified diff content to apply to the existing file. + The horizontal scroll distance. - - `path: str` + - `scroll_y: int` - Path of the file to update relative to the workspace root. + The vertical scroll distance. - - `type: Literal["update_file"]` + - `type: Literal["scroll"]` - The operation type. Always `update_file`. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"update_file"` + - `"scroll"` - - `status: Literal["in_progress", "completed"]` + - `x: int` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The x-coordinate where the scroll occurred. - - `"in_progress"` + - `y: int` - - `"completed"` + The y-coordinate where the scroll occurred. - - `type: Literal["apply_patch_call"]` + - `keys: Optional[List[str]]` - The type of the item. Always `apply_patch_call`. + The keys being held while scrolling. - - `"apply_patch_call"` + - `class Type: …` - - `id: Optional[str]` + An action to type in text. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `text: str` - - `agent: Optional[ApplyPatchCallAgent]` + The text to type. - The agent that produced this item. + - `type: Literal["type"]` - - `agent_name: str` + Specifies the event type. For a type action, this property is always set to `type`. - The canonical name of the agent that produced this item. + - `"type"` - - `caller: Optional[ApplyPatchCallCaller]` + - `class Wait: …` - The execution context that produced this tool call. + A wait action. - - `class ApplyPatchCallCallerDirect: …` + - `type: Literal["wait"]` - - `type: Literal["direct"]` + Specifies the event type. For a wait action, this property is always set to `wait`. - The caller type. Always `direct`. + - `"wait"` - - `"direct"` + - `actions: Optional[BetaComputerActionList]` - - `class ApplyPatchCallCallerProgram: …` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `caller_id: str` + - `class Click: …` - The call ID of the program item that produced this tool call. + A click action. - - `type: Literal["program"]` + - `class DoubleClick: …` - The caller type. Always `program`. + A double click action. - - `"program"` + - `class Drag: …` - - `class ApplyPatchCallOutput: …` + A drag action. - The streamed output emitted by an apply patch tool call. + - `class Keypress: …` - - `call_id: str` + A collection of keypresses the model would like to perform. - The unique ID of the apply patch tool call generated by the model. + - `class Move: …` - - `status: Literal["completed", "failed"]` + A mouse move action. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `class Screenshot: …` - - `"completed"` + A screenshot action. - - `"failed"` + - `class Scroll: …` - - `type: Literal["apply_patch_call_output"]` + A scroll action. - The type of the item. Always `apply_patch_call_output`. + - `class Type: …` - - `"apply_patch_call_output"` + An action to type in text. - - `id: Optional[str]` + - `class Wait: …` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + A wait action. - - `agent: Optional[ApplyPatchCallOutputAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -57718,73 +68929,60 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ApplyPatchCallOutputCaller]` - - The execution context that produced this tool call. - - - `class ApplyPatchCallOutputCallerDirect: …` - - - `type: Literal["direct"]` - - The caller type. Always `direct`. - - - `"direct"` - - - `class ApplyPatchCallOutputCallerProgram: …` - - - `caller_id: str` + - `class ComputerCallOutput: …` - The call ID of the program item that produced this tool call. + The output of a computer tool call. - - `type: Literal["program"]` + - `call_id: str` - The caller type. Always `program`. + The ID of the computer tool call that produced the output. - - `"program"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `output: Optional[str]` + A computer screenshot image used with the computer use tool. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `type: Literal["computer_screenshot"]` - - `class McpListTools: …` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - A list of tools available on an MCP server. + - `"computer_screenshot"` - - `id: str` + - `file_id: Optional[str]` - The unique ID of the list. + The identifier of an uploaded file that contains the screenshot. - - `server_label: str` + - `image_url: Optional[str]` - The label of the MCP server. + The URL of the screenshot image. - - `tools: List[McpListToolsTool]` + - `type: Literal["computer_call_output"]` - The tools available on the server. + The type of the computer tool call output. Always `computer_call_output`. - - `input_schema: object` + - `"computer_call_output"` - The JSON schema describing the tool's input. + - `id: Optional[str]` - - `name: str` + The ID of the computer tool call output. - The name of the tool. + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - - `annotations: Optional[object]` + The safety checks reported by the API that have been acknowledged by the developer. - Additional annotations about the tool. + - `id: str` - - `description: Optional[str]` + The ID of the pending safety check. - The description of the tool. + - `code: Optional[str]` - - `type: Literal["mcp_list_tools"]` + The type of the pending safety check. - The type of the item. Always `mcp_list_tools`. + - `message: Optional[str]` - - `"mcp_list_tools"` + Details about the pending safety check. - - `agent: Optional[McpListToolsAgent]` + - `agent: Optional[ComputerCallOutputAgent]` The agent that produced this item. @@ -57792,181 +68990,146 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `error: Optional[str]` - - Error message if the server could not list tools. - - - `class McpApprovalRequest: …` - - A request for human approval of a tool invocation. - - - `id: str` - - The unique ID of the approval request. - - - `arguments: str` - - A JSON string of arguments for the tool. - - - `name: str` - - The name of the tool to run. - - - `server_label: str` - - The label of the MCP server making the request. - - - `type: Literal["mcp_approval_request"]` - - The type of the item. Always `mcp_approval_request`. - - - `"mcp_approval_request"` - - - `agent: Optional[McpApprovalRequestAgent]` - - The agent that produced this item. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `agent_name: str` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The canonical name of the agent that produced this item. + - `"in_progress"` - - `class McpApprovalResponse: …` + - `"completed"` - A response to an MCP approval request. + - `"incomplete"` - - `approval_request_id: str` + - `class BetaResponseFunctionWebSearch: …` - The ID of the approval request being answered. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `approve: bool` + - `id: str` - Whether the request was approved. + The unique ID of the web search tool call. - - `type: Literal["mcp_approval_response"]` + - `action: Action` - The type of the item. Always `mcp_approval_response`. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `"mcp_approval_response"` + - `class ActionSearch: …` - - `id: Optional[str]` + Action type "search" - Performs a web search query. - The unique ID of the approval response + - `type: Literal["search"]` - - `agent: Optional[McpApprovalResponseAgent]` + The action type. - The agent that produced this item. + - `"search"` - - `agent_name: str` + - `queries: Optional[List[str]]` - The canonical name of the agent that produced this item. + The search queries. - - `reason: Optional[str]` + - `query: Optional[str]` - Optional reason for the decision. + The search query. - - `class McpCall: …` + - `sources: Optional[List[ActionSearchSource]]` - An invocation of a tool on an MCP server. + The sources used in the search. - - `id: str` + - `type: Literal["url"]` - The unique ID of the tool call. + The type of source. Always `url`. - - `arguments: str` + - `"url"` - A JSON string of the arguments passed to the tool. + - `url: str` - - `name: str` + The URL of the source. - The name of the tool that was run. + - `class ActionOpenPage: …` - - `server_label: str` + Action type "open_page" - Opens a specific URL from search results. - The label of the MCP server running the tool. + - `type: Literal["open_page"]` - - `type: Literal["mcp_call"]` + The action type. - The type of the item. Always `mcp_call`. + - `"open_page"` - - `"mcp_call"` + - `url: Optional[str]` - - `agent: Optional[McpCallAgent]` + The URL opened by the model. - The agent that produced this item. + - `class ActionFindInPage: …` - - `agent_name: str` + Action type "find_in_page": Searches for a pattern within a loaded page. - The canonical name of the agent that produced this item. + - `pattern: str` - - `approval_request_id: Optional[str]` + The pattern or text to search for within the page. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `type: Literal["find_in_page"]` - - `error: Optional[str]` + The action type. - The error from the tool call, if any. + - `"find_in_page"` - - `output: Optional[str]` + - `url: str` - The output from the tool call. + The URL of the page searched for the pattern. - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The status of the web search tool call. - `"in_progress"` - - `"completed"` - - - `"incomplete"` + - `"searching"` - - `"calling"` + - `"completed"` - `"failed"` - - `class BetaResponseCustomToolCallOutput: …` - - The output of a custom tool call from your code, being sent back to the model. + - `type: Literal["web_search_call"]` - - `call_id: str` + The type of the web search tool call. Always `web_search_call`. - The call ID, used to map this custom tool call output to a custom tool call. + - `"web_search_call"` - - `output: Union[str, List[OutputOutputContentList]]` + - `agent: Optional[Agent]` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The agent that produced this item. - - `str` + - `agent_name: str` - A string of the output of the custom tool call. + The canonical name of the agent that produced this item. - - `List[OutputOutputContentList]` + - `class BetaResponseFunctionToolCall: …` - Text, image, or file output of the custom tool call. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `class BetaResponseInputText: …` + - `arguments: str` - A text input to the model. + A JSON string of the arguments to pass to the function. - - `class BetaResponseInputImage: …` + - `call_id: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The unique ID of the function tool call generated by the model. - - `class BetaResponseInputFile: …` + - `name: str` - A file input to the model. + The name of the function to run. - - `type: Literal["custom_tool_call_output"]` + - `type: Literal["function_call"]` - The type of the custom tool call output. Always `custom_tool_call_output`. + The type of the function tool call. Always `function_call`. - - `"custom_tool_call_output"` + - `"function_call"` - `id: Optional[str]` - The unique ID of the custom tool call output in the OpenAI platform. + The unique ID of the function tool call. - `agent: Optional[Agent]` @@ -57984,8 +69147,6 @@ print(compacted_response) - `type: Literal["direct"]` - The caller type. Always `direct`. - - `"direct"` - `class CallerProgram: …` @@ -57996,133 +69157,162 @@ print(compacted_response) - `type: Literal["program"]` - The caller type. Always `program`. - - `"program"` - - `class BetaResponseCustomToolCall: …` + - `namespace: Optional[str]` - A call to a custom tool created by the model. + The namespace of the function to run. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class FunctionCallOutput: …` + + The output of a function tool call. - `call_id: str` - An identifier used to map this custom tool call to a tool call output. + The unique ID of the function tool call generated by the model. - - `input: str` + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - The input for the custom tool call generated by the model. + Text, image, or file output of the function tool call. - - `name: str` + - `str` - The name of the custom tool being called. + A JSON string of the output of the function tool call. - - `type: Literal["custom_tool_call"]` + - `List[BetaResponseFunctionCallOutputItem]` - The type of the custom tool call. Always `custom_tool_call`. + - `class BetaResponseInputTextContent: …` - - `"custom_tool_call"` + A text input to the model. - - `id: Optional[str]` + - `text: str` - The unique ID of the custom tool call in the OpenAI platform. + The text input to the model. - - `agent: Optional[Agent]` + - `type: Literal["input_text"]` - The agent that produced this item. + The type of the input item. Always `input_text`. - - `agent_name: str` + - `"input_text"` - The canonical name of the agent that produced this item. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `caller: Optional[Caller]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The execution context that produced this tool call. + - `mode: Literal["explicit"]` - - `class CallerDirect: …` + The breakpoint mode. Always `explicit`. - - `type: Literal["direct"]` + - `"explicit"` - - `"direct"` + - `class BetaResponseInputImageContent: …` - - `class CallerProgram: …` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `caller_id: str` + - `type: Literal["input_image"]` - The call ID of the program item that produced this tool call. + The type of the input item. Always `input_image`. - - `type: Literal["program"]` + - `"input_image"` - - `"program"` + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - - `namespace: Optional[str]` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The namespace of the custom tool being called. + - `"low"` - - `class CompactionTrigger: …` + - `"high"` - Compacts the current context. Must be the final input item. + - `"auto"` - - `type: Literal["compaction_trigger"]` + - `"original"` - The type of the item. Always `compaction_trigger`. + - `file_id: Optional[str]` - - `"compaction_trigger"` + The ID of the file to be sent to the model. - - `agent: Optional[CompactionTriggerAgent]` + - `image_url: Optional[str]` - The agent that produced this item. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `agent_name: str` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The canonical name of the agent that produced this item. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class ItemReference: …` + - `mode: Literal["explicit"]` - An internal identifier for an item to reference. + The breakpoint mode. Always `explicit`. - - `id: str` + - `"explicit"` - The ID of the item to reference. + - `class BetaResponseInputFileContent: …` - - `agent: Optional[ItemReferenceAgent]` + A file input to the model. - The agent that produced this item. + - `type: Literal["input_file"]` - - `agent_name: str` + The type of the input item. Always `input_file`. - The canonical name of the agent that produced this item. + - `"input_file"` - - `type: Optional[Literal["item_reference"]]` + - `detail: Optional[Literal["auto", "low", "high"]]` - The type of item to reference. Always `item_reference`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `"item_reference"` + - `"auto"` - - `class Program: …` + - `"low"` - - `id: str` + - `"high"` - The unique ID of this program item. + - `file_data: Optional[str]` - - `call_id: str` + The base64-encoded data of the file to be sent to the model. - The stable call ID of the program item. + - `file_id: Optional[str]` - - `code: str` + The ID of the file to be sent to the model. - The JavaScript source executed by programmatic tool calling. + - `file_url: Optional[str]` - - `fingerprint: str` + The URL of the file to be sent to the model. - Opaque program replay fingerprint that must be round-tripped. + - `filename: Optional[str]` - - `type: Literal["program"]` + The name of the file to be sent to the model. - The item type. Always `program`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"program"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `agent: Optional[ProgramAgent]` + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `type: Literal["function_call_output"]` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: Optional[str]` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: Optional[FunctionCallOutputAgent]` The agent that produced this item. @@ -58130,327 +69320,309 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ProgramOutput: …` + - `caller: Optional[FunctionCallOutputCaller]` - - `id: str` + The execution context that produced this tool call. - The unique ID of this program output item. + - `class FunctionCallOutputCallerDirect: …` - - `call_id: str` + - `type: Literal["direct"]` - The call ID of the program item. + The caller type. Always `direct`. - - `result: str` + - `"direct"` - The result produced by the program item. + - `class FunctionCallOutputCallerProgram: …` - - `status: Literal["completed", "incomplete"]` + - `caller_id: str` - The terminal status of the program output. + The call ID of the program item that produced this tool call. - - `"completed"` + - `type: Literal["program"]` - - `"incomplete"` + The caller type. Always `program`. - - `type: Literal["program_output"]` + - `"program"` - The item type. Always `program_output`. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"program_output"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `agent: Optional[ProgramOutputAgent]` + - `"in_progress"` - The agent that produced this item. + - `"completed"` - - `agent_name: str` + - `"incomplete"` - The canonical name of the agent that produced this item. + - `class AgentMessage: …` - - `metadata: Optional[Dict[str, str]]` + A message routed between agents. - 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. + - `author: str` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The sending agent identity. - - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` + - `content: List[AgentMessageContent]` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + Plaintext, image, or encrypted content sent between agents. - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` + - `class BetaResponseInputTextContent: …` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + A text input to the model. - - `"gpt-5.6-sol"` + - `class BetaResponseInputImageContent: …` - - `"gpt-5.6-terra"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `"gpt-5.6-luna"` + - `class AgentMessageContentEncryptedContent: …` - - `"gpt-5.4"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"gpt-5.4-mini"` + - `encrypted_content: str` - - `"gpt-5.4-nano"` + Opaque encrypted content. - - `"gpt-5.4-mini-2026-03-17"` + - `type: Literal["encrypted_content"]` - - `"gpt-5.4-nano-2026-03-17"` + The type of the input item. Always `encrypted_content`. - - `"gpt-5.3-chat-latest"` + - `"encrypted_content"` - - `"gpt-5.2"` + - `recipient: str` - - `"gpt-5.2-2025-12-11"` + The destination agent identity. - - `"gpt-5.2-chat-latest"` + - `type: Literal["agent_message"]` - - `"gpt-5.2-pro"` + The item type. Always `agent_message`. - - `"gpt-5.2-pro-2025-12-11"` + - `"agent_message"` - - `"gpt-5.1"` + - `id: Optional[str]` - - `"gpt-5.1-2025-11-13"` + The unique ID of this agent message item. - - `"gpt-5.1-codex"` + - `agent: Optional[AgentMessageAgent]` - - `"gpt-5.1-mini"` + The agent that produced this item. - - `"gpt-5.1-chat-latest"` + - `agent_name: str` - - `"gpt-5"` + The canonical name of the agent that produced this item. - - `"gpt-5-mini"` + - `class MultiAgentCall: …` - - `"gpt-5-nano"` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"gpt-5-2025-08-07"` + The multi-agent action that was executed. - - `"gpt-5-mini-2025-08-07"` + - `"spawn_agent"` - - `"gpt-5-nano-2025-08-07"` + - `"interrupt_agent"` - - `"gpt-5-chat-latest"` + - `"list_agents"` - - `"gpt-4.1"` + - `"send_message"` - - `"gpt-4.1-mini"` + - `"followup_task"` - - `"gpt-4.1-nano"` + - `"wait_agent"` - - `"gpt-4.1-2025-04-14"` + - `arguments: str` - - `"gpt-4.1-mini-2025-04-14"` + The action arguments as a JSON string. - - `"gpt-4.1-nano-2025-04-14"` + - `call_id: str` - - `"o4-mini"` + The unique ID linking this call to its output. - - `"o4-mini-2025-04-16"` + - `type: Literal["multi_agent_call"]` - - `"o3"` + The item type. Always `multi_agent_call`. - - `"o3-2025-04-16"` + - `"multi_agent_call"` - - `"o3-mini"` + - `id: Optional[str]` - - `"o3-mini-2025-01-31"` + The unique ID of this multi-agent call. - - `"o1"` + - `agent: Optional[MultiAgentCallAgent]` - - `"o1-2024-12-17"` + The agent that produced this item. - - `"o1-preview"` + - `agent_name: str` - - `"o1-preview-2024-09-12"` + The canonical name of the agent that produced this item. - - `"o1-mini"` + - `class MultiAgentCallOutput: …` - - `"o1-mini-2024-09-12"` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"gpt-4o"` + The multi-agent action that produced this result. - - `"gpt-4o-2024-11-20"` + - `"spawn_agent"` - - `"gpt-4o-2024-08-06"` + - `"interrupt_agent"` - - `"gpt-4o-2024-05-13"` + - `"list_agents"` - - `"gpt-4o-audio-preview"` + - `"send_message"` - - `"gpt-4o-audio-preview-2024-10-01"` + - `"followup_task"` - - `"gpt-4o-audio-preview-2024-12-17"` + - `"wait_agent"` - - `"gpt-4o-audio-preview-2025-06-03"` + - `call_id: str` - - `"gpt-4o-mini-audio-preview"` + The unique ID of the multi-agent call. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `output: List[MultiAgentCallOutputOutput]` - - `"gpt-4o-search-preview"` + Text output returned by the multi-agent action. - - `"gpt-4o-mini-search-preview"` + - `text: str` - - `"gpt-4o-search-preview-2025-03-11"` + The text content. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `type: Literal["output_text"]` - - `"chatgpt-4o-latest"` + The content type. Always `output_text`. - - `"codex-mini-latest"` + - `"output_text"` - - `"gpt-4o-mini"` + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - - `"gpt-4o-mini-2024-07-18"` + Citations associated with the text content. - - `"gpt-4-turbo"` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - - `"gpt-4-turbo-2024-04-09"` + - `file_id: str` - - `"gpt-4-0125-preview"` + The ID of the file. - - `"gpt-4-turbo-preview"` + - `filename: str` - - `"gpt-4-1106-preview"` + The filename of the file cited. - - `"gpt-4-vision-preview"` + - `index: int` - - `"gpt-4"` + The index of the file in the list of files. - - `"gpt-4-0314"` + - `type: Literal["file_citation"]` - - `"gpt-4-0613"` + The citation type. Always `file_citation`. - - `"gpt-4-32k"` + - `"file_citation"` - - `"gpt-4-32k-0314"` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` - - `"gpt-4-32k-0613"` + - `end_index: int` - - `"gpt-3.5-turbo"` + The index of the last character of the citation in the message. - - `"gpt-3.5-turbo-16k"` + - `start_index: int` - - `"gpt-3.5-turbo-0301"` + The index of the first character of the citation in the message. - - `"gpt-3.5-turbo-0613"` + - `title: str` - - `"gpt-3.5-turbo-1106"` + The title of the cited resource. - - `"gpt-3.5-turbo-0125"` + - `type: Literal["url_citation"]` - - `"gpt-3.5-turbo-16k-0613"` + The citation type. Always `url_citation`. - - `"o1-pro"` + - `"url_citation"` - - `"o1-pro-2025-03-19"` + - `url: str` - - `"o3-pro"` + The URL of the cited resource. - - `"o3-pro-2025-06-10"` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` - - `"o3-deep-research"` + - `container_id: str` - - `"o3-deep-research-2025-06-26"` + The ID of the container. - - `"o4-mini-deep-research"` + - `end_index: int` - - `"o4-mini-deep-research-2025-06-26"` + The index of the last character of the citation in the message. - - `"computer-use-preview"` + - `file_id: str` - - `"computer-use-preview-2025-03-11"` + The ID of the container file. - - `"gpt-5-codex"` + - `filename: str` - - `"gpt-5-pro"` + The filename of the container file cited. - - `"gpt-5-pro-2025-10-06"` + - `start_index: int` - - `"gpt-5.1-codex-max"` + The index of the first character of the citation in the message. - - `str` + - `type: Literal["container_file_citation"]` - - `object: Literal["response"]` + The citation type. Always `container_file_citation`. - The object type of this resource - always set to `response`. + - `"container_file_citation"` - - `"response"` + - `type: Literal["multi_agent_call_output"]` - - `output: List[BetaResponseOutputItem]` + The item type. Always `multi_agent_call_output`. - An array of content items generated by the model. + - `"multi_agent_call_output"` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `id: Optional[str]` - - `class BetaResponseOutputMessage: …` + The unique ID of this multi-agent call output. - An output message from the model. + - `agent: Optional[MultiAgentCallOutputAgent]` - - `class BetaResponseFileSearchToolCall: …` + The agent that produced this item. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `agent_name: str` - - `class BetaResponseFunctionToolCall: …` + The canonical name of the agent that produced this item. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `class ToolSearchCall: …` - - `class BetaResponseFunctionToolCallOutputItem: …` + - `arguments: object` - - `id: str` + The arguments supplied to the tool search call. - The unique ID of the function call tool output. + - `type: Literal["tool_search_call"]` - - `call_id: str` + The item type. Always `tool_search_call`. - The unique ID of the function tool call generated by the model. + - `"tool_search_call"` - - `output: Union[str, List[OutputOutputContentList]]` + - `id: Optional[str]` - The output from the function call generated by your code. - Can be a string or an list of output content. + The unique ID of this tool search call. - - `str` + - `agent: Optional[ToolSearchCallAgent]` - A string of the output of the function call. + The agent that produced this item. - - `List[OutputOutputContentList]` + - `agent_name: str` - Text, image, or file output of the function call. + The canonical name of the agent that produced this item. - - `class BetaResponseInputText: …` + - `call_id: Optional[str]` - A text input to the model. + The unique ID of the tool search call generated by the model. - - `class BetaResponseInputImage: …` + - `execution: Optional[Literal["server", "client"]]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Whether tool search was executed by the server or by the client. - - `class BetaResponseInputFile: …` + - `"server"` - A file input to the model. + - `"client"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the tool search call. - `"in_progress"` @@ -58458,1062 +69630,1115 @@ print(compacted_response) - `"incomplete"` - - `type: Literal["function_call_output"]` - - The type of the function tool call output. Always `function_call_output`. + - `class BetaResponseToolSearchOutputItemParam: …` - - `"function_call_output"` + - `tools: List[BetaTool]` - - `agent: Optional[Agent]` + The loaded tool definitions returned by the tool search output. - The agent that produced this item. + - `class BetaFunctionTool: …` - - `agent_name: str` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The canonical name of the agent that produced this item. + - `name: str` - - `caller: Optional[Caller]` + The name of the function to call. - The execution context that produced this tool call. + - `parameters: Optional[Dict[str, object]]` - - `class CallerDirect: …` + A JSON schema object describing the parameters of the function. - - `type: Literal["direct"]` + - `strict: Optional[bool]` - The caller type. Always `direct`. + Whether strict parameter validation is enforced for this function tool. - - `"direct"` + - `type: Literal["function"]` - - `class CallerProgram: …` + The type of the function tool. Always `function`. - - `caller_id: str` + - `"function"` - The call ID of the program item that produced this tool call. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `type: Literal["program"]` + The tool invocation context(s). - The caller type. Always `program`. + - `"direct"` - - `"program"` + - `"programmatic"` - - `created_by: Optional[str]` + - `defer_loading: Optional[bool]` - The identifier of the actor that created the item. + Whether this function is deferred and loaded via tool search. - - `class AgentMessage: …` + - `description: Optional[str]` - - `id: str` + A description of the function. Used by the model to determine whether or not to call the function. - The unique ID of the agent message. + - `output_schema: Optional[Dict[str, object]]` - - `author: str` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The sending agent identity. + - `class BetaFileSearchTool: …` - - `content: List[AgentMessageContent]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - Encrypted content sent between agents. + - `type: Literal["file_search"]` - - `class BetaResponseInputText: …` + The type of the file search tool. Always `file_search`. - A text input to the model. + - `"file_search"` - - `class BetaResponseOutputText: …` + - `vector_store_ids: List[str]` - A text output from the model. + The IDs of the vector stores to search. - - `class AgentMessageContentText: …` + - `filters: Optional[Filters]` - A text content. + A filter to apply. - - `text: str` + - `class FiltersComparisonFilter: …` - - `type: Literal["text"]` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"text"` + - `key: str` - - `class AgentMessageContentSummaryText: …` + The key to compare against the value. - A summary text from the model. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `text: str` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A summary of the reasoning output from the model so far. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `type: Literal["summary_text"]` + - `"eq"` - The type of the object. Always `summary_text`. + - `"ne"` - - `"summary_text"` + - `"gt"` - - `class AgentMessageContentReasoningText: …` + - `"gte"` - Reasoning text from the model. + - `"lt"` - - `text: str` + - `"lte"` - The reasoning text from the model. + - `"in"` - - `type: Literal["reasoning_text"]` + - `"nin"` - The type of the reasoning text. Always `reasoning_text`. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `"reasoning_text"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `class BetaResponseOutputRefusal: …` + - `str` - A refusal from the model. + - `float` - - `class BetaResponseInputImage: …` + - `bool` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `List[Union[str, float]]` - - `class AgentMessageContentComputerScreenshot: …` + - `str` - A screenshot of a computer. + - `float` - - `detail: Literal["low", "high", "auto", "original"]` + - `class FiltersCompoundFilter: …` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Combine multiple filters using `and` or `or`. - - `"low"` + - `filters: List[FiltersCompoundFilterFilter]` - - `"high"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"auto"` + - `class FiltersCompoundFilterFilterComparisonFilter: …` - - `"original"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `file_id: Optional[str]` + - `key: str` - The identifier of an uploaded file that contains the screenshot. + The key to compare against the value. - - `image_url: Optional[str]` + - `type: Literal["eq", "ne", "gt", 5 more]` - The URL of the screenshot image. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: Literal["computer_screenshot"]` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"eq"` - - `"computer_screenshot"` + - `"ne"` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `"gt"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"gte"` - - `mode: Literal["explicit"]` + - `"lt"` - The breakpoint mode. Always `explicit`. + - `"lte"` - - `"explicit"` + - `"in"` - - `class BetaResponseInputFile: …` + - `"nin"` - A file input to the model. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `class AgentMessageContentEncryptedContent: …` + The value to compare against the attribute key; supports string, number, or boolean types. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `str` - - `encrypted_content: str` + - `float` - Opaque encrypted content. + - `bool` - - `type: Literal["encrypted_content"]` + - `List[Union[str, float]]` - The type of the input item. Always `encrypted_content`. + - `str` - - `"encrypted_content"` + - `float` - - `recipient: str` + - `object` - The destination agent identity. + - `type: Literal["and", "or"]` - - `type: Literal["agent_message"]` + Type of operation: `and` or `or`. - The type of the item. Always `agent_message`. + - `"and"` - - `"agent_message"` + - `"or"` - - `agent: Optional[AgentMessageAgent]` + - `max_num_results: Optional[int]` - The agent that produced this item. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `agent_name: str` + - `ranking_options: Optional[RankingOptions]` - The canonical name of the agent that produced this item. + Ranking options for search. - - `class MultiAgentCall: …` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - `id: str` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The unique ID of the multi-agent call item. + - `embedding_weight: float` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The weight of the embedding in the reciprocal ranking fusion. - The multi-agent action to execute. + - `text_weight: float` - - `"spawn_agent"` + The weight of the text in the reciprocal ranking fusion. - - `"interrupt_agent"` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - - `"list_agents"` + The ranker to use for the file search. - - `"send_message"` + - `"auto"` - - `"followup_task"` + - `"default-2024-11-15"` - - `"wait_agent"` + - `score_threshold: Optional[float]` - - `arguments: str` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The JSON string of arguments generated for the action. + - `class BetaComputerTool: …` - - `call_id: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The unique ID linking this call to its output. + - `type: Literal["computer"]` - - `type: Literal["multi_agent_call"]` + The type of the computer tool. Always `computer`. - The type of the multi-agent call. Always `multi_agent_call`. + - `"computer"` - - `"multi_agent_call"` + - `class BetaComputerUsePreviewTool: …` - - `agent: Optional[MultiAgentCallAgent]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The agent that produced this item. + - `display_height: int` - - `agent_name: str` + The height of the computer display. - The canonical name of the agent that produced this item. + - `display_width: int` - - `class MultiAgentCallOutput: …` + The width of the computer display. - - `id: str` + - `environment: Literal["windows", "mac", "linux", 2 more]` - The unique ID of the multi-agent call output item. + The type of computer environment to control. - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `"windows"` - The multi-agent action that produced this result. + - `"mac"` - - `"spawn_agent"` + - `"linux"` - - `"interrupt_agent"` + - `"ubuntu"` - - `"list_agents"` + - `"browser"` - - `"send_message"` + - `type: Literal["computer_use_preview"]` - - `"followup_task"` + The type of the computer use tool. Always `computer_use_preview`. - - `"wait_agent"` + - `"computer_use_preview"` - - `call_id: str` + - `class BetaWebSearchTool: …` - The unique ID of the multi-agent call. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `output: List[BetaResponseOutputText]` + - `type: Literal["web_search", "web_search_2025_08_26"]` - Text output returned by the multi-agent action. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `annotations: List[Annotation]` + - `"web_search"` - The annotations of the text output. + - `"web_search_2025_08_26"` - - `text: str` + - `filters: Optional[Filters]` - The text output from the model. + Filters for the search. - - `type: Literal["output_text"]` + - `allowed_domains: Optional[List[str]]` - The type of the output text. Always `output_text`. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `logprobs: Optional[List[Logprob]]` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `type: Literal["multi_agent_call_output"]` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The type of the multi-agent result. Always `multi_agent_call_output`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `"multi_agent_call_output"` + - `"low"` - - `agent: Optional[MultiAgentCallOutputAgent]` + - `"medium"` - The agent that produced this item. + - `"high"` - - `agent_name: str` + - `user_location: Optional[UserLocation]` - The canonical name of the agent that produced this item. + The approximate location of the user. - - `class BetaResponseFunctionWebSearch: …` + - `city: Optional[str]` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + Free text input for the city of the user, e.g. `San Francisco`. - - `class BetaResponseComputerToolCall: …` + - `country: Optional[str]` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `class BetaResponseComputerToolCallOutputItem: …` + - `region: Optional[str]` - - `id: str` + Free text input for the region of the user, e.g. `California`. - The unique ID of the computer call tool output. + - `timezone: Optional[str]` - - `call_id: str` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The ID of the computer tool call that produced the output. + - `type: Optional[Literal["approximate"]]` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The type of location approximation. Always `approximate`. - A computer screenshot image used with the computer use tool. + - `"approximate"` - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + - `class Mcp: …` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"completed"` + - `server_label: str` - - `"incomplete"` + A label for this MCP server, used to identify it in tool calls. - - `"failed"` + - `type: Literal["mcp"]` - - `"in_progress"` + The type of the MCP tool. Always `mcp`. - - `type: Literal["computer_call_output"]` + - `"mcp"` - The type of the computer tool call output. Always `computer_call_output`. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"computer_call_output"` + The tool invocation context(s). - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + - `"direct"` - The safety checks reported by the API that have been acknowledged by the - developer. + - `"programmatic"` - - `id: str` + - `allowed_tools: Optional[McpAllowedTools]` - The ID of the pending safety check. + List of allowed tool names or a filter object. - - `code: Optional[str]` + - `List[str]` - The type of the pending safety check. + A string array of allowed tool names - - `message: Optional[str]` + - `class McpAllowedToolsMcpToolFilter: …` - Details about the pending safety check. + A filter object to specify which tools are allowed. - - `agent: Optional[Agent]` + - `read_only: Optional[bool]` - The agent that produced this item. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `agent_name: str` + - `tool_names: Optional[List[str]]` - The canonical name of the agent that produced this item. + List of allowed tool names. - - `created_by: Optional[str]` + - `authorization: Optional[str]` - The identifier of the actor that created the item. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `class BetaResponseReasoningItem: …` + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `class Program: …` + Currently supported `connector_id` values are: - - `id: str` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The unique ID of the program item. + - `"connector_dropbox"` - - `call_id: str` + - `"connector_gmail"` - The stable call ID of the program item. + - `"connector_googlecalendar"` - - `code: str` + - `"connector_googledrive"` - The JavaScript source executed by programmatic tool calling. + - `"connector_microsoftteams"` - - `fingerprint: str` + - `"connector_outlookcalendar"` - Opaque program replay fingerprint that must be round-tripped. + - `"connector_outlookemail"` - - `type: Literal["program"]` + - `"connector_sharepoint"` - The type of the item. Always `program`. + - `defer_loading: Optional[bool]` - - `"program"` + Whether this MCP tool is deferred and discovered via tool search. - - `agent: Optional[ProgramAgent]` + - `headers: Optional[Dict[str, str]]` - The agent that produced this item. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `agent_name: str` + - `require_approval: Optional[McpRequireApproval]` - The canonical name of the agent that produced this item. + Specify which of the MCP server's tools require approval. - - `class ProgramOutput: …` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - - `id: str` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The unique ID of the program output item. + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `call_id: str` + A filter object to specify which tools are allowed. - The call ID of the program item. + - `read_only: Optional[bool]` - - `result: str` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The result produced by the program item. + - `tool_names: Optional[List[str]]` - - `status: Literal["completed", "incomplete"]` + List of allowed tool names. - The terminal status of the program output item. + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - - `"completed"` + A filter object to specify which tools are allowed. - - `"incomplete"` + - `read_only: Optional[bool]` - - `type: Literal["program_output"]` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The type of the item. Always `program_output`. + - `tool_names: Optional[List[str]]` - - `"program_output"` + List of allowed tool names. - - `agent: Optional[ProgramOutputAgent]` + - `Literal["always", "never"]` - The agent that produced this item. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `agent_name: str` + - `"always"` - The canonical name of the agent that produced this item. + - `"never"` - - `class BetaResponseToolSearchCall: …` + - `server_description: Optional[str]` - - `id: str` + Optional description of the MCP server, used to provide more context. - The unique ID of the tool search call item. + - `server_url: Optional[str]` - - `arguments: object` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - Arguments used for the tool search call. + - `tunnel_id: Optional[str]` - - `call_id: Optional[str]` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The unique ID of the tool search call generated by the model. + - `class CodeInterpreter: …` - - `execution: Literal["server", "client"]` + A tool that runs Python code to help generate a response to a prompt. - Whether tool search was executed by the server or by the client. + - `container: CodeInterpreterContainer` - - `"server"` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `"client"` + - `str` - - `status: Literal["in_progress", "completed", "incomplete"]` + The container ID. - The status of the tool search call item that was recorded. + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `"in_progress"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"completed"` + - `type: Literal["auto"]` - - `"incomplete"` + Always `auto`. - - `type: Literal["tool_search_call"]` + - `"auto"` - The type of the item. Always `tool_search_call`. + - `file_ids: Optional[List[str]]` - - `"tool_search_call"` + An optional list of uploaded files to make available to your code. - - `agent: Optional[Agent]` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The agent that produced this item. + The memory limit for the code interpreter container. - - `agent_name: str` + - `"1g"` - The canonical name of the agent that produced this item. + - `"4g"` - - `created_by: Optional[str]` + - `"16g"` - The identifier of the actor that created the item. + - `"64g"` - - `class BetaResponseToolSearchOutputItem: …` + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - - `id: str` + Network access policy for the container. - The unique ID of the tool search output item. + - `class BetaContainerNetworkPolicyDisabled: …` - - `call_id: Optional[str]` + - `type: Literal["disabled"]` - The unique ID of the tool search call generated by the model. + Disable outbound network access. Always `disabled`. - - `execution: Literal["server", "client"]` + - `"disabled"` - Whether tool search was executed by the server or by the client. + - `class BetaContainerNetworkPolicyAllowlist: …` - - `"server"` + - `allowed_domains: List[str]` - - `"client"` + A list of allowed domains when type is `allowlist`. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `type: Literal["allowlist"]` - The status of the tool search output item that was recorded. + Allow outbound network access only to specified domains. Always `allowlist`. - - `"in_progress"` + - `"allowlist"` - - `"completed"` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `"incomplete"` + Optional domain-scoped secrets for allowlisted domains. - - `tools: List[BetaTool]` + - `domain: str` - The loaded tool definitions returned by tool search. + The domain associated with the secret. - - `class BetaFunctionTool: …` + - `name: str` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The name of the secret to inject for the domain. - - `class BetaFileSearchTool: …` + - `value: str` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The secret value to inject for the domain. - - `class BetaComputerTool: …` + - `type: Literal["code_interpreter"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the code interpreter tool. Always `code_interpreter`. - - `class BetaComputerUsePreviewTool: …` + - `"code_interpreter"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `class BetaWebSearchTool: …` + The tool invocation context(s). - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"direct"` - - `class Mcp: …` + - `"programmatic"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `class ProgrammaticToolCalling: …` - - `class CodeInterpreter: …` + - `type: Literal["programmatic_tool_calling"]` - A tool that runs Python code to help generate a response to a prompt. + The type of the tool. Always `programmatic_tool_calling`. - - `class ProgrammaticToolCalling: …` + - `"programmatic_tool_calling"` - `class ImageGeneration: …` A tool that generates images using the GPT image models. - - `class LocalShell: …` + - `type: Literal["image_generation"]` - A tool that allows the model to execute shell commands in a local environment. + The type of the image generation tool. Always `image_generation`. - - `class BetaFunctionShellTool: …` + - `"image_generation"` - A tool that allows the model to execute shell commands. + - `action: Optional[Literal["generate", "edit", "auto"]]` - - `class BetaCustomTool: …` + Whether to generate a new image or edit an existing image. Default: `auto`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"generate"` - - `class BetaNamespaceTool: …` + - `"edit"` - Groups function/custom tools under a shared namespace. + - `"auto"` - - `class BetaToolSearchTool: …` + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - Hosted or BYOT tool search configuration for deferred tools. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `class BetaWebSearchPreviewTool: …` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `class BetaApplyPatchTool: …` + - `"transparent"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"opaque"` - - `type: Literal["tool_search_output"]` + - `"auto"` - The type of the item. Always `tool_search_output`. + - `input_fidelity: Optional[Literal["high", "low"]]` - - `"tool_search_output"` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `agent: Optional[Agent]` + - `"high"` - The agent that produced this item. + - `"low"` - - `agent_name: str` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - The canonical name of the agent that produced this item. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `created_by: Optional[str]` + - `file_id: Optional[str]` - The identifier of the actor that created the item. + File ID for the mask image. - - `class AdditionalTools: …` + - `image_url: Optional[str]` - - `id: str` + Base64-encoded mask image. - The unique ID of the additional tools item. + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - - `role: Literal["unknown", "user", "assistant", 5 more]` + The image generation model to use. Default: `gpt-image-1`. - The role that provided the additional tools. + - `str` - - `"unknown"` + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `"user"` + The image generation model to use. Default: `gpt-image-1`. - - `"assistant"` + - `"gpt-image-1"` - - `"system"` + - `"gpt-image-1-mini"` - - `"critic"` + - `"gpt-image-2"` - - `"discriminator"` + - `"gpt-image-2-2026-04-21"` - - `"developer"` + - `"gpt-image-1.5"` - - `"tool"` + - `"chatgpt-image-latest"` - - `tools: List[BetaTool]` + - `moderation: Optional[Literal["auto", "low"]]` - The additional tool definitions made available at this item. + Moderation level for the generated image. Default: `auto`. - - `class BetaFunctionTool: …` + - `"auto"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `"low"` - - `class BetaFileSearchTool: …` + - `output_compression: Optional[int]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + Compression level for the output image. Default: 100. - - `class BetaComputerTool: …` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `class BetaComputerUsePreviewTool: …` + - `"png"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"webp"` - - `class BetaWebSearchTool: …` + - `"jpeg"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `partial_images: Optional[int]` - - `class Mcp: …` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - - `class CodeInterpreter: …` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - A tool that runs Python code to help generate a response to a prompt. + - `"low"` - - `class ProgrammaticToolCalling: …` + - `"medium"` - - `class ImageGeneration: …` + - `"high"` - A tool that generates images using the GPT image models. + - `"auto"` - - `class LocalShell: …` + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - A tool that allows the model to execute shell commands in a local environment. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `class BetaFunctionShellTool: …` + - `str` - A tool that allows the model to execute shell commands. + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `class BetaCustomTool: …` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"1024x1024"` - - `class BetaNamespaceTool: …` + - `"1024x1536"` - Groups function/custom tools under a shared namespace. + - `"1536x1024"` - - `class BetaToolSearchTool: …` + - `"auto"` - Hosted or BYOT tool search configuration for deferred tools. + - `class LocalShell: …` - - `class BetaWebSearchPreviewTool: …` + A tool that allows the model to execute shell commands in a local environment. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `type: Literal["local_shell"]` - - `class BetaApplyPatchTool: …` + The type of the local shell tool. Always `local_shell`. - Allows the assistant to create, delete, or update files using unified diffs. + - `"local_shell"` - - `type: Literal["additional_tools"]` + - `class BetaFunctionShellTool: …` - The type of the item. Always `additional_tools`. + A tool that allows the model to execute shell commands. - - `"additional_tools"` + - `type: Literal["shell"]` - - `agent: Optional[AdditionalToolsAgent]` + The type of the shell tool. Always `shell`. - The agent that produced this item. + - `"shell"` - - `agent_name: str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The canonical name of the agent that produced this item. + The tool invocation context(s). - - `class BetaResponseCompactionItem: …` + - `"direct"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"programmatic"` - - `id: str` + - `environment: Optional[Environment]` - The unique ID of the compaction item. + - `class BetaContainerAuto: …` - - `encrypted_content: str` + - `type: Literal["container_auto"]` - The encrypted content that was produced by compaction. + Automatically creates a container for this request - - `type: Literal["compaction"]` + - `"container_auto"` - The type of the item. Always `compaction`. + - `file_ids: Optional[List[str]]` - - `"compaction"` + An optional list of uploaded files to make available to your code. - - `agent: Optional[Agent]` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The agent that produced this item. + The memory limit for the container. - - `agent_name: str` + - `"1g"` - The canonical name of the agent that produced this item. + - `"4g"` - - `created_by: Optional[str]` + - `"16g"` - The identifier of the actor that created the item. + - `"64g"` - - `class ImageGenerationCall: …` + - `network_policy: Optional[NetworkPolicy]` - An image generation request made by the model. + Network access policy for the container. - - `id: str` + - `class BetaContainerNetworkPolicyDisabled: …` - The unique ID of the image generation call. + - `class BetaContainerNetworkPolicyAllowlist: …` - - `result: Optional[str]` + - `skills: Optional[List[Skill]]` - The generated image encoded in base64. + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference: …` + + - `skill_id: str` + + The ID of the referenced skill. + + - `type: Literal["skill_reference"]` + + References a skill created with the /v1/skills endpoint. + + - `"skill_reference"` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `version: Optional[str]` - The status of the image generation call. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `"in_progress"` + - `class BetaInlineSkill: …` - - `"completed"` + - `description: str` - - `"generating"` + The description of the skill. - - `"failed"` + - `name: str` - - `type: Literal["image_generation_call"]` + The name of the skill. - The type of the image generation call. Always `image_generation_call`. + - `source: BetaInlineSkillSource` - - `"image_generation_call"` + Inline skill payload - - `agent: Optional[ImageGenerationCallAgent]` + - `data: str` - The agent that produced this item. + Base64-encoded skill zip bundle. - - `agent_name: str` + - `media_type: Literal["application/zip"]` - The canonical name of the agent that produced this item. + The media type of the inline skill payload. Must be `application/zip`. - - `class BetaResponseCodeInterpreterToolCall: …` + - `"application/zip"` - A tool call to run code. + - `type: Literal["base64"]` - - `class LocalShellCall: …` + The type of the inline skill source. Must be `base64`. - A tool call to run a command on the local shell. + - `"base64"` - - `id: str` + - `type: Literal["inline"]` - The unique ID of the local shell call. + Defines an inline skill for this request. - - `action: LocalShellCallAction` + - `"inline"` - Execute a shell command on the server. + - `class BetaLocalEnvironment: …` - - `command: List[str]` + - `type: Literal["local"]` - The command to run. + Use a local computer environment. - - `env: Dict[str, str]` + - `"local"` - Environment variables to set for the command. + - `skills: Optional[List[BetaLocalSkill]]` - - `type: Literal["exec"]` + An optional list of skills. - The type of the local shell action. Always `exec`. + - `description: str` - - `"exec"` + The description of the skill. - - `timeout_ms: Optional[int]` + - `name: str` - Optional timeout in milliseconds for the command. + The name of the skill. - - `user: Optional[str]` + - `path: str` - Optional user to run the command as. + The path to the directory containing the skill. - - `working_directory: Optional[str]` + - `class BetaContainerReference: …` - Optional working directory to run the command in. + - `container_id: str` - - `call_id: str` + The ID of the referenced container. - The unique ID of the local shell tool call generated by the model. + - `type: Literal["container_reference"]` - - `status: Literal["in_progress", "completed", "incomplete"]` + References a container created with the /v1/containers endpoint - The status of the local shell call. + - `"container_reference"` - - `"in_progress"` + - `class BetaCustomTool: …` - - `"completed"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `"incomplete"` + - `name: str` - - `type: Literal["local_shell_call"]` + The name of the custom tool, used to identify it in tool calls. - The type of the local shell call. Always `local_shell_call`. + - `type: Literal["custom"]` - - `"local_shell_call"` + The type of the custom tool. Always `custom`. - - `agent: Optional[LocalShellCallAgent]` + - `"custom"` - The agent that produced this item. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `agent_name: str` + The tool invocation context(s). - The canonical name of the agent that produced this item. + - `"direct"` - - `class LocalShellCallOutput: …` + - `"programmatic"` - The output of a local shell tool call. + - `defer_loading: Optional[bool]` - - `id: str` + Whether this tool should be deferred and discovered via tool search. - The unique ID of the local shell tool call generated by the model. + - `description: Optional[str]` - - `output: str` + Optional description of the custom tool, used to provide more context. - A JSON string of the output of the local shell tool call. + - `format: Optional[Format]` - - `type: Literal["local_shell_call_output"]` + The input format for the custom tool. Default is unconstrained text. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `class FormatText: …` - - `"local_shell_call_output"` + Unconstrained free-form text. - - `agent: Optional[LocalShellCallOutputAgent]` + - `type: Literal["text"]` - The agent that produced this item. + Unconstrained text format. Always `text`. - - `agent_name: str` + - `"text"` - The canonical name of the agent that produced this item. + - `class FormatGrammar: …` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + A grammar defined by the user. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `definition: str` - - `"in_progress"` + The grammar definition. - - `"completed"` + - `syntax: Literal["lark", "regex"]` - - `"incomplete"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `class BetaResponseFunctionShellToolCall: …` + - `"lark"` - A tool call that executes one or more shell commands in a managed environment. + - `"regex"` - - `id: str` + - `type: Literal["grammar"]` - The unique ID of the shell tool call. Populated when this item is returned via API. + Grammar format. Always `grammar`. - - `action: Action` + - `"grammar"` - The shell commands and limits that describe how to run the tool call. + - `class BetaNamespaceTool: …` - - `commands: List[str]` + Groups function/custom tools under a shared namespace. - - `max_output_length: Optional[int]` + - `description: str` - Optional maximum number of characters to return from each command. + A description of the namespace shown to the model. - - `timeout_ms: Optional[int]` + - `name: str` - Optional timeout in milliseconds for the commands. + The namespace name used in tool calls (for example, `crm`). - - `call_id: str` + - `tools: List[Tool]` - The unique ID of the shell tool call generated by the model. + The function/custom tools available inside this namespace. - - `environment: Optional[Environment]` + - `class ToolFunction: …` - Represents the use of a local environment to perform shell actions. + - `name: str` - - `class BetaResponseLocalEnvironment: …` + - `type: Literal["function"]` - Represents the use of a local environment to perform shell actions. + - `"function"` - - `type: Literal["local"]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The environment type. Always `local`. + The tool invocation context(s). - - `"local"` + - `"direct"` - - `class BetaResponseContainerReference: …` + - `"programmatic"` - Represents a container created with /v1/containers. + - `defer_loading: Optional[bool]` - - `container_id: str` + Whether this function should be deferred and discovered via tool search. - - `type: Literal["container_reference"]` + - `description: Optional[str]` - The environment type. Always `container_reference`. + - `output_schema: Optional[Dict[str, object]]` - - `"container_reference"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `parameters: Optional[object]` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `strict: Optional[bool]` - - `"in_progress"` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `"completed"` + - `class BetaCustomTool: …` - - `"incomplete"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `type: Literal["shell_call"]` + - `type: Literal["namespace"]` - The type of the item. Always `shell_call`. + The type of the tool. Always `namespace`. - - `"shell_call"` + - `"namespace"` - - `agent: Optional[Agent]` + - `class BetaToolSearchTool: …` - The agent that produced this item. + Hosted or BYOT tool search configuration for deferred tools. - - `agent_name: str` + - `type: Literal["tool_search"]` - The canonical name of the agent that produced this item. + The type of the tool. Always `tool_search`. - - `caller: Optional[Caller]` + - `"tool_search"` - The execution context that produced this tool call. + - `description: Optional[str]` - - `class CallerDirect: …` + Description shown to the model for a client-executed tool search tool. - - `type: Literal["direct"]` + - `execution: Optional[Literal["server", "client"]]` - - `"direct"` + Whether tool search is executed by the server or by the client. - - `class CallerProgram: …` + - `"server"` - - `caller_id: str` + - `"client"` - The call ID of the program item that produced this tool call. + - `parameters: Optional[object]` - - `type: Literal["program"]` + Parameter schema for a client-executed tool search tool. - - `"program"` + - `class BetaWebSearchPreviewTool: …` - - `created_by: Optional[str]` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The ID of the entity that created this tool call. + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - - `class BetaResponseFunctionShellToolCallOutput: …` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The output of a shell tool call that was emitted. + - `"web_search_preview"` - - `id: str` + - `"web_search_preview_2025_03_11"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `call_id: str` + - `"text"` - The unique ID of the shell tool call generated by the model. + - `"image"` - - `max_output_length: Optional[int]` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `output: List[Output]` + - `"low"` - An array of shell call output contents + - `"medium"` - - `outcome: OutputOutcome` + - `"high"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `user_location: Optional[UserLocation]` - - `class OutputOutcomeTimeout: …` + The user's location. - Indicates that the shell call exceeded its configured time limit. + - `type: Literal["approximate"]` - - `type: Literal["timeout"]` + The type of location approximation. Always `approximate`. - The outcome type. Always `timeout`. + - `"approximate"` - - `"timeout"` + - `city: Optional[str]` - - `class OutputOutcomeExit: …` + Free text input for the city of the user, e.g. `San Francisco`. - Indicates that the shell commands finished and returned an exit code. + - `country: Optional[str]` - - `exit_code: int` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Exit code from the shell process. + - `region: Optional[str]` - - `type: Literal["exit"]` + Free text input for the region of the user, e.g. `California`. - The outcome type. Always `exit`. + - `timezone: Optional[str]` - - `"exit"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `stderr: str` + - `class BetaApplyPatchTool: …` - The standard error output that was captured. + Allows the assistant to create, delete, or update files using unified diffs. - - `stdout: str` + - `type: Literal["apply_patch"]` - The standard output that was captured. + The type of the tool. Always `apply_patch`. - - `created_by: Optional[str]` + - `"apply_patch"` - The identifier of the actor that created the item. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `status: Literal["in_progress", "completed", "incomplete"]` + The tool invocation context(s). - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `"direct"` - - `"in_progress"` + - `"programmatic"` - - `"completed"` + - `type: Literal["tool_search_output"]` - - `"incomplete"` + The item type. Always `tool_search_output`. - - `type: Literal["shell_call_output"]` + - `"tool_search_output"` - The type of the shell call output. Always `shell_call_output`. + - `id: Optional[str]` - - `"shell_call_output"` + The unique ID of this tool search output. - `agent: Optional[Agent]` @@ -59523,111 +70748,115 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `call_id: Optional[str]` - The execution context that produced this tool call. + The unique ID of the tool search call generated by the model. - - `class CallerDirect: …` + - `execution: Optional[Literal["server", "client"]]` - - `type: Literal["direct"]` + Whether tool search was executed by the server or by the client. - - `"direct"` + - `"server"` - - `class CallerProgram: …` + - `"client"` - - `caller_id: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The call ID of the program item that produced this tool call. + The status of the tool search output. - - `type: Literal["program"]` + - `"in_progress"` - - `"program"` + - `"completed"` - - `created_by: Optional[str]` + - `"incomplete"` - The identifier of the actor that created the item. + - `class AdditionalTools: …` - - `class BetaResponseApplyPatchToolCall: …` + - `role: Literal["developer"]` - A tool call that applies file diffs by creating, deleting, or updating files. + The role that provided the additional tools. Only `developer` is supported. - - `id: str` + - `"developer"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `tools: List[BetaTool]` - - `call_id: str` + A list of additional tools made available at this item. - The unique ID of the apply patch tool call generated by the model. + - `class BetaFunctionTool: …` - - `operation: Operation` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `class BetaFileSearchTool: …` - - `class OperationCreateFile: …` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - Instruction describing how to create a file via the apply_patch tool. + - `class BetaComputerTool: …` - - `diff: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Diff to apply. + - `class BetaComputerUsePreviewTool: …` - - `path: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Path of the file to create. + - `class BetaWebSearchTool: …` - - `type: Literal["create_file"]` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Create a new file with the provided diff. + - `class Mcp: …` - - `"create_file"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `class OperationDeleteFile: …` + - `class CodeInterpreter: …` - Instruction describing how to delete a file via the apply_patch tool. + A tool that runs Python code to help generate a response to a prompt. - - `path: str` + - `class ProgrammaticToolCalling: …` - Path of the file to delete. + - `class ImageGeneration: …` - - `type: Literal["delete_file"]` + A tool that generates images using the GPT image models. - Delete the specified file. + - `class LocalShell: …` - - `"delete_file"` + A tool that allows the model to execute shell commands in a local environment. - - `class OperationUpdateFile: …` + - `class BetaFunctionShellTool: …` - Instruction describing how to update a file via the apply_patch tool. + A tool that allows the model to execute shell commands. - - `diff: str` + - `class BetaCustomTool: …` - Diff to apply. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `path: str` + - `class BetaNamespaceTool: …` - Path of the file to update. + Groups function/custom tools under a shared namespace. - - `type: Literal["update_file"]` + - `class BetaToolSearchTool: …` - Update an existing file with the provided diff. + Hosted or BYOT tool search configuration for deferred tools. - - `"update_file"` + - `class BetaWebSearchPreviewTool: …` - - `status: Literal["in_progress", "completed"]` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `class BetaApplyPatchTool: …` - - `"in_progress"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"completed"` + - `type: Literal["additional_tools"]` - - `type: Literal["apply_patch_call"]` + The item type. Always `additional_tools`. - The type of the item. Always `apply_patch_call`. + - `"additional_tools"` - - `"apply_patch_call"` + - `id: Optional[str]` - - `agent: Optional[Agent]` + The unique ID of this additional tools item. + + - `agent: Optional[AdditionalToolsAgent]` The agent that produced this item. @@ -59635,55 +70864,36 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` - - - `type: Literal["direct"]` - - - `"direct"` - - - `class CallerProgram: …` - - - `caller_id: str` - - The call ID of the program item that produced this tool call. - - - `type: Literal["program"]` - - - `"program"` - - - `created_by: Optional[str]` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput: …` + - `class BetaResponseReasoningItem: …` - The output emitted by an apply patch tool call. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: str` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The unique identifier of the reasoning content. - - `call_id: str` + - `summary: List[Summary]` - The unique ID of the apply patch tool call generated by the model. + Reasoning summary content. - - `status: Literal["completed", "failed"]` + - `text: str` - The status of the apply patch tool call output. One of `completed` or `failed`. + A summary of the reasoning output from the model so far. - - `"completed"` + - `type: Literal["summary_text"]` - - `"failed"` + The type of the object. Always `summary_text`. - - `type: Literal["apply_patch_call_output"]` + - `"summary_text"` - The type of the item. Always `apply_patch_call_output`. + - `type: Literal["reasoning"]` - - `"apply_patch_call_output"` + The type of the object. Always `reasoning`. + + - `"reasoning"` - `agent: Optional[Agent]` @@ -59693,61 +70903,55 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` - - - `type: Literal["direct"]` - - - `"direct"` + - `content: Optional[List[Content]]` - - `class CallerProgram: …` + Reasoning text content. - - `caller_id: str` + - `text: str` - The call ID of the program item that produced this tool call. + The reasoning text from the model. - - `type: Literal["program"]` + - `type: Literal["reasoning_text"]` - - `"program"` + The type of the reasoning text. Always `reasoning_text`. - - `created_by: Optional[str]` + - `"reasoning_text"` - The ID of the entity that created this tool call output. + - `encrypted_content: Optional[str]` - - `output: Optional[str]` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - Optional textual output returned by the apply patch tool. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `class McpCall: …` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - An invocation of a tool on an MCP server. + - `"in_progress"` - - `id: str` + - `"completed"` - The unique ID of the tool call. + - `"incomplete"` - - `arguments: str` + - `class BetaResponseCompactionItemParam: …` - A JSON string of the arguments passed to the tool. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `name: str` + - `encrypted_content: str` - The name of the tool that was run. + The encrypted content of the compaction summary. - - `server_label: str` + - `type: Literal["compaction"]` - The label of the MCP server running the tool. + The type of the item. Always `compaction`. - - `type: Literal["mcp_call"]` + - `"compaction"` - The type of the item. Always `mcp_call`. + - `id: Optional[str]` - - `"mcp_call"` + The ID of the compaction item. - - `agent: Optional[McpCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -59755,110 +70959,114 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `approval_request_id: Optional[str]` + - `class ImageGenerationCall: …` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + An image generation request made by the model. - - `error: Optional[str]` + - `id: str` - The error from the tool call, if any. + The unique ID of the image generation call. - - `output: Optional[str]` + - `result: Optional[str]` - The output from the tool call. + The generated image encoded in base64. - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The status of the image generation call. - `"in_progress"` - `"completed"` - - `"incomplete"` - - - `"calling"` + - `"generating"` - `"failed"` - - `class McpListTools: …` + - `type: Literal["image_generation_call"]` - A list of tools available on an MCP server. + The type of the image generation call. Always `image_generation_call`. - - `id: str` + - `"image_generation_call"` - The unique ID of the list. + - `agent: Optional[ImageGenerationCallAgent]` - - `server_label: str` + The agent that produced this item. - The label of the MCP server. + - `agent_name: str` - - `tools: List[McpListToolsTool]` + The canonical name of the agent that produced this item. - The tools available on the server. + - `class BetaResponseCodeInterpreterToolCall: …` - - `input_schema: object` + A tool call to run code. - The JSON schema describing the tool's input. + - `id: str` - - `name: str` + The unique ID of the code interpreter tool call. - The name of the tool. + - `code: Optional[str]` - - `annotations: Optional[object]` + The code to run, or null if not available. - Additional annotations about the tool. + - `container_id: str` - - `description: Optional[str]` + The ID of the container used to run the code. - The description of the tool. + - `outputs: Optional[List[Output]]` - - `type: Literal["mcp_list_tools"]` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The type of the item. Always `mcp_list_tools`. + - `class OutputLogs: …` - - `"mcp_list_tools"` + The logs output from the code interpreter. - - `agent: Optional[McpListToolsAgent]` + - `logs: str` - The agent that produced this item. + The logs output from the code interpreter. - - `agent_name: str` + - `type: Literal["logs"]` - The canonical name of the agent that produced this item. + The type of the output. Always `logs`. - - `error: Optional[str]` + - `"logs"` - Error message if the server could not list tools. + - `class OutputImage: …` - - `class McpApprovalRequest: …` + The image output from the code interpreter. - A request for human approval of a tool invocation. + - `type: Literal["image"]` - - `id: str` + The type of the output. Always `image`. - The unique ID of the approval request. + - `"image"` - - `arguments: str` + - `url: str` - A JSON string of arguments for the tool. + The URL of the image output from the code interpreter. - - `name: str` + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - The name of the tool to run. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `server_label: str` + - `"in_progress"` - The label of the MCP server making the request. + - `"completed"` - - `type: Literal["mcp_approval_request"]` + - `"incomplete"` - The type of the item. Always `mcp_approval_request`. + - `"interpreting"` - - `"mcp_approval_request"` + - `"failed"` - - `agent: Optional[McpApprovalRequestAgent]` + - `type: Literal["code_interpreter_call"]` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `agent: Optional[Agent]` The agent that produced this item. @@ -59866,56 +71074,51 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class McpApprovalResponse: …` + - `class LocalShellCall: …` - A response to an MCP approval request. + A tool call to run a command on the local shell. - `id: str` - The unique ID of the approval response - - - `approval_request_id: str` - - The ID of the approval request being answered. + The unique ID of the local shell call. - - `approve: bool` + - `action: LocalShellCallAction` - Whether the request was approved. + Execute a shell command on the server. - - `type: Literal["mcp_approval_response"]` + - `command: List[str]` - The type of the item. Always `mcp_approval_response`. + The command to run. - - `"mcp_approval_response"` + - `env: Dict[str, str]` - - `agent: Optional[McpApprovalResponseAgent]` + Environment variables to set for the command. - The agent that produced this item. + - `type: Literal["exec"]` - - `agent_name: str` + The type of the local shell action. Always `exec`. - The canonical name of the agent that produced this item. + - `"exec"` - - `reason: Optional[str]` + - `timeout_ms: Optional[int]` - Optional reason for the decision. + Optional timeout in milliseconds for the command. - - `class BetaResponseCustomToolCall: …` + - `user: Optional[str]` - A call to a custom tool created by the model. + Optional user to run the command as. - - `class BetaResponseCustomToolCallOutputItem: …` + - `working_directory: Optional[str]` - The output of a custom tool call from your code, being sent back to the model. + Optional working directory to run the command in. - - `id: str` + - `call_id: str` - The unique ID of the custom tool call output item. + The unique ID of the local shell tool call generated by the model. - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the local shell call. - `"in_progress"` @@ -59923,868 +71126,757 @@ print(compacted_response) - `"incomplete"` - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `parallel_tool_calls: bool` - - Whether to allow the model to run tool calls in parallel. - - - `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. - We generally recommend altering this or `top_p` but not both. - - - `tool_choice: ToolChoice` - - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. - - - `Literal["none", "auto", "required"]` - - - `"none"` + - `type: Literal["local_shell_call"]` - - `"auto"` + The type of the local shell call. Always `local_shell_call`. - - `"required"` + - `"local_shell_call"` - - `class BetaToolChoiceAllowed: …` + - `agent: Optional[LocalShellCallAgent]` - Constrains the tools available to the model to a pre-defined set. + The agent that produced this item. - - `mode: Literal["auto", "required"]` + - `agent_name: str` - Constrains the tools available to the model to a pre-defined set. + The canonical name of the agent that produced this item. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `class LocalShellCallOutput: …` - `required` requires the model to call one or more of the allowed tools. + The output of a local shell tool call. - - `"auto"` + - `id: str` - - `"required"` + The unique ID of the local shell tool call generated by the model. - - `tools: List[Dict[str, object]]` + - `output: str` - A list of tool definitions that the model should be allowed to call. + A JSON string of the output of the local shell tool call. - For the Responses API, the list of tool definitions might look like: + - `type: Literal["local_shell_call_output"]` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `type: Literal["allowed_tools"]` + - `"local_shell_call_output"` - Allowed tool configuration type. Always `allowed_tools`. + - `agent: Optional[LocalShellCallOutputAgent]` - - `"allowed_tools"` + The agent that produced this item. - - `class BetaToolChoiceTypes: …` + - `agent_name: str` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + The canonical name of the agent that produced this item. - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Allowed values are: + - `"in_progress"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"completed"` - - `"file_search"` + - `"incomplete"` - - `"web_search_preview"` + - `class ShellCall: …` - - `"computer"` + A tool representing a request to execute one or more shell commands. - - `"computer_use_preview"` + - `action: ShellCallAction` - - `"computer_use"` + The shell commands and limits that describe how to run the tool call. - - `"web_search_preview_2025_03_11"` + - `commands: List[str]` - - `"image_generation"` + Ordered shell commands for the execution environment to run. - - `"code_interpreter"` + - `max_output_length: Optional[int]` - - `class BetaToolChoiceFunction: …` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Use this option to force the model to call a specific function. + - `timeout_ms: Optional[int]` - - `name: str` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The name of the function to call. + - `call_id: str` - - `type: Literal["function"]` + The unique ID of the shell tool call generated by the model. - For function calling, the type is always `function`. + - `type: Literal["shell_call"]` - - `"function"` + The type of the item. Always `shell_call`. - - `class BetaToolChoiceMcp: …` + - `"shell_call"` - Use this option to force the model to call a specific tool on a remote MCP server. + - `id: Optional[str]` - - `server_label: str` + The unique ID of the shell tool call. Populated when this item is returned via API. - The label of the MCP server to use. + - `agent: Optional[ShellCallAgent]` - - `type: Literal["mcp"]` + The agent that produced this item. - For MCP tools, the type is always `mcp`. + - `agent_name: str` - - `"mcp"` + The canonical name of the agent that produced this item. - - `name: Optional[str]` + - `caller: Optional[ShellCallCaller]` - The name of the tool to call on the server. + The execution context that produced this tool call. - - `class BetaToolChoiceCustom: …` + - `class ShellCallCallerDirect: …` - Use this option to force the model to call a specific custom tool. + - `type: Literal["direct"]` - - `name: str` + The caller type. Always `direct`. - The name of the custom tool to call. + - `"direct"` - - `type: Literal["custom"]` + - `class ShellCallCallerProgram: …` - For custom tool calling, the type is always `custom`. + - `caller_id: str` - - `"custom"` + The call ID of the program item that produced this tool call. - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + - `type: Literal["program"]` - - `type: Literal["programmatic_tool_calling"]` + The caller type. Always `program`. - The tool to call. Always `programmatic_tool_calling`. + - `"program"` - - `"programmatic_tool_calling"` + - `environment: Optional[ShellCallEnvironment]` - - `class BetaToolChoiceApplyPatch: …` + The environment to execute the shell commands in. - Forces the model to call the apply_patch tool when executing a tool call. + - `class BetaLocalEnvironment: …` - - `type: Literal["apply_patch"]` + - `class BetaContainerReference: …` - The tool to call. Always `apply_patch`. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"apply_patch"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `class BetaToolChoiceShell: …` + - `"in_progress"` - Forces the model to call the shell tool when a tool call is required. + - `"completed"` - - `type: Literal["shell"]` + - `"incomplete"` - The tool to call. Always `shell`. + - `class ShellCallOutput: …` - - `"shell"` + The streamed output items emitted by a shell tool call. - - `tools: List[BetaTool]` + - `call_id: str` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The unique ID of the shell tool call generated by the model. - We support the following categories of tools: + - `output: List[BetaResponseFunctionShellCallOutputContent]` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `class BetaFunctionTool: …` + - `outcome: Outcome` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The exit or timeout outcome associated with this shell call. - - `class BetaFileSearchTool: …` + - `class OutcomeTimeout: …` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + Indicates that the shell call exceeded its configured time limit. - - `class BetaComputerTool: …` + - `type: Literal["timeout"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The outcome type. Always `timeout`. - - `class BetaComputerUsePreviewTool: …` + - `"timeout"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class OutcomeExit: …` - - `class BetaWebSearchTool: …` + Indicates that the shell commands finished and returned an exit code. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `exit_code: int` - - `class Mcp: …` + The exit code returned by the shell process. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: Literal["exit"]` - - `class CodeInterpreter: …` + The outcome type. Always `exit`. - A tool that runs Python code to help generate a response to a prompt. + - `"exit"` - - `class ProgrammaticToolCalling: …` + - `stderr: str` - - `class ImageGeneration: …` + Captured stderr output for the shell call. - A tool that generates images using the GPT image models. + - `stdout: str` - - `class LocalShell: …` + Captured stdout output for the shell call. - A tool that allows the model to execute shell commands in a local environment. + - `type: Literal["shell_call_output"]` - - `class BetaFunctionShellTool: …` + The type of the item. Always `shell_call_output`. - A tool that allows the model to execute shell commands. + - `"shell_call_output"` - - `class BetaCustomTool: …` + - `id: Optional[str]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `class BetaNamespaceTool: …` + - `agent: Optional[ShellCallOutputAgent]` - Groups function/custom tools under a shared namespace. + The agent that produced this item. - - `class BetaToolSearchTool: …` + - `agent_name: str` - Hosted or BYOT tool search configuration for deferred tools. + The canonical name of the agent that produced this item. - - `class BetaWebSearchPreviewTool: …` + - `caller: Optional[ShellCallOutputCaller]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The execution context that produced this tool call. - - `class BetaApplyPatchTool: …` + - `class ShellCallOutputCallerDirect: …` - Allows the assistant to create, delete, or update files using unified diffs. + - `type: Literal["direct"]` - - `top_p: Optional[float]` + The caller type. Always `direct`. - 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. + - `"direct"` - We generally recommend altering this or `temperature` but not both. + - `class ShellCallOutputCallerProgram: …` - - `background: Optional[bool]` + - `caller_id: str` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The call ID of the program item that produced this tool call. - - `completed_at: Optional[float]` + - `type: Literal["program"]` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The caller type. Always `program`. - - `conversation: Optional[Conversation]` + - `"program"` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `max_output_length: Optional[int]` - - `id: str` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The unique ID of the conversation that this response was associated with. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `max_output_tokens: Optional[int]` + The status of the shell call output. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `"in_progress"` - - `max_tool_calls: Optional[int]` + - `"completed"` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `"incomplete"` - - `moderation: Optional[Moderation]` + - `class ApplyPatchCall: …` - Moderation results for the response input and output, if moderated completions were requested. + A tool call representing a request to create, delete, or update files using diff patches. - - `input: ModerationInput` + - `call_id: str` - Moderation for the response input. + The unique ID of the apply patch tool call generated by the model. - - `class ModerationInputModerationResult: …` + - `operation: ApplyPatchCallOperation` - A moderation result produced for the response input or output. + The specific create, delete, or update instruction for the apply_patch tool call. - - `categories: Dict[str, bool]` + - `class ApplyPatchCallOperationCreateFile: …` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + Instruction for creating a new file via the apply_patch tool. - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `diff: str` - Which modalities of input are reflected by the score for each category. + Unified diff content to apply when creating the file. - - `"text"` + - `path: str` - - `"image"` + Path of the file to create relative to the workspace root. - - `category_scores: Dict[str, float]` + - `type: Literal["create_file"]` - A dictionary of moderation categories to scores. + The operation type. Always `create_file`. - - `flagged: bool` + - `"create_file"` - A boolean indicating whether the content was flagged by any category. + - `class ApplyPatchCallOperationDeleteFile: …` - - `model: str` + Instruction for deleting an existing file via the apply_patch tool. - The moderation model that produced this result. + - `path: str` - - `type: Literal["moderation_result"]` + Path of the file to delete relative to the workspace root. - The object type, which was always `moderation_result` for successful moderation results. + - `type: Literal["delete_file"]` - - `"moderation_result"` + The operation type. Always `delete_file`. - - `class ModerationInputError: …` + - `"delete_file"` - An error produced while attempting moderation for the response input or output. + - `class ApplyPatchCallOperationUpdateFile: …` - - `code: str` + Instruction for updating an existing file via the apply_patch tool. - The error code. + - `diff: str` - - `message: str` + Unified diff content to apply to the existing file. - The error message. + - `path: str` - - `type: Literal["error"]` + Path of the file to update relative to the workspace root. - The object type, which was always `error` for moderation failures. + - `type: Literal["update_file"]` - - `"error"` + The operation type. Always `update_file`. - - `output: ModerationOutput` + - `"update_file"` - Moderation for the response output. + - `status: Literal["in_progress", "completed"]` - - `class ModerationOutputModerationResult: …` + The status of the apply patch tool call. One of `in_progress` or `completed`. - A moderation result produced for the response input or output. + - `"in_progress"` - - `categories: Dict[str, bool]` + - `"completed"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `type: Literal["apply_patch_call"]` - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + The type of the item. Always `apply_patch_call`. - Which modalities of input are reflected by the score for each category. + - `"apply_patch_call"` - - `"text"` + - `id: Optional[str]` - - `"image"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `category_scores: Dict[str, float]` + - `agent: Optional[ApplyPatchCallAgent]` - A dictionary of moderation categories to scores. + The agent that produced this item. - - `flagged: bool` + - `agent_name: str` - A boolean indicating whether the content was flagged by any category. + The canonical name of the agent that produced this item. - - `model: str` + - `caller: Optional[ApplyPatchCallCaller]` - The moderation model that produced this result. + The execution context that produced this tool call. - - `type: Literal["moderation_result"]` + - `class ApplyPatchCallCallerDirect: …` - The object type, which was always `moderation_result` for successful moderation results. + - `type: Literal["direct"]` - - `"moderation_result"` + The caller type. Always `direct`. - - `class ModerationOutputError: …` + - `"direct"` - An error produced while attempting moderation for the response input or output. + - `class ApplyPatchCallCallerProgram: …` - - `code: str` + - `caller_id: str` - The error code. + The call ID of the program item that produced this tool call. - - `message: str` + - `type: Literal["program"]` - The error message. + The caller type. Always `program`. - - `type: Literal["error"]` + - `"program"` - The object type, which was always `error` for moderation failures. + - `class ApplyPatchCallOutput: …` - - `"error"` + The streamed output emitted by an apply patch tool call. - - `previous_response_id: Optional[str]` + - `call_id: str` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + The unique ID of the apply patch tool call generated by the model. - - `prompt: Optional[BetaResponsePrompt]` + - `status: Literal["completed", "failed"]` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The status of the apply patch tool call output. One of `completed` or `failed`. - - `id: str` + - `"completed"` - The unique identifier of the prompt template to use. + - `"failed"` - - `variables: Optional[Dict[str, Variables]]` + - `type: Literal["apply_patch_call_output"]` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The type of the item. Always `apply_patch_call_output`. - - `str` + - `"apply_patch_call_output"` - - `class BetaResponseInputText: …` + - `id: Optional[str]` - A text input to the model. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `class BetaResponseInputImage: …` + - `agent: Optional[ApplyPatchCallOutputAgent]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The agent that produced this item. - - `class BetaResponseInputFile: …` + - `agent_name: str` - A file input to the model. + The canonical name of the agent that produced this item. - - `version: Optional[str]` + - `caller: Optional[ApplyPatchCallOutputCaller]` - Optional version of the prompt template. + The execution context that produced this tool call. - - `prompt_cache_key: Optional[str]` + - `class ApplyPatchCallOutputCallerDirect: …` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `type: Literal["direct"]` - - `prompt_cache_options: Optional[PromptCacheOptions]` + The caller type. Always `direct`. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `"direct"` - - `mode: Literal["implicit", "explicit"]` + - `class ApplyPatchCallOutputCallerProgram: …` - Whether implicit prompt-cache breakpoints were enabled. + - `caller_id: str` - - `"implicit"` + The call ID of the program item that produced this tool call. - - `"explicit"` + - `type: Literal["program"]` - - `ttl: Literal["30m"]` + The caller type. Always `program`. - The minimum lifetime applied to each cache breakpoint. + - `"program"` - - `"30m"` + - `output: Optional[str]` - - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - Deprecated. Use `prompt_cache_options.ttl` instead. + - `class McpListTools: …` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + A list of tools available on an MCP server. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `id: str` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + The unique ID of the list. - - `"in_memory"` + - `server_label: str` - - `"24h"` + The label of the MCP server. - - `reasoning: Optional[Reasoning]` + - `tools: List[McpListToolsTool]` - **gpt-5 and o-series models only** + The tools available on the server. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `input_schema: object` - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + The JSON schema describing the tool's input. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `name: str` - - `"auto"` + The name of the tool. - - `"current_turn"` + - `annotations: Optional[object]` - - `"all_turns"` + Additional annotations about the tool. - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + - `description: Optional[str]` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The description of the tool. - - `"none"` + - `type: Literal["mcp_list_tools"]` - - `"minimal"` + The type of the item. Always `mcp_list_tools`. - - `"low"` + - `"mcp_list_tools"` - - `"medium"` + - `agent: Optional[McpListToolsAgent]` - - `"high"` + The agent that produced this item. - - `"xhigh"` + - `agent_name: str` - - `"max"` + The canonical name of the agent that produced this item. - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + - `error: Optional[str]` - **Deprecated:** use `summary` instead. + Error message if the server could not list tools. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `class McpApprovalRequest: …` - - `"auto"` + A request for human approval of a tool invocation. - - `"concise"` + - `id: str` - - `"detailed"` + The unique ID of the approval request. - - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + - `arguments: str` - Controls the reasoning execution mode for the request. + A JSON string of arguments for the tool. - When returned on a response, this is the effective execution mode. + - `name: str` - - `str` + The name of the tool to run. - - `Literal["standard", "pro"]` + - `server_label: str` - Controls the reasoning execution mode for the request. + The label of the MCP server making the request. - When returned on a response, this is the effective execution mode. + - `type: Literal["mcp_approval_request"]` - - `"standard"` + The type of the item. Always `mcp_approval_request`. - - `"pro"` + - `"mcp_approval_request"` - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + - `agent: Optional[McpApprovalRequestAgent]` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The agent that produced this item. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `agent_name: str` - - `"auto"` + The canonical name of the agent that produced this item. - - `"concise"` + - `class McpApprovalResponse: …` - - `"detailed"` + A response to an MCP approval request. - - `safety_identifier: Optional[str]` + - `approval_request_id: str` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The ID of the approval request being answered. - - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + - `approve: bool` - Specifies the processing type used for serving the request. + Whether the request was approved. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `type: Literal["mcp_approval_response"]` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + The type of the item. Always `mcp_approval_response`. - - `"auto"` + - `"mcp_approval_response"` - - `"default"` + - `id: Optional[str]` - - `"flex"` + The unique ID of the approval response - - `"scale"` + - `agent: Optional[McpApprovalResponseAgent]` - - `"priority"` + The agent that produced this item. - - `status: Optional[BetaResponseStatus]` + - `agent_name: str` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The canonical name of the agent that produced this item. - - `"completed"` + - `reason: Optional[str]` - - `"failed"` + Optional reason for the decision. - - `"in_progress"` + - `class McpCall: …` - - `"cancelled"` + An invocation of a tool on an MCP server. - - `"queued"` + - `id: str` - - `"incomplete"` + The unique ID of the tool call. - - `text: Optional[BetaResponseTextConfig]` + - `arguments: str` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + A JSON string of the arguments passed to the tool. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `name: str` - - `format: Optional[BetaResponseFormatTextConfig]` + The name of the tool that was run. - An object specifying the format that the model must output. + - `server_label: str` - Configuring `{ "type": "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). + The label of the MCP server running the tool. - The default format is `{ "type": "text" }` with no additional options. + - `type: Literal["mcp_call"]` - **Not recommended for gpt-4o and newer models:** + The type of the item. Always `mcp_call`. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `"mcp_call"` - - `class Text: …` + - `agent: Optional[McpCallAgent]` - Default response format. Used to generate text responses. + The agent that produced this item. - - `type: Literal["text"]` + - `agent_name: str` - The type of response format being defined. Always `text`. + The canonical name of the agent that produced this item. - - `"text"` + - `approval_request_id: Optional[str]` - - `class BetaResponseFormatTextJSONSchemaConfig: …` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `error: Optional[str]` - - `name: str` + The error from the tool call, if any. - 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. + - `output: Optional[str]` - - `schema: Dict[str, object]` + The output from the tool call. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - `type: Literal["json_schema"]` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The type of response format being defined. Always `json_schema`. + - `"in_progress"` - - `"json_schema"` + - `"completed"` - - `description: Optional[str]` + - `"incomplete"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"calling"` - - `strict: Optional[bool]` + - `"failed"` - 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). + - `class BetaResponseCustomToolCallOutput: …` - - `class JSONObject: …` + The output of a custom tool call from your code, being sent back to the model. - 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. + - `call_id: str` - - `type: Literal["json_object"]` + The call ID, used to map this custom tool call output to a custom tool call. - The type of response format being defined. Always `json_object`. + - `output: Union[str, List[OutputOutputContentList]]` - - `"json_object"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `verbosity: Optional[Literal["low", "medium", "high"]]` + - `str` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + A string of the output of the custom tool call. - - `"low"` + - `List[OutputOutputContentList]` - - `"medium"` + Text, image, or file output of the custom tool call. - - `"high"` + - `class BetaResponseInputText: …` - - `top_logprobs: Optional[int]` + A text input to the model. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `class BetaResponseInputImage: …` - - `truncation: Optional[Literal["auto", "disabled"]]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The truncation strategy to use for the model response. + - `class BetaResponseInputFile: …` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + A file input to the model. - - `"auto"` + - `type: Literal["custom_tool_call_output"]` - - `"disabled"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `usage: Optional[BetaResponseUsage]` + - `"custom_tool_call_output"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `id: Optional[str]` - - `input_tokens: int` + The unique ID of the custom tool call output in the OpenAI platform. - The number of input tokens. + - `agent: Optional[Agent]` - - `input_tokens_details: InputTokensDetails` + The agent that produced this item. - A detailed breakdown of the input tokens. + - `agent_name: str` - - `cache_write_tokens: int` + The canonical name of the agent that produced this item. - The number of input tokens that were written to the cache. + - `caller: Optional[Caller]` - - `cached_tokens: int` + The execution context that produced this tool call. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `class CallerDirect: …` - - `output_tokens: int` + - `type: Literal["direct"]` - The number of output tokens. + The caller type. Always `direct`. - - `output_tokens_details: OutputTokensDetails` + - `"direct"` - A detailed breakdown of the output tokens. + - `class CallerProgram: …` - - `reasoning_tokens: int` + - `caller_id: str` - The number of reasoning tokens. + The call ID of the program item that produced this tool call. - - `total_tokens: int` + - `type: Literal["program"]` - The total number of tokens used. + The caller type. Always `program`. - - `user: Optional[str]` + - `"program"` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `class BetaResponseCustomToolCall: …` -### Beta Response Apply Patch Tool Call + A call to a custom tool created by the model. -- `class BetaResponseApplyPatchToolCall: …` + - `call_id: str` - A tool call that applies file diffs by creating, deleting, or updating files. + An identifier used to map this custom tool call to a tool call output. - - `id: str` + - `input: str` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The input for the custom tool call generated by the model. - - `call_id: str` + - `name: str` - The unique ID of the apply patch tool call generated by the model. + The name of the custom tool being called. - - `operation: Operation` + - `type: Literal["custom_tool_call"]` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The type of the custom tool call. Always `custom_tool_call`. - - `class OperationCreateFile: …` + - `"custom_tool_call"` - Instruction describing how to create a file via the apply_patch tool. + - `id: Optional[str]` - - `diff: str` + The unique ID of the custom tool call in the OpenAI platform. - Diff to apply. + - `agent: Optional[Agent]` - - `path: str` + The agent that produced this item. - Path of the file to create. + - `agent_name: str` - - `type: Literal["create_file"]` + The canonical name of the agent that produced this item. - Create a new file with the provided diff. + - `caller: Optional[Caller]` - - `"create_file"` + The execution context that produced this tool call. - - `class OperationDeleteFile: …` + - `class CallerDirect: …` - Instruction describing how to delete a file via the apply_patch tool. + - `type: Literal["direct"]` - - `path: str` + - `"direct"` - Path of the file to delete. + - `class CallerProgram: …` - - `type: Literal["delete_file"]` + - `caller_id: str` - Delete the specified file. + The call ID of the program item that produced this tool call. - - `"delete_file"` + - `type: Literal["program"]` - - `class OperationUpdateFile: …` + - `"program"` - Instruction describing how to update a file via the apply_patch tool. + - `namespace: Optional[str]` - - `diff: str` + The namespace of the custom tool being called. - Diff to apply. + - `class CompactionTrigger: …` - - `path: str` + Compacts the current context. Must be the final input item. - Path of the file to update. + - `type: Literal["compaction_trigger"]` - - `type: Literal["update_file"]` + The type of the item. Always `compaction_trigger`. - Update an existing file with the provided diff. + - `"compaction_trigger"` - - `"update_file"` + - `agent: Optional[CompactionTriggerAgent]` - - `status: Literal["in_progress", "completed"]` + The agent that produced this item. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `agent_name: str` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"completed"` + - `class ItemReference: …` - - `type: Literal["apply_patch_call"]` + An internal identifier for an item to reference. - The type of the item. Always `apply_patch_call`. + - `id: str` - - `"apply_patch_call"` + The ID of the item to reference. - - `agent: Optional[Agent]` + - `agent: Optional[ItemReferenceAgent]` The agent that produced this item. @@ -60792,59 +71884,73 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `type: Optional[Literal["item_reference"]]` - The execution context that produced this tool call. + The type of item to reference. Always `item_reference`. - - `class CallerDirect: …` + - `"item_reference"` - - `type: Literal["direct"]` + - `class Program: …` - - `"direct"` + - `id: str` - - `class CallerProgram: …` + The unique ID of this program item. - - `caller_id: str` + - `call_id: str` - The call ID of the program item that produced this tool call. + The stable call ID of the program item. + + - `code: str` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: str` + + Opaque program replay fingerprint that must be round-tripped. - `type: Literal["program"]` + The item type. Always `program`. + - `"program"` - - `created_by: Optional[str]` + - `agent: Optional[ProgramAgent]` - The ID of the entity that created this tool call. + The agent that produced this item. -### Beta Response Apply Patch Tool Call Output + - `agent_name: str` -- `class BetaResponseApplyPatchToolCallOutput: …` + The canonical name of the agent that produced this item. - The output emitted by an apply patch tool call. + - `class ProgramOutput: …` - `id: str` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The unique ID of this program output item. - `call_id: str` - The unique ID of the apply patch tool call generated by the model. + The call ID of the program item. - - `status: Literal["completed", "failed"]` + - `result: str` - The status of the apply patch tool call output. One of `completed` or `failed`. + The result produced by the program item. + + - `status: Literal["completed", "incomplete"]` + + The terminal status of the program output. - `"completed"` - - `"failed"` + - `"incomplete"` - - `type: Literal["apply_patch_call_output"]` + - `type: Literal["program_output"]` - The type of the item. Always `apply_patch_call_output`. + The item type. Always `program_output`. - - `"apply_patch_call_output"` + - `"program_output"` - - `agent: Optional[Agent]` + - `agent: Optional[ProgramOutputAgent]` The agent that produced this item. @@ -60852,744 +71958,758 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `metadata: Optional[Dict[str, str]]` - The execution context that produced this tool call. + 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. - - `class CallerDirect: …` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: Literal["direct"]` + - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` - - `"direct"` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `class CallerProgram: …` + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` - - `caller_id: str` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - The call ID of the program item that produced this tool call. + - `"gpt-5.6-sol"` - - `type: Literal["program"]` + - `"gpt-5.6-terra"` - - `"program"` + - `"gpt-5.6-luna"` - - `created_by: Optional[str]` + - `"gpt-5.4"` - The ID of the entity that created this tool call output. + - `"gpt-5.4-mini"` - - `output: Optional[str]` + - `"gpt-5.4-nano"` - Optional textual output returned by the apply patch tool. + - `"gpt-5.4-mini-2026-03-17"` -### Beta Response Audio Delta Event + - `"gpt-5.4-nano-2026-03-17"` -- `class BetaResponseAudioDeltaEvent: …` + - `"gpt-5.3-chat-latest"` - Emitted when there is a partial audio response. + - `"gpt-5.2"` - - `delta: str` + - `"gpt-5.2-2025-12-11"` - A chunk of Base64 encoded response audio bytes. + - `"gpt-5.2-chat-latest"` - - `sequence_number: int` + - `"gpt-5.2-pro"` - A sequence number for this chunk of the stream response. + - `"gpt-5.2-pro-2025-12-11"` - - `type: Literal["response.audio.delta"]` + - `"gpt-5.1"` - The type of the event. Always `response.audio.delta`. + - `"gpt-5.1-2025-11-13"` - - `"response.audio.delta"` + - `"gpt-5.1-codex"` - - `agent: Optional[Agent]` + - `"gpt-5.1-mini"` - The agent that owns this multi-agent streaming event. + - `"gpt-5.1-chat-latest"` - - `agent_name: str` + - `"gpt-5"` - The canonical name of the agent that produced this item. + - `"gpt-5-mini"` -### Beta Response Audio Done Event + - `"gpt-5-nano"` -- `class BetaResponseAudioDoneEvent: …` + - `"gpt-5-2025-08-07"` - Emitted when the audio response is complete. + - `"gpt-5-mini-2025-08-07"` - - `sequence_number: int` + - `"gpt-5-nano-2025-08-07"` - The sequence number of the delta. + - `"gpt-5-chat-latest"` - - `type: Literal["response.audio.done"]` + - `"gpt-4.1"` - The type of the event. Always `response.audio.done`. + - `"gpt-4.1-mini"` - - `"response.audio.done"` + - `"gpt-4.1-nano"` - - `agent: Optional[Agent]` + - `"gpt-4.1-2025-04-14"` - The agent that owns this multi-agent streaming event. + - `"gpt-4.1-mini-2025-04-14"` - - `agent_name: str` + - `"gpt-4.1-nano-2025-04-14"` - The canonical name of the agent that produced this item. + - `"o4-mini"` -### Beta Response Audio Transcript Delta Event + - `"o4-mini-2025-04-16"` -- `class BetaResponseAudioTranscriptDeltaEvent: …` + - `"o3"` - Emitted when there is a partial transcript of audio. + - `"o3-2025-04-16"` - - `delta: str` + - `"o3-mini"` - The partial transcript of the audio response. + - `"o3-mini-2025-01-31"` - - `sequence_number: int` + - `"o1"` - The sequence number of this event. + - `"o1-2024-12-17"` - - `type: Literal["response.audio.transcript.delta"]` + - `"o1-preview"` - The type of the event. Always `response.audio.transcript.delta`. + - `"o1-preview-2024-09-12"` - - `"response.audio.transcript.delta"` + - `"o1-mini"` - - `agent: Optional[Agent]` + - `"o1-mini-2024-09-12"` - The agent that owns this multi-agent streaming event. + - `"gpt-4o"` - - `agent_name: str` + - `"gpt-4o-2024-11-20"` - The canonical name of the agent that produced this item. + - `"gpt-4o-2024-08-06"` -### Beta Response Audio Transcript Done Event + - `"gpt-4o-2024-05-13"` -- `class BetaResponseAudioTranscriptDoneEvent: …` + - `"gpt-4o-audio-preview"` - Emitted when the full audio transcript is completed. + - `"gpt-4o-audio-preview-2024-10-01"` - - `sequence_number: int` + - `"gpt-4o-audio-preview-2024-12-17"` - The sequence number of this event. + - `"gpt-4o-audio-preview-2025-06-03"` - - `type: Literal["response.audio.transcript.done"]` + - `"gpt-4o-mini-audio-preview"` - The type of the event. Always `response.audio.transcript.done`. + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `"response.audio.transcript.done"` + - `"gpt-4o-search-preview"` - - `agent: Optional[Agent]` + - `"gpt-4o-mini-search-preview"` - The agent that owns this multi-agent streaming event. + - `"gpt-4o-search-preview-2025-03-11"` - - `agent_name: str` + - `"gpt-4o-mini-search-preview-2025-03-11"` - The canonical name of the agent that produced this item. + - `"chatgpt-4o-latest"` -### Beta Response Code Interpreter Call Code Delta Event + - `"codex-mini-latest"` -- `class BetaResponseCodeInterpreterCallCodeDeltaEvent: …` + - `"gpt-4o-mini"` - Emitted when a partial code snippet is streamed by the code interpreter. + - `"gpt-4o-mini-2024-07-18"` - - `delta: str` + - `"gpt-4-turbo"` - The partial code snippet being streamed by the code interpreter. + - `"gpt-4-turbo-2024-04-09"` - - `item_id: str` + - `"gpt-4-0125-preview"` - The unique identifier of the code interpreter tool call item. + - `"gpt-4-turbo-preview"` - - `output_index: int` + - `"gpt-4-1106-preview"` - The index of the output item in the response for which the code is being streamed. + - `"gpt-4-vision-preview"` - - `sequence_number: int` + - `"gpt-4"` - The sequence number of this event, used to order streaming events. + - `"gpt-4-0314"` - - `type: Literal["response.code_interpreter_call_code.delta"]` + - `"gpt-4-0613"` - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `"gpt-4-32k"` - - `"response.code_interpreter_call_code.delta"` + - `"gpt-4-32k-0314"` - - `agent: Optional[Agent]` + - `"gpt-4-32k-0613"` - The agent that owns this multi-agent streaming event. + - `"gpt-3.5-turbo"` - - `agent_name: str` + - `"gpt-3.5-turbo-16k"` - The canonical name of the agent that produced this item. + - `"gpt-3.5-turbo-0301"` -### Beta Response Code Interpreter Call Code Done Event + - `"gpt-3.5-turbo-0613"` -- `class BetaResponseCodeInterpreterCallCodeDoneEvent: …` + - `"gpt-3.5-turbo-1106"` - Emitted when the code snippet is finalized by the code interpreter. + - `"gpt-3.5-turbo-0125"` - - `code: str` + - `"gpt-3.5-turbo-16k-0613"` - The final code snippet output by the code interpreter. + - `"o1-pro"` - - `item_id: str` + - `"o1-pro-2025-03-19"` - The unique identifier of the code interpreter tool call item. + - `"o3-pro"` - - `output_index: int` + - `"o3-pro-2025-06-10"` - The index of the output item in the response for which the code is finalized. + - `"o3-deep-research"` - - `sequence_number: int` + - `"o3-deep-research-2025-06-26"` - The sequence number of this event, used to order streaming events. + - `"o4-mini-deep-research"` - - `type: Literal["response.code_interpreter_call_code.done"]` + - `"o4-mini-deep-research-2025-06-26"` - The type of the event. Always `response.code_interpreter_call_code.done`. + - `"computer-use-preview"` - - `"response.code_interpreter_call_code.done"` + - `"computer-use-preview-2025-03-11"` - - `agent: Optional[Agent]` + - `"gpt-5-codex"` - The agent that owns this multi-agent streaming event. + - `"gpt-5-pro"` - - `agent_name: str` + - `"gpt-5-pro-2025-10-06"` - The canonical name of the agent that produced this item. + - `"gpt-5.1-codex-max"` -### Beta Response Code Interpreter Call Completed Event + - `str` -- `class BetaResponseCodeInterpreterCallCompletedEvent: …` + - `object: Literal["response"]` - Emitted when the code interpreter call is completed. + The object type of this resource - always set to `response`. - - `item_id: str` + - `"response"` - The unique identifier of the code interpreter tool call item. + - `output: List[BetaResponseOutputItem]` - - `output_index: int` + An array of content items generated by the model. - The index of the output item in the response for which the code interpreter call is completed. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `sequence_number: int` + - `class BetaResponseOutputMessage: …` - The sequence number of this event, used to order streaming events. + An output message from the model. - - `type: Literal["response.code_interpreter_call.completed"]` + - `class BetaResponseFileSearchToolCall: …` - The type of the event. Always `response.code_interpreter_call.completed`. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `"response.code_interpreter_call.completed"` + - `class BetaResponseFunctionToolCall: …` - - `agent: Optional[Agent]` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The agent that owns this multi-agent streaming event. + - `class BetaResponseFunctionToolCallOutputItem: …` - - `agent_name: str` + - `id: str` - The canonical name of the agent that produced this item. + The unique ID of the function call tool output. -### Beta Response Code Interpreter Call In Progress Event + - `call_id: str` -- `class BetaResponseCodeInterpreterCallInProgressEvent: …` + The unique ID of the function tool call generated by the model. - Emitted when a code interpreter call is in progress. + - `output: Union[str, List[OutputOutputContentList]]` - - `item_id: str` + The output from the function call generated by your code. + Can be a string or an list of output content. - The unique identifier of the code interpreter tool call item. + - `str` - - `output_index: int` + A string of the output of the function call. - The index of the output item in the response for which the code interpreter call is in progress. + - `List[OutputOutputContentList]` - - `sequence_number: int` + Text, image, or file output of the function call. - The sequence number of this event, used to order streaming events. + - `class BetaResponseInputText: …` - - `type: Literal["response.code_interpreter_call.in_progress"]` + A text input to the model. - The type of the event. Always `response.code_interpreter_call.in_progress`. + - `class BetaResponseInputImage: …` - - `"response.code_interpreter_call.in_progress"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `agent: Optional[Agent]` + - `class BetaResponseInputFile: …` - The agent that owns this multi-agent streaming event. + A file input to the model. - - `agent_name: str` + - `status: Literal["in_progress", "completed", "incomplete"]` - The canonical name of the agent that produced this item. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -### Beta Response Code Interpreter Call Interpreting Event + - `"in_progress"` -- `class BetaResponseCodeInterpreterCallInterpretingEvent: …` + - `"completed"` - Emitted when the code interpreter is actively interpreting the code snippet. + - `"incomplete"` - - `item_id: str` + - `type: Literal["function_call_output"]` - The unique identifier of the code interpreter tool call item. + The type of the function tool call output. Always `function_call_output`. - - `output_index: int` + - `"function_call_output"` - The index of the output item in the response for which the code interpreter is interpreting code. + - `agent: Optional[Agent]` - - `sequence_number: int` + The agent that produced this item. - The sequence number of this event, used to order streaming events. + - `agent_name: str` - - `type: Literal["response.code_interpreter_call.interpreting"]` + The canonical name of the agent that produced this item. - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `caller: Optional[Caller]` - - `"response.code_interpreter_call.interpreting"` + The execution context that produced this tool call. - - `agent: Optional[Agent]` + - `class CallerDirect: …` - The agent that owns this multi-agent streaming event. + - `type: Literal["direct"]` - - `agent_name: str` + The caller type. Always `direct`. - The canonical name of the agent that produced this item. + - `"direct"` -### Beta Response Code Interpreter Tool Call + - `class CallerProgram: …` -- `class BetaResponseCodeInterpreterToolCall: …` + - `caller_id: str` - A tool call to run code. + The call ID of the program item that produced this tool call. - - `id: str` + - `type: Literal["program"]` - The unique ID of the code interpreter tool call. + The caller type. Always `program`. - - `code: Optional[str]` + - `"program"` - The code to run, or null if not available. + - `created_by: Optional[str]` - - `container_id: str` + The identifier of the actor that created the item. - The ID of the container used to run the code. + - `class AgentMessage: …` - - `outputs: Optional[List[Output]]` + - `id: str` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The unique ID of the agent message. - - `class OutputLogs: …` + - `author: str` - The logs output from the code interpreter. + The sending agent identity. - - `logs: str` + - `content: List[AgentMessageContent]` - The logs output from the code interpreter. + Encrypted content sent between agents. - - `type: Literal["logs"]` + - `class BetaResponseInputText: …` - The type of the output. Always `logs`. + A text input to the model. - - `"logs"` + - `class BetaResponseOutputText: …` - - `class OutputImage: …` + A text output from the model. - The image output from the code interpreter. + - `class AgentMessageContentText: …` - - `type: Literal["image"]` + A text content. - The type of the output. Always `image`. + - `text: str` - - `"image"` + - `type: Literal["text"]` - - `url: str` + - `"text"` - The URL of the image output from the code interpreter. + - `class AgentMessageContentSummaryText: …` - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + A summary text from the model. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `text: str` - - `"in_progress"` + A summary of the reasoning output from the model so far. - - `"completed"` + - `type: Literal["summary_text"]` - - `"incomplete"` + The type of the object. Always `summary_text`. - - `"interpreting"` + - `"summary_text"` - - `"failed"` + - `class AgentMessageContentReasoningText: …` - - `type: Literal["code_interpreter_call"]` + Reasoning text from the model. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `text: str` - - `"code_interpreter_call"` + The reasoning text from the model. - - `agent: Optional[Agent]` + - `type: Literal["reasoning_text"]` - The agent that produced this item. + The type of the reasoning text. Always `reasoning_text`. - - `agent_name: str` + - `"reasoning_text"` - The canonical name of the agent that produced this item. + - `class BetaResponseOutputRefusal: …` -### Beta Response Compaction Item + A refusal from the model. -- `class BetaResponseCompactionItem: …` + - `class BetaResponseInputImage: …` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `id: str` + - `class AgentMessageContentComputerScreenshot: …` - The unique ID of the compaction item. + A screenshot of a computer. - - `encrypted_content: str` + - `detail: Literal["low", "high", "auto", "original"]` - The encrypted content that was produced by compaction. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: Literal["compaction"]` + - `"low"` - The type of the item. Always `compaction`. + - `"high"` - - `"compaction"` + - `"auto"` - - `agent: Optional[Agent]` + - `"original"` - The agent that produced this item. + - `file_id: Optional[str]` - - `agent_name: str` + The identifier of an uploaded file that contains the screenshot. - The canonical name of the agent that produced this item. + - `image_url: Optional[str]` - - `created_by: Optional[str]` + The URL of the screenshot image. - The identifier of the actor that created the item. + - `type: Literal["computer_screenshot"]` -### Beta Response Compaction Item Param + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. -- `class BetaResponseCompactionItemParam: …` + - `"computer_screenshot"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - - `encrypted_content: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` - The encrypted content of the compaction summary. + - `class BetaResponseInputFile: …` - - `type: Literal["compaction"]` + A file input to the model. - The type of the item. Always `compaction`. + - `class AgentMessageContentEncryptedContent: …` - - `"compaction"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `id: Optional[str]` + - `encrypted_content: str` - The ID of the compaction item. + Opaque encrypted content. - - `agent: Optional[Agent]` + - `type: Literal["encrypted_content"]` - The agent that produced this item. + The type of the input item. Always `encrypted_content`. - - `agent_name: str` + - `"encrypted_content"` - The canonical name of the agent that produced this item. + - `recipient: str` -### Beta Response Completed Event + The destination agent identity. -- `class BetaResponseCompletedEvent: …` + - `type: Literal["agent_message"]` - Emitted when the model response is complete. + The type of the item. Always `agent_message`. - - `response: BetaResponse` + - `"agent_message"` - Properties of the completed response. + - `agent: Optional[AgentMessageAgent]` - - `id: str` + The agent that produced this item. - Unique identifier for this Response. + - `agent_name: str` - - `created_at: float` + The canonical name of the agent that produced this item. - Unix timestamp (in seconds) of when this Response was created. + - `class MultiAgentCall: …` - - `error: Optional[BetaResponseError]` + - `id: str` - An error object returned when the model fails to generate a Response. + The unique ID of the multi-agent call item. - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - The error code for the response. + The multi-agent action to execute. - - `"server_error"` + - `"spawn_agent"` - - `"rate_limit_exceeded"` + - `"interrupt_agent"` - - `"invalid_prompt"` + - `"list_agents"` - - `"bio_policy"` + - `"send_message"` - - `"vector_store_timeout"` + - `"followup_task"` - - `"invalid_image"` + - `"wait_agent"` - - `"invalid_image_format"` + - `arguments: str` - - `"invalid_base64_image"` + The JSON string of arguments generated for the action. - - `"invalid_image_url"` + - `call_id: str` - - `"image_too_large"` + The unique ID linking this call to its output. - - `"image_too_small"` + - `type: Literal["multi_agent_call"]` - - `"image_parse_error"` + The type of the multi-agent call. Always `multi_agent_call`. - - `"image_content_policy_violation"` + - `"multi_agent_call"` - - `"invalid_image_mode"` + - `agent: Optional[MultiAgentCallAgent]` - - `"image_file_too_large"` + The agent that produced this item. - - `"unsupported_image_media_type"` + - `agent_name: str` - - `"empty_image_file"` + The canonical name of the agent that produced this item. - - `"failed_to_download_image"` + - `class MultiAgentCallOutput: …` - - `"image_file_not_found"` + - `id: str` - - `message: str` + The unique ID of the multi-agent call output item. - A human-readable description of the error. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `incomplete_details: Optional[IncompleteDetails]` + The multi-agent action that produced this result. - Details about why the response is incomplete. + - `"spawn_agent"` - - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` + - `"interrupt_agent"` - The reason why the response is incomplete. + - `"list_agents"` - - `"max_output_tokens"` + - `"send_message"` - - `"content_filter"` + - `"followup_task"` - - `instructions: Union[str, List[BetaResponseInputItem], null]` + - `"wait_agent"` - A system (or developer) message inserted into the model's context. + - `call_id: str` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + The unique ID of the multi-agent call. - - `str` + - `output: List[BetaResponseOutputText]` - A text input to the model, equivalent to a text input with the - `developer` role. + Text output returned by the multi-agent action. - - `List[BetaResponseInputItem]` + - `annotations: List[Annotation]` - A list of one or many input items to the model, containing - different content types. + The annotations of the text output. - - `class BetaEasyInputMessage: …` + - `text: str` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The text output from the model. - - `content: Union[str, BetaResponseInputMessageContentList]` + - `type: Literal["output_text"]` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The type of the output text. Always `output_text`. - - `str` + - `logprobs: Optional[List[Logprob]]` - A text input to the model. + - `type: Literal["multi_agent_call_output"]` - - `List[BetaResponseInputContent]` + The type of the multi-agent result. Always `multi_agent_call_output`. - - `class BetaResponseInputText: …` + - `"multi_agent_call_output"` - A text input to the model. + - `agent: Optional[MultiAgentCallOutputAgent]` - - `text: str` + The agent that produced this item. - The text input to the model. + - `agent_name: str` - - `type: Literal["input_text"]` + The canonical name of the agent that produced this item. - The type of the input item. Always `input_text`. + - `class BetaResponseFunctionWebSearch: …` - - `"input_text"` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `class BetaResponseComputerToolCall: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `mode: Literal["explicit"]` + - `class BetaResponseComputerToolCallOutputItem: …` - The breakpoint mode. Always `explicit`. + - `id: str` - - `"explicit"` + The unique ID of the computer call tool output. - - `class BetaResponseInputImage: …` + - `call_id: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The ID of the computer tool call that produced the output. - - `detail: Literal["low", "high", "auto", "original"]` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + A computer screenshot image used with the computer use tool. - - `"low"` + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - `"high"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"auto"` + - `"completed"` - - `"original"` + - `"incomplete"` - - `type: Literal["input_image"]` + - `"failed"` - The type of the input item. Always `input_image`. + - `"in_progress"` - - `"input_image"` + - `type: Literal["computer_call_output"]` - - `file_id: Optional[str]` + The type of the computer tool call output. Always `computer_call_output`. - The ID of the file to be sent to the model. + - `"computer_call_output"` - - `image_url: Optional[str]` + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The safety checks reported by the API that have been acknowledged by the + developer. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `id: str` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The ID of the pending safety check. - - `mode: Literal["explicit"]` + - `code: Optional[str]` - The breakpoint mode. Always `explicit`. + The type of the pending safety check. - - `"explicit"` + - `message: Optional[str]` - - `class BetaResponseInputFile: …` + Details about the pending safety check. - A file input to the model. + - `agent: Optional[Agent]` - - `type: Literal["input_file"]` + The agent that produced this item. - The type of the input item. Always `input_file`. + - `agent_name: str` - - `"input_file"` + The canonical name of the agent that produced this item. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `created_by: Optional[str]` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The identifier of the actor that created the item. - - `"auto"` + - `class BetaResponseReasoningItem: …` - - `"low"` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `"high"` + - `class Program: …` - - `file_data: Optional[str]` + - `id: str` - The content of the file to be sent to the model. + The unique ID of the program item. - - `file_id: Optional[str]` + - `call_id: str` - The ID of the file to be sent to the model. + The stable call ID of the program item. - - `file_url: Optional[str]` + - `code: str` - The URL of the file to be sent to the model. + The JavaScript source executed by programmatic tool calling. - - `filename: Optional[str]` + - `fingerprint: str` - The name of the file to be sent to the model. + Opaque program replay fingerprint that must be round-tripped. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["program"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The type of the item. Always `program`. - - `mode: Literal["explicit"]` + - `"program"` - The breakpoint mode. Always `explicit`. + - `agent: Optional[ProgramAgent]` - - `"explicit"` + The agent that produced this item. - - `role: Literal["user", "assistant", "system", "developer"]` + - `agent_name: str` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The canonical name of the agent that produced this item. - - `"user"` + - `class ProgramOutput: …` - - `"assistant"` + - `id: str` - - `"system"` + The unique ID of the program output item. - - `"developer"` + - `call_id: str` - - `phase: Optional[Literal["commentary"]]` + The call ID of the program item. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `result: str` - - `"commentary"` + The result produced by the program item. - - `type: Optional[Literal["message"]]` + - `status: Literal["completed", "incomplete"]` - The type of the message input. Always `message`. + The terminal status of the program output item. - - `"message"` + - `"completed"` - - `class Message: …` + - `"incomplete"` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + - `type: Literal["program_output"]` - - `content: BetaResponseInputMessageContentList` + The type of the item. Always `program_output`. - A list of one or many input items to the model, containing different content - types. + - `"program_output"` - - `class BetaResponseInputText: …` + - `agent: Optional[ProgramOutputAgent]` - A text input to the model. + The agent that produced this item. - - `class BetaResponseInputImage: …` + - `agent_name: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The canonical name of the agent that produced this item. - - `class BetaResponseInputFile: …` + - `class BetaResponseToolSearchCall: …` - A file input to the model. + - `id: str` - - `role: Literal["user", "system", "developer"]` + The unique ID of the tool search call item. - The role of the message input. One of `user`, `system`, or `developer`. + - `arguments: object` - - `"user"` + Arguments used for the tool search call. - - `"system"` + - `call_id: Optional[str]` - - `"developer"` + The unique ID of the tool search call generated by the model. - - `agent: Optional[MessageAgent]` + - `execution: Literal["server", "client"]` - The agent that produced this item. + Whether tool search was executed by the server or by the client. - - `agent_name: str` + - `"server"` - The canonical name of the agent that produced this item. + - `"client"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the tool search call item that was recorded. - `"in_progress"` @@ -61597,242 +72717,239 @@ print(compacted_response) - `"incomplete"` - - `type: Optional[Literal["message"]]` - - The type of the message input. Always set to `message`. + - `type: Literal["tool_search_call"]` - - `"message"` + The type of the item. Always `tool_search_call`. - - `class BetaResponseOutputMessage: …` + - `"tool_search_call"` - An output message from the model. + - `agent: Optional[Agent]` - - `id: str` + The agent that produced this item. - The unique ID of the output message. + - `agent_name: str` - - `content: List[Content]` + The canonical name of the agent that produced this item. - The content of the output message. + - `created_by: Optional[str]` - - `class BetaResponseOutputText: …` + The identifier of the actor that created the item. - A text output from the model. + - `class BetaResponseToolSearchOutputItem: …` - - `annotations: List[Annotation]` + - `id: str` - The annotations of the text output. + The unique ID of the tool search output item. - - `class AnnotationFileCitation: …` + - `call_id: Optional[str]` - A citation to a file. + The unique ID of the tool search call generated by the model. - - `file_id: str` + - `execution: Literal["server", "client"]` - The ID of the file. + Whether tool search was executed by the server or by the client. - - `filename: str` + - `"server"` - The filename of the file cited. + - `"client"` - - `index: int` + - `status: Literal["in_progress", "completed", "incomplete"]` - The index of the file in the list of files. + The status of the tool search output item that was recorded. - - `type: Literal["file_citation"]` + - `"in_progress"` - The type of the file citation. Always `file_citation`. + - `"completed"` - - `"file_citation"` + - `"incomplete"` - - `class AnnotationURLCitation: …` + - `tools: List[BetaTool]` - A citation for a web resource used to generate a model response. + The loaded tool definitions returned by tool search. - - `end_index: int` + - `class BetaFunctionTool: …` - The index of the last character of the URL citation in the message. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `start_index: int` + - `class BetaFileSearchTool: …` - The index of the first character of the URL citation in the message. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `title: str` + - `class BetaComputerTool: …` - The title of the web resource. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: Literal["url_citation"]` + - `class BetaComputerUsePreviewTool: …` - The type of the URL citation. Always `url_citation`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"url_citation"` + - `class BetaWebSearchTool: …` - - `url: str` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The URL of the web resource. + - `class Mcp: …` - - `class AnnotationContainerFileCitation: …` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - A citation for a container file used to generate a model response. + - `class CodeInterpreter: …` - - `container_id: str` + A tool that runs Python code to help generate a response to a prompt. - The ID of the container file. + - `class ProgrammaticToolCalling: …` - - `end_index: int` + - `class ImageGeneration: …` - The index of the last character of the container file citation in the message. + A tool that generates images using the GPT image models. - - `file_id: str` + - `class LocalShell: …` - The ID of the file. + A tool that allows the model to execute shell commands in a local environment. - - `filename: str` + - `class BetaFunctionShellTool: …` - The filename of the container file cited. + A tool that allows the model to execute shell commands. - - `start_index: int` + - `class BetaCustomTool: …` - The index of the first character of the container file citation in the message. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `type: Literal["container_file_citation"]` + - `class BetaNamespaceTool: …` - The type of the container file citation. Always `container_file_citation`. + Groups function/custom tools under a shared namespace. - - `"container_file_citation"` + - `class BetaToolSearchTool: …` - - `class AnnotationFilePath: …` + Hosted or BYOT tool search configuration for deferred tools. - A path to a file. + - `class BetaWebSearchPreviewTool: …` - - `file_id: str` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The ID of the file. + - `class BetaApplyPatchTool: …` - - `index: int` + Allows the assistant to create, delete, or update files using unified diffs. - The index of the file in the list of files. + - `type: Literal["tool_search_output"]` - - `type: Literal["file_path"]` + The type of the item. Always `tool_search_output`. - The type of the file path. Always `file_path`. + - `"tool_search_output"` - - `"file_path"` + - `agent: Optional[Agent]` - - `text: str` + The agent that produced this item. - The text output from the model. + - `agent_name: str` - - `type: Literal["output_text"]` + The canonical name of the agent that produced this item. - The type of the output text. Always `output_text`. + - `created_by: Optional[str]` - - `"output_text"` + The identifier of the actor that created the item. - - `logprobs: Optional[List[Logprob]]` + - `class AdditionalTools: …` - - `token: str` + - `id: str` - - `bytes: List[int]` + The unique ID of the additional tools item. - - `logprob: float` + - `role: Literal["unknown", "user", "assistant", 5 more]` - - `top_logprobs: List[LogprobTopLogprob]` + The role that provided the additional tools. - - `token: str` + - `"unknown"` - - `bytes: List[int]` + - `"user"` - - `logprob: float` + - `"assistant"` - - `class BetaResponseOutputRefusal: …` + - `"system"` - A refusal from the model. + - `"critic"` - - `refusal: str` + - `"discriminator"` - The refusal explanation from the model. + - `"developer"` - - `type: Literal["refusal"]` + - `"tool"` - The type of the refusal. Always `refusal`. + - `tools: List[BetaTool]` - - `"refusal"` + The additional tool definitions made available at this item. - - `role: Literal["assistant"]` + - `class BetaFunctionTool: …` - The role of the output message. Always `assistant`. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"assistant"` + - `class BetaFileSearchTool: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `class BetaComputerTool: …` - - `"in_progress"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"completed"` + - `class BetaComputerUsePreviewTool: …` - - `"incomplete"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: Literal["message"]` + - `class BetaWebSearchTool: …` - The type of the output message. Always `message`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"message"` + - `class Mcp: …` - - `agent: Optional[Agent]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The agent that produced this item. + - `class CodeInterpreter: …` - - `agent_name: str` + A tool that runs Python code to help generate a response to a prompt. - The canonical name of the agent that produced this item. + - `class ProgrammaticToolCalling: …` - - `phase: Optional[Literal["commentary"]]` + - `class ImageGeneration: …` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + A tool that generates images using the GPT image models. - - `"commentary"` + - `class LocalShell: …` - - `class BetaResponseFileSearchToolCall: …` + A tool that allows the model to execute shell commands in a local environment. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `class BetaFunctionShellTool: …` - - `id: str` + A tool that allows the model to execute shell commands. - The unique ID of the file search tool call. + - `class BetaCustomTool: …` - - `queries: List[str]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The queries used to search for files. + - `class BetaNamespaceTool: …` - - `status: Literal["in_progress", "searching", "completed", 2 more]` + Groups function/custom tools under a shared namespace. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `class BetaToolSearchTool: …` - - `"in_progress"` + Hosted or BYOT tool search configuration for deferred tools. - - `"searching"` + - `class BetaWebSearchPreviewTool: …` - - `"completed"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"incomplete"` + - `class BetaApplyPatchTool: …` - - `"failed"` + Allows the assistant to create, delete, or update files using unified diffs. - - `type: Literal["file_search_call"]` + - `type: Literal["additional_tools"]` - The type of the file search tool call. Always `file_search_call`. + The type of the item. Always `additional_tools`. - - `"file_search_call"` + - `"additional_tools"` - - `agent: Optional[Agent]` + - `agent: Optional[AdditionalToolsAgent]` The agent that produced this item. @@ -61840,531 +72957,525 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `results: Optional[List[Result]]` + - `class BetaResponseCompactionItem: …` - The results of the file search tool call. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + - `id: str` - 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, booleans, or numbers. + The unique ID of the compaction item. - - `str` + - `encrypted_content: str` - - `float` + The encrypted content that was produced by compaction. - - `bool` + - `type: Literal["compaction"]` - - `file_id: Optional[str]` + The type of the item. Always `compaction`. - The unique ID of the file. + - `"compaction"` - - `filename: Optional[str]` + - `agent: Optional[Agent]` - The name of the file. + The agent that produced this item. - - `score: Optional[float]` + - `agent_name: str` - The relevance score of the file - a value between 0 and 1. + The canonical name of the agent that produced this item. - - `text: Optional[str]` + - `created_by: Optional[str]` - The text that was retrieved from the file. + The identifier of the actor that created the item. - - `class BetaResponseComputerToolCall: …` + - `class ImageGenerationCall: …` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + An image generation request made by the model. - `id: str` - The unique ID of the computer call. + The unique ID of the image generation call. - - `call_id: str` + - `result: Optional[str]` - An identifier used when responding to the tool call with output. + The generated image encoded in base64. - - `pending_safety_checks: List[PendingSafetyCheck]` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - The pending safety checks for the computer call. + The status of the image generation call. - - `id: str` + - `"in_progress"` - The ID of the pending safety check. + - `"completed"` - - `code: Optional[str]` + - `"generating"` - The type of the pending safety check. + - `"failed"` - - `message: Optional[str]` + - `type: Literal["image_generation_call"]` - Details about the pending safety check. + The type of the image generation call. Always `image_generation_call`. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"image_generation_call"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `agent: Optional[ImageGenerationCallAgent]` - - `"in_progress"` + The agent that produced this item. - - `"completed"` + - `agent_name: str` - - `"incomplete"` + The canonical name of the agent that produced this item. - - `type: Literal["computer_call"]` + - `class BetaResponseCodeInterpreterToolCall: …` - The type of the computer call. Always `computer_call`. + A tool call to run code. - - `"computer_call"` + - `class LocalShellCall: …` - - `action: Optional[BetaComputerAction]` + A tool call to run a command on the local shell. - A click action. + - `id: str` - - `class Click: …` + The unique ID of the local shell call. - A click action. + - `action: LocalShellCallAction` - - `button: Literal["left", "right", "wheel", 2 more]` + Execute a shell command on the server. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `command: List[str]` - - `"left"` + The command to run. - - `"right"` + - `env: Dict[str, str]` - - `"wheel"` + Environment variables to set for the command. - - `"back"` + - `type: Literal["exec"]` - - `"forward"` + The type of the local shell action. Always `exec`. - - `type: Literal["click"]` + - `"exec"` - Specifies the event type. For a click action, this property is always `click`. + - `timeout_ms: Optional[int]` - - `"click"` + Optional timeout in milliseconds for the command. - - `x: int` + - `user: Optional[str]` - The x-coordinate where the click occurred. + Optional user to run the command as. - - `y: int` + - `working_directory: Optional[str]` - The y-coordinate where the click occurred. + Optional working directory to run the command in. - - `keys: Optional[List[str]]` + - `call_id: str` - The keys being held while clicking. + The unique ID of the local shell tool call generated by the model. - - `class DoubleClick: …` + - `status: Literal["in_progress", "completed", "incomplete"]` - A double click action. + The status of the local shell call. - - `keys: Optional[List[str]]` + - `"in_progress"` - The keys being held while double-clicking. + - `"completed"` - - `type: Literal["double_click"]` + - `"incomplete"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `type: Literal["local_shell_call"]` - - `"double_click"` + The type of the local shell call. Always `local_shell_call`. - - `x: int` + - `"local_shell_call"` - The x-coordinate where the double click occurred. + - `agent: Optional[LocalShellCallAgent]` - - `y: int` + The agent that produced this item. - The y-coordinate where the double click occurred. + - `agent_name: str` - - `class Drag: …` + The canonical name of the agent that produced this item. - A drag action. + - `class LocalShellCallOutput: …` - - `path: List[DragPath]` + The output of a local shell tool call. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `id: str` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The unique ID of the local shell tool call generated by the model. - - `x: int` + - `output: str` - The x-coordinate. + A JSON string of the output of the local shell tool call. - - `y: int` + - `type: Literal["local_shell_call_output"]` - The y-coordinate. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `type: Literal["drag"]` + - `"local_shell_call_output"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `agent: Optional[LocalShellCallOutputAgent]` - - `"drag"` + The agent that produced this item. - - `keys: Optional[List[str]]` + - `agent_name: str` - The keys being held while dragging the mouse. + The canonical name of the agent that produced this item. - - `class Keypress: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A collection of keypresses the model would like to perform. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `keys: List[str]` + - `"in_progress"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"completed"` - - `type: Literal["keypress"]` + - `"incomplete"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `class BetaResponseFunctionShellToolCall: …` - - `"keypress"` + A tool call that executes one or more shell commands in a managed environment. - - `class Move: …` + - `id: str` - A mouse move action. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `type: Literal["move"]` + - `action: Action` - Specifies the event type. For a move action, this property is always set to `move`. + The shell commands and limits that describe how to run the tool call. - - `"move"` + - `commands: List[str]` - - `x: int` + - `max_output_length: Optional[int]` - The x-coordinate to move to. + Optional maximum number of characters to return from each command. - - `y: int` + - `timeout_ms: Optional[int]` - The y-coordinate to move to. + Optional timeout in milliseconds for the commands. - - `keys: Optional[List[str]]` + - `call_id: str` - The keys being held while moving the mouse. + The unique ID of the shell tool call generated by the model. - - `class Screenshot: …` + - `environment: Optional[Environment]` - A screenshot action. + Represents the use of a local environment to perform shell actions. - - `type: Literal["screenshot"]` + - `class BetaResponseLocalEnvironment: …` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + Represents the use of a local environment to perform shell actions. - - `"screenshot"` + - `type: Literal["local"]` - - `class Scroll: …` + The environment type. Always `local`. - A scroll action. + - `"local"` - - `scroll_x: int` + - `class BetaResponseContainerReference: …` - The horizontal scroll distance. + Represents a container created with /v1/containers. - - `scroll_y: int` + - `container_id: str` - The vertical scroll distance. + - `type: Literal["container_reference"]` - - `type: Literal["scroll"]` + The environment type. Always `container_reference`. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"container_reference"` - - `"scroll"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `x: int` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The x-coordinate where the scroll occurred. + - `"in_progress"` - - `y: int` + - `"completed"` - The y-coordinate where the scroll occurred. + - `"incomplete"` - - `keys: Optional[List[str]]` + - `type: Literal["shell_call"]` - The keys being held while scrolling. + The type of the item. Always `shell_call`. - - `class Type: …` + - `"shell_call"` - An action to type in text. + - `agent: Optional[Agent]` - - `text: str` + The agent that produced this item. - The text to type. + - `agent_name: str` - - `type: Literal["type"]` + The canonical name of the agent that produced this item. - Specifies the event type. For a type action, this property is always set to `type`. + - `caller: Optional[Caller]` - - `"type"` + The execution context that produced this tool call. - - `class Wait: …` + - `class CallerDirect: …` - A wait action. + - `type: Literal["direct"]` - - `type: Literal["wait"]` + - `"direct"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `class CallerProgram: …` - - `"wait"` + - `caller_id: str` - - `actions: Optional[BetaComputerActionList]` + The call ID of the program item that produced this tool call. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `type: Literal["program"]` - - `class Click: …` + - `"program"` - A click action. + - `created_by: Optional[str]` - - `class DoubleClick: …` + The ID of the entity that created this tool call. - A double click action. + - `class BetaResponseFunctionShellToolCallOutput: …` - - `class Drag: …` + The output of a shell tool call that was emitted. - A drag action. + - `id: str` - - `class Keypress: …` + The unique ID of the shell call output. Populated when this item is returned via API. - A collection of keypresses the model would like to perform. + - `call_id: str` - - `class Move: …` + The unique ID of the shell tool call generated by the model. - A mouse move action. + - `max_output_length: Optional[int]` - - `class Screenshot: …` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - A screenshot action. + - `output: List[Output]` - - `class Scroll: …` + An array of shell call output contents - A scroll action. + - `outcome: OutputOutcome` - - `class Type: …` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - An action to type in text. + - `class OutputOutcomeTimeout: …` - - `class Wait: …` + Indicates that the shell call exceeded its configured time limit. - A wait action. + - `type: Literal["timeout"]` - - `agent: Optional[Agent]` + The outcome type. Always `timeout`. - The agent that produced this item. + - `"timeout"` - - `agent_name: str` + - `class OutputOutcomeExit: …` - The canonical name of the agent that produced this item. + Indicates that the shell commands finished and returned an exit code. - - `class ComputerCallOutput: …` + - `exit_code: int` - The output of a computer tool call. + Exit code from the shell process. - - `call_id: str` + - `type: Literal["exit"]` - The ID of the computer tool call that produced the output. + The outcome type. Always `exit`. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"exit"` - A computer screenshot image used with the computer use tool. + - `stderr: str` - - `type: Literal["computer_screenshot"]` + The standard error output that was captured. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `stdout: str` - - `"computer_screenshot"` + The standard output that was captured. - - `file_id: Optional[str]` + - `created_by: Optional[str]` - The identifier of an uploaded file that contains the screenshot. + The identifier of the actor that created the item. - - `image_url: Optional[str]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The URL of the screenshot image. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `type: Literal["computer_call_output"]` + - `"in_progress"` - The type of the computer tool call output. Always `computer_call_output`. + - `"completed"` - - `"computer_call_output"` + - `"incomplete"` - - `id: Optional[str]` + - `type: Literal["shell_call_output"]` - The ID of the computer tool call output. + The type of the shell call output. Always `shell_call_output`. - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + - `"shell_call_output"` - The safety checks reported by the API that have been acknowledged by the developer. + - `agent: Optional[Agent]` - - `id: str` + The agent that produced this item. - The ID of the pending safety check. + - `agent_name: str` - - `code: Optional[str]` + The canonical name of the agent that produced this item. - The type of the pending safety check. + - `caller: Optional[Caller]` - - `message: Optional[str]` + The execution context that produced this tool call. - Details about the pending safety check. + - `class CallerDirect: …` - - `agent: Optional[ComputerCallOutputAgent]` + - `type: Literal["direct"]` - The agent that produced this item. + - `"direct"` - - `agent_name: str` + - `class CallerProgram: …` - The canonical name of the agent that produced this item. + - `caller_id: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The call ID of the program item that produced this tool call. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `type: Literal["program"]` - - `"in_progress"` + - `"program"` - - `"completed"` + - `created_by: Optional[str]` - - `"incomplete"` + The identifier of the actor that created the item. - - `class BetaResponseFunctionWebSearch: …` + - `class BetaResponseApplyPatchToolCall: …` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + A tool call that applies file diffs by creating, deleting, or updating files. - `id: str` - The unique ID of the web search tool call. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `action: Action` + - `call_id: str` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + The unique ID of the apply patch tool call generated by the model. - - `class ActionSearch: …` + - `operation: Operation` - Action type "search" - Performs a web search query. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `type: Literal["search"]` + - `class OperationCreateFile: …` - The action type. + Instruction describing how to create a file via the apply_patch tool. - - `"search"` + - `diff: str` - - `queries: Optional[List[str]]` + Diff to apply. - The search queries. + - `path: str` - - `query: Optional[str]` + Path of the file to create. - The search query. + - `type: Literal["create_file"]` - - `sources: Optional[List[ActionSearchSource]]` + Create a new file with the provided diff. - The sources used in the search. + - `"create_file"` - - `type: Literal["url"]` + - `class OperationDeleteFile: …` - The type of source. Always `url`. + Instruction describing how to delete a file via the apply_patch tool. - - `"url"` + - `path: str` - - `url: str` + Path of the file to delete. - The URL of the source. + - `type: Literal["delete_file"]` - - `class ActionOpenPage: …` + Delete the specified file. - Action type "open_page" - Opens a specific URL from search results. + - `"delete_file"` - - `type: Literal["open_page"]` + - `class OperationUpdateFile: …` - The action type. + Instruction describing how to update a file via the apply_patch tool. - - `"open_page"` + - `diff: str` + + Diff to apply. + + - `path: str` + + Path of the file to update. + + - `type: Literal["update_file"]` + + Update an existing file with the provided diff. - - `url: Optional[str]` + - `"update_file"` - The URL opened by the model. + - `status: Literal["in_progress", "completed"]` - - `class ActionFindInPage: …` + The status of the apply patch tool call. One of `in_progress` or `completed`. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"in_progress"` - - `pattern: str` + - `"completed"` - The pattern or text to search for within the page. + - `type: Literal["apply_patch_call"]` - - `type: Literal["find_in_page"]` + The type of the item. Always `apply_patch_call`. - The action type. + - `"apply_patch_call"` - - `"find_in_page"` + - `agent: Optional[Agent]` - - `url: str` + The agent that produced this item. - The URL of the page searched for the pattern. + - `agent_name: str` - - `status: Literal["in_progress", "searching", "completed", "failed"]` + The canonical name of the agent that produced this item. - The status of the web search tool call. + - `caller: Optional[Caller]` - - `"in_progress"` + The execution context that produced this tool call. - - `"searching"` + - `class CallerDirect: …` - - `"completed"` + - `type: Literal["direct"]` - - `"failed"` + - `"direct"` - - `type: Literal["web_search_call"]` + - `class CallerProgram: …` - The type of the web search tool call. Always `web_search_call`. + - `caller_id: str` - - `"web_search_call"` + The call ID of the program item that produced this tool call. - - `agent: Optional[Agent]` + - `type: Literal["program"]` - The agent that produced this item. + - `"program"` - - `agent_name: str` + - `created_by: Optional[str]` - The canonical name of the agent that produced this item. + The ID of the entity that created this tool call. - - `class BetaResponseFunctionToolCall: …` + - `class BetaResponseApplyPatchToolCallOutput: …` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The output emitted by an apply patch tool call. - - `arguments: str` + - `id: str` - A JSON string of the arguments to pass to the function. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id: str` - The unique ID of the function tool call generated by the model. + The unique ID of the apply patch tool call generated by the model. - - `name: str` + - `status: Literal["completed", "failed"]` - The name of the function to run. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `type: Literal["function_call"]` + - `"completed"` - The type of the function tool call. Always `function_call`. + - `"failed"` - - `"function_call"` + - `type: Literal["apply_patch_call_output"]` - - `id: Optional[str]` + The type of the item. Always `apply_patch_call_output`. - The unique ID of the function tool call. + - `"apply_patch_call_output"` - `agent: Optional[Agent]` @@ -62394,194 +73505,209 @@ print(compacted_response) - `"program"` - - `namespace: Optional[str]` + - `created_by: Optional[str]` - The namespace of the function to run. + The ID of the entity that created this tool call output. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `output: Optional[str]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Optional textual output returned by the apply patch tool. - - `"in_progress"` + - `class McpCall: …` - - `"completed"` + An invocation of a tool on an MCP server. - - `"incomplete"` + - `id: str` - - `class FunctionCallOutput: …` + The unique ID of the tool call. - The output of a function tool call. + - `arguments: str` - - `call_id: str` + A JSON string of the arguments passed to the tool. - The unique ID of the function tool call generated by the model. + - `name: str` - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + The name of the tool that was run. - Text, image, or file output of the function tool call. + - `server_label: str` - - `str` + The label of the MCP server running the tool. - A JSON string of the output of the function tool call. + - `type: Literal["mcp_call"]` - - `List[BetaResponseFunctionCallOutputItem]` + The type of the item. Always `mcp_call`. - - `class BetaResponseInputTextContent: …` + - `"mcp_call"` - A text input to the model. + - `agent: Optional[McpCallAgent]` - - `text: str` + The agent that produced this item. - The text input to the model. + - `agent_name: str` - - `type: Literal["input_text"]` + The canonical name of the agent that produced this item. - The type of the input item. Always `input_text`. + - `approval_request_id: Optional[str]` - - `"input_text"` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `error: Optional[str]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The error from the tool call, if any. - - `mode: Literal["explicit"]` + - `output: Optional[str]` - The breakpoint mode. Always `explicit`. + The output from the tool call. - - `"explicit"` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - `class BetaResponseInputImageContent: …` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"in_progress"` - - `type: Literal["input_image"]` + - `"completed"` - The type of the input item. Always `input_image`. + - `"incomplete"` - - `"input_image"` + - `"calling"` - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + - `"failed"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `class McpListTools: …` - - `"low"` + A list of tools available on an MCP server. - - `"high"` + - `id: str` - - `"auto"` + The unique ID of the list. - - `"original"` + - `server_label: str` - - `file_id: Optional[str]` + The label of the MCP server. - The ID of the file to be sent to the model. + - `tools: List[McpListToolsTool]` - - `image_url: Optional[str]` + The tools available on the server. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `input_schema: object` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The JSON schema describing the tool's input. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `name: str` - - `mode: Literal["explicit"]` + The name of the tool. - The breakpoint mode. Always `explicit`. + - `annotations: Optional[object]` - - `"explicit"` + Additional annotations about the tool. - - `class BetaResponseInputFileContent: …` + - `description: Optional[str]` - A file input to the model. + The description of the tool. - - `type: Literal["input_file"]` + - `type: Literal["mcp_list_tools"]` - The type of the input item. Always `input_file`. + The type of the item. Always `mcp_list_tools`. - - `"input_file"` + - `"mcp_list_tools"` - - `detail: Optional[Literal["auto", "low", "high"]]` + - `agent: Optional[McpListToolsAgent]` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The agent that produced this item. - - `"auto"` + - `agent_name: str` - - `"low"` + The canonical name of the agent that produced this item. - - `"high"` + - `error: Optional[str]` - - `file_data: Optional[str]` + Error message if the server could not list tools. - The base64-encoded data of the file to be sent to the model. + - `class McpApprovalRequest: …` - - `file_id: Optional[str]` + A request for human approval of a tool invocation. - The ID of the file to be sent to the model. + - `id: str` - - `file_url: Optional[str]` + The unique ID of the approval request. - The URL of the file to be sent to the model. + - `arguments: str` - - `filename: Optional[str]` + A JSON string of arguments for the tool. - The name of the file to be sent to the model. + - `name: str` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The name of the tool to run. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `server_label: str` - - `mode: Literal["explicit"]` + The label of the MCP server making the request. - The breakpoint mode. Always `explicit`. + - `type: Literal["mcp_approval_request"]` - - `"explicit"` + The type of the item. Always `mcp_approval_request`. - - `type: Literal["function_call_output"]` + - `"mcp_approval_request"` - The type of the function tool call output. Always `function_call_output`. + - `agent: Optional[McpApprovalRequestAgent]` - - `"function_call_output"` + The agent that produced this item. - - `id: Optional[str]` + - `agent_name: str` - The unique ID of the function tool call output. Populated when this item is returned via API. + The canonical name of the agent that produced this item. - - `agent: Optional[FunctionCallOutputAgent]` + - `class McpApprovalResponse: …` - The agent that produced this item. + A response to an MCP approval request. - - `agent_name: str` + - `id: str` - The canonical name of the agent that produced this item. + The unique ID of the approval response - - `caller: Optional[FunctionCallOutputCaller]` + - `approval_request_id: str` - The execution context that produced this tool call. + The ID of the approval request being answered. - - `class FunctionCallOutputCallerDirect: …` + - `approve: bool` - - `type: Literal["direct"]` + Whether the request was approved. - The caller type. Always `direct`. + - `type: Literal["mcp_approval_response"]` - - `"direct"` + The type of the item. Always `mcp_approval_response`. - - `class FunctionCallOutputCallerProgram: …` + - `"mcp_approval_response"` - - `caller_id: str` + - `agent: Optional[McpApprovalResponseAgent]` - The call ID of the program item that produced this tool call. + The agent that produced this item. - - `type: Literal["program"]` + - `agent_name: str` - The caller type. Always `program`. + The canonical name of the agent that produced this item. - - `"program"` + - `reason: Optional[str]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + Optional reason for the decision. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `class BetaResponseCustomToolCall: …` + + A call to a custom tool created by the model. + + - `class BetaResponseCustomToolCallOutputItem: …` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: str` + + The unique ID of the custom tool call output item. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -62589,1634 +73715,1765 @@ print(compacted_response) - `"incomplete"` - - `class AgentMessage: …` + - `created_by: Optional[str]` - A message routed between agents. + The identifier of the actor that created the item. - - `author: str` + - `parallel_tool_calls: bool` - The sending agent identity. + Whether to allow the model to run tool calls in parallel. - - `content: List[AgentMessageContent]` + - `temperature: Optional[float]` - Plaintext, image, or encrypted content sent between agents. + 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. + We generally recommend altering this or `top_p` but not both. - - `class BetaResponseInputTextContent: …` + - `tool_choice: ToolChoice` - A text input to the model. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `class BetaResponseInputImageContent: …` + - `Literal["none", "auto", "required"]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"none"` - - `class AgentMessageContentEncryptedContent: …` + - `"auto"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"required"` - - `encrypted_content: str` + - `class BetaToolChoiceAllowed: …` - Opaque encrypted content. + Constrains the tools available to the model to a pre-defined set. - - `type: Literal["encrypted_content"]` + - `mode: Literal["auto", "required"]` - The type of the input item. Always `encrypted_content`. + Constrains the tools available to the model to a pre-defined set. - - `"encrypted_content"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `recipient: str` + `required` requires the model to call one or more of the allowed tools. - The destination agent identity. + - `"auto"` - - `type: Literal["agent_message"]` + - `"required"` - The item type. Always `agent_message`. + - `tools: List[Dict[str, object]]` - - `"agent_message"` + A list of tool definitions that the model should be allowed to call. - - `id: Optional[str]` + For the Responses API, the list of tool definitions might look like: - The unique ID of this agent message item. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `agent: Optional[AgentMessageAgent]` + - `type: Literal["allowed_tools"]` - The agent that produced this item. + Allowed tool configuration type. Always `allowed_tools`. - - `agent_name: str` + - `"allowed_tools"` - The canonical name of the agent that produced this item. + - `class BetaToolChoiceTypes: …` - - `class MultiAgentCall: …` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` - The multi-agent action that was executed. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `"spawn_agent"` + Allowed values are: - - `"interrupt_agent"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `"list_agents"` + - `"file_search"` - - `"send_message"` + - `"web_search_preview"` - - `"followup_task"` + - `"computer"` - - `"wait_agent"` + - `"computer_use_preview"` - - `arguments: str` + - `"computer_use"` - The action arguments as a JSON string. + - `"web_search_preview_2025_03_11"` - - `call_id: str` + - `"image_generation"` - The unique ID linking this call to its output. + - `"code_interpreter"` - - `type: Literal["multi_agent_call"]` + - `class BetaToolChoiceFunction: …` - The item type. Always `multi_agent_call`. + Use this option to force the model to call a specific function. - - `"multi_agent_call"` + - `name: str` - - `id: Optional[str]` + The name of the function to call. - The unique ID of this multi-agent call. + - `type: Literal["function"]` - - `agent: Optional[MultiAgentCallAgent]` + For function calling, the type is always `function`. - The agent that produced this item. + - `"function"` - - `agent_name: str` + - `class BetaToolChoiceMcp: …` - The canonical name of the agent that produced this item. + Use this option to force the model to call a specific tool on a remote MCP server. - - `class MultiAgentCallOutput: …` + - `server_label: str` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The label of the MCP server to use. - The multi-agent action that produced this result. + - `type: Literal["mcp"]` - - `"spawn_agent"` + For MCP tools, the type is always `mcp`. - - `"interrupt_agent"` + - `"mcp"` - - `"list_agents"` + - `name: Optional[str]` - - `"send_message"` + The name of the tool to call on the server. - - `"followup_task"` + - `class BetaToolChoiceCustom: …` - - `"wait_agent"` + Use this option to force the model to call a specific custom tool. - - `call_id: str` + - `name: str` - The unique ID of the multi-agent call. + The name of the custom tool to call. - - `output: List[MultiAgentCallOutputOutput]` + - `type: Literal["custom"]` - Text output returned by the multi-agent action. + For custom tool calling, the type is always `custom`. - - `text: str` + - `"custom"` - The text content. + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` - - `type: Literal["output_text"]` + - `type: Literal["programmatic_tool_calling"]` - The content type. Always `output_text`. + The tool to call. Always `programmatic_tool_calling`. - - `"output_text"` + - `"programmatic_tool_calling"` - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + - `class BetaToolChoiceApplyPatch: …` - Citations associated with the text content. + Forces the model to call the apply_patch tool when executing a tool call. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + - `type: Literal["apply_patch"]` - - `file_id: str` + The tool to call. Always `apply_patch`. - The ID of the file. + - `"apply_patch"` - - `filename: str` + - `class BetaToolChoiceShell: …` - The filename of the file cited. + Forces the model to call the shell tool when a tool call is required. - - `index: int` + - `type: Literal["shell"]` - The index of the file in the list of files. + The tool to call. Always `shell`. - - `type: Literal["file_citation"]` + - `"shell"` - The citation type. Always `file_citation`. + - `tools: List[BetaTool]` - - `"file_citation"` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + We support the following categories of tools: - - `end_index: int` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - The index of the last character of the citation in the message. + - `class BetaFunctionTool: …` - - `start_index: int` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The index of the first character of the citation in the message. + - `class BetaFileSearchTool: …` - - `title: str` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The title of the cited resource. + - `class BetaComputerTool: …` - - `type: Literal["url_citation"]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The citation type. Always `url_citation`. + - `class BetaComputerUsePreviewTool: …` - - `"url_citation"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `url: str` + - `class BetaWebSearchTool: …` - The URL of the cited resource. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `class Mcp: …` - - `container_id: str` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The ID of the container. + - `class CodeInterpreter: …` - - `end_index: int` + A tool that runs Python code to help generate a response to a prompt. - The index of the last character of the citation in the message. + - `class ProgrammaticToolCalling: …` - - `file_id: str` + - `class ImageGeneration: …` - The ID of the container file. + A tool that generates images using the GPT image models. - - `filename: str` + - `class LocalShell: …` - The filename of the container file cited. + A tool that allows the model to execute shell commands in a local environment. - - `start_index: int` + - `class BetaFunctionShellTool: …` - The index of the first character of the citation in the message. + A tool that allows the model to execute shell commands. - - `type: Literal["container_file_citation"]` + - `class BetaCustomTool: …` - The citation type. Always `container_file_citation`. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `"container_file_citation"` + - `class BetaNamespaceTool: …` - - `type: Literal["multi_agent_call_output"]` + Groups function/custom tools under a shared namespace. - The item type. Always `multi_agent_call_output`. + - `class BetaToolSearchTool: …` - - `"multi_agent_call_output"` + Hosted or BYOT tool search configuration for deferred tools. - - `id: Optional[str]` + - `class BetaWebSearchPreviewTool: …` - The unique ID of this multi-agent call output. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `agent: Optional[MultiAgentCallOutputAgent]` + - `class BetaApplyPatchTool: …` - The agent that produced this item. + Allows the assistant to create, delete, or update files using unified diffs. - - `agent_name: str` + - `top_p: Optional[float]` - The canonical name of the agent that produced this item. + 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. - - `class ToolSearchCall: …` + We generally recommend altering this or `temperature` but not both. - - `arguments: object` + - `background: Optional[bool]` - The arguments supplied to the tool search call. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `type: Literal["tool_search_call"]` + - `completed_at: Optional[float]` - The item type. Always `tool_search_call`. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `"tool_search_call"` + - `conversation: Optional[Conversation]` - - `id: Optional[str]` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The unique ID of this tool search call. + - `id: str` - - `agent: Optional[ToolSearchCallAgent]` + The unique ID of the conversation that this response was associated with. - The agent that produced this item. + - `max_output_tokens: Optional[int]` - - `agent_name: str` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - The canonical name of the agent that produced this item. + - `max_tool_calls: Optional[int]` - - `call_id: Optional[str]` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - The unique ID of the tool search call generated by the model. + - `moderation: Optional[Moderation]` - - `execution: Optional[Literal["server", "client"]]` + Moderation results for the response input and output, if moderated completions were requested. - Whether tool search was executed by the server or by the client. + - `input: ModerationInput` - - `"server"` + Moderation for the response input. - - `"client"` + - `class ModerationInputModerationResult: …` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + A moderation result produced for the response input or output. - The status of the tool search call. + - `categories: Dict[str, bool]` - - `"in_progress"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"completed"` + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - - `"incomplete"` + Which modalities of input are reflected by the score for each category. - - `class BetaResponseToolSearchOutputItemParam: …` + - `"text"` - - `tools: List[BetaTool]` + - `"image"` - The loaded tool definitions returned by the tool search output. + - `category_scores: Dict[str, float]` - - `class BetaFunctionTool: …` + A dictionary of moderation categories to scores. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `flagged: bool` - - `name: str` + A boolean indicating whether the content was flagged by any category. - The name of the function to call. + - `model: str` - - `parameters: Optional[Dict[str, object]]` + The moderation model that produced this result. - A JSON schema object describing the parameters of the function. + - `type: Literal["moderation_result"]` - - `strict: Optional[bool]` + The object type, which was always `moderation_result` for successful moderation results. - Whether strict parameter validation is enforced for this function tool. + - `"moderation_result"` - - `type: Literal["function"]` + - `class ModerationInputError: …` - The type of the function tool. Always `function`. + An error produced while attempting moderation for the response input or output. - - `"function"` + - `code: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The error code. - The tool invocation context(s). + - `message: str` - - `"direct"` + The error message. - - `"programmatic"` + - `type: Literal["error"]` - - `defer_loading: Optional[bool]` + The object type, which was always `error` for moderation failures. - Whether this function is deferred and loaded via tool search. + - `"error"` - - `description: Optional[str]` + - `output: ModerationOutput` - A description of the function. Used by the model to determine whether or not to call the function. + Moderation for the response output. - - `output_schema: Optional[Dict[str, object]]` + - `class ModerationOutputModerationResult: …` - A JSON schema object describing the JSON value encoded in string outputs for this function. + A moderation result produced for the response input or output. - - `class BetaFileSearchTool: …` + - `categories: Dict[str, bool]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `type: Literal["file_search"]` + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - The type of the file search tool. Always `file_search`. + Which modalities of input are reflected by the score for each category. - - `"file_search"` + - `"text"` - - `vector_store_ids: List[str]` + - `"image"` - The IDs of the vector stores to search. + - `category_scores: Dict[str, float]` - - `filters: Optional[Filters]` + A dictionary of moderation categories to scores. - A filter to apply. + - `flagged: bool` - - `class FiltersComparisonFilter: …` + A boolean indicating whether the content was flagged by any category. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `model: str` - - `key: str` + The moderation model that produced this result. - The key to compare against the value. + - `type: Literal["moderation_result"]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The object type, which was always `moderation_result` for successful moderation results. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"moderation_result"` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `class ModerationOutputError: …` - - `"eq"` + An error produced while attempting moderation for the response input or output. - - `"ne"` + - `code: str` - - `"gt"` + The error code. - - `"gte"` + - `message: str` - - `"lt"` + The error message. - - `"lte"` + - `type: Literal["error"]` - - `"in"` + The object type, which was always `error` for moderation failures. - - `"nin"` + - `"error"` - - `value: Union[str, float, bool, List[object]]` + - `previous_response_id: Optional[str]` - The value to compare against the attribute key; supports string, number, or boolean types. + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `prompt: Optional[BetaResponsePrompt]` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `id: str` + + The unique identifier of the prompt template to use. + + - `variables: Optional[Dict[str, Variables]]` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - `str` - - `float` + - `class BetaResponseInputText: …` - - `bool` + A text input to the model. - - `List[object]` + - `class BetaResponseInputImage: …` - - `class FiltersCompoundFilter: …` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Combine multiple filters using `and` or `or`. + - `class BetaResponseInputFile: …` - - `filters: List[FiltersCompoundFilterFilter]` + A file input to the model. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `version: Optional[str]` - - `class FiltersCompoundFilterFilterComparisonFilter: …` + Optional version of the prompt template. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `prompt_cache_key: Optional[str]` - - `key: str` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - The key to compare against the value. + - `prompt_cache_options: Optional[PromptCacheOptions]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `mode: Literal["implicit", "explicit"]` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + Whether implicit prompt-cache breakpoints were enabled. - - `"eq"` + - `"implicit"` - - `"ne"` + - `"explicit"` - - `"gt"` + - `ttl: Literal["30m"]` - - `"gte"` + The minimum lifetime applied to each cache breakpoint. - - `"lt"` + - `"30m"` - - `"lte"` + - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` - - `"in"` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `"nin"` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `value: Union[str, float, bool, List[object]]` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The value to compare against the attribute key; supports string, number, or boolean types. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `str` + - `"in_memory"` - - `float` + - `"24h"` - - `bool` + - `reasoning: Optional[Reasoning]` - - `List[object]` + **gpt-5 and o-series models only** - - `object` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `type: Literal["and", "or"]` + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` - Type of operation: `and` or `or`. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `"and"` + - `"auto"` - - `"or"` + - `"current_turn"` - - `max_num_results: Optional[int]` + - `"all_turns"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` - - `ranking_options: Optional[RankingOptions]` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - Ranking options for search. + - `"none"` - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + - `"minimal"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"low"` - - `embedding_weight: float` + - `"medium"` - The weight of the embedding in the reciprocal ranking fusion. + - `"high"` - - `text_weight: float` + - `"xhigh"` - The weight of the text in the reciprocal ranking fusion. + - `"max"` - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` - The ranker to use for the file search. + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - `"auto"` - - `"default-2024-11-15"` + - `"concise"` - - `score_threshold: Optional[float]` + - `"detailed"` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` - - `class BetaComputerTool: …` + Controls the reasoning execution mode for the request. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + When returned on a response, this is the effective execution mode. - - `type: Literal["computer"]` + - `str` - The type of the computer tool. Always `computer`. + - `Literal["standard", "pro"]` - - `"computer"` + Controls the reasoning execution mode for the request. - - `class BetaComputerUsePreviewTool: …` + When returned on a response, this is the effective execution mode. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"standard"` - - `display_height: int` + - `"pro"` - The height of the computer display. + - `summary: Optional[Literal["auto", "concise", "detailed"]]` - - `display_width: int` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The width of the computer display. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `"auto"` - The type of computer environment to control. + - `"concise"` - - `"windows"` + - `"detailed"` - - `"mac"` + - `safety_identifier: Optional[str]` - - `"linux"` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `"ubuntu"` + - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` - - `"browser"` + Specifies the processing type used for serving the request. - - `type: Literal["computer_use_preview"]` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - The type of the computer use tool. Always `computer_use_preview`. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `"computer_use_preview"` + - `"auto"` - - `class BetaWebSearchTool: …` + - `"default"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"flex"` - - `type: Literal["web_search", "web_search_2025_08_26"]` + - `"scale"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"priority"` - - `"web_search"` + - `status: Optional[BetaResponseStatus]` - - `"web_search_2025_08_26"` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `filters: Optional[Filters]` + - `"completed"` - Filters for the search. + - `"failed"` - - `allowed_domains: Optional[List[str]]` + - `"in_progress"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"cancelled"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"queued"` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `"incomplete"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `text: Optional[BetaResponseTextConfig]` - - `"low"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"medium"` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `"high"` + - `format: Optional[BetaResponseFormatTextConfig]` - - `user_location: Optional[UserLocation]` + An object specifying the format that the model must output. - The approximate location of the user. + Configuring `{ "type": "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). - - `city: Optional[str]` + The default format is `{ "type": "text" }` with no additional options. - Free text input for the city of the user, e.g. `San Francisco`. + **Not recommended for gpt-4o and newer models:** - - `country: Optional[str]` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `class Text: …` - - `region: Optional[str]` + Default response format. Used to generate text responses. - Free text input for the region of the user, e.g. `California`. + - `type: Literal["text"]` - - `timezone: Optional[str]` + The type of response format being defined. Always `text`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"text"` - - `type: Optional[Literal["approximate"]]` + - `class BetaResponseFormatTextJSONSchemaConfig: …` - The type of location approximation. Always `approximate`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `"approximate"` + - `name: str` - - `class Mcp: …` + 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. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `schema: Dict[str, object]` - - `server_label: str` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - A label for this MCP server, used to identify it in tool calls. + - `type: Literal["json_schema"]` - - `type: Literal["mcp"]` + The type of response format being defined. Always `json_schema`. - The type of the MCP tool. Always `mcp`. + - `"json_schema"` - - `"mcp"` + - `description: Optional[str]` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `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). + + - `class JSONObject: …` + + 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"` + + - `verbosity: Optional[Literal["low", "medium", "high"]]` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `top_logprobs: Optional[int]` + + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + + - `truncation: Optional[Literal["auto", "disabled"]]` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `"auto"` + + - `"disabled"` + + - `usage: Optional[BetaResponseUsage]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The tool invocation context(s). + - `input_tokens: int` - - `"direct"` + The number of input tokens. - - `"programmatic"` + - `input_tokens_details: InputTokensDetails` - - `allowed_tools: Optional[McpAllowedTools]` + A detailed breakdown of the input tokens. - List of allowed tool names or a filter object. + - `cache_write_tokens: int` - - `List[str]` + The number of input tokens that were written to the cache. - A string array of allowed tool names + - `cached_tokens: int` - - `class McpAllowedToolsMcpToolFilter: …` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - A filter object to specify which tools are allowed. + - `output_tokens: int` - - `read_only: Optional[bool]` + The number of output tokens. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `output_tokens_details: OutputTokensDetails` - - `tool_names: Optional[List[str]]` + A detailed breakdown of the output tokens. - List of allowed tool names. + - `reasoning_tokens: int` - - `authorization: Optional[str]` + The number of reasoning tokens. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `total_tokens: int` - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + The total number of tokens used. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `user: Optional[str]` - Currently supported `connector_id` values are: + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `sequence_number: int` - - `"connector_dropbox"` + The sequence number of this event. - - `"connector_gmail"` + - `type: Literal["response.in_progress"]` - - `"connector_googlecalendar"` + The type of the event. Always `response.in_progress`. - - `"connector_googledrive"` + - `"response.in_progress"` - - `"connector_microsoftteams"` + - `agent: Optional[Agent]` - - `"connector_outlookcalendar"` + The agent that owns this multi-agent streaming event. - - `"connector_outlookemail"` + - `agent_name: str` - - `"connector_sharepoint"` + The canonical name of the agent that produced this item. - - `defer_loading: Optional[bool]` +### Beta Response Includable - Whether this MCP tool is deferred and discovered via tool search. +- `Literal["file_search_call.results", "web_search_call.results", "web_search_call.action.sources", 5 more]` - - `headers: Optional[Dict[str, str]]` + Specify additional output data to include in the model response. Currently supported values are: - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `web_search_call.results`: Include the search results of the web search tool call. + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - - `require_approval: Optional[McpRequireApproval]` + - `"file_search_call.results"` - Specify which of the MCP server's tools require approval. + - `"web_search_call.results"` - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `"web_search_call.action.sources"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"message.input_image.image_url"` - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `"computer_call_output.output.image_url"` - A filter object to specify which tools are allowed. + - `"code_interpreter_call.outputs"` - - `read_only: Optional[bool]` + - `"reasoning.encrypted_content"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"message.output_text.logprobs"` - - `tool_names: Optional[List[str]]` +### Beta Response Incomplete Event - List of allowed tool names. +- `class BetaResponseIncompleteEvent: …` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + An event that is emitted when a response finishes as incomplete. - A filter object to specify which tools are allowed. + - `response: BetaResponse` - - `read_only: Optional[bool]` + The response that was incomplete. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `id: str` - - `tool_names: Optional[List[str]]` + Unique identifier for this Response. - List of allowed tool names. + - `created_at: float` - - `Literal["always", "never"]` + Unix timestamp (in seconds) of when this Response was created. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `error: Optional[BetaResponseError]` - - `"always"` + An error object returned when the model fails to generate a Response. - - `"never"` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` - - `server_description: Optional[str]` + The error code for the response. - Optional description of the MCP server, used to provide more context. + - `"server_error"` - - `server_url: Optional[str]` + - `"rate_limit_exceeded"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"invalid_prompt"` - - `tunnel_id: Optional[str]` + - `"bio_policy"` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `"vector_store_timeout"` - - `class CodeInterpreter: …` + - `"invalid_image"` - A tool that runs Python code to help generate a response to a prompt. + - `"invalid_image_format"` - - `container: CodeInterpreterContainer` + - `"invalid_base64_image"` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `"invalid_image_url"` - - `str` + - `"image_too_large"` - The container ID. + - `"image_too_small"` - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `"image_parse_error"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"image_content_policy_violation"` - - `type: Literal["auto"]` + - `"invalid_image_mode"` - Always `auto`. + - `"image_file_too_large"` - - `"auto"` + - `"unsupported_image_media_type"` - - `file_ids: Optional[List[str]]` + - `"empty_image_file"` - An optional list of uploaded files to make available to your code. + - `"failed_to_download_image"` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `"image_file_not_found"` - The memory limit for the code interpreter container. + - `message: str` - - `"1g"` + A human-readable description of the error. - - `"4g"` + - `incomplete_details: Optional[IncompleteDetails]` - - `"16g"` + Details about why the response is incomplete. - - `"64g"` + - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + The reason why the response is incomplete. - Network access policy for the container. + - `"max_output_tokens"` - - `class BetaContainerNetworkPolicyDisabled: …` + - `"content_filter"` - - `type: Literal["disabled"]` + - `instructions: Union[str, List[BetaResponseInputItem], null]` - Disable outbound network access. Always `disabled`. + A system (or developer) message inserted into the model's context. - - `"disabled"` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `str` - - `allowed_domains: List[str]` + A text input to the model, equivalent to a text input with the + `developer` role. - A list of allowed domains when type is `allowlist`. + - `List[BetaResponseInputItem]` - - `type: Literal["allowlist"]` + A list of one or many input items to the model, containing + different content types. - Allow outbound network access only to specified domains. Always `allowlist`. + - `class BetaEasyInputMessage: …` - - `"allowlist"` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `content: Union[str, BetaResponseInputMessageContentList]` - Optional domain-scoped secrets for allowlisted domains. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `domain: str` + - `str` - The domain associated with the secret. + A text input to the model. - - `name: str` + - `List[BetaResponseInputContent]` - The name of the secret to inject for the domain. + - `class BetaResponseInputText: …` - - `value: str` + A text input to the model. - The secret value to inject for the domain. + - `text: str` - - `type: Literal["code_interpreter"]` + The text input to the model. - The type of the code interpreter tool. Always `code_interpreter`. + - `type: Literal["input_text"]` - - `"code_interpreter"` + The type of the input item. Always `input_text`. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"input_text"` - The tool invocation context(s). + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"direct"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"programmatic"` + - `mode: Literal["explicit"]` - - `class ProgrammaticToolCalling: …` + The breakpoint mode. Always `explicit`. - - `type: Literal["programmatic_tool_calling"]` + - `"explicit"` - The type of the tool. Always `programmatic_tool_calling`. + - `class BetaResponseInputImage: …` - - `"programmatic_tool_calling"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class ImageGeneration: …` + - `detail: Literal["low", "high", "auto", "original"]` - A tool that generates images using the GPT image models. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: Literal["image_generation"]` + - `"low"` - The type of the image generation tool. Always `image_generation`. + - `"high"` - - `"image_generation"` + - `"auto"` - - `action: Optional[Literal["generate", "edit", "auto"]]` + - `"original"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `type: Literal["input_image"]` - - `"generate"` + The type of the input item. Always `input_image`. - - `"edit"` + - `"input_image"` - - `"auto"` + - `file_id: Optional[str]` - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + The ID of the file to be sent to the model. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `image_url: Optional[str]` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"transparent"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"opaque"` + - `mode: Literal["explicit"]` - - `"auto"` + The breakpoint mode. Always `explicit`. - - `input_fidelity: Optional[Literal["high", "low"]]` + - `"explicit"` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `class BetaResponseInputFile: …` - - `"high"` + A file input to the model. - - `"low"` + - `type: Literal["input_file"]` - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + The type of the input item. Always `input_file`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"input_file"` - - `file_id: Optional[str]` + - `detail: Optional[Literal["auto", "low", "high"]]` - File ID for the mask image. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `image_url: Optional[str]` + - `"auto"` - Base64-encoded mask image. + - `"low"` - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + - `"high"` - The image generation model to use. Default: `gpt-image-1`. + - `file_data: Optional[str]` - - `str` + The content of the file to be sent to the model. - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `file_id: Optional[str]` - The image generation model to use. Default: `gpt-image-1`. + The ID of the file to be sent to the model. - - `"gpt-image-1"` + - `file_url: Optional[str]` - - `"gpt-image-1-mini"` + The URL of the file to be sent to the model. - - `"gpt-image-2"` + - `filename: Optional[str]` - - `"gpt-image-2-2026-04-21"` + The name of the file to be sent to the model. - - `"gpt-image-1.5"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"chatgpt-image-latest"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `moderation: Optional[Literal["auto", "low"]]` + - `mode: Literal["explicit"]` - Moderation level for the generated image. Default: `auto`. + The breakpoint mode. Always `explicit`. - - `"auto"` + - `"explicit"` - - `"low"` + - `role: Literal["user", "assistant", "system", "developer"]` - - `output_compression: Optional[int]` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - Compression level for the output image. Default: 100. + - `"user"` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + - `"assistant"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"system"` - - `"png"` + - `"developer"` - - `"webp"` + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `"jpeg"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `partial_images: Optional[int]` + - `"commentary"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"final_answer"` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + - `type: Optional[Literal["message"]]` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The type of the message input. Always `message`. - - `"low"` + - `"message"` - - `"medium"` + - `class Message: …` - - `"high"` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `"auto"` + - `content: BetaResponseInputMessageContentList` - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + A list of one or many input items to the model, containing different content + types. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `class BetaResponseInputText: …` - - `str` + A text input to the model. - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `class BetaResponseInputImage: …` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"1024x1024"` + - `class BetaResponseInputFile: …` - - `"1024x1536"` + A file input to the model. - - `"1536x1024"` + - `role: Literal["user", "system", "developer"]` - - `"auto"` + The role of the message input. One of `user`, `system`, or `developer`. - - `class LocalShell: …` + - `"user"` - A tool that allows the model to execute shell commands in a local environment. + - `"system"` - - `type: Literal["local_shell"]` + - `"developer"` - The type of the local shell tool. Always `local_shell`. + - `agent: Optional[MessageAgent]` - - `"local_shell"` + The agent that produced this item. - - `class BetaFunctionShellTool: …` + - `agent_name: str` - A tool that allows the model to execute shell commands. + The canonical name of the agent that produced this item. - - `type: Literal["shell"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The type of the shell tool. Always `shell`. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"shell"` + - `"in_progress"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"completed"` - The tool invocation context(s). + - `"incomplete"` - - `"direct"` + - `type: Optional[Literal["message"]]` - - `"programmatic"` + The type of the message input. Always set to `message`. - - `environment: Optional[Environment]` + - `"message"` - - `class BetaContainerAuto: …` + - `class BetaResponseOutputMessage: …` - - `type: Literal["container_auto"]` + An output message from the model. - Automatically creates a container for this request + - `id: str` - - `"container_auto"` + The unique ID of the output message. - - `file_ids: Optional[List[str]]` + - `content: List[Content]` - An optional list of uploaded files to make available to your code. + The content of the output message. - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `class BetaResponseOutputText: …` - The memory limit for the container. + A text output from the model. - - `"1g"` + - `annotations: List[Annotation]` - - `"4g"` + The annotations of the text output. - - `"16g"` + - `class AnnotationFileCitation: …` - - `"64g"` + A citation to a file. - - `network_policy: Optional[NetworkPolicy]` + - `file_id: str` - Network access policy for the container. + The ID of the file. - - `class BetaContainerNetworkPolicyDisabled: …` + - `filename: str` - - `class BetaContainerNetworkPolicyAllowlist: …` + The filename of the file cited. - - `skills: Optional[List[Skill]]` + - `index: int` - An optional list of skills referenced by id or inline data. + The index of the file in the list of files. - - `class BetaSkillReference: …` + - `type: Literal["file_citation"]` - - `skill_id: str` + The type of the file citation. Always `file_citation`. - The ID of the referenced skill. + - `"file_citation"` - - `type: Literal["skill_reference"]` + - `class AnnotationURLCitation: …` - References a skill created with the /v1/skills endpoint. + A citation for a web resource used to generate a model response. - - `"skill_reference"` + - `end_index: int` - - `version: Optional[str]` + The index of the last character of the URL citation in the message. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `start_index: int` - - `class BetaInlineSkill: …` + The index of the first character of the URL citation in the message. - - `description: str` + - `title: str` - The description of the skill. + The title of the web resource. - - `name: str` + - `type: Literal["url_citation"]` - The name of the skill. + The type of the URL citation. Always `url_citation`. - - `source: BetaInlineSkillSource` + - `"url_citation"` - Inline skill payload + - `url: str` - - `data: str` + The URL of the web resource. - Base64-encoded skill zip bundle. + - `class AnnotationContainerFileCitation: …` - - `media_type: Literal["application/zip"]` + A citation for a container file used to generate a model response. - The media type of the inline skill payload. Must be `application/zip`. + - `container_id: str` - - `"application/zip"` + The ID of the container file. - - `type: Literal["base64"]` + - `end_index: int` - The type of the inline skill source. Must be `base64`. + The index of the last character of the container file citation in the message. - - `"base64"` + - `file_id: str` - - `type: Literal["inline"]` + The ID of the file. - Defines an inline skill for this request. + - `filename: str` - - `"inline"` + The filename of the container file cited. - - `class BetaLocalEnvironment: …` + - `start_index: int` - - `type: Literal["local"]` + The index of the first character of the container file citation in the message. - Use a local computer environment. + - `type: Literal["container_file_citation"]` - - `"local"` + The type of the container file citation. Always `container_file_citation`. - - `skills: Optional[List[BetaLocalSkill]]` + - `"container_file_citation"` - An optional list of skills. + - `class AnnotationFilePath: …` - - `description: str` + A path to a file. - The description of the skill. + - `file_id: str` - - `name: str` + The ID of the file. - The name of the skill. + - `index: int` - - `path: str` + The index of the file in the list of files. - The path to the directory containing the skill. + - `type: Literal["file_path"]` - - `class BetaContainerReference: …` + The type of the file path. Always `file_path`. - - `container_id: str` + - `"file_path"` - The ID of the referenced container. + - `text: str` - - `type: Literal["container_reference"]` + The text output from the model. - References a container created with the /v1/containers endpoint + - `type: Literal["output_text"]` - - `"container_reference"` + The type of the output text. Always `output_text`. - - `class BetaCustomTool: …` + - `"output_text"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `logprobs: Optional[List[Logprob]]` - - `name: str` + - `token: str` - The name of the custom tool, used to identify it in tool calls. + - `bytes: List[int]` - - `type: Literal["custom"]` + - `logprob: float` - The type of the custom tool. Always `custom`. + - `top_logprobs: List[LogprobTopLogprob]` - - `"custom"` + - `token: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `bytes: List[int]` - The tool invocation context(s). + - `logprob: float` - - `"direct"` + - `class BetaResponseOutputRefusal: …` - - `"programmatic"` + A refusal from the model. - - `defer_loading: Optional[bool]` + - `refusal: str` - Whether this tool should be deferred and discovered via tool search. + The refusal explanation from the model. - - `description: Optional[str]` + - `type: Literal["refusal"]` - Optional description of the custom tool, used to provide more context. + The type of the refusal. Always `refusal`. - - `format: Optional[Format]` + - `"refusal"` - The input format for the custom tool. Default is unconstrained text. + - `role: Literal["assistant"]` - - `class FormatText: …` + The role of the output message. Always `assistant`. - Unconstrained free-form text. + - `"assistant"` - - `type: Literal["text"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - Unconstrained text format. Always `text`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"text"` + - `"in_progress"` - - `class FormatGrammar: …` + - `"completed"` - A grammar defined by the user. + - `"incomplete"` - - `definition: str` + - `type: Literal["message"]` - The grammar definition. + The type of the output message. Always `message`. - - `syntax: Literal["lark", "regex"]` + - `"message"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `agent: Optional[Agent]` - - `"lark"` + The agent that produced this item. - - `"regex"` + - `agent_name: str` - - `type: Literal["grammar"]` + The canonical name of the agent that produced this item. - Grammar format. Always `grammar`. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `"grammar"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `class BetaNamespaceTool: …` + - `"commentary"` - Groups function/custom tools under a shared namespace. + - `"final_answer"` - - `description: str` + - `class BetaResponseFileSearchToolCall: …` - A description of the namespace shown to the model. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `name: str` + - `id: str` - The namespace name used in tool calls (for example, `crm`). + The unique ID of the file search tool call. - - `tools: List[Tool]` + - `queries: List[str]` - The function/custom tools available inside this namespace. + The queries used to search for files. - - `class ToolFunction: …` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - - `name: str` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `type: Literal["function"]` + - `"in_progress"` - - `"function"` + - `"searching"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"completed"` - The tool invocation context(s). + - `"incomplete"` - - `"direct"` + - `"failed"` - - `"programmatic"` + - `type: Literal["file_search_call"]` - - `defer_loading: Optional[bool]` + The type of the file search tool call. Always `file_search_call`. - Whether this function should be deferred and discovered via tool search. + - `"file_search_call"` - - `description: Optional[str]` + - `agent: Optional[Agent]` - - `output_schema: Optional[Dict[str, object]]` + The agent that produced this item. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `agent_name: str` - - `parameters: Optional[object]` + The canonical name of the agent that produced this item. - - `strict: Optional[bool]` + - `results: Optional[List[Result]]` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The results of the file search tool call. - - `class BetaCustomTool: …` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + 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, booleans, or numbers. - - `type: Literal["namespace"]` + - `str` - The type of the tool. Always `namespace`. + - `float` - - `"namespace"` + - `bool` - - `class BetaToolSearchTool: …` + - `file_id: Optional[str]` - Hosted or BYOT tool search configuration for deferred tools. + The unique ID of the file. - - `type: Literal["tool_search"]` + - `filename: Optional[str]` - The type of the tool. Always `tool_search`. + The name of the file. - - `"tool_search"` + - `score: Optional[float]` - - `description: Optional[str]` + The relevance score of the file - a value between 0 and 1. - Description shown to the model for a client-executed tool search tool. + - `text: Optional[str]` - - `execution: Optional[Literal["server", "client"]]` + The text that was retrieved from the file. - Whether tool search is executed by the server or by the client. + - `class BetaResponseComputerToolCall: …` - - `"server"` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `"client"` + - `id: str` - - `parameters: Optional[object]` + The unique ID of the computer call. - Parameter schema for a client-executed tool search tool. + - `call_id: str` - - `class BetaWebSearchPreviewTool: …` + An identifier used when responding to the tool call with output. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `pending_safety_checks: List[PendingSafetyCheck]` - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + The pending safety checks for the computer call. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `id: str` - - `"web_search_preview"` + The ID of the pending safety check. - - `"web_search_preview_2025_03_11"` + - `code: Optional[str]` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + The type of the pending safety check. - - `"text"` + - `message: Optional[str]` - - `"image"` + Details about the pending safety check. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"low"` + - `"in_progress"` - - `"medium"` + - `"completed"` - - `"high"` + - `"incomplete"` - - `user_location: Optional[UserLocation]` + - `type: Literal["computer_call"]` - The user's location. + The type of the computer call. Always `computer_call`. - - `type: Literal["approximate"]` + - `"computer_call"` - The type of location approximation. Always `approximate`. + - `action: Optional[BetaComputerAction]` - - `"approximate"` + A click action. - - `city: Optional[str]` + - `class Click: …` - Free text input for the city of the user, e.g. `San Francisco`. + A click action. - - `country: Optional[str]` + - `button: Literal["left", "right", "wheel", 2 more]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `region: Optional[str]` + - `"left"` - Free text input for the region of the user, e.g. `California`. + - `"right"` - - `timezone: Optional[str]` + - `"wheel"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"back"` - - `class BetaApplyPatchTool: …` + - `"forward"` - Allows the assistant to create, delete, or update files using unified diffs. + - `type: Literal["click"]` - - `type: Literal["apply_patch"]` + Specifies the event type. For a click action, this property is always `click`. - The type of the tool. Always `apply_patch`. + - `"click"` - - `"apply_patch"` + - `x: int` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The x-coordinate where the click occurred. - The tool invocation context(s). + - `y: int` - - `"direct"` + The y-coordinate where the click occurred. - - `"programmatic"` + - `keys: Optional[List[str]]` - - `type: Literal["tool_search_output"]` + The keys being held while clicking. - The item type. Always `tool_search_output`. + - `class DoubleClick: …` - - `"tool_search_output"` + A double click action. - - `id: Optional[str]` + - `keys: Optional[List[str]]` - The unique ID of this tool search output. + The keys being held while double-clicking. - - `agent: Optional[Agent]` + - `type: Literal["double_click"]` - The agent that produced this item. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `agent_name: str` + - `"double_click"` - The canonical name of the agent that produced this item. + - `x: int` - - `call_id: Optional[str]` + The x-coordinate where the double click occurred. - The unique ID of the tool search call generated by the model. + - `y: int` - - `execution: Optional[Literal["server", "client"]]` + The y-coordinate where the double click occurred. - Whether tool search was executed by the server or by the client. + - `class Drag: …` - - `"server"` + A drag action. - - `"client"` + - `path: List[DragPath]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The status of the tool search output. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"in_progress"` + - `x: int` - - `"completed"` + The x-coordinate. - - `"incomplete"` + - `y: int` - - `class AdditionalTools: …` + The y-coordinate. - - `role: Literal["developer"]` + - `type: Literal["drag"]` - The role that provided the additional tools. Only `developer` is supported. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"developer"` + - `"drag"` - - `tools: List[BetaTool]` + - `keys: Optional[List[str]]` - A list of additional tools made available at this item. + The keys being held while dragging the mouse. - - `class BetaFunctionTool: …` + - `class Keypress: …` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + A collection of keypresses the model would like to perform. - - `class BetaFileSearchTool: …` + - `keys: List[str]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `class BetaComputerTool: …` + - `type: Literal["keypress"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `class BetaComputerUsePreviewTool: …` + - `"keypress"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class Move: …` - - `class BetaWebSearchTool: …` + A mouse move action. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `type: Literal["move"]` - - `class Mcp: …` + Specifies the event type. For a move action, this property is always set to `move`. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"move"` - - `class CodeInterpreter: …` + - `x: int` - A tool that runs Python code to help generate a response to a prompt. + The x-coordinate to move to. - - `class ProgrammaticToolCalling: …` + - `y: int` - - `class ImageGeneration: …` + The y-coordinate to move to. - A tool that generates images using the GPT image models. + - `keys: Optional[List[str]]` - - `class LocalShell: …` + The keys being held while moving the mouse. - A tool that allows the model to execute shell commands in a local environment. + - `class Screenshot: …` - - `class BetaFunctionShellTool: …` + A screenshot action. - A tool that allows the model to execute shell commands. + - `type: Literal["screenshot"]` - - `class BetaCustomTool: …` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"screenshot"` - - `class BetaNamespaceTool: …` + - `class Scroll: …` - Groups function/custom tools under a shared namespace. + A scroll action. - - `class BetaToolSearchTool: …` + - `scroll_x: int` - Hosted or BYOT tool search configuration for deferred tools. + The horizontal scroll distance. - - `class BetaWebSearchPreviewTool: …` + - `scroll_y: int` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The vertical scroll distance. - - `class BetaApplyPatchTool: …` + - `type: Literal["scroll"]` - Allows the assistant to create, delete, or update files using unified diffs. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `type: Literal["additional_tools"]` + - `"scroll"` - The item type. Always `additional_tools`. + - `x: int` - - `"additional_tools"` + The x-coordinate where the scroll occurred. - - `id: Optional[str]` + - `y: int` - The unique ID of this additional tools item. + The y-coordinate where the scroll occurred. - - `agent: Optional[AdditionalToolsAgent]` + - `keys: Optional[List[str]]` - The agent that produced this item. + The keys being held while scrolling. - - `agent_name: str` + - `class Type: …` - The canonical name of the agent that produced this item. + An action to type in text. - - `class BetaResponseReasoningItem: …` + - `text: str` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The text to type. - - `id: str` + - `type: Literal["type"]` - The unique identifier of the reasoning content. + Specifies the event type. For a type action, this property is always set to `type`. - - `summary: List[Summary]` + - `"type"` - Reasoning summary content. + - `class Wait: …` - - `text: str` + A wait action. - A summary of the reasoning output from the model so far. + - `type: Literal["wait"]` - - `type: Literal["summary_text"]` + Specifies the event type. For a wait action, this property is always set to `wait`. - The type of the object. Always `summary_text`. + - `"wait"` - - `"summary_text"` + - `actions: Optional[BetaComputerActionList]` - - `type: Literal["reasoning"]` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The type of the object. Always `reasoning`. + - `class Click: …` - - `"reasoning"` + A click action. - - `agent: Optional[Agent]` + - `class DoubleClick: …` - The agent that produced this item. + A double click action. - - `agent_name: str` + - `class Drag: …` - The canonical name of the agent that produced this item. + A drag action. - - `content: Optional[List[Content]]` + - `class Keypress: …` - Reasoning text content. + A collection of keypresses the model would like to perform. - - `text: str` + - `class Move: …` - The reasoning text from the model. + A mouse move action. - - `type: Literal["reasoning_text"]` + - `class Screenshot: …` - The type of the reasoning text. Always `reasoning_text`. + A screenshot action. - - `"reasoning_text"` + - `class Scroll: …` - - `encrypted_content: Optional[str]` + A scroll action. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `class Type: …` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + An action to type in text. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class Wait: …` - - `"in_progress"` + A wait action. - - `"completed"` + - `agent: Optional[Agent]` - - `"incomplete"` + The agent that produced this item. - - `class BetaResponseCompactionItemParam: …` + - `agent_name: str` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The canonical name of the agent that produced this item. - - `encrypted_content: str` + - `class ComputerCallOutput: …` - The encrypted content of the compaction summary. + The output of a computer tool call. - - `type: Literal["compaction"]` + - `call_id: str` - The type of the item. Always `compaction`. + The ID of the computer tool call that produced the output. - - `"compaction"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `id: Optional[str]` + A computer screenshot image used with the computer use tool. - The ID of the compaction item. + - `type: Literal["computer_screenshot"]` - - `agent: Optional[Agent]` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The agent that produced this item. + - `"computer_screenshot"` - - `agent_name: str` + - `file_id: Optional[str]` - The canonical name of the agent that produced this item. + The identifier of an uploaded file that contains the screenshot. - - `class ImageGenerationCall: …` + - `image_url: Optional[str]` - An image generation request made by the model. + The URL of the screenshot image. - - `id: str` + - `type: Literal["computer_call_output"]` - The unique ID of the image generation call. + The type of the computer tool call output. Always `computer_call_output`. - - `result: Optional[str]` + - `"computer_call_output"` - The generated image encoded in base64. + - `id: Optional[str]` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + The ID of the computer tool call output. - The status of the image generation call. + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - - `"in_progress"` + The safety checks reported by the API that have been acknowledged by the developer. - - `"completed"` + - `id: str` - - `"generating"` + The ID of the pending safety check. - - `"failed"` + - `code: Optional[str]` - - `type: Literal["image_generation_call"]` + The type of the pending safety check. - The type of the image generation call. Always `image_generation_call`. + - `message: Optional[str]` - - `"image_generation_call"` + Details about the pending safety check. - - `agent: Optional[ImageGenerationCallAgent]` + - `agent: Optional[ComputerCallOutputAgent]` The agent that produced this item. @@ -64224,142 +75481,148 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A tool call to run code. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `id: str` + - `"in_progress"` - The unique ID of the code interpreter tool call. + - `"completed"` - - `code: Optional[str]` + - `"incomplete"` - The code to run, or null if not available. + - `class BetaResponseFunctionWebSearch: …` - - `container_id: str` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The ID of the container used to run the code. + - `id: str` - - `outputs: Optional[List[Output]]` + The unique ID of the web search tool call. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `action: Action` - - `class OutputLogs: …` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - The logs output from the code interpreter. + - `class ActionSearch: …` - - `logs: str` + Action type "search" - Performs a web search query. - The logs output from the code interpreter. + - `type: Literal["search"]` - - `type: Literal["logs"]` + The action type. - The type of the output. Always `logs`. + - `"search"` - - `"logs"` + - `queries: Optional[List[str]]` - - `class OutputImage: …` + The search queries. - The image output from the code interpreter. + - `query: Optional[str]` - - `type: Literal["image"]` + The search query. - The type of the output. Always `image`. + - `sources: Optional[List[ActionSearchSource]]` - - `"image"` + The sources used in the search. + + - `type: Literal["url"]` + + The type of source. Always `url`. + + - `"url"` - `url: str` - The URL of the image output from the code interpreter. + The URL of the source. - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + - `class ActionOpenPage: …` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + Action type "open_page" - Opens a specific URL from search results. - - `"in_progress"` + - `type: Literal["open_page"]` - - `"completed"` + The action type. - - `"incomplete"` + - `"open_page"` - - `"interpreting"` + - `url: Optional[str]` - - `"failed"` + The URL opened by the model. - - `type: Literal["code_interpreter_call"]` + - `class ActionFindInPage: …` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"code_interpreter_call"` + - `pattern: str` - - `agent: Optional[Agent]` + The pattern or text to search for within the page. - The agent that produced this item. + - `type: Literal["find_in_page"]` - - `agent_name: str` + The action type. - The canonical name of the agent that produced this item. + - `"find_in_page"` - - `class LocalShellCall: …` + - `url: str` - A tool call to run a command on the local shell. + The URL of the page searched for the pattern. - - `id: str` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - The unique ID of the local shell call. + The status of the web search tool call. - - `action: LocalShellCallAction` + - `"in_progress"` - Execute a shell command on the server. + - `"searching"` - - `command: List[str]` + - `"completed"` - The command to run. + - `"failed"` - - `env: Dict[str, str]` + - `type: Literal["web_search_call"]` - Environment variables to set for the command. + The type of the web search tool call. Always `web_search_call`. - - `type: Literal["exec"]` + - `"web_search_call"` - The type of the local shell action. Always `exec`. + - `agent: Optional[Agent]` - - `"exec"` + The agent that produced this item. - - `timeout_ms: Optional[int]` + - `agent_name: str` - Optional timeout in milliseconds for the command. + The canonical name of the agent that produced this item. - - `user: Optional[str]` + - `class BetaResponseFunctionToolCall: …` - Optional user to run the command as. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `working_directory: Optional[str]` + - `arguments: str` - Optional working directory to run the command in. + A JSON string of the arguments to pass to the function. - `call_id: str` - The unique ID of the local shell tool call generated by the model. - - - `status: Literal["in_progress", "completed", "incomplete"]` + The unique ID of the function tool call generated by the model. - The status of the local shell call. + - `name: str` - - `"in_progress"` + The name of the function to run. - - `"completed"` + - `type: Literal["function_call"]` - - `"incomplete"` + The type of the function tool call. Always `function_call`. - - `type: Literal["local_shell_call"]` + - `"function_call"` - The type of the local shell call. Always `local_shell_call`. + - `id: Optional[str]` - - `"local_shell_call"` + The unique ID of the function tool call. - - `agent: Optional[LocalShellCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -64367,35 +75630,34 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCallOutput: …` - - The output of a local shell tool call. + - `caller: Optional[Caller]` - - `id: str` + The execution context that produced this tool call. - The unique ID of the local shell tool call generated by the model. + - `class CallerDirect: …` - - `output: str` + - `type: Literal["direct"]` - A JSON string of the output of the local shell tool call. + - `"direct"` - - `type: Literal["local_shell_call_output"]` + - `class CallerProgram: …` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `caller_id: str` - - `"local_shell_call_output"` + The call ID of the program item that produced this tool call. - - `agent: Optional[LocalShellCallOutputAgent]` + - `type: Literal["program"]` - The agent that produced this item. + - `"program"` - - `agent_name: str` + - `namespace: Optional[str]` - The canonical name of the agent that produced this item. + The namespace of the function to run. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -64403,149 +75665,145 @@ print(compacted_response) - `"incomplete"` - - `class ShellCall: …` - - A tool representing a request to execute one or more shell commands. - - - `action: ShellCallAction` + - `class FunctionCallOutput: …` - The shell commands and limits that describe how to run the tool call. + The output of a function tool call. - - `commands: List[str]` + - `call_id: str` - Ordered shell commands for the execution environment to run. + The unique ID of the function tool call generated by the model. - - `max_output_length: Optional[int]` + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Text, image, or file output of the function tool call. - - `timeout_ms: Optional[int]` + - `str` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + A JSON string of the output of the function tool call. - - `call_id: str` + - `List[BetaResponseFunctionCallOutputItem]` - The unique ID of the shell tool call generated by the model. + - `class BetaResponseInputTextContent: …` - - `type: Literal["shell_call"]` + A text input to the model. - The type of the item. Always `shell_call`. + - `text: str` - - `"shell_call"` + The text input to the model. - - `id: Optional[str]` + - `type: Literal["input_text"]` - The unique ID of the shell tool call. Populated when this item is returned via API. + The type of the input item. Always `input_text`. - - `agent: Optional[ShellCallAgent]` + - `"input_text"` - The agent that produced this item. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `agent_name: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The canonical name of the agent that produced this item. + - `mode: Literal["explicit"]` - - `caller: Optional[ShellCallCaller]` + The breakpoint mode. Always `explicit`. - The execution context that produced this tool call. + - `"explicit"` - - `class ShellCallCallerDirect: …` + - `class BetaResponseInputImageContent: …` - - `type: Literal["direct"]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The caller type. Always `direct`. + - `type: Literal["input_image"]` - - `"direct"` + The type of the input item. Always `input_image`. - - `class ShellCallCallerProgram: …` + - `"input_image"` - - `caller_id: str` + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - The call ID of the program item that produced this tool call. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: Literal["program"]` + - `"low"` - The caller type. Always `program`. + - `"high"` - - `"program"` + - `"auto"` - - `environment: Optional[ShellCallEnvironment]` + - `"original"` - The environment to execute the shell commands in. + - `file_id: Optional[str]` - - `class BetaLocalEnvironment: …` + The ID of the file to be sent to the model. - - `class BetaContainerReference: …` + - `image_url: Optional[str]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"in_progress"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"completed"` + - `mode: Literal["explicit"]` - - `"incomplete"` + The breakpoint mode. Always `explicit`. - - `class ShellCallOutput: …` + - `"explicit"` - The streamed output items emitted by a shell tool call. + - `class BetaResponseInputFileContent: …` - - `call_id: str` + A file input to the model. - The unique ID of the shell tool call generated by the model. + - `type: Literal["input_file"]` - - `output: List[BetaResponseFunctionShellCallOutputContent]` + The type of the input item. Always `input_file`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"input_file"` - - `outcome: Outcome` + - `detail: Optional[Literal["auto", "low", "high"]]` - The exit or timeout outcome associated with this shell call. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `class OutcomeTimeout: …` + - `"auto"` - Indicates that the shell call exceeded its configured time limit. + - `"low"` - - `type: Literal["timeout"]` + - `"high"` - The outcome type. Always `timeout`. + - `file_data: Optional[str]` - - `"timeout"` + The base64-encoded data of the file to be sent to the model. - - `class OutcomeExit: …` + - `file_id: Optional[str]` - Indicates that the shell commands finished and returned an exit code. + The ID of the file to be sent to the model. - - `exit_code: int` + - `file_url: Optional[str]` - The exit code returned by the shell process. + The URL of the file to be sent to the model. - - `type: Literal["exit"]` + - `filename: Optional[str]` - The outcome type. Always `exit`. + The name of the file to be sent to the model. - - `"exit"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `stderr: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Captured stderr output for the shell call. + - `mode: Literal["explicit"]` - - `stdout: str` + The breakpoint mode. Always `explicit`. - Captured stdout output for the shell call. + - `"explicit"` - - `type: Literal["shell_call_output"]` + - `type: Literal["function_call_output"]` - The type of the item. Always `shell_call_output`. + The type of the function tool call output. Always `function_call_output`. - - `"shell_call_output"` + - `"function_call_output"` - `id: Optional[str]` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `agent: Optional[ShellCallOutputAgent]` + - `agent: Optional[FunctionCallOutputAgent]` The agent that produced this item. @@ -64553,11 +75811,11 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ShellCallOutputCaller]` + - `caller: Optional[FunctionCallOutputCaller]` The execution context that produced this tool call. - - `class ShellCallOutputCallerDirect: …` + - `class FunctionCallOutputCallerDirect: …` - `type: Literal["direct"]` @@ -64565,7 +75823,7 @@ print(compacted_response) - `"direct"` - - `class ShellCallOutputCallerProgram: …` + - `class FunctionCallOutputCallerProgram: …` - `caller_id: str` @@ -64577,13 +75835,9 @@ print(compacted_response) - `"program"` - - `max_output_length: Optional[int]` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the shell call output. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -64591,87 +75845,99 @@ print(compacted_response) - `"incomplete"` - - `class ApplyPatchCall: …` + - `class AgentMessage: …` - A tool call representing a request to create, delete, or update files using diff patches. + A message routed between agents. - - `call_id: str` + - `author: str` - The unique ID of the apply patch tool call generated by the model. + The sending agent identity. - - `operation: ApplyPatchCallOperation` + - `content: List[AgentMessageContent]` - The specific create, delete, or update instruction for the apply_patch tool call. + Plaintext, image, or encrypted content sent between agents. - - `class ApplyPatchCallOperationCreateFile: …` + - `class BetaResponseInputTextContent: …` - Instruction for creating a new file via the apply_patch tool. + A text input to the model. - - `diff: str` + - `class BetaResponseInputImageContent: …` - Unified diff content to apply when creating the file. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `path: str` + - `class AgentMessageContentEncryptedContent: …` - Path of the file to create relative to the workspace root. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `type: Literal["create_file"]` + - `encrypted_content: str` - The operation type. Always `create_file`. + Opaque encrypted content. - - `"create_file"` + - `type: Literal["encrypted_content"]` - - `class ApplyPatchCallOperationDeleteFile: …` + The type of the input item. Always `encrypted_content`. - Instruction for deleting an existing file via the apply_patch tool. + - `"encrypted_content"` - - `path: str` + - `recipient: str` - Path of the file to delete relative to the workspace root. + The destination agent identity. - - `type: Literal["delete_file"]` + - `type: Literal["agent_message"]` - The operation type. Always `delete_file`. + The item type. Always `agent_message`. - - `"delete_file"` + - `"agent_message"` - - `class ApplyPatchCallOperationUpdateFile: …` + - `id: Optional[str]` - Instruction for updating an existing file via the apply_patch tool. + The unique ID of this agent message item. - - `diff: str` + - `agent: Optional[AgentMessageAgent]` - Unified diff content to apply to the existing file. + The agent that produced this item. - - `path: str` + - `agent_name: str` - Path of the file to update relative to the workspace root. + The canonical name of the agent that produced this item. - - `type: Literal["update_file"]` + - `class MultiAgentCall: …` - The operation type. Always `update_file`. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"update_file"` + The multi-agent action that was executed. - - `status: Literal["in_progress", "completed"]` + - `"spawn_agent"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"interrupt_agent"` - - `"in_progress"` + - `"list_agents"` - - `"completed"` + - `"send_message"` - - `type: Literal["apply_patch_call"]` + - `"followup_task"` - The type of the item. Always `apply_patch_call`. + - `"wait_agent"` - - `"apply_patch_call"` + - `arguments: str` + + The action arguments as a JSON string. + + - `call_id: str` + + The unique ID linking this call to its output. + + - `type: Literal["multi_agent_call"]` + + The item type. Always `multi_agent_call`. + + - `"multi_agent_call"` - `id: Optional[str]` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of this multi-agent call. - - `agent: Optional[ApplyPatchCallAgent]` + - `agent: Optional[MultiAgentCallAgent]` The agent that produced this item. @@ -64679,131 +75945,129 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ApplyPatchCallCaller]` - - The execution context that produced this tool call. + - `class MultiAgentCallOutput: …` - - `class ApplyPatchCallCallerDirect: …` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `type: Literal["direct"]` + The multi-agent action that produced this result. - The caller type. Always `direct`. + - `"spawn_agent"` - - `"direct"` + - `"interrupt_agent"` - - `class ApplyPatchCallCallerProgram: …` + - `"list_agents"` - - `caller_id: str` + - `"send_message"` - The call ID of the program item that produced this tool call. + - `"followup_task"` - - `type: Literal["program"]` + - `"wait_agent"` - The caller type. Always `program`. + - `call_id: str` - - `"program"` + The unique ID of the multi-agent call. - - `class ApplyPatchCallOutput: …` + - `output: List[MultiAgentCallOutputOutput]` - The streamed output emitted by an apply patch tool call. + Text output returned by the multi-agent action. - - `call_id: str` + - `text: str` - The unique ID of the apply patch tool call generated by the model. + The text content. - - `status: Literal["completed", "failed"]` + - `type: Literal["output_text"]` - The status of the apply patch tool call output. One of `completed` or `failed`. + The content type. Always `output_text`. - - `"completed"` + - `"output_text"` - - `"failed"` + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - - `type: Literal["apply_patch_call_output"]` + Citations associated with the text content. - The type of the item. Always `apply_patch_call_output`. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - - `"apply_patch_call_output"` + - `file_id: str` - - `id: Optional[str]` + The ID of the file. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `filename: str` - - `agent: Optional[ApplyPatchCallOutputAgent]` + The filename of the file cited. - The agent that produced this item. + - `index: int` - - `agent_name: str` + The index of the file in the list of files. - The canonical name of the agent that produced this item. + - `type: Literal["file_citation"]` - - `caller: Optional[ApplyPatchCallOutputCaller]` + The citation type. Always `file_citation`. - The execution context that produced this tool call. + - `"file_citation"` - - `class ApplyPatchCallOutputCallerDirect: …` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` - - `type: Literal["direct"]` + - `end_index: int` - The caller type. Always `direct`. + The index of the last character of the citation in the message. - - `"direct"` + - `start_index: int` - - `class ApplyPatchCallOutputCallerProgram: …` + The index of the first character of the citation in the message. - - `caller_id: str` + - `title: str` - The call ID of the program item that produced this tool call. + The title of the cited resource. - - `type: Literal["program"]` + - `type: Literal["url_citation"]` - The caller type. Always `program`. + The citation type. Always `url_citation`. - - `"program"` + - `"url_citation"` - - `output: Optional[str]` + - `url: str` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The URL of the cited resource. - - `class McpListTools: …` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` - A list of tools available on an MCP server. + - `container_id: str` - - `id: str` + The ID of the container. - The unique ID of the list. + - `end_index: int` - - `server_label: str` + The index of the last character of the citation in the message. - The label of the MCP server. + - `file_id: str` - - `tools: List[McpListToolsTool]` + The ID of the container file. - The tools available on the server. + - `filename: str` - - `input_schema: object` + The filename of the container file cited. - The JSON schema describing the tool's input. + - `start_index: int` - - `name: str` + The index of the first character of the citation in the message. - The name of the tool. + - `type: Literal["container_file_citation"]` - - `annotations: Optional[object]` + The citation type. Always `container_file_citation`. - Additional annotations about the tool. + - `"container_file_citation"` - - `description: Optional[str]` + - `type: Literal["multi_agent_call_output"]` - The description of the tool. + The item type. Always `multi_agent_call_output`. - - `type: Literal["mcp_list_tools"]` + - `"multi_agent_call_output"` - The type of the item. Always `mcp_list_tools`. + - `id: Optional[str]` - - `"mcp_list_tools"` + The unique ID of this multi-agent call output. - - `agent: Optional[McpListToolsAgent]` + - `agent: Optional[MultiAgentCallOutputAgent]` The agent that produced this item. @@ -64811,37 +76075,23 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `error: Optional[str]` - - Error message if the server could not list tools. - - - `class McpApprovalRequest: …` - - A request for human approval of a tool invocation. - - - `id: str` - - The unique ID of the approval request. - - - `arguments: str` - - A JSON string of arguments for the tool. + - `class ToolSearchCall: …` - - `name: str` + - `arguments: object` - The name of the tool to run. + The arguments supplied to the tool search call. - - `server_label: str` + - `type: Literal["tool_search_call"]` - The label of the MCP server making the request. + The item type. Always `tool_search_call`. - - `type: Literal["mcp_approval_request"]` + - `"tool_search_call"` - The type of the item. Always `mcp_approval_request`. + - `id: Optional[str]` - - `"mcp_approval_request"` + The unique ID of this tool search call. - - `agent: Optional[McpApprovalRequestAgent]` + - `agent: Optional[ToolSearchCallAgent]` The agent that produced this item. @@ -64849,1106 +76099,1137 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class McpApprovalResponse: …` + - `call_id: Optional[str]` - A response to an MCP approval request. + The unique ID of the tool search call generated by the model. - - `approval_request_id: str` + - `execution: Optional[Literal["server", "client"]]` - The ID of the approval request being answered. + Whether tool search was executed by the server or by the client. - - `approve: bool` + - `"server"` - Whether the request was approved. + - `"client"` - - `type: Literal["mcp_approval_response"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The type of the item. Always `mcp_approval_response`. + The status of the tool search call. - - `"mcp_approval_response"` + - `"in_progress"` - - `id: Optional[str]` + - `"completed"` - The unique ID of the approval response + - `"incomplete"` - - `agent: Optional[McpApprovalResponseAgent]` + - `class BetaResponseToolSearchOutputItemParam: …` - The agent that produced this item. + - `tools: List[BetaTool]` - - `agent_name: str` + The loaded tool definitions returned by the tool search output. - The canonical name of the agent that produced this item. + - `class BetaFunctionTool: …` - - `reason: Optional[str]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Optional reason for the decision. + - `name: str` - - `class McpCall: …` + The name of the function to call. - An invocation of a tool on an MCP server. + - `parameters: Optional[Dict[str, object]]` - - `id: str` + A JSON schema object describing the parameters of the function. - The unique ID of the tool call. + - `strict: Optional[bool]` - - `arguments: str` + Whether strict parameter validation is enforced for this function tool. - A JSON string of the arguments passed to the tool. + - `type: Literal["function"]` - - `name: str` + The type of the function tool. Always `function`. - The name of the tool that was run. + - `"function"` - - `server_label: str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The label of the MCP server running the tool. + The tool invocation context(s). - - `type: Literal["mcp_call"]` + - `"direct"` - The type of the item. Always `mcp_call`. + - `"programmatic"` - - `"mcp_call"` + - `defer_loading: Optional[bool]` - - `agent: Optional[McpCallAgent]` + Whether this function is deferred and loaded via tool search. - The agent that produced this item. + - `description: Optional[str]` - - `agent_name: str` + A description of the function. Used by the model to determine whether or not to call the function. - The canonical name of the agent that produced this item. + - `output_schema: Optional[Dict[str, object]]` - - `approval_request_id: Optional[str]` + A JSON schema object describing the JSON value encoded in string outputs for this function. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `class BetaFileSearchTool: …` - - `error: Optional[str]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The error from the tool call, if any. + - `type: Literal["file_search"]` - - `output: Optional[str]` + The type of the file search tool. Always `file_search`. - The output from the tool call. + - `"file_search"` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `vector_store_ids: List[str]` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The IDs of the vector stores to search. - - `"in_progress"` + - `filters: Optional[Filters]` - - `"completed"` + A filter to apply. - - `"incomplete"` + - `class FiltersComparisonFilter: …` - - `"calling"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"failed"` + - `key: str` - - `class BetaResponseCustomToolCallOutput: …` + The key to compare against the value. - The output of a custom tool call from your code, being sent back to the model. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `call_id: str` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The call ID, used to map this custom tool call output to a custom tool call. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `output: Union[str, List[OutputOutputContentList]]` + - `"eq"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"ne"` - - `str` + - `"gt"` - A string of the output of the custom tool call. + - `"gte"` - - `List[OutputOutputContentList]` + - `"lt"` - Text, image, or file output of the custom tool call. + - `"lte"` - - `class BetaResponseInputText: …` + - `"in"` - A text input to the model. + - `"nin"` - - `class BetaResponseInputImage: …` + - `value: Union[str, float, bool, List[Union[str, float]]]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The value to compare against the attribute key; supports string, number, or boolean types. - - `class BetaResponseInputFile: …` + - `str` - A file input to the model. + - `float` - - `type: Literal["custom_tool_call_output"]` + - `bool` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `List[Union[str, float]]` - - `"custom_tool_call_output"` + - `str` - - `id: Optional[str]` + - `float` - The unique ID of the custom tool call output in the OpenAI platform. + - `class FiltersCompoundFilter: …` - - `agent: Optional[Agent]` + Combine multiple filters using `and` or `or`. - The agent that produced this item. + - `filters: List[FiltersCompoundFilterFilter]` - - `agent_name: str` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The canonical name of the agent that produced this item. + - `class FiltersCompoundFilterFilterComparisonFilter: …` - - `caller: Optional[Caller]` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The execution context that produced this tool call. + - `key: str` - - `class CallerDirect: …` + The key to compare against the value. - - `type: Literal["direct"]` + - `type: Literal["eq", "ne", "gt", 5 more]` - The caller type. Always `direct`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"direct"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `class CallerProgram: …` + - `"eq"` - - `caller_id: str` + - `"ne"` - The call ID of the program item that produced this tool call. + - `"gt"` - - `type: Literal["program"]` + - `"gte"` - The caller type. Always `program`. + - `"lt"` - - `"program"` + - `"lte"` - - `class BetaResponseCustomToolCall: …` + - `"in"` - A call to a custom tool created by the model. + - `"nin"` - - `call_id: str` + - `value: Union[str, float, bool, List[Union[str, float]]]` - An identifier used to map this custom tool call to a tool call output. + The value to compare against the attribute key; supports string, number, or boolean types. - - `input: str` + - `str` - The input for the custom tool call generated by the model. + - `float` - - `name: str` + - `bool` - The name of the custom tool being called. + - `List[Union[str, float]]` - - `type: Literal["custom_tool_call"]` + - `str` - The type of the custom tool call. Always `custom_tool_call`. + - `float` - - `"custom_tool_call"` + - `object` - - `id: Optional[str]` + - `type: Literal["and", "or"]` - The unique ID of the custom tool call in the OpenAI platform. + Type of operation: `and` or `or`. - - `agent: Optional[Agent]` + - `"and"` - The agent that produced this item. + - `"or"` - - `agent_name: str` + - `max_num_results: Optional[int]` - The canonical name of the agent that produced this item. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `caller: Optional[Caller]` + - `ranking_options: Optional[RankingOptions]` - The execution context that produced this tool call. + Ranking options for search. - - `class CallerDirect: …` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - `type: Literal["direct"]` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"direct"` + - `embedding_weight: float` - - `class CallerProgram: …` + The weight of the embedding in the reciprocal ranking fusion. - - `caller_id: str` + - `text_weight: float` - The call ID of the program item that produced this tool call. + The weight of the text in the reciprocal ranking fusion. - - `type: Literal["program"]` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - - `"program"` + The ranker to use for the file search. - - `namespace: Optional[str]` + - `"auto"` - The namespace of the custom tool being called. + - `"default-2024-11-15"` - - `class CompactionTrigger: …` + - `score_threshold: Optional[float]` - Compacts the current context. Must be the final input item. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `type: Literal["compaction_trigger"]` + - `class BetaComputerTool: …` - The type of the item. Always `compaction_trigger`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"compaction_trigger"` + - `type: Literal["computer"]` - - `agent: Optional[CompactionTriggerAgent]` + The type of the computer tool. Always `computer`. - The agent that produced this item. + - `"computer"` - - `agent_name: str` + - `class BetaComputerUsePreviewTool: …` - The canonical name of the agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class ItemReference: …` + - `display_height: int` - An internal identifier for an item to reference. + The height of the computer display. - - `id: str` + - `display_width: int` - The ID of the item to reference. + The width of the computer display. - - `agent: Optional[ItemReferenceAgent]` + - `environment: Literal["windows", "mac", "linux", 2 more]` - The agent that produced this item. + The type of computer environment to control. - - `agent_name: str` + - `"windows"` - The canonical name of the agent that produced this item. + - `"mac"` - - `type: Optional[Literal["item_reference"]]` + - `"linux"` - The type of item to reference. Always `item_reference`. + - `"ubuntu"` - - `"item_reference"` + - `"browser"` - - `class Program: …` + - `type: Literal["computer_use_preview"]` - - `id: str` + The type of the computer use tool. Always `computer_use_preview`. - The unique ID of this program item. + - `"computer_use_preview"` - - `call_id: str` + - `class BetaWebSearchTool: …` - The stable call ID of the program item. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `code: str` + - `type: Literal["web_search", "web_search_2025_08_26"]` - The JavaScript source executed by programmatic tool calling. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `fingerprint: str` + - `"web_search"` - Opaque program replay fingerprint that must be round-tripped. + - `"web_search_2025_08_26"` - - `type: Literal["program"]` + - `filters: Optional[Filters]` - The item type. Always `program`. + Filters for the search. - - `"program"` + - `allowed_domains: Optional[List[str]]` - - `agent: Optional[ProgramAgent]` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The agent that produced this item. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `agent_name: str` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The canonical name of the agent that produced this item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `class ProgramOutput: …` + - `"low"` - - `id: str` + - `"medium"` - The unique ID of this program output item. + - `"high"` - - `call_id: str` + - `user_location: Optional[UserLocation]` - The call ID of the program item. + The approximate location of the user. - - `result: str` + - `city: Optional[str]` - The result produced by the program item. + Free text input for the city of the user, e.g. `San Francisco`. - - `status: Literal["completed", "incomplete"]` + - `country: Optional[str]` - The terminal status of the program output. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"completed"` + - `region: Optional[str]` - - `"incomplete"` + Free text input for the region of the user, e.g. `California`. - - `type: Literal["program_output"]` + - `timezone: Optional[str]` - The item type. Always `program_output`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"program_output"` + - `type: Optional[Literal["approximate"]]` - - `agent: Optional[ProgramOutputAgent]` + The type of location approximation. Always `approximate`. - The agent that produced this item. + - `"approximate"` - - `agent_name: str` + - `class Mcp: …` - The canonical name of the agent that produced this item. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `metadata: Optional[Dict[str, str]]` + - `server_label: str` - 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. + A label for this MCP server, used to identify it in tool calls. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: Literal["mcp"]` - - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` + The type of the MCP tool. Always `mcp`. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `"mcp"` - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + The tool invocation context(s). - - `"gpt-5.6-sol"` + - `"direct"` - - `"gpt-5.6-terra"` + - `"programmatic"` - - `"gpt-5.6-luna"` + - `allowed_tools: Optional[McpAllowedTools]` - - `"gpt-5.4"` + List of allowed tool names or a filter object. - - `"gpt-5.4-mini"` + - `List[str]` - - `"gpt-5.4-nano"` + A string array of allowed tool names - - `"gpt-5.4-mini-2026-03-17"` + - `class McpAllowedToolsMcpToolFilter: …` - - `"gpt-5.4-nano-2026-03-17"` + A filter object to specify which tools are allowed. - - `"gpt-5.3-chat-latest"` + - `read_only: Optional[bool]` - - `"gpt-5.2"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"gpt-5.2-2025-12-11"` + - `tool_names: Optional[List[str]]` - - `"gpt-5.2-chat-latest"` + List of allowed tool names. - - `"gpt-5.2-pro"` + - `authorization: Optional[str]` - - `"gpt-5.2-pro-2025-12-11"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `"gpt-5.1"` + Currently supported `connector_id` values are: - - `"gpt-5.1-2025-11-13"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `"gpt-5.1-codex"` + - `"connector_dropbox"` - - `"gpt-5.1-mini"` + - `"connector_gmail"` - - `"gpt-5.1-chat-latest"` + - `"connector_googlecalendar"` - - `"gpt-5"` + - `"connector_googledrive"` - - `"gpt-5-mini"` + - `"connector_microsoftteams"` - - `"gpt-5-nano"` + - `"connector_outlookcalendar"` - - `"gpt-5-2025-08-07"` + - `"connector_outlookemail"` - - `"gpt-5-mini-2025-08-07"` + - `"connector_sharepoint"` - - `"gpt-5-nano-2025-08-07"` + - `defer_loading: Optional[bool]` - - `"gpt-5-chat-latest"` + Whether this MCP tool is deferred and discovered via tool search. - - `"gpt-4.1"` + - `headers: Optional[Dict[str, str]]` - - `"gpt-4.1-mini"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"gpt-4.1-nano"` + - `require_approval: Optional[McpRequireApproval]` - - `"gpt-4.1-2025-04-14"` + Specify which of the MCP server's tools require approval. - - `"gpt-4.1-mini-2025-04-14"` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - - `"gpt-4.1-nano-2025-04-14"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"o4-mini"` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `"o4-mini-2025-04-16"` + A filter object to specify which tools are allowed. - - `"o3"` + - `read_only: Optional[bool]` - - `"o3-2025-04-16"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"o3-mini"` + - `tool_names: Optional[List[str]]` - - `"o3-mini-2025-01-31"` + List of allowed tool names. - - `"o1"` + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - - `"o1-2024-12-17"` + A filter object to specify which tools are allowed. - - `"o1-preview"` + - `read_only: Optional[bool]` - - `"o1-preview-2024-09-12"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"o1-mini"` + - `tool_names: Optional[List[str]]` - - `"o1-mini-2024-09-12"` + List of allowed tool names. - - `"gpt-4o"` + - `Literal["always", "never"]` - - `"gpt-4o-2024-11-20"` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `"gpt-4o-2024-08-06"` + - `"always"` - - `"gpt-4o-2024-05-13"` + - `"never"` - - `"gpt-4o-audio-preview"` + - `server_description: Optional[str]` - - `"gpt-4o-audio-preview-2024-10-01"` + Optional description of the MCP server, used to provide more context. - - `"gpt-4o-audio-preview-2024-12-17"` + - `server_url: Optional[str]` - - `"gpt-4o-audio-preview-2025-06-03"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"gpt-4o-mini-audio-preview"` + - `tunnel_id: Optional[str]` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `"gpt-4o-search-preview"` + - `class CodeInterpreter: …` - - `"gpt-4o-mini-search-preview"` + A tool that runs Python code to help generate a response to a prompt. - - `"gpt-4o-search-preview-2025-03-11"` + - `container: CodeInterpreterContainer` - - `"gpt-4o-mini-search-preview-2025-03-11"` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `"chatgpt-4o-latest"` + - `str` - - `"codex-mini-latest"` + The container ID. - - `"gpt-4o-mini"` + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `"gpt-4o-mini-2024-07-18"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"gpt-4-turbo"` + - `type: Literal["auto"]` - - `"gpt-4-turbo-2024-04-09"` + Always `auto`. - - `"gpt-4-0125-preview"` + - `"auto"` - - `"gpt-4-turbo-preview"` + - `file_ids: Optional[List[str]]` - - `"gpt-4-1106-preview"` + An optional list of uploaded files to make available to your code. - - `"gpt-4-vision-preview"` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `"gpt-4"` + The memory limit for the code interpreter container. - - `"gpt-4-0314"` + - `"1g"` - - `"gpt-4-0613"` + - `"4g"` - - `"gpt-4-32k"` + - `"16g"` - - `"gpt-4-32k-0314"` + - `"64g"` - - `"gpt-4-32k-0613"` + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - - `"gpt-3.5-turbo"` + Network access policy for the container. - - `"gpt-3.5-turbo-16k"` + - `class BetaContainerNetworkPolicyDisabled: …` - - `"gpt-3.5-turbo-0301"` + - `type: Literal["disabled"]` - - `"gpt-3.5-turbo-0613"` + Disable outbound network access. Always `disabled`. - - `"gpt-3.5-turbo-1106"` + - `"disabled"` - - `"gpt-3.5-turbo-0125"` + - `class BetaContainerNetworkPolicyAllowlist: …` - - `"gpt-3.5-turbo-16k-0613"` + - `allowed_domains: List[str]` - - `"o1-pro"` + A list of allowed domains when type is `allowlist`. - - `"o1-pro-2025-03-19"` + - `type: Literal["allowlist"]` - - `"o3-pro"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"o3-pro-2025-06-10"` + - `"allowlist"` - - `"o3-deep-research"` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `"o3-deep-research-2025-06-26"` + Optional domain-scoped secrets for allowlisted domains. - - `"o4-mini-deep-research"` + - `domain: str` - - `"o4-mini-deep-research-2025-06-26"` + The domain associated with the secret. - - `"computer-use-preview"` + - `name: str` - - `"computer-use-preview-2025-03-11"` + The name of the secret to inject for the domain. - - `"gpt-5-codex"` + - `value: str` - - `"gpt-5-pro"` + The secret value to inject for the domain. - - `"gpt-5-pro-2025-10-06"` + - `type: Literal["code_interpreter"]` - - `"gpt-5.1-codex-max"` + The type of the code interpreter tool. Always `code_interpreter`. - - `str` + - `"code_interpreter"` - - `object: Literal["response"]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The object type of this resource - always set to `response`. + The tool invocation context(s). - - `"response"` + - `"direct"` - - `output: List[BetaResponseOutputItem]` + - `"programmatic"` - An array of content items generated by the model. + - `class ProgrammaticToolCalling: …` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `type: Literal["programmatic_tool_calling"]` - - `class BetaResponseOutputMessage: …` + The type of the tool. Always `programmatic_tool_calling`. - An output message from the model. + - `"programmatic_tool_calling"` - - `class BetaResponseFileSearchToolCall: …` + - `class ImageGeneration: …` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + A tool that generates images using the GPT image models. - - `class BetaResponseFunctionToolCall: …` + - `type: Literal["image_generation"]` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The type of the image generation tool. Always `image_generation`. - - `class BetaResponseFunctionToolCallOutputItem: …` + - `"image_generation"` - - `id: str` + - `action: Optional[Literal["generate", "edit", "auto"]]` - The unique ID of the function call tool output. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `call_id: str` + - `"generate"` - The unique ID of the function tool call generated by the model. + - `"edit"` - - `output: Union[str, List[OutputOutputContentList]]` + - `"auto"` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `str` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - A string of the output of the function call. + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `List[OutputOutputContentList]` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - Text, image, or file output of the function call. + - `"transparent"` - - `class BetaResponseInputText: …` + - `"opaque"` - A text input to the model. + - `"auto"` - - `class BetaResponseInputImage: …` + - `input_fidelity: Optional[Literal["high", "low"]]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `class BetaResponseInputFile: …` + - `"high"` - A file input to the model. + - `"low"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"in_progress"` + - `file_id: Optional[str]` - - `"completed"` + File ID for the mask image. - - `"incomplete"` + - `image_url: Optional[str]` - - `type: Literal["function_call_output"]` + Base64-encoded mask image. - The type of the function tool call output. Always `function_call_output`. + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - - `"function_call_output"` + The image generation model to use. Default: `gpt-image-1`. - - `agent: Optional[Agent]` + - `str` - The agent that produced this item. + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `agent_name: str` + The image generation model to use. Default: `gpt-image-1`. - The canonical name of the agent that produced this item. + - `"gpt-image-1"` - - `caller: Optional[Caller]` + - `"gpt-image-1-mini"` - The execution context that produced this tool call. + - `"gpt-image-2"` - - `class CallerDirect: …` + - `"gpt-image-2-2026-04-21"` - - `type: Literal["direct"]` + - `"gpt-image-1.5"` - The caller type. Always `direct`. + - `"chatgpt-image-latest"` - - `"direct"` + - `moderation: Optional[Literal["auto", "low"]]` - - `class CallerProgram: …` + Moderation level for the generated image. Default: `auto`. - - `caller_id: str` + - `"auto"` - The call ID of the program item that produced this tool call. + - `"low"` - - `type: Literal["program"]` + - `output_compression: Optional[int]` - The caller type. Always `program`. + Compression level for the output image. Default: 100. - - `"program"` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `created_by: Optional[str]` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The identifier of the actor that created the item. + - `"png"` - - `class AgentMessage: …` + - `"webp"` - - `id: str` + - `"jpeg"` - The unique ID of the agent message. + - `partial_images: Optional[int]` - - `author: str` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The sending agent identity. + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - - `content: List[AgentMessageContent]` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Encrypted content sent between agents. + - `"low"` - - `class BetaResponseInputText: …` + - `"medium"` - A text input to the model. + - `"high"` - - `class BetaResponseOutputText: …` + - `"auto"` - A text output from the model. + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - - `class AgentMessageContentText: …` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - A text content. + - `str` - - `text: str` + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `type: Literal["text"]` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `"text"` + - `"1024x1024"` - - `class AgentMessageContentSummaryText: …` + - `"1024x1536"` - A summary text from the model. + - `"1536x1024"` - - `text: str` + - `"auto"` - A summary of the reasoning output from the model so far. + - `class LocalShell: …` - - `type: Literal["summary_text"]` + A tool that allows the model to execute shell commands in a local environment. - The type of the object. Always `summary_text`. + - `type: Literal["local_shell"]` - - `"summary_text"` + The type of the local shell tool. Always `local_shell`. - - `class AgentMessageContentReasoningText: …` + - `"local_shell"` - Reasoning text from the model. + - `class BetaFunctionShellTool: …` - - `text: str` + A tool that allows the model to execute shell commands. - The reasoning text from the model. + - `type: Literal["shell"]` - - `type: Literal["reasoning_text"]` + The type of the shell tool. Always `shell`. - The type of the reasoning text. Always `reasoning_text`. + - `"shell"` - - `"reasoning_text"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `class BetaResponseOutputRefusal: …` + The tool invocation context(s). - A refusal from the model. + - `"direct"` - - `class BetaResponseInputImage: …` + - `"programmatic"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `environment: Optional[Environment]` - - `class AgentMessageContentComputerScreenshot: …` + - `class BetaContainerAuto: …` - A screenshot of a computer. + - `type: Literal["container_auto"]` - - `detail: Literal["low", "high", "auto", "original"]` + Automatically creates a container for this request - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"container_auto"` - - `"low"` + - `file_ids: Optional[List[str]]` - - `"high"` + An optional list of uploaded files to make available to your code. - - `"auto"` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `"original"` + The memory limit for the container. - - `file_id: Optional[str]` + - `"1g"` - The identifier of an uploaded file that contains the screenshot. + - `"4g"` - - `image_url: Optional[str]` + - `"16g"` - The URL of the screenshot image. + - `"64g"` - - `type: Literal["computer_screenshot"]` + - `network_policy: Optional[NetworkPolicy]` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Network access policy for the container. - - `"computer_screenshot"` + - `class BetaContainerNetworkPolicyDisabled: …` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `class BetaContainerNetworkPolicyAllowlist: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `skills: Optional[List[Skill]]` - - `mode: Literal["explicit"]` + An optional list of skills referenced by id or inline data. - The breakpoint mode. Always `explicit`. + - `class BetaSkillReference: …` - - `"explicit"` + - `skill_id: str` - - `class BetaResponseInputFile: …` + The ID of the referenced skill. - A file input to the model. + - `type: Literal["skill_reference"]` - - `class AgentMessageContentEncryptedContent: …` + References a skill created with the /v1/skills endpoint. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"skill_reference"` - - `encrypted_content: str` + - `version: Optional[str]` - Opaque encrypted content. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `type: Literal["encrypted_content"]` + - `class BetaInlineSkill: …` - The type of the input item. Always `encrypted_content`. + - `description: str` - - `"encrypted_content"` + The description of the skill. - - `recipient: str` + - `name: str` - The destination agent identity. + The name of the skill. - - `type: Literal["agent_message"]` + - `source: BetaInlineSkillSource` - The type of the item. Always `agent_message`. + Inline skill payload - - `"agent_message"` + - `data: str` - - `agent: Optional[AgentMessageAgent]` + Base64-encoded skill zip bundle. - The agent that produced this item. + - `media_type: Literal["application/zip"]` - - `agent_name: str` + The media type of the inline skill payload. Must be `application/zip`. - The canonical name of the agent that produced this item. + - `"application/zip"` - - `class MultiAgentCall: …` + - `type: Literal["base64"]` - - `id: str` + The type of the inline skill source. Must be `base64`. - The unique ID of the multi-agent call item. + - `"base64"` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `type: Literal["inline"]` - The multi-agent action to execute. + Defines an inline skill for this request. - - `"spawn_agent"` + - `"inline"` - - `"interrupt_agent"` + - `class BetaLocalEnvironment: …` - - `"list_agents"` + - `type: Literal["local"]` - - `"send_message"` + Use a local computer environment. - - `"followup_task"` + - `"local"` - - `"wait_agent"` + - `skills: Optional[List[BetaLocalSkill]]` - - `arguments: str` + An optional list of skills. - The JSON string of arguments generated for the action. + - `description: str` - - `call_id: str` + The description of the skill. - The unique ID linking this call to its output. + - `name: str` - - `type: Literal["multi_agent_call"]` + The name of the skill. - The type of the multi-agent call. Always `multi_agent_call`. + - `path: str` - - `"multi_agent_call"` + The path to the directory containing the skill. - - `agent: Optional[MultiAgentCallAgent]` + - `class BetaContainerReference: …` - The agent that produced this item. + - `container_id: str` - - `agent_name: str` + The ID of the referenced container. - The canonical name of the agent that produced this item. + - `type: Literal["container_reference"]` - - `class MultiAgentCallOutput: …` + References a container created with the /v1/containers endpoint - - `id: str` + - `"container_reference"` - The unique ID of the multi-agent call output item. + - `class BetaCustomTool: …` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The multi-agent action that produced this result. + - `name: str` - - `"spawn_agent"` + The name of the custom tool, used to identify it in tool calls. - - `"interrupt_agent"` + - `type: Literal["custom"]` - - `"list_agents"` + The type of the custom tool. Always `custom`. - - `"send_message"` + - `"custom"` - - `"followup_task"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"wait_agent"` + The tool invocation context(s). - - `call_id: str` + - `"direct"` - The unique ID of the multi-agent call. + - `"programmatic"` - - `output: List[BetaResponseOutputText]` + - `defer_loading: Optional[bool]` - Text output returned by the multi-agent action. + Whether this tool should be deferred and discovered via tool search. - - `annotations: List[Annotation]` + - `description: Optional[str]` - The annotations of the text output. + Optional description of the custom tool, used to provide more context. - - `text: str` + - `format: Optional[Format]` - The text output from the model. + The input format for the custom tool. Default is unconstrained text. - - `type: Literal["output_text"]` + - `class FormatText: …` - The type of the output text. Always `output_text`. + Unconstrained free-form text. - - `logprobs: Optional[List[Logprob]]` + - `type: Literal["text"]` - - `type: Literal["multi_agent_call_output"]` + Unconstrained text format. Always `text`. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"text"` - - `"multi_agent_call_output"` + - `class FormatGrammar: …` - - `agent: Optional[MultiAgentCallOutputAgent]` + A grammar defined by the user. - The agent that produced this item. + - `definition: str` - - `agent_name: str` + The grammar definition. - The canonical name of the agent that produced this item. + - `syntax: Literal["lark", "regex"]` - - `class BetaResponseFunctionWebSearch: …` + The syntax of the grammar definition. One of `lark` or `regex`. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `"lark"` - - `class BetaResponseComputerToolCall: …` + - `"regex"` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `type: Literal["grammar"]` - - `class BetaResponseComputerToolCallOutputItem: …` + Grammar format. Always `grammar`. - - `id: str` + - `"grammar"` - The unique ID of the computer call tool output. + - `class BetaNamespaceTool: …` - - `call_id: str` + Groups function/custom tools under a shared namespace. - The ID of the computer tool call that produced the output. + - `description: str` - - `output: BetaResponseComputerToolCallOutputScreenshot` + A description of the namespace shown to the model. - A computer screenshot image used with the computer use tool. + - `name: str` - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + The namespace name used in tool calls (for example, `crm`). - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `tools: List[Tool]` - - `"completed"` + The function/custom tools available inside this namespace. - - `"incomplete"` + - `class ToolFunction: …` - - `"failed"` + - `name: str` - - `"in_progress"` + - `type: Literal["function"]` - - `type: Literal["computer_call_output"]` + - `"function"` - The type of the computer tool call output. Always `computer_call_output`. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"computer_call_output"` + The tool invocation context(s). - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + - `"direct"` - The safety checks reported by the API that have been acknowledged by the - developer. + - `"programmatic"` - - `id: str` + - `defer_loading: Optional[bool]` - The ID of the pending safety check. + Whether this function should be deferred and discovered via tool search. - - `code: Optional[str]` + - `description: Optional[str]` - The type of the pending safety check. + - `output_schema: Optional[Dict[str, object]]` - - `message: Optional[str]` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Details about the pending safety check. + - `parameters: Optional[object]` - - `agent: Optional[Agent]` + - `strict: Optional[bool]` - The agent that produced this item. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `agent_name: str` + - `class BetaCustomTool: …` - The canonical name of the agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `created_by: Optional[str]` + - `type: Literal["namespace"]` - The identifier of the actor that created the item. + The type of the tool. Always `namespace`. - - `class BetaResponseReasoningItem: …` + - `"namespace"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class BetaToolSearchTool: …` - - `class Program: …` + Hosted or BYOT tool search configuration for deferred tools. - - `id: str` + - `type: Literal["tool_search"]` - The unique ID of the program item. + The type of the tool. Always `tool_search`. - - `call_id: str` + - `"tool_search"` - The stable call ID of the program item. + - `description: Optional[str]` - - `code: str` + Description shown to the model for a client-executed tool search tool. - The JavaScript source executed by programmatic tool calling. + - `execution: Optional[Literal["server", "client"]]` - - `fingerprint: str` + Whether tool search is executed by the server or by the client. - Opaque program replay fingerprint that must be round-tripped. + - `"server"` - - `type: Literal["program"]` + - `"client"` - The type of the item. Always `program`. + - `parameters: Optional[object]` - - `"program"` + Parameter schema for a client-executed tool search tool. - - `agent: Optional[ProgramAgent]` + - `class BetaWebSearchPreviewTool: …` - The agent that produced this item. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `agent_name: str` + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - The canonical name of the agent that produced this item. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `class ProgramOutput: …` + - `"web_search_preview"` - - `id: str` + - `"web_search_preview_2025_03_11"` - The unique ID of the program output item. + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `call_id: str` + - `"text"` - The call ID of the program item. + - `"image"` - - `result: str` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The result produced by the program item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `status: Literal["completed", "incomplete"]` + - `"low"` - The terminal status of the program output item. + - `"medium"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `user_location: Optional[UserLocation]` - - `type: Literal["program_output"]` + The user's location. - The type of the item. Always `program_output`. + - `type: Literal["approximate"]` - - `"program_output"` + The type of location approximation. Always `approximate`. - - `agent: Optional[ProgramOutputAgent]` + - `"approximate"` - The agent that produced this item. + - `city: Optional[str]` - - `agent_name: str` + Free text input for the city of the user, e.g. `San Francisco`. - The canonical name of the agent that produced this item. + - `country: Optional[str]` - - `class BetaResponseToolSearchCall: …` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `id: str` + - `region: Optional[str]` - The unique ID of the tool search call item. + Free text input for the region of the user, e.g. `California`. - - `arguments: object` + - `timezone: Optional[str]` - Arguments used for the tool search call. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `call_id: Optional[str]` + - `class BetaApplyPatchTool: …` - The unique ID of the tool search call generated by the model. + Allows the assistant to create, delete, or update files using unified diffs. - - `execution: Literal["server", "client"]` + - `type: Literal["apply_patch"]` - Whether tool search was executed by the server or by the client. + The type of the tool. Always `apply_patch`. - - `"server"` + - `"apply_patch"` - - `"client"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `status: Literal["in_progress", "completed", "incomplete"]` + The tool invocation context(s). - The status of the tool search call item that was recorded. + - `"direct"` - - `"in_progress"` + - `"programmatic"` - - `"completed"` + - `type: Literal["tool_search_output"]` - - `"incomplete"` + The item type. Always `tool_search_output`. - - `type: Literal["tool_search_call"]` + - `"tool_search_output"` - The type of the item. Always `tool_search_call`. + - `id: Optional[str]` - - `"tool_search_call"` + The unique ID of this tool search output. - `agent: Optional[Agent]` @@ -65958,21 +77239,11 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `class BetaResponseToolSearchOutputItem: …` - - - `id: str` - - The unique ID of the tool search output item. - - `call_id: Optional[str]` The unique ID of the tool search call generated by the model. - - `execution: Literal["server", "client"]` + - `execution: Optional[Literal["server", "client"]]` Whether tool search was executed by the server or by the client. @@ -65980,9 +77251,9 @@ print(compacted_response) - `"client"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the tool search output item that was recorded. + The status of the tool search output. - `"in_progress"` @@ -65990,9 +77261,17 @@ print(compacted_response) - `"incomplete"` + - `class AdditionalTools: …` + + - `role: Literal["developer"]` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + - `tools: List[BetaTool]` - The loaded tool definitions returned by tool search. + A list of additional tools made available at this item. - `class BetaFunctionTool: …` @@ -66058,13 +77337,17 @@ print(compacted_response) Allows the assistant to create, delete, or update files using unified diffs. - - `type: Literal["tool_search_output"]` + - `type: Literal["additional_tools"]` - The type of the item. Always `tool_search_output`. + The item type. Always `additional_tools`. - - `"tool_search_output"` + - `"additional_tools"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of this additional tools item. + + - `agent: Optional[AdditionalToolsAgent]` The agent that produced this item. @@ -66072,111 +77355,132 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. + - `class BetaResponseReasoningItem: …` - - `class AdditionalTools: …` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: str` - The unique ID of the additional tools item. + The unique identifier of the reasoning content. - - `role: Literal["unknown", "user", "assistant", 5 more]` + - `summary: List[Summary]` - The role that provided the additional tools. + Reasoning summary content. - - `"unknown"` + - `text: str` - - `"user"` + A summary of the reasoning output from the model so far. - - `"assistant"` + - `type: Literal["summary_text"]` - - `"system"` + The type of the object. Always `summary_text`. - - `"critic"` + - `"summary_text"` - - `"discriminator"` + - `type: Literal["reasoning"]` - - `"developer"` + The type of the object. Always `reasoning`. - - `"tool"` + - `"reasoning"` - - `tools: List[BetaTool]` + - `agent: Optional[Agent]` - The additional tool definitions made available at this item. + The agent that produced this item. - - `class BetaFunctionTool: …` + - `agent_name: str` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The canonical name of the agent that produced this item. - - `class BetaFileSearchTool: …` + - `content: Optional[List[Content]]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + Reasoning text content. - - `class BetaComputerTool: …` + - `text: str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The reasoning text from the model. - - `class BetaComputerUsePreviewTool: …` + - `type: Literal["reasoning_text"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the reasoning text. Always `reasoning_text`. - - `class BetaWebSearchTool: …` + - `"reasoning_text"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `encrypted_content: Optional[str]` - - `class Mcp: …` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `class CodeInterpreter: …` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A tool that runs Python code to help generate a response to a prompt. + - `"in_progress"` - - `class ProgrammaticToolCalling: …` + - `"completed"` - - `class ImageGeneration: …` + - `"incomplete"` - A tool that generates images using the GPT image models. + - `class BetaResponseCompactionItemParam: …` - - `class LocalShell: …` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - A tool that allows the model to execute shell commands in a local environment. + - `encrypted_content: str` - - `class BetaFunctionShellTool: …` + The encrypted content of the compaction summary. - A tool that allows the model to execute shell commands. + - `type: Literal["compaction"]` - - `class BetaCustomTool: …` + The type of the item. Always `compaction`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"compaction"` - - `class BetaNamespaceTool: …` + - `id: Optional[str]` - Groups function/custom tools under a shared namespace. + The ID of the compaction item. - - `class BetaToolSearchTool: …` + - `agent: Optional[Agent]` - Hosted or BYOT tool search configuration for deferred tools. + The agent that produced this item. - - `class BetaWebSearchPreviewTool: …` + - `agent_name: str` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The canonical name of the agent that produced this item. - - `class BetaApplyPatchTool: …` + - `class ImageGenerationCall: …` - Allows the assistant to create, delete, or update files using unified diffs. + An image generation request made by the model. - - `type: Literal["additional_tools"]` + - `id: str` - The type of the item. Always `additional_tools`. + The unique ID of the image generation call. - - `"additional_tools"` + - `result: Optional[str]` - - `agent: Optional[AdditionalToolsAgent]` + The generated image encoded in base64. + + - `status: Literal["in_progress", "completed", "generating", "failed"]` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: Literal["image_generation_call"]` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `agent: Optional[ImageGenerationCallAgent]` The agent that produced this item. @@ -66184,67 +77488,76 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem: …` + - `class BetaResponseCodeInterpreterToolCall: …` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A tool call to run code. - `id: str` - The unique ID of the compaction item. + The unique ID of the code interpreter tool call. - - `encrypted_content: str` + - `code: Optional[str]` - The encrypted content that was produced by compaction. + The code to run, or null if not available. - - `type: Literal["compaction"]` + - `container_id: str` - The type of the item. Always `compaction`. + The ID of the container used to run the code. - - `"compaction"` + - `outputs: Optional[List[Output]]` - - `agent: Optional[Agent]` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The agent that produced this item. + - `class OutputLogs: …` - - `agent_name: str` + The logs output from the code interpreter. - The canonical name of the agent that produced this item. + - `logs: str` - - `created_by: Optional[str]` + The logs output from the code interpreter. - The identifier of the actor that created the item. + - `type: Literal["logs"]` - - `class ImageGenerationCall: …` + The type of the output. Always `logs`. - An image generation request made by the model. + - `"logs"` - - `id: str` + - `class OutputImage: …` - The unique ID of the image generation call. + The image output from the code interpreter. - - `result: Optional[str]` + - `type: Literal["image"]` - The generated image encoded in base64. + The type of the output. Always `image`. - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `"image"` - The status of the image generation call. + - `url: str` + + The URL of the image output from the code interpreter. + + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `"in_progress"` - `"completed"` - - `"generating"` + - `"incomplete"` + + - `"interpreting"` - `"failed"` - - `type: Literal["image_generation_call"]` + - `type: Literal["code_interpreter_call"]` - The type of the image generation call. Always `image_generation_call`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"image_generation_call"` + - `"code_interpreter_call"` - - `agent: Optional[ImageGenerationCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -66252,10 +77565,6 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall: …` - - A tool call to run code. - - `class LocalShellCall: …` A tool call to run a command on the local shell. @@ -66358,67 +77667,29 @@ print(compacted_response) - `"incomplete"` - - `class BetaResponseFunctionShellToolCall: …` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: str` - - The unique ID of the shell tool call. Populated when this item is returned via API. - - - `action: Action` - - The shell commands and limits that describe how to run the tool call. - - - `commands: List[str]` - - - `max_output_length: Optional[int]` - - Optional maximum number of characters to return from each command. - - - `timeout_ms: Optional[int]` - - Optional timeout in milliseconds for the commands. - - - `call_id: str` - - The unique ID of the shell tool call generated by the model. - - - `environment: Optional[Environment]` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment: …` - - Represents the use of a local environment to perform shell actions. - - - `type: Literal["local"]` - - The environment type. Always `local`. - - - `"local"` + - `class ShellCall: …` - - `class BetaResponseContainerReference: …` + A tool representing a request to execute one or more shell commands. - Represents a container created with /v1/containers. + - `action: ShellCallAction` - - `container_id: str` + The shell commands and limits that describe how to run the tool call. - - `type: Literal["container_reference"]` + - `commands: List[str]` - The environment type. Always `container_reference`. + Ordered shell commands for the execution environment to run. - - `"container_reference"` + - `max_output_length: Optional[int]` - - `status: Literal["in_progress", "completed", "incomplete"]` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `timeout_ms: Optional[int]` - - `"in_progress"` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `"completed"` + - `call_id: str` - - `"incomplete"` + The unique ID of the shell tool call generated by the model. - `type: Literal["shell_call"]` @@ -66426,7 +77697,11 @@ print(compacted_response) - `"shell_call"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: Optional[ShellCallAgent]` The agent that produced this item. @@ -66434,17 +77709,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ShellCallCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ShellCallCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ShellCallCallerProgram: …` - `caller_id: str` @@ -66452,37 +77729,45 @@ print(compacted_response) - `type: Literal["program"]` + The caller type. Always `program`. + - `"program"` - - `created_by: Optional[str]` + - `environment: Optional[ShellCallEnvironment]` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `class BetaResponseFunctionShellToolCallOutput: …` + - `class BetaLocalEnvironment: …` - The output of a shell tool call that was emitted. + - `class BetaContainerReference: …` - - `id: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The unique ID of the shell call output. Populated when this item is returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `call_id: str` + - `"in_progress"` - The unique ID of the shell tool call generated by the model. + - `"completed"` - - `max_output_length: Optional[int]` + - `"incomplete"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `class ShellCallOutput: …` - - `output: List[Output]` + The streamed output items emitted by a shell tool call. - An array of shell call output contents + - `call_id: str` - - `outcome: OutputOutcome` + The unique ID of the shell tool call generated by the model. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `output: List[BetaResponseFunctionShellCallOutputContent]` - - `class OutputOutcomeTimeout: …` + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: Outcome` + + The exit or timeout outcome associated with this shell call. + + - `class OutcomeTimeout: …` Indicates that the shell call exceeded its configured time limit. @@ -66492,13 +77777,13 @@ print(compacted_response) - `"timeout"` - - `class OutputOutcomeExit: …` + - `class OutcomeExit: …` Indicates that the shell commands finished and returned an exit code. - `exit_code: int` - Exit code from the shell process. + The exit code returned by the shell process. - `type: Literal["exit"]` @@ -66508,33 +77793,23 @@ print(compacted_response) - `stderr: str` - The standard error output that was captured. + Captured stderr output for the shell call. - `stdout: str` - The standard output that was captured. - - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` + Captured stdout output for the shell call. - `type: Literal["shell_call_output"]` - The type of the shell call output. Always `shell_call_output`. + The type of the item. Always `shell_call_output`. - `"shell_call_output"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: Optional[ShellCallOutputAgent]` The agent that produced this item. @@ -66542,17 +77817,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ShellCallOutputCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ShellCallOutputCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ShellCallOutputCallerProgram: …` - `caller_id: str` @@ -66560,75 +77837,83 @@ print(compacted_response) - `type: Literal["program"]` + The caller type. Always `program`. + - `"program"` - - `created_by: Optional[str]` + - `max_output_length: Optional[int]` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseApplyPatchToolCall: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A tool call that applies file diffs by creating, deleting, or updating files. + The status of the shell call output. - - `id: str` + - `"in_progress"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"completed"` + + - `"incomplete"` + + - `class ApplyPatchCall: …` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: str` The unique ID of the apply patch tool call generated by the model. - - `operation: Operation` + - `operation: ApplyPatchCallOperation` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - - `class OperationCreateFile: …` + - `class ApplyPatchCallOperationCreateFile: …` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `diff: str` - Diff to apply. + Unified diff content to apply when creating the file. - `path: str` - Path of the file to create. + Path of the file to create relative to the workspace root. - `type: Literal["create_file"]` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `"create_file"` - - `class OperationDeleteFile: …` + - `class ApplyPatchCallOperationDeleteFile: …` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `path: str` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `type: Literal["delete_file"]` - Delete the specified file. + The operation type. Always `delete_file`. - `"delete_file"` - - `class OperationUpdateFile: …` + - `class ApplyPatchCallOperationUpdateFile: …` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `diff: str` - Diff to apply. + Unified diff content to apply to the existing file. - `path: str` - Path of the file to update. + Path of the file to update relative to the workspace root. - `type: Literal["update_file"]` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `"update_file"` @@ -66646,7 +77931,11 @@ print(compacted_response) - `"apply_patch_call"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallAgent]` The agent that produced this item. @@ -66654,17 +77943,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ApplyPatchCallCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ApplyPatchCallCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ApplyPatchCallCallerProgram: …` - `caller_id: str` @@ -66672,19 +77963,13 @@ print(compacted_response) - `type: Literal["program"]` - - `"program"` - - - `created_by: Optional[str]` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput: …` + The caller type. Always `program`. - The output emitted by an apply patch tool call. + - `"program"` - - `id: str` + - `class ApplyPatchCallOutput: …` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The streamed output emitted by an apply patch tool call. - `call_id: str` @@ -66704,7 +77989,11 @@ print(compacted_response) - `"apply_patch_call_output"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallOutputAgent]` The agent that produced this item. @@ -66712,17 +78001,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ApplyPatchCallOutputCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ApplyPatchCallOutputCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ApplyPatchCallOutputCallerProgram: …` - `caller_id: str` @@ -66730,76 +78021,13 @@ print(compacted_response) - `type: Literal["program"]` - - `"program"` - - - `created_by: Optional[str]` - - The ID of the entity that created this tool call output. - - - `output: Optional[str]` - - Optional textual output returned by the apply patch tool. - - - `class McpCall: …` - - An invocation of a tool on an MCP server. - - - `id: str` - - The unique ID of the tool call. - - - `arguments: str` - - A JSON string of the arguments passed to the tool. - - - `name: str` - - The name of the tool that was run. - - - `server_label: str` - - The label of the MCP server running the tool. - - - `type: Literal["mcp_call"]` - - The type of the item. Always `mcp_call`. - - - `"mcp_call"` - - - `agent: Optional[McpCallAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `approval_request_id: Optional[str]` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: Optional[str]` + The caller type. Always `program`. - The error from the tool call, if any. + - `"program"` - `output: Optional[str]` - The output from the tool call. - - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"calling"` - - - `"failed"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `class McpListTools: …` @@ -66889,10 +78117,6 @@ print(compacted_response) A response to an MCP approval request. - - `id: str` - - The unique ID of the approval response - - `approval_request_id: str` The ID of the approval request being answered. @@ -66907,6 +78131,10 @@ print(compacted_response) - `"mcp_approval_response"` + - `id: Optional[str]` + + The unique ID of the approval response + - `agent: Optional[McpApprovalResponseAgent]` The agent that produced this item. @@ -66919,1111 +78147,881 @@ print(compacted_response) Optional reason for the decision. - - `class BetaResponseCustomToolCall: …` - - A call to a custom tool created by the model. - - - `class BetaResponseCustomToolCallOutputItem: …` + - `class McpCall: …` - The output of a custom tool call from your code, being sent back to the model. + An invocation of a tool on an MCP server. - `id: str` - The unique ID of the custom tool call output item. - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `parallel_tool_calls: bool` - - Whether to allow the model to run tool calls in parallel. - - - `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. - We generally recommend altering this or `top_p` but not both. - - - `tool_choice: ToolChoice` - - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. - - - `Literal["none", "auto", "required"]` - - - `"none"` - - - `"auto"` - - - `"required"` - - - `class BetaToolChoiceAllowed: …` - - Constrains the tools available to the model to a pre-defined set. - - - `mode: Literal["auto", "required"]` - - Constrains the tools available to the model to a pre-defined set. - - `auto` allows the model to pick from among the allowed tools and generate a - message. - - `required` requires the model to call one or more of the allowed tools. - - - `"auto"` - - - `"required"` - - - `tools: List[Dict[str, object]]` - - A list of tool definitions that the model should be allowed to call. - - For the Responses API, the list of tool definitions might look like: - - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` - - - `type: Literal["allowed_tools"]` - - Allowed tool configuration type. Always `allowed_tools`. - - - `"allowed_tools"` - - - `class BetaToolChoiceTypes: …` - - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` - - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - Allowed values are: - - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` - - - `"file_search"` - - - `"web_search_preview"` - - - `"computer"` - - - `"computer_use_preview"` - - - `"computer_use"` - - - `"web_search_preview_2025_03_11"` - - - `"image_generation"` - - - `"code_interpreter"` + The unique ID of the tool call. - - `class BetaToolChoiceFunction: …` + - `arguments: str` - Use this option to force the model to call a specific function. + A JSON string of the arguments passed to the tool. - `name: str` - The name of the function to call. - - - `type: Literal["function"]` - - For function calling, the type is always `function`. - - - `"function"` - - - `class BetaToolChoiceMcp: …` - - Use this option to force the model to call a specific tool on a remote MCP server. + The name of the tool that was run. - `server_label: str` - The label of the MCP server to use. - - - `type: Literal["mcp"]` - - For MCP tools, the type is always `mcp`. - - - `"mcp"` - - - `name: Optional[str]` - - The name of the tool to call on the server. - - - `class BetaToolChoiceCustom: …` - - Use this option to force the model to call a specific custom tool. - - - `name: str` - - The name of the custom tool to call. - - - `type: Literal["custom"]` - - For custom tool calling, the type is always `custom`. - - - `"custom"` - - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` - - - `type: Literal["programmatic_tool_calling"]` - - The tool to call. Always `programmatic_tool_calling`. - - - `"programmatic_tool_calling"` + The label of the MCP server running the tool. - - `class BetaToolChoiceApplyPatch: …` + - `type: Literal["mcp_call"]` - Forces the model to call the apply_patch tool when executing a tool call. + The type of the item. Always `mcp_call`. - - `type: Literal["apply_patch"]` + - `"mcp_call"` - The tool to call. Always `apply_patch`. + - `agent: Optional[McpCallAgent]` - - `"apply_patch"` + The agent that produced this item. - - `class BetaToolChoiceShell: …` + - `agent_name: str` - Forces the model to call the shell tool when a tool call is required. + The canonical name of the agent that produced this item. - - `type: Literal["shell"]` + - `approval_request_id: Optional[str]` - The tool to call. Always `shell`. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `"shell"` + - `error: Optional[str]` - - `tools: List[BetaTool]` + The error from the tool call, if any. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `output: Optional[str]` - We support the following categories of tools: + The output from the tool call. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - `class BetaFunctionTool: …` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `"in_progress"` - - `class BetaFileSearchTool: …` + - `"completed"` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `"incomplete"` - - `class BetaComputerTool: …` + - `"calling"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"failed"` - - `class BetaComputerUsePreviewTool: …` + - `class BetaResponseCustomToolCallOutput: …` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The output of a custom tool call from your code, being sent back to the model. - - `class BetaWebSearchTool: …` + - `call_id: str` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The call ID, used to map this custom tool call output to a custom tool call. - - `class Mcp: …` + - `output: Union[str, List[OutputOutputContentList]]` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `class CodeInterpreter: …` + - `str` - A tool that runs Python code to help generate a response to a prompt. + A string of the output of the custom tool call. - - `class ProgrammaticToolCalling: …` + - `List[OutputOutputContentList]` - - `class ImageGeneration: …` + Text, image, or file output of the custom tool call. - A tool that generates images using the GPT image models. + - `class BetaResponseInputText: …` - - `class LocalShell: …` + A text input to the model. - A tool that allows the model to execute shell commands in a local environment. + - `class BetaResponseInputImage: …` - - `class BetaFunctionShellTool: …` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - A tool that allows the model to execute shell commands. + - `class BetaResponseInputFile: …` - - `class BetaCustomTool: …` + A file input to the model. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: Literal["custom_tool_call_output"]` - - `class BetaNamespaceTool: …` + The type of the custom tool call output. Always `custom_tool_call_output`. - Groups function/custom tools under a shared namespace. + - `"custom_tool_call_output"` - - `class BetaToolSearchTool: …` + - `id: Optional[str]` - Hosted or BYOT tool search configuration for deferred tools. + The unique ID of the custom tool call output in the OpenAI platform. - - `class BetaWebSearchPreviewTool: …` + - `agent: Optional[Agent]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The agent that produced this item. - - `class BetaApplyPatchTool: …` + - `agent_name: str` - Allows the assistant to create, delete, or update files using unified diffs. + The canonical name of the agent that produced this item. - - `top_p: Optional[float]` + - `caller: Optional[Caller]` - 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. + The execution context that produced this tool call. - We generally recommend altering this or `temperature` but not both. + - `class CallerDirect: …` - - `background: Optional[bool]` + - `type: Literal["direct"]` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The caller type. Always `direct`. - - `completed_at: Optional[float]` + - `"direct"` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `class CallerProgram: …` - - `conversation: Optional[Conversation]` + - `caller_id: str` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The call ID of the program item that produced this tool call. - - `id: str` + - `type: Literal["program"]` - The unique ID of the conversation that this response was associated with. + The caller type. Always `program`. - - `max_output_tokens: Optional[int]` + - `"program"` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `class BetaResponseCustomToolCall: …` - - `max_tool_calls: Optional[int]` + A call to a custom tool created by the model. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `call_id: str` - - `moderation: Optional[Moderation]` + An identifier used to map this custom tool call to a tool call output. - Moderation results for the response input and output, if moderated completions were requested. + - `input: str` - - `input: ModerationInput` + The input for the custom tool call generated by the model. - Moderation for the response input. + - `name: str` - - `class ModerationInputModerationResult: …` + The name of the custom tool being called. - A moderation result produced for the response input or output. + - `type: Literal["custom_tool_call"]` - - `categories: Dict[str, bool]` + The type of the custom tool call. Always `custom_tool_call`. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"custom_tool_call"` - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `id: Optional[str]` - Which modalities of input are reflected by the score for each category. + The unique ID of the custom tool call in the OpenAI platform. - - `"text"` + - `agent: Optional[Agent]` - - `"image"` + The agent that produced this item. - - `category_scores: Dict[str, float]` + - `agent_name: str` - A dictionary of moderation categories to scores. + The canonical name of the agent that produced this item. - - `flagged: bool` + - `caller: Optional[Caller]` - A boolean indicating whether the content was flagged by any category. + The execution context that produced this tool call. - - `model: str` + - `class CallerDirect: …` - The moderation model that produced this result. + - `type: Literal["direct"]` - - `type: Literal["moderation_result"]` + - `"direct"` - The object type, which was always `moderation_result` for successful moderation results. + - `class CallerProgram: …` - - `"moderation_result"` + - `caller_id: str` - - `class ModerationInputError: …` + The call ID of the program item that produced this tool call. - An error produced while attempting moderation for the response input or output. + - `type: Literal["program"]` - - `code: str` + - `"program"` - The error code. + - `namespace: Optional[str]` - - `message: str` + The namespace of the custom tool being called. - The error message. + - `class CompactionTrigger: …` - - `type: Literal["error"]` + Compacts the current context. Must be the final input item. - The object type, which was always `error` for moderation failures. + - `type: Literal["compaction_trigger"]` - - `"error"` + The type of the item. Always `compaction_trigger`. - - `output: ModerationOutput` + - `"compaction_trigger"` - Moderation for the response output. + - `agent: Optional[CompactionTriggerAgent]` - - `class ModerationOutputModerationResult: …` + The agent that produced this item. - A moderation result produced for the response input or output. + - `agent_name: str` - - `categories: Dict[str, bool]` + The canonical name of the agent that produced this item. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `class ItemReference: …` - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + An internal identifier for an item to reference. - Which modalities of input are reflected by the score for each category. + - `id: str` - - `"text"` + The ID of the item to reference. - - `"image"` + - `agent: Optional[ItemReferenceAgent]` - - `category_scores: Dict[str, float]` + The agent that produced this item. - A dictionary of moderation categories to scores. + - `agent_name: str` - - `flagged: bool` + The canonical name of the agent that produced this item. - A boolean indicating whether the content was flagged by any category. + - `type: Optional[Literal["item_reference"]]` - - `model: str` + The type of item to reference. Always `item_reference`. - The moderation model that produced this result. + - `"item_reference"` - - `type: Literal["moderation_result"]` + - `class Program: …` - The object type, which was always `moderation_result` for successful moderation results. + - `id: str` - - `"moderation_result"` + The unique ID of this program item. - - `class ModerationOutputError: …` + - `call_id: str` - An error produced while attempting moderation for the response input or output. + The stable call ID of the program item. - `code: str` - The error code. - - - `message: str` - - The error message. - - - `type: Literal["error"]` - - The object type, which was always `error` for moderation failures. + The JavaScript source executed by programmatic tool calling. - - `"error"` + - `fingerprint: str` - - `previous_response_id: Optional[str]` + Opaque program replay fingerprint that must be round-tripped. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `type: Literal["program"]` - - `prompt: Optional[BetaResponsePrompt]` + The item type. Always `program`. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `"program"` - - `id: str` + - `agent: Optional[ProgramAgent]` - The unique identifier of the prompt template to use. + The agent that produced this item. - - `variables: Optional[Dict[str, Variables]]` + - `agent_name: str` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The canonical name of the agent that produced this item. - - `str` + - `class ProgramOutput: …` - - `class BetaResponseInputText: …` + - `id: str` - A text input to the model. + The unique ID of this program output item. - - `class BetaResponseInputImage: …` + - `call_id: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The call ID of the program item. - - `class BetaResponseInputFile: …` + - `result: str` - A file input to the model. + The result produced by the program item. - - `version: Optional[str]` + - `status: Literal["completed", "incomplete"]` - Optional version of the prompt template. + The terminal status of the program output. - - `prompt_cache_key: Optional[str]` + - `"completed"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `"incomplete"` - - `prompt_cache_options: Optional[PromptCacheOptions]` + - `type: Literal["program_output"]` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The item type. Always `program_output`. - - `mode: Literal["implicit", "explicit"]` + - `"program_output"` - Whether implicit prompt-cache breakpoints were enabled. + - `agent: Optional[ProgramOutputAgent]` - - `"implicit"` + The agent that produced this item. - - `"explicit"` + - `agent_name: str` - - `ttl: Literal["30m"]` + The canonical name of the agent that produced this item. - The minimum lifetime applied to each cache breakpoint. + - `metadata: Optional[Dict[str, str]]` - - `"30m"` + 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. - - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `"in_memory"` + - `"gpt-5.6-sol"` - - `"24h"` + - `"gpt-5.6-terra"` - - `reasoning: Optional[Reasoning]` + - `"gpt-5.6-luna"` - **gpt-5 and o-series models only** + - `"gpt-5.4"` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `"gpt-5.4-mini"` - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + - `"gpt-5.4-nano"` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `"gpt-5.4-mini-2026-03-17"` - - `"auto"` + - `"gpt-5.4-nano-2026-03-17"` - - `"current_turn"` + - `"gpt-5.3-chat-latest"` - - `"all_turns"` + - `"gpt-5.2"` - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + - `"gpt-5.2-2025-12-11"` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `"gpt-5.2-chat-latest"` - - `"none"` + - `"gpt-5.2-pro"` - - `"minimal"` + - `"gpt-5.2-pro-2025-12-11"` - - `"low"` + - `"gpt-5.1"` - - `"medium"` + - `"gpt-5.1-2025-11-13"` - - `"high"` + - `"gpt-5.1-codex"` - - `"xhigh"` + - `"gpt-5.1-mini"` - - `"max"` + - `"gpt-5.1-chat-latest"` - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + - `"gpt-5"` - **Deprecated:** use `summary` instead. + - `"gpt-5-mini"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"gpt-5-nano"` - - `"auto"` + - `"gpt-5-2025-08-07"` - - `"concise"` + - `"gpt-5-mini-2025-08-07"` - - `"detailed"` + - `"gpt-5-nano-2025-08-07"` - - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + - `"gpt-5-chat-latest"` - Controls the reasoning execution mode for the request. + - `"gpt-4.1"` - When returned on a response, this is the effective execution mode. + - `"gpt-4.1-mini"` - - `str` + - `"gpt-4.1-nano"` - - `Literal["standard", "pro"]` + - `"gpt-4.1-2025-04-14"` - Controls the reasoning execution mode for the request. + - `"gpt-4.1-mini-2025-04-14"` - When returned on a response, this is the effective execution mode. + - `"gpt-4.1-nano-2025-04-14"` - - `"standard"` + - `"o4-mini"` - - `"pro"` + - `"o4-mini-2025-04-16"` - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + - `"o3"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"o3-2025-04-16"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `"o3-mini"` - - `"auto"` + - `"o3-mini-2025-01-31"` - - `"concise"` + - `"o1"` - - `"detailed"` + - `"o1-2024-12-17"` - - `safety_identifier: Optional[str]` + - `"o1-preview"` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"o1-preview-2024-09-12"` - - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + - `"o1-mini"` - Specifies the processing type used for serving the request. + - `"o1-mini-2024-09-12"` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `"gpt-4o"` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `"gpt-4o-2024-11-20"` - - `"auto"` + - `"gpt-4o-2024-08-06"` - - `"default"` + - `"gpt-4o-2024-05-13"` - - `"flex"` + - `"gpt-4o-audio-preview"` - - `"scale"` + - `"gpt-4o-audio-preview-2024-10-01"` - - `"priority"` + - `"gpt-4o-audio-preview-2024-12-17"` - - `status: Optional[BetaResponseStatus]` + - `"gpt-4o-audio-preview-2025-06-03"` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `"gpt-4o-mini-audio-preview"` - - `"completed"` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `"failed"` + - `"gpt-4o-search-preview"` - - `"in_progress"` + - `"gpt-4o-mini-search-preview"` - - `"cancelled"` + - `"gpt-4o-search-preview-2025-03-11"` - - `"queued"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `"incomplete"` + - `"chatgpt-4o-latest"` - - `text: Optional[BetaResponseTextConfig]` + - `"codex-mini-latest"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `"gpt-4o-mini"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `"gpt-4o-mini-2024-07-18"` - - `format: Optional[BetaResponseFormatTextConfig]` + - `"gpt-4-turbo"` - An object specifying the format that the model must output. + - `"gpt-4-turbo-2024-04-09"` - Configuring `{ "type": "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). + - `"gpt-4-0125-preview"` - The default format is `{ "type": "text" }` with no additional options. + - `"gpt-4-turbo-preview"` - **Not recommended for gpt-4o and newer models:** + - `"gpt-4-1106-preview"` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `"gpt-4-vision-preview"` - - `class Text: …` + - `"gpt-4"` - Default response format. Used to generate text responses. + - `"gpt-4-0314"` - - `type: Literal["text"]` + - `"gpt-4-0613"` - The type of response format being defined. Always `text`. + - `"gpt-4-32k"` - - `"text"` + - `"gpt-4-32k-0314"` - - `class BetaResponseFormatTextJSONSchemaConfig: …` + - `"gpt-4-32k-0613"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"gpt-3.5-turbo"` - - `name: str` + - `"gpt-3.5-turbo-16k"` - 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. + - `"gpt-3.5-turbo-0301"` - - `schema: Dict[str, object]` + - `"gpt-3.5-turbo-0613"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"gpt-3.5-turbo-1106"` - - `type: Literal["json_schema"]` + - `"gpt-3.5-turbo-0125"` - The type of response format being defined. Always `json_schema`. + - `"gpt-3.5-turbo-16k-0613"` - - `"json_schema"` + - `"o1-pro"` - - `description: Optional[str]` + - `"o1-pro-2025-03-19"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"o3-pro"` - - `strict: Optional[bool]` + - `"o3-pro-2025-06-10"` - 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). + - `"o3-deep-research"` - - `class JSONObject: …` + - `"o3-deep-research-2025-06-26"` - 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. + - `"o4-mini-deep-research"` - - `type: Literal["json_object"]` + - `"o4-mini-deep-research-2025-06-26"` - The type of response format being defined. Always `json_object`. + - `"computer-use-preview"` - - `"json_object"` + - `"computer-use-preview-2025-03-11"` - - `verbosity: Optional[Literal["low", "medium", "high"]]` + - `"gpt-5-codex"` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `"gpt-5-pro"` - - `"low"` + - `"gpt-5-pro-2025-10-06"` - - `"medium"` + - `"gpt-5.1-codex-max"` - - `"high"` + - `str` - - `top_logprobs: Optional[int]` + - `object: Literal["response"]` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The object type of this resource - always set to `response`. - - `truncation: Optional[Literal["auto", "disabled"]]` + - `"response"` - The truncation strategy to use for the model response. + - `output: List[BetaResponseOutputItem]` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + An array of content items generated by the model. - - `"auto"` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `"disabled"` + - `class BetaResponseOutputMessage: …` - - `usage: Optional[BetaResponseUsage]` + An output message from the model. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `class BetaResponseFileSearchToolCall: …` - - `input_tokens: int` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The number of input tokens. + - `class BetaResponseFunctionToolCall: …` - - `input_tokens_details: InputTokensDetails` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - A detailed breakdown of the input tokens. + - `class BetaResponseFunctionToolCallOutputItem: …` - - `cache_write_tokens: int` + - `id: str` - The number of input tokens that were written to the cache. + The unique ID of the function call tool output. - - `cached_tokens: int` + - `call_id: str` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The unique ID of the function tool call generated by the model. - - `output_tokens: int` + - `output: Union[str, List[OutputOutputContentList]]` - The number of output tokens. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `output_tokens_details: OutputTokensDetails` + - `str` - A detailed breakdown of the output tokens. + A string of the output of the function call. - - `reasoning_tokens: int` + - `List[OutputOutputContentList]` - The number of reasoning tokens. + Text, image, or file output of the function call. - - `total_tokens: int` + - `class BetaResponseInputText: …` - The total number of tokens used. + A text input to the model. - - `user: Optional[str]` + - `class BetaResponseInputImage: …` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `sequence_number: int` + - `class BetaResponseInputFile: …` - The sequence number for this event. + A file input to the model. - - `type: Literal["response.completed"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The type of the event. Always `response.completed`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"response.completed"` + - `"in_progress"` - - `agent: Optional[Agent]` + - `"completed"` - The agent that owns this multi-agent streaming event. + - `"incomplete"` - - `agent_name: str` + - `type: Literal["function_call_output"]` - The canonical name of the agent that produced this item. + The type of the function tool call output. Always `function_call_output`. -### Beta Response Computer Tool Call + - `"function_call_output"` -- `class BetaResponseComputerToolCall: …` + - `agent: Optional[Agent]` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The agent that produced this item. - - `id: str` + - `agent_name: str` - The unique ID of the computer call. + The canonical name of the agent that produced this item. - - `call_id: str` + - `caller: Optional[Caller]` - An identifier used when responding to the tool call with output. + The execution context that produced this tool call. - - `pending_safety_checks: List[PendingSafetyCheck]` + - `class CallerDirect: …` - The pending safety checks for the computer call. + - `type: Literal["direct"]` - - `id: str` + The caller type. Always `direct`. - The ID of the pending safety check. + - `"direct"` - - `code: Optional[str]` + - `class CallerProgram: …` - The type of the pending safety check. + - `caller_id: str` - - `message: Optional[str]` + The call ID of the program item that produced this tool call. - Details about the pending safety check. + - `type: Literal["program"]` - - `status: Literal["in_progress", "completed", "incomplete"]` + The caller type. Always `program`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"program"` - - `"in_progress"` + - `created_by: Optional[str]` - - `"completed"` + The identifier of the actor that created the item. - - `"incomplete"` + - `class AgentMessage: …` - - `type: Literal["computer_call"]` + - `id: str` - The type of the computer call. Always `computer_call`. + The unique ID of the agent message. - - `"computer_call"` + - `author: str` - - `action: Optional[BetaComputerAction]` + The sending agent identity. - A click action. + - `content: List[AgentMessageContent]` - - `class Click: …` + Encrypted content sent between agents. - A click action. + - `class BetaResponseInputText: …` - - `button: Literal["left", "right", "wheel", 2 more]` + A text input to the model. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `class BetaResponseOutputText: …` - - `"left"` + A text output from the model. - - `"right"` + - `class AgentMessageContentText: …` - - `"wheel"` + A text content. - - `"back"` + - `text: str` - - `"forward"` + - `type: Literal["text"]` - - `type: Literal["click"]` + - `"text"` - Specifies the event type. For a click action, this property is always `click`. + - `class AgentMessageContentSummaryText: …` - - `"click"` + A summary text from the model. - - `x: int` + - `text: str` - The x-coordinate where the click occurred. + A summary of the reasoning output from the model so far. - - `y: int` + - `type: Literal["summary_text"]` - The y-coordinate where the click occurred. + The type of the object. Always `summary_text`. - - `keys: Optional[List[str]]` + - `"summary_text"` - The keys being held while clicking. + - `class AgentMessageContentReasoningText: …` - - `class DoubleClick: …` + Reasoning text from the model. - A double click action. + - `text: str` - - `keys: Optional[List[str]]` + The reasoning text from the model. - The keys being held while double-clicking. + - `type: Literal["reasoning_text"]` - - `type: Literal["double_click"]` + The type of the reasoning text. Always `reasoning_text`. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"reasoning_text"` - - `"double_click"` + - `class BetaResponseOutputRefusal: …` - - `x: int` + A refusal from the model. - The x-coordinate where the double click occurred. + - `class BetaResponseInputImage: …` - - `y: int` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The y-coordinate where the double click occurred. + - `class AgentMessageContentComputerScreenshot: …` - - `class Drag: …` + A screenshot of a computer. - A drag action. + - `detail: Literal["low", "high", "auto", "original"]` - - `path: List[DragPath]` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"low"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"high"` - - `x: int` + - `"auto"` - The x-coordinate. + - `"original"` - - `y: int` + - `file_id: Optional[str]` - The y-coordinate. + The identifier of an uploaded file that contains the screenshot. - - `type: Literal["drag"]` + - `image_url: Optional[str]` - Specifies the event type. For a drag action, this property is always set to `drag`. + The URL of the screenshot image. - - `"drag"` + - `type: Literal["computer_screenshot"]` - - `keys: Optional[List[str]]` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The keys being held while dragging the mouse. + - `"computer_screenshot"` - - `class Keypress: …` + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - A collection of keypresses the model would like to perform. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `keys: List[str]` + - `mode: Literal["explicit"]` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The breakpoint mode. Always `explicit`. - - `type: Literal["keypress"]` + - `"explicit"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `class BetaResponseInputFile: …` - - `"keypress"` + A file input to the model. - - `class Move: …` + - `class AgentMessageContentEncryptedContent: …` - A mouse move action. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `type: Literal["move"]` + - `encrypted_content: str` - Specifies the event type. For a move action, this property is always set to `move`. + Opaque encrypted content. - - `"move"` + - `type: Literal["encrypted_content"]` - - `x: int` + The type of the input item. Always `encrypted_content`. - The x-coordinate to move to. + - `"encrypted_content"` - - `y: int` + - `recipient: str` - The y-coordinate to move to. + The destination agent identity. - - `keys: Optional[List[str]]` + - `type: Literal["agent_message"]` - The keys being held while moving the mouse. + The type of the item. Always `agent_message`. - - `class Screenshot: …` + - `"agent_message"` - A screenshot action. + - `agent: Optional[AgentMessageAgent]` - - `type: Literal["screenshot"]` + The agent that produced this item. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `agent_name: str` - - `"screenshot"` + The canonical name of the agent that produced this item. - - `class Scroll: …` + - `class MultiAgentCall: …` - A scroll action. + - `id: str` - - `scroll_x: int` + The unique ID of the multi-agent call item. - The horizontal scroll distance. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `scroll_y: int` + The multi-agent action to execute. - The vertical scroll distance. + - `"spawn_agent"` - - `type: Literal["scroll"]` + - `"interrupt_agent"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"list_agents"` - - `"scroll"` + - `"send_message"` - - `x: int` + - `"followup_task"` - The x-coordinate where the scroll occurred. + - `"wait_agent"` - - `y: int` + - `arguments: str` - The y-coordinate where the scroll occurred. + The JSON string of arguments generated for the action. - - `keys: Optional[List[str]]` + - `call_id: str` - The keys being held while scrolling. + The unique ID linking this call to its output. - - `class Type: …` + - `type: Literal["multi_agent_call"]` - An action to type in text. + The type of the multi-agent call. Always `multi_agent_call`. - - `text: str` + - `"multi_agent_call"` - The text to type. + - `agent: Optional[MultiAgentCallAgent]` - - `type: Literal["type"]` + The agent that produced this item. - Specifies the event type. For a type action, this property is always set to `type`. + - `agent_name: str` - - `"type"` + The canonical name of the agent that produced this item. - - `class Wait: …` + - `class MultiAgentCallOutput: …` - A wait action. + - `id: str` - - `type: Literal["wait"]` + The unique ID of the multi-agent call output item. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"wait"` + The multi-agent action that produced this result. - - `actions: Optional[BetaComputerActionList]` + - `"spawn_agent"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"interrupt_agent"` - - `class Click: …` + - `"list_agents"` - A click action. + - `"send_message"` - - `class DoubleClick: …` + - `"followup_task"` - A double click action. + - `"wait_agent"` - - `class Drag: …` + - `call_id: str` - A drag action. + The unique ID of the multi-agent call. - - `class Keypress: …` + - `output: List[BetaResponseOutputText]` - A collection of keypresses the model would like to perform. + Text output returned by the multi-agent action. - - `class Move: …` + - `annotations: List[Annotation]` - A mouse move action. + The annotations of the text output. - - `class Screenshot: …` + - `text: str` - A screenshot action. + The text output from the model. - - `class Scroll: …` + - `type: Literal["output_text"]` - A scroll action. + The type of the output text. Always `output_text`. - - `class Type: …` + - `logprobs: Optional[List[Logprob]]` - An action to type in text. + - `type: Literal["multi_agent_call_output"]` - - `class Wait: …` + The type of the multi-agent result. Always `multi_agent_call_output`. - A wait action. + - `"multi_agent_call_output"` - - `agent: Optional[Agent]` + - `agent: Optional[MultiAgentCallOutputAgent]` The agent that produced this item. @@ -68031,9 +79029,17 @@ print(compacted_response) The canonical name of the agent that produced this item. -### Beta Response Computer Tool Call Output Item + - `class BetaResponseFunctionWebSearch: …` -- `class BetaResponseComputerToolCallOutputItem: …` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `class BetaResponseComputerToolCall: …` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `class BetaResponseComputerToolCallOutputItem: …` - `id: str` @@ -68047,21 +79053,6 @@ print(compacted_response) A computer screenshot image used with the computer use tool. - - `type: Literal["computer_screenshot"]` - - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. - - - `"computer_screenshot"` - - - `file_id: Optional[str]` - - The identifier of an uploaded file that contains the screenshot. - - - `image_url: Optional[str]` - - The URL of the screenshot image. - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` The status of the message input. One of `in_progress`, `completed`, or @@ -68110,1009 +79101,1047 @@ print(compacted_response) The identifier of the actor that created the item. -### Beta Response Computer Tool Call Output Screenshot - -- `class BetaResponseComputerToolCallOutputScreenshot: …` + - `class BetaResponseReasoningItem: …` - A computer screenshot image used with the computer use tool. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `type: Literal["computer_screenshot"]` + - `class Program: …` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `id: str` - - `"computer_screenshot"` + The unique ID of the program item. - - `file_id: Optional[str]` + - `call_id: str` - The identifier of an uploaded file that contains the screenshot. + The stable call ID of the program item. - - `image_url: Optional[str]` + - `code: str` - The URL of the screenshot image. + The JavaScript source executed by programmatic tool calling. -### Beta Response Container Reference + - `fingerprint: str` -- `class BetaResponseContainerReference: …` + Opaque program replay fingerprint that must be round-tripped. - Represents a container created with /v1/containers. + - `type: Literal["program"]` - - `container_id: str` + The type of the item. Always `program`. - - `type: Literal["container_reference"]` + - `"program"` - The environment type. Always `container_reference`. + - `agent: Optional[ProgramAgent]` - - `"container_reference"` + The agent that produced this item. -### Beta Response Content + - `agent_name: str` -- `BetaResponseContent` + The canonical name of the agent that produced this item. - Multi-modal input and output contents. + - `class ProgramOutput: …` - - `class BetaResponseInputText: …` + - `id: str` - A text input to the model. + The unique ID of the program output item. - - `text: str` + - `call_id: str` - The text input to the model. + The call ID of the program item. - - `type: Literal["input_text"]` + - `result: str` - The type of the input item. Always `input_text`. + The result produced by the program item. - - `"input_text"` + - `status: Literal["completed", "incomplete"]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The terminal status of the program output item. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"completed"` - - `mode: Literal["explicit"]` + - `"incomplete"` - The breakpoint mode. Always `explicit`. + - `type: Literal["program_output"]` - - `"explicit"` + The type of the item. Always `program_output`. - - `class BetaResponseInputImage: …` + - `"program_output"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `agent: Optional[ProgramOutputAgent]` - - `detail: Literal["low", "high", "auto", "original"]` + The agent that produced this item. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `agent_name: str` - - `"low"` + The canonical name of the agent that produced this item. - - `"high"` + - `class BetaResponseToolSearchCall: …` - - `"auto"` + - `id: str` - - `"original"` + The unique ID of the tool search call item. - - `type: Literal["input_image"]` + - `arguments: object` - The type of the input item. Always `input_image`. + Arguments used for the tool search call. - - `"input_image"` + - `call_id: Optional[str]` - - `file_id: Optional[str]` + The unique ID of the tool search call generated by the model. - The ID of the file to be sent to the model. + - `execution: Literal["server", "client"]` - - `image_url: Optional[str]` + Whether tool search was executed by the server or by the client. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"server"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"client"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `mode: Literal["explicit"]` + The status of the tool search call item that was recorded. - The breakpoint mode. Always `explicit`. + - `"in_progress"` - - `"explicit"` + - `"completed"` - - `class BetaResponseInputFile: …` + - `"incomplete"` - A file input to the model. + - `type: Literal["tool_search_call"]` - - `type: Literal["input_file"]` + The type of the item. Always `tool_search_call`. - The type of the input item. Always `input_file`. + - `"tool_search_call"` - - `"input_file"` + - `agent: Optional[Agent]` - - `detail: Optional[Literal["auto", "low", "high"]]` + The agent that produced this item. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `agent_name: str` - - `"auto"` + The canonical name of the agent that produced this item. - - `"low"` + - `created_by: Optional[str]` - - `"high"` + The identifier of the actor that created the item. - - `file_data: Optional[str]` + - `class BetaResponseToolSearchOutputItem: …` - The content of the file to be sent to the model. + - `id: str` - - `file_id: Optional[str]` + The unique ID of the tool search output item. - The ID of the file to be sent to the model. + - `call_id: Optional[str]` - - `file_url: Optional[str]` + The unique ID of the tool search call generated by the model. - The URL of the file to be sent to the model. + - `execution: Literal["server", "client"]` - - `filename: Optional[str]` + Whether tool search was executed by the server or by the client. - The name of the file to be sent to the model. + - `"server"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"client"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `mode: Literal["explicit"]` + The status of the tool search output item that was recorded. - The breakpoint mode. Always `explicit`. + - `"in_progress"` - - `"explicit"` + - `"completed"` - - `class BetaResponseOutputText: …` + - `"incomplete"` - A text output from the model. + - `tools: List[BetaTool]` - - `annotations: List[Annotation]` + The loaded tool definitions returned by tool search. - The annotations of the text output. + - `class BetaFunctionTool: …` - - `class AnnotationFileCitation: …` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - A citation to a file. + - `class BetaFileSearchTool: …` - - `file_id: str` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The ID of the file. + - `class BetaComputerTool: …` - - `filename: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The filename of the file cited. + - `class BetaComputerUsePreviewTool: …` - - `index: int` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The index of the file in the list of files. + - `class BetaWebSearchTool: …` - - `type: Literal["file_citation"]` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The type of the file citation. Always `file_citation`. + - `class Mcp: …` - - `"file_citation"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `class AnnotationURLCitation: …` + - `class CodeInterpreter: …` - A citation for a web resource used to generate a model response. + A tool that runs Python code to help generate a response to a prompt. - - `end_index: int` + - `class ProgrammaticToolCalling: …` - The index of the last character of the URL citation in the message. + - `class ImageGeneration: …` - - `start_index: int` + A tool that generates images using the GPT image models. - The index of the first character of the URL citation in the message. + - `class LocalShell: …` - - `title: str` + A tool that allows the model to execute shell commands in a local environment. - The title of the web resource. + - `class BetaFunctionShellTool: …` - - `type: Literal["url_citation"]` + A tool that allows the model to execute shell commands. - The type of the URL citation. Always `url_citation`. + - `class BetaCustomTool: …` - - `"url_citation"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `url: str` + - `class BetaNamespaceTool: …` - The URL of the web resource. + Groups function/custom tools under a shared namespace. - - `class AnnotationContainerFileCitation: …` + - `class BetaToolSearchTool: …` - A citation for a container file used to generate a model response. + Hosted or BYOT tool search configuration for deferred tools. - - `container_id: str` + - `class BetaWebSearchPreviewTool: …` - The ID of the container file. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `end_index: int` + - `class BetaApplyPatchTool: …` - The index of the last character of the container file citation in the message. + Allows the assistant to create, delete, or update files using unified diffs. - - `file_id: str` + - `type: Literal["tool_search_output"]` - The ID of the file. + The type of the item. Always `tool_search_output`. - - `filename: str` + - `"tool_search_output"` - The filename of the container file cited. + - `agent: Optional[Agent]` - - `start_index: int` + The agent that produced this item. - The index of the first character of the container file citation in the message. + - `agent_name: str` - - `type: Literal["container_file_citation"]` + The canonical name of the agent that produced this item. - The type of the container file citation. Always `container_file_citation`. + - `created_by: Optional[str]` - - `"container_file_citation"` + The identifier of the actor that created the item. - - `class AnnotationFilePath: …` + - `class AdditionalTools: …` - A path to a file. + - `id: str` - - `file_id: str` + The unique ID of the additional tools item. - The ID of the file. + - `role: Literal["unknown", "user", "assistant", 5 more]` - - `index: int` + The role that provided the additional tools. - The index of the file in the list of files. + - `"unknown"` - - `type: Literal["file_path"]` + - `"user"` - The type of the file path. Always `file_path`. + - `"assistant"` - - `"file_path"` + - `"system"` - - `text: str` + - `"critic"` - The text output from the model. + - `"discriminator"` - - `type: Literal["output_text"]` + - `"developer"` - The type of the output text. Always `output_text`. + - `"tool"` - - `"output_text"` + - `tools: List[BetaTool]` - - `logprobs: Optional[List[Logprob]]` + The additional tool definitions made available at this item. - - `token: str` + - `class BetaFunctionTool: …` - - `bytes: List[int]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `logprob: float` + - `class BetaFileSearchTool: …` - - `top_logprobs: List[LogprobTopLogprob]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `token: str` + - `class BetaComputerTool: …` - - `bytes: List[int]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `logprob: float` + - `class BetaComputerUsePreviewTool: …` - - `class BetaResponseOutputRefusal: …` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A refusal from the model. + - `class BetaWebSearchTool: …` - - `refusal: str` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The refusal explanation from the model. + - `class Mcp: …` - - `type: Literal["refusal"]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The type of the refusal. Always `refusal`. + - `class CodeInterpreter: …` - - `"refusal"` + A tool that runs Python code to help generate a response to a prompt. - - `class ReasoningText: …` + - `class ProgrammaticToolCalling: …` - Reasoning text from the model. + - `class ImageGeneration: …` - - `text: str` + A tool that generates images using the GPT image models. - The reasoning text from the model. + - `class LocalShell: …` - - `type: Literal["reasoning_text"]` + A tool that allows the model to execute shell commands in a local environment. - The type of the reasoning text. Always `reasoning_text`. + - `class BetaFunctionShellTool: …` - - `"reasoning_text"` + A tool that allows the model to execute shell commands. -### Beta Response Content Part Added Event + - `class BetaCustomTool: …` -- `class BetaResponseContentPartAddedEvent: …` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - Emitted when a new content part is added. + - `class BetaNamespaceTool: …` - - `content_index: int` + Groups function/custom tools under a shared namespace. - The index of the content part that was added. + - `class BetaToolSearchTool: …` - - `item_id: str` + Hosted or BYOT tool search configuration for deferred tools. - The ID of the output item that the content part was added to. + - `class BetaWebSearchPreviewTool: …` - - `output_index: int` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The index of the output item that the content part was added to. + - `class BetaApplyPatchTool: …` - - `part: Part` + Allows the assistant to create, delete, or update files using unified diffs. - The content part that was added. + - `type: Literal["additional_tools"]` - - `class BetaResponseOutputText: …` + The type of the item. Always `additional_tools`. - A text output from the model. + - `"additional_tools"` - - `annotations: List[Annotation]` + - `agent: Optional[AdditionalToolsAgent]` - The annotations of the text output. + The agent that produced this item. - - `class AnnotationFileCitation: …` + - `agent_name: str` - A citation to a file. + The canonical name of the agent that produced this item. - - `file_id: str` + - `class BetaResponseCompactionItem: …` - The ID of the file. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `filename: str` + - `id: str` - The filename of the file cited. + The unique ID of the compaction item. - - `index: int` + - `encrypted_content: str` - The index of the file in the list of files. + The encrypted content that was produced by compaction. - - `type: Literal["file_citation"]` + - `type: Literal["compaction"]` - The type of the file citation. Always `file_citation`. + The type of the item. Always `compaction`. - - `"file_citation"` + - `"compaction"` - - `class AnnotationURLCitation: …` + - `agent: Optional[Agent]` - A citation for a web resource used to generate a model response. + The agent that produced this item. - - `end_index: int` + - `agent_name: str` - The index of the last character of the URL citation in the message. + The canonical name of the agent that produced this item. - - `start_index: int` + - `created_by: Optional[str]` - The index of the first character of the URL citation in the message. + The identifier of the actor that created the item. - - `title: str` + - `class ImageGenerationCall: …` - The title of the web resource. + An image generation request made by the model. - - `type: Literal["url_citation"]` + - `id: str` - The type of the URL citation. Always `url_citation`. + The unique ID of the image generation call. - - `"url_citation"` + - `result: Optional[str]` - - `url: str` + The generated image encoded in base64. - The URL of the web resource. + - `status: Literal["in_progress", "completed", "generating", "failed"]` - - `class AnnotationContainerFileCitation: …` + The status of the image generation call. - A citation for a container file used to generate a model response. + - `"in_progress"` - - `container_id: str` + - `"completed"` - The ID of the container file. + - `"generating"` - - `end_index: int` + - `"failed"` - The index of the last character of the container file citation in the message. + - `type: Literal["image_generation_call"]` - - `file_id: str` + The type of the image generation call. Always `image_generation_call`. - The ID of the file. + - `"image_generation_call"` - - `filename: str` + - `agent: Optional[ImageGenerationCallAgent]` - The filename of the container file cited. + The agent that produced this item. - - `start_index: int` + - `agent_name: str` - The index of the first character of the container file citation in the message. + The canonical name of the agent that produced this item. - - `type: Literal["container_file_citation"]` + - `class BetaResponseCodeInterpreterToolCall: …` - The type of the container file citation. Always `container_file_citation`. + A tool call to run code. - - `"container_file_citation"` + - `class LocalShellCall: …` - - `class AnnotationFilePath: …` + A tool call to run a command on the local shell. - A path to a file. + - `id: str` - - `file_id: str` + The unique ID of the local shell call. - The ID of the file. + - `action: LocalShellCallAction` - - `index: int` + Execute a shell command on the server. - The index of the file in the list of files. + - `command: List[str]` - - `type: Literal["file_path"]` + The command to run. - The type of the file path. Always `file_path`. + - `env: Dict[str, str]` - - `"file_path"` + Environment variables to set for the command. - - `text: str` + - `type: Literal["exec"]` - The text output from the model. + The type of the local shell action. Always `exec`. - - `type: Literal["output_text"]` + - `"exec"` - The type of the output text. Always `output_text`. + - `timeout_ms: Optional[int]` - - `"output_text"` + Optional timeout in milliseconds for the command. - - `logprobs: Optional[List[Logprob]]` + - `user: Optional[str]` - - `token: str` + Optional user to run the command as. - - `bytes: List[int]` + - `working_directory: Optional[str]` - - `logprob: float` + Optional working directory to run the command in. - - `top_logprobs: List[LogprobTopLogprob]` + - `call_id: str` - - `token: str` + The unique ID of the local shell tool call generated by the model. - - `bytes: List[int]` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `logprob: float` + The status of the local shell call. - - `class BetaResponseOutputRefusal: …` + - `"in_progress"` - A refusal from the model. + - `"completed"` - - `refusal: str` + - `"incomplete"` - The refusal explanation from the model. + - `type: Literal["local_shell_call"]` - - `type: Literal["refusal"]` + The type of the local shell call. Always `local_shell_call`. - The type of the refusal. Always `refusal`. + - `"local_shell_call"` - - `"refusal"` + - `agent: Optional[LocalShellCallAgent]` - - `class PartReasoningText: …` + The agent that produced this item. - Reasoning text from the model. + - `agent_name: str` - - `text: str` + The canonical name of the agent that produced this item. - The reasoning text from the model. + - `class LocalShellCallOutput: …` - - `type: Literal["reasoning_text"]` + The output of a local shell tool call. - The type of the reasoning text. Always `reasoning_text`. + - `id: str` - - `"reasoning_text"` + The unique ID of the local shell tool call generated by the model. - - `sequence_number: int` + - `output: str` - The sequence number of this event. + A JSON string of the output of the local shell tool call. - - `type: Literal["response.content_part.added"]` + - `type: Literal["local_shell_call_output"]` - The type of the event. Always `response.content_part.added`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"response.content_part.added"` + - `"local_shell_call_output"` - - `agent: Optional[Agent]` + - `agent: Optional[LocalShellCallOutputAgent]` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. -### Beta Response Content Part Done Event + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` -- `class BetaResponseContentPartDoneEvent: …` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Emitted when a content part is done. + - `"in_progress"` - - `content_index: int` + - `"completed"` - The index of the content part that is done. + - `"incomplete"` - - `item_id: str` + - `class BetaResponseFunctionShellToolCall: …` - The ID of the output item that the content part was added to. + A tool call that executes one or more shell commands in a managed environment. - - `output_index: int` + - `id: str` - The index of the output item that the content part was added to. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `part: Part` + - `action: Action` - The content part that is done. + The shell commands and limits that describe how to run the tool call. - - `class BetaResponseOutputText: …` + - `commands: List[str]` - A text output from the model. + - `max_output_length: Optional[int]` - - `annotations: List[Annotation]` + Optional maximum number of characters to return from each command. - The annotations of the text output. + - `timeout_ms: Optional[int]` - - `class AnnotationFileCitation: …` + Optional timeout in milliseconds for the commands. - A citation to a file. + - `call_id: str` - - `file_id: str` + The unique ID of the shell tool call generated by the model. - The ID of the file. + - `environment: Optional[Environment]` - - `filename: str` + Represents the use of a local environment to perform shell actions. - The filename of the file cited. + - `class BetaResponseLocalEnvironment: …` - - `index: int` + Represents the use of a local environment to perform shell actions. - The index of the file in the list of files. + - `type: Literal["local"]` - - `type: Literal["file_citation"]` + The environment type. Always `local`. - The type of the file citation. Always `file_citation`. + - `"local"` - - `"file_citation"` + - `class BetaResponseContainerReference: …` - - `class AnnotationURLCitation: …` + Represents a container created with /v1/containers. - A citation for a web resource used to generate a model response. + - `container_id: str` - - `end_index: int` + - `type: Literal["container_reference"]` - The index of the last character of the URL citation in the message. + The environment type. Always `container_reference`. - - `start_index: int` + - `"container_reference"` - The index of the first character of the URL citation in the message. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `title: str` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The title of the web resource. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["shell_call"]` + + The type of the item. Always `shell_call`. + + - `"shell_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `created_by: Optional[str]` + + The ID of the entity that created this tool call. + + - `class BetaResponseFunctionShellToolCallOutput: …` + + The output of a shell tool call that was emitted. + + - `id: str` - - `type: Literal["url_citation"]` + The unique ID of the shell call output. Populated when this item is returned via API. - The type of the URL citation. Always `url_citation`. + - `call_id: str` - - `"url_citation"` + The unique ID of the shell tool call generated by the model. - - `url: str` + - `max_output_length: Optional[int]` - The URL of the web resource. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `class AnnotationContainerFileCitation: …` + - `output: List[Output]` - A citation for a container file used to generate a model response. + An array of shell call output contents - - `container_id: str` + - `outcome: OutputOutcome` - The ID of the container file. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `end_index: int` + - `class OutputOutcomeTimeout: …` - The index of the last character of the container file citation in the message. + Indicates that the shell call exceeded its configured time limit. - - `file_id: str` + - `type: Literal["timeout"]` - The ID of the file. + The outcome type. Always `timeout`. - - `filename: str` + - `"timeout"` - The filename of the container file cited. + - `class OutputOutcomeExit: …` - - `start_index: int` + Indicates that the shell commands finished and returned an exit code. - The index of the first character of the container file citation in the message. + - `exit_code: int` - - `type: Literal["container_file_citation"]` + Exit code from the shell process. - The type of the container file citation. Always `container_file_citation`. + - `type: Literal["exit"]` - - `"container_file_citation"` + The outcome type. Always `exit`. - - `class AnnotationFilePath: …` + - `"exit"` - A path to a file. + - `stderr: str` - - `file_id: str` + The standard error output that was captured. - The ID of the file. + - `stdout: str` - - `index: int` + The standard output that was captured. - The index of the file in the list of files. + - `created_by: Optional[str]` - - `type: Literal["file_path"]` + The identifier of the actor that created the item. - The type of the file path. Always `file_path`. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"file_path"` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `text: str` + - `"in_progress"` - The text output from the model. + - `"completed"` - - `type: Literal["output_text"]` + - `"incomplete"` - The type of the output text. Always `output_text`. + - `type: Literal["shell_call_output"]` - - `"output_text"` + The type of the shell call output. Always `shell_call_output`. - - `logprobs: Optional[List[Logprob]]` + - `"shell_call_output"` - - `token: str` + - `agent: Optional[Agent]` - - `bytes: List[int]` + The agent that produced this item. - - `logprob: float` + - `agent_name: str` - - `top_logprobs: List[LogprobTopLogprob]` + The canonical name of the agent that produced this item. - - `token: str` + - `caller: Optional[Caller]` - - `bytes: List[int]` + The execution context that produced this tool call. - - `logprob: float` + - `class CallerDirect: …` - - `class BetaResponseOutputRefusal: …` + - `type: Literal["direct"]` - A refusal from the model. + - `"direct"` - - `refusal: str` + - `class CallerProgram: …` - The refusal explanation from the model. + - `caller_id: str` - - `type: Literal["refusal"]` + The call ID of the program item that produced this tool call. - The type of the refusal. Always `refusal`. + - `type: Literal["program"]` - - `"refusal"` + - `"program"` - - `class PartReasoningText: …` + - `created_by: Optional[str]` - Reasoning text from the model. + The identifier of the actor that created the item. - - `text: str` + - `class BetaResponseApplyPatchToolCall: …` - The reasoning text from the model. + A tool call that applies file diffs by creating, deleting, or updating files. - - `type: Literal["reasoning_text"]` + - `id: str` - The type of the reasoning text. Always `reasoning_text`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"reasoning_text"` + - `call_id: str` - - `sequence_number: int` + The unique ID of the apply patch tool call generated by the model. - The sequence number of this event. + - `operation: Operation` - - `type: Literal["response.content_part.done"]` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The type of the event. Always `response.content_part.done`. + - `class OperationCreateFile: …` - - `"response.content_part.done"` + Instruction describing how to create a file via the apply_patch tool. - - `agent: Optional[Agent]` + - `diff: str` - The agent that owns this multi-agent streaming event. + Diff to apply. - - `agent_name: str` + - `path: str` - The canonical name of the agent that produced this item. + Path of the file to create. -### Beta Response Conversation Param + - `type: Literal["create_file"]` -- `class BetaResponseConversationParam: …` + Create a new file with the provided diff. - The conversation that this response belongs to. + - `"create_file"` - - `id: str` + - `class OperationDeleteFile: …` - The unique ID of the conversation. + Instruction describing how to delete a file via the apply_patch tool. -### Beta Response Created Event + - `path: str` -- `class BetaResponseCreatedEvent: …` + Path of the file to delete. - An event that is emitted when a response is created. + - `type: Literal["delete_file"]` - - `response: BetaResponse` + Delete the specified file. - The response that was created. + - `"delete_file"` - - `id: str` + - `class OperationUpdateFile: …` - Unique identifier for this Response. + Instruction describing how to update a file via the apply_patch tool. - - `created_at: float` + - `diff: str` - Unix timestamp (in seconds) of when this Response was created. + Diff to apply. - - `error: Optional[BetaResponseError]` + - `path: str` - An error object returned when the model fails to generate a Response. + Path of the file to update. - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + - `type: Literal["update_file"]` - The error code for the response. + Update an existing file with the provided diff. - - `"server_error"` + - `"update_file"` - - `"rate_limit_exceeded"` + - `status: Literal["in_progress", "completed"]` - - `"invalid_prompt"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"bio_policy"` + - `"in_progress"` - - `"vector_store_timeout"` + - `"completed"` - - `"invalid_image"` + - `type: Literal["apply_patch_call"]` - - `"invalid_image_format"` + The type of the item. Always `apply_patch_call`. - - `"invalid_base64_image"` + - `"apply_patch_call"` - - `"invalid_image_url"` + - `agent: Optional[Agent]` - - `"image_too_large"` + The agent that produced this item. - - `"image_too_small"` + - `agent_name: str` - - `"image_parse_error"` + The canonical name of the agent that produced this item. - - `"image_content_policy_violation"` + - `caller: Optional[Caller]` - - `"invalid_image_mode"` + The execution context that produced this tool call. - - `"image_file_too_large"` + - `class CallerDirect: …` - - `"unsupported_image_media_type"` + - `type: Literal["direct"]` - - `"empty_image_file"` + - `"direct"` - - `"failed_to_download_image"` + - `class CallerProgram: …` - - `"image_file_not_found"` + - `caller_id: str` - - `message: str` + The call ID of the program item that produced this tool call. - A human-readable description of the error. + - `type: Literal["program"]` - - `incomplete_details: Optional[IncompleteDetails]` + - `"program"` - Details about why the response is incomplete. + - `created_by: Optional[str]` - - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` + The ID of the entity that created this tool call. - The reason why the response is incomplete. + - `class BetaResponseApplyPatchToolCallOutput: …` - - `"max_output_tokens"` + The output emitted by an apply patch tool call. - - `"content_filter"` + - `id: str` - - `instructions: Union[str, List[BetaResponseInputItem], null]` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - A system (or developer) message inserted into the model's context. + - `call_id: str` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + The unique ID of the apply patch tool call generated by the model. - - `str` + - `status: Literal["completed", "failed"]` - A text input to the model, equivalent to a text input with the - `developer` role. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `List[BetaResponseInputItem]` + - `"completed"` - A list of one or many input items to the model, containing - different content types. + - `"failed"` - - `class BetaEasyInputMessage: …` + - `type: Literal["apply_patch_call_output"]` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The type of the item. Always `apply_patch_call_output`. - - `content: Union[str, BetaResponseInputMessageContentList]` + - `"apply_patch_call_output"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `agent: Optional[Agent]` - - `str` + The agent that produced this item. - A text input to the model. + - `agent_name: str` - - `List[BetaResponseInputContent]` + The canonical name of the agent that produced this item. - - `class BetaResponseInputText: …` + - `caller: Optional[Caller]` - A text input to the model. + The execution context that produced this tool call. - - `text: str` + - `class CallerDirect: …` - The text input to the model. + - `type: Literal["direct"]` - - `type: Literal["input_text"]` + - `"direct"` - The type of the input item. Always `input_text`. + - `class CallerProgram: …` - - `"input_text"` + - `caller_id: str` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The call ID of the program item that produced this tool call. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: Literal["program"]` - - `mode: Literal["explicit"]` + - `"program"` - The breakpoint mode. Always `explicit`. + - `created_by: Optional[str]` - - `"explicit"` + The ID of the entity that created this tool call output. - - `class BetaResponseInputImage: …` + - `output: Optional[str]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Optional textual output returned by the apply patch tool. - - `detail: Literal["low", "high", "auto", "original"]` + - `class McpCall: …` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + An invocation of a tool on an MCP server. - - `"low"` + - `id: str` - - `"high"` + The unique ID of the tool call. - - `"auto"` + - `arguments: str` - - `"original"` + A JSON string of the arguments passed to the tool. - - `type: Literal["input_image"]` + - `name: str` - The type of the input item. Always `input_image`. + The name of the tool that was run. - - `"input_image"` + - `server_label: str` - - `file_id: Optional[str]` + The label of the MCP server running the tool. - The ID of the file to be sent to the model. + - `type: Literal["mcp_call"]` - - `image_url: Optional[str]` + The type of the item. Always `mcp_call`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"mcp_call"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `agent: Optional[McpCallAgent]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The agent that produced this item. - - `mode: Literal["explicit"]` + - `agent_name: str` - The breakpoint mode. Always `explicit`. + The canonical name of the agent that produced this item. - - `"explicit"` + - `approval_request_id: Optional[str]` - - `class BetaResponseInputFile: …` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - A file input to the model. + - `error: Optional[str]` - - `type: Literal["input_file"]` + The error from the tool call, if any. - The type of the input item. Always `input_file`. + - `output: Optional[str]` - - `"input_file"` + The output from the tool call. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"auto"` + - `"in_progress"` - - `"low"` + - `"completed"` - - `"high"` + - `"incomplete"` - - `file_data: Optional[str]` + - `"calling"` - The content of the file to be sent to the model. + - `"failed"` - - `file_id: Optional[str]` + - `class McpListTools: …` - The ID of the file to be sent to the model. + A list of tools available on an MCP server. - - `file_url: Optional[str]` + - `id: str` - The URL of the file to be sent to the model. + The unique ID of the list. - - `filename: Optional[str]` + - `server_label: str` - The name of the file to be sent to the model. + The label of the MCP server. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `tools: List[McpListToolsTool]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The tools available on the server. - - `mode: Literal["explicit"]` + - `input_schema: object` - The breakpoint mode. Always `explicit`. + The JSON schema describing the tool's input. - - `"explicit"` + - `name: str` - - `role: Literal["user", "assistant", "system", "developer"]` + The name of the tool. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `annotations: Optional[object]` - - `"user"` + Additional annotations about the tool. - - `"assistant"` + - `description: Optional[str]` - - `"system"` + The description of the tool. - - `"developer"` + - `type: Literal["mcp_list_tools"]` - - `phase: Optional[Literal["commentary"]]` + The type of the item. Always `mcp_list_tools`. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `"mcp_list_tools"` - - `"commentary"` + - `agent: Optional[McpListToolsAgent]` - - `type: Optional[Literal["message"]]` + The agent that produced this item. - The type of the message input. Always `message`. + - `agent_name: str` - - `"message"` + The canonical name of the agent that produced this item. - - `class Message: …` + - `error: Optional[str]` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + Error message if the server could not list tools. - - `content: BetaResponseInputMessageContentList` + - `class McpApprovalRequest: …` - A list of one or many input items to the model, containing different content - types. + A request for human approval of a tool invocation. - - `class BetaResponseInputText: …` + - `id: str` - A text input to the model. + The unique ID of the approval request. - - `class BetaResponseInputImage: …` + - `arguments: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A JSON string of arguments for the tool. - - `class BetaResponseInputFile: …` + - `name: str` - A file input to the model. + The name of the tool to run. - - `role: Literal["user", "system", "developer"]` + - `server_label: str` - The role of the message input. One of `user`, `system`, or `developer`. + The label of the MCP server making the request. - - `"user"` + - `type: Literal["mcp_approval_request"]` - - `"system"` + The type of the item. Always `mcp_approval_request`. - - `"developer"` + - `"mcp_approval_request"` - - `agent: Optional[MessageAgent]` + - `agent: Optional[McpApprovalRequestAgent]` The agent that produced this item. @@ -69120,848 +80149,918 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` + - `class McpApprovalResponse: …` - - `type: Optional[Literal["message"]]` + A response to an MCP approval request. - The type of the message input. Always set to `message`. + - `id: str` - - `"message"` + The unique ID of the approval response - - `class BetaResponseOutputMessage: …` + - `approval_request_id: str` - An output message from the model. + The ID of the approval request being answered. - - `id: str` + - `approve: bool` - The unique ID of the output message. + Whether the request was approved. - - `content: List[Content]` + - `type: Literal["mcp_approval_response"]` - The content of the output message. + The type of the item. Always `mcp_approval_response`. - - `class BetaResponseOutputText: …` + - `"mcp_approval_response"` - A text output from the model. + - `agent: Optional[McpApprovalResponseAgent]` - - `annotations: List[Annotation]` + The agent that produced this item. - The annotations of the text output. + - `agent_name: str` - - `class AnnotationFileCitation: …` + The canonical name of the agent that produced this item. - A citation to a file. + - `reason: Optional[str]` - - `file_id: str` + Optional reason for the decision. - The ID of the file. + - `class BetaResponseCustomToolCall: …` - - `filename: str` + A call to a custom tool created by the model. - The filename of the file cited. + - `class BetaResponseCustomToolCallOutputItem: …` - - `index: int` + The output of a custom tool call from your code, being sent back to the model. - The index of the file in the list of files. + - `id: str` - - `type: Literal["file_citation"]` + The unique ID of the custom tool call output item. - The type of the file citation. Always `file_citation`. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"file_citation"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class AnnotationURLCitation: …` + - `"in_progress"` - A citation for a web resource used to generate a model response. + - `"completed"` - - `end_index: int` + - `"incomplete"` - The index of the last character of the URL citation in the message. + - `created_by: Optional[str]` - - `start_index: int` + The identifier of the actor that created the item. - The index of the first character of the URL citation in the message. + - `parallel_tool_calls: bool` - - `title: str` + Whether to allow the model to run tool calls in parallel. - The title of the web resource. + - `temperature: Optional[float]` - - `type: Literal["url_citation"]` + 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. + We generally recommend altering this or `top_p` but not both. - The type of the URL citation. Always `url_citation`. + - `tool_choice: ToolChoice` - - `"url_citation"` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `url: str` + - `Literal["none", "auto", "required"]` - The URL of the web resource. + - `"none"` - - `class AnnotationContainerFileCitation: …` + - `"auto"` - A citation for a container file used to generate a model response. + - `"required"` - - `container_id: str` + - `class BetaToolChoiceAllowed: …` - The ID of the container file. + Constrains the tools available to the model to a pre-defined set. - - `end_index: int` + - `mode: Literal["auto", "required"]` - The index of the last character of the container file citation in the message. + Constrains the tools available to the model to a pre-defined set. - - `file_id: str` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The ID of the file. + `required` requires the model to call one or more of the allowed tools. - - `filename: str` + - `"auto"` - The filename of the container file cited. + - `"required"` - - `start_index: int` + - `tools: List[Dict[str, object]]` - The index of the first character of the container file citation in the message. + A list of tool definitions that the model should be allowed to call. - - `type: Literal["container_file_citation"]` + For the Responses API, the list of tool definitions might look like: - The type of the container file citation. Always `container_file_citation`. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `"container_file_citation"` + - `type: Literal["allowed_tools"]` - - `class AnnotationFilePath: …` + Allowed tool configuration type. Always `allowed_tools`. - A path to a file. + - `"allowed_tools"` - - `file_id: str` + - `class BetaToolChoiceTypes: …` - The ID of the file. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `index: int` + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` - The index of the file in the list of files. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `type: Literal["file_path"]` + Allowed values are: - The type of the file path. Always `file_path`. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `"file_path"` + - `"file_search"` - - `text: str` + - `"web_search_preview"` - The text output from the model. + - `"computer"` - - `type: Literal["output_text"]` + - `"computer_use_preview"` - The type of the output text. Always `output_text`. + - `"computer_use"` - - `"output_text"` + - `"web_search_preview_2025_03_11"` - - `logprobs: Optional[List[Logprob]]` + - `"image_generation"` - - `token: str` + - `"code_interpreter"` - - `bytes: List[int]` + - `class BetaToolChoiceFunction: …` - - `logprob: float` + Use this option to force the model to call a specific function. - - `top_logprobs: List[LogprobTopLogprob]` + - `name: str` - - `token: str` + The name of the function to call. - - `bytes: List[int]` + - `type: Literal["function"]` - - `logprob: float` + For function calling, the type is always `function`. - - `class BetaResponseOutputRefusal: …` + - `"function"` - A refusal from the model. + - `class BetaToolChoiceMcp: …` - - `refusal: str` + Use this option to force the model to call a specific tool on a remote MCP server. - The refusal explanation from the model. + - `server_label: str` - - `type: Literal["refusal"]` + The label of the MCP server to use. - The type of the refusal. Always `refusal`. + - `type: Literal["mcp"]` - - `"refusal"` + For MCP tools, the type is always `mcp`. - - `role: Literal["assistant"]` + - `"mcp"` - The role of the output message. Always `assistant`. + - `name: Optional[str]` - - `"assistant"` + The name of the tool to call on the server. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `class BetaToolChoiceCustom: …` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Use this option to force the model to call a specific custom tool. - - `"in_progress"` + - `name: str` - - `"completed"` + The name of the custom tool to call. - - `"incomplete"` + - `type: Literal["custom"]` - - `type: Literal["message"]` + For custom tool calling, the type is always `custom`. - The type of the output message. Always `message`. + - `"custom"` - - `"message"` + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` - - `agent: Optional[Agent]` + - `type: Literal["programmatic_tool_calling"]` - The agent that produced this item. + The tool to call. Always `programmatic_tool_calling`. - - `agent_name: str` + - `"programmatic_tool_calling"` - The canonical name of the agent that produced this item. + - `class BetaToolChoiceApplyPatch: …` - - `phase: Optional[Literal["commentary"]]` + Forces the model to call the apply_patch tool when executing a tool call. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `type: Literal["apply_patch"]` - - `"commentary"` + The tool to call. Always `apply_patch`. - - `class BetaResponseFileSearchToolCall: …` + - `"apply_patch"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `class BetaToolChoiceShell: …` - - `id: str` + Forces the model to call the shell tool when a tool call is required. - The unique ID of the file search tool call. + - `type: Literal["shell"]` - - `queries: List[str]` + The tool to call. Always `shell`. - The queries used to search for files. + - `"shell"` - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `tools: List[BetaTool]` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `"in_progress"` + We support the following categories of tools: - - `"searching"` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `"completed"` + - `class BetaFunctionTool: …` - - `"incomplete"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"failed"` + - `class BetaFileSearchTool: …` - - `type: Literal["file_search_call"]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The type of the file search tool call. Always `file_search_call`. + - `class BetaComputerTool: …` - - `"file_search_call"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `agent: Optional[Agent]` + - `class BetaComputerUsePreviewTool: …` - The agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `agent_name: str` + - `class BetaWebSearchTool: …` - The canonical name of the agent that produced this item. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `results: Optional[List[Result]]` + - `class Mcp: …` - The results of the file search tool call. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + - `class CodeInterpreter: …` - 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, booleans, or numbers. + A tool that runs Python code to help generate a response to a prompt. - - `str` + - `class ProgrammaticToolCalling: …` - - `float` + - `class ImageGeneration: …` - - `bool` + A tool that generates images using the GPT image models. - - `file_id: Optional[str]` + - `class LocalShell: …` - The unique ID of the file. + A tool that allows the model to execute shell commands in a local environment. - - `filename: Optional[str]` + - `class BetaFunctionShellTool: …` - The name of the file. + A tool that allows the model to execute shell commands. - - `score: Optional[float]` + - `class BetaCustomTool: …` - The relevance score of the file - a value between 0 and 1. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `text: Optional[str]` + - `class BetaNamespaceTool: …` - The text that was retrieved from the file. + Groups function/custom tools under a shared namespace. - - `class BetaResponseComputerToolCall: …` + - `class BetaToolSearchTool: …` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Hosted or BYOT tool search configuration for deferred tools. - - `id: str` + - `class BetaWebSearchPreviewTool: …` - The unique ID of the computer call. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `call_id: str` + - `class BetaApplyPatchTool: …` - An identifier used when responding to the tool call with output. + Allows the assistant to create, delete, or update files using unified diffs. - - `pending_safety_checks: List[PendingSafetyCheck]` + - `top_p: Optional[float]` - The pending safety checks for the computer call. + 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. - - `id: str` + We generally recommend altering this or `temperature` but not both. - The ID of the pending safety check. + - `background: Optional[bool]` - - `code: Optional[str]` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The type of the pending safety check. + - `completed_at: Optional[float]` - - `message: Optional[str]` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - Details about the pending safety check. + - `conversation: Optional[Conversation]` - - `status: Literal["in_progress", "completed", "incomplete"]` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `id: str` - - `"in_progress"` + The unique ID of the conversation that this response was associated with. - - `"completed"` + - `max_output_tokens: Optional[int]` - - `"incomplete"` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `type: Literal["computer_call"]` + - `max_tool_calls: Optional[int]` - The type of the computer call. Always `computer_call`. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `"computer_call"` + - `moderation: Optional[Moderation]` - - `action: Optional[BetaComputerAction]` + Moderation results for the response input and output, if moderated completions were requested. - A click action. + - `input: ModerationInput` - - `class Click: …` + Moderation for the response input. - A click action. + - `class ModerationInputModerationResult: …` - - `button: Literal["left", "right", "wheel", 2 more]` + A moderation result produced for the response input or output. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `categories: Dict[str, bool]` - - `"left"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"right"` + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - - `"wheel"` + Which modalities of input are reflected by the score for each category. - - `"back"` + - `"text"` - - `"forward"` + - `"image"` - - `type: Literal["click"]` + - `category_scores: Dict[str, float]` - Specifies the event type. For a click action, this property is always `click`. + A dictionary of moderation categories to scores. - - `"click"` + - `flagged: bool` - - `x: int` + A boolean indicating whether the content was flagged by any category. - The x-coordinate where the click occurred. + - `model: str` - - `y: int` + The moderation model that produced this result. - The y-coordinate where the click occurred. + - `type: Literal["moderation_result"]` - - `keys: Optional[List[str]]` + The object type, which was always `moderation_result` for successful moderation results. - The keys being held while clicking. + - `"moderation_result"` - - `class DoubleClick: …` + - `class ModerationInputError: …` - A double click action. + An error produced while attempting moderation for the response input or output. - - `keys: Optional[List[str]]` + - `code: str` - The keys being held while double-clicking. + The error code. - - `type: Literal["double_click"]` + - `message: str` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The error message. - - `"double_click"` + - `type: Literal["error"]` - - `x: int` + The object type, which was always `error` for moderation failures. - The x-coordinate where the double click occurred. + - `"error"` - - `y: int` + - `output: ModerationOutput` - The y-coordinate where the double click occurred. + Moderation for the response output. - - `class Drag: …` + - `class ModerationOutputModerationResult: …` - A drag action. + A moderation result produced for the response input or output. - - `path: List[DragPath]` + - `categories: Dict[str, bool]` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - - `x: int` + Which modalities of input are reflected by the score for each category. - The x-coordinate. + - `"text"` - - `y: int` + - `"image"` - The y-coordinate. + - `category_scores: Dict[str, float]` - - `type: Literal["drag"]` + A dictionary of moderation categories to scores. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `flagged: bool` - - `"drag"` + A boolean indicating whether the content was flagged by any category. - - `keys: Optional[List[str]]` + - `model: str` - The keys being held while dragging the mouse. + The moderation model that produced this result. - - `class Keypress: …` + - `type: Literal["moderation_result"]` - A collection of keypresses the model would like to perform. + The object type, which was always `moderation_result` for successful moderation results. - - `keys: List[str]` + - `"moderation_result"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `class ModerationOutputError: …` - - `type: Literal["keypress"]` + An error produced while attempting moderation for the response input or output. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `code: str` - - `"keypress"` + The error code. - - `class Move: …` + - `message: str` - A mouse move action. + The error message. - - `type: Literal["move"]` + - `type: Literal["error"]` - Specifies the event type. For a move action, this property is always set to `move`. + The object type, which was always `error` for moderation failures. - - `"move"` + - `"error"` - - `x: int` + - `previous_response_id: Optional[str]` - The x-coordinate to move to. + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `y: int` + - `prompt: Optional[BetaResponsePrompt]` - The y-coordinate to move to. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `keys: Optional[List[str]]` + - `id: str` - The keys being held while moving the mouse. + The unique identifier of the prompt template to use. - - `class Screenshot: …` + - `variables: Optional[Dict[str, Variables]]` - A screenshot action. + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `type: Literal["screenshot"]` + - `str` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `class BetaResponseInputText: …` - - `"screenshot"` + A text input to the model. - - `class Scroll: …` + - `class BetaResponseInputImage: …` - A scroll action. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `scroll_x: int` + - `class BetaResponseInputFile: …` - The horizontal scroll distance. + A file input to the model. - - `scroll_y: int` + - `version: Optional[str]` - The vertical scroll distance. + Optional version of the prompt template. - - `type: Literal["scroll"]` + - `prompt_cache_key: Optional[str]` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `"scroll"` + - `prompt_cache_options: Optional[PromptCacheOptions]` - - `x: int` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The x-coordinate where the scroll occurred. + - `mode: Literal["implicit", "explicit"]` - - `y: int` + Whether implicit prompt-cache breakpoints were enabled. - The y-coordinate where the scroll occurred. + - `"implicit"` - - `keys: Optional[List[str]]` + - `"explicit"` - The keys being held while scrolling. + - `ttl: Literal["30m"]` - - `class Type: …` + The minimum lifetime applied to each cache breakpoint. - An action to type in text. + - `"30m"` - - `text: str` + - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` - The text to type. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `type: Literal["type"]` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - Specifies the event type. For a type action, this property is always set to `type`. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `"type"` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `class Wait: …` + - `"in_memory"` - A wait action. + - `"24h"` - - `type: Literal["wait"]` + - `reasoning: Optional[Reasoning]` - Specifies the event type. For a wait action, this property is always set to `wait`. + **gpt-5 and o-series models only** - - `"wait"` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `actions: Optional[BetaComputerActionList]` + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `class Click: …` + - `"auto"` - A click action. + - `"current_turn"` - - `class DoubleClick: …` + - `"all_turns"` - A double click action. + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` - - `class Drag: …` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - A drag action. + - `"none"` - - `class Keypress: …` + - `"minimal"` - A collection of keypresses the model would like to perform. + - `"low"` - - `class Move: …` + - `"medium"` - A mouse move action. + - `"high"` - - `class Screenshot: …` + - `"xhigh"` - A screenshot action. + - `"max"` - - `class Scroll: …` + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` - A scroll action. + **Deprecated:** use `summary` instead. - - `class Type: …` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - An action to type in text. + - `"auto"` - - `class Wait: …` + - `"concise"` - A wait action. + - `"detailed"` - - `agent: Optional[Agent]` + - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` - The agent that produced this item. + Controls the reasoning execution mode for the request. - - `agent_name: str` + When returned on a response, this is the effective execution mode. - The canonical name of the agent that produced this item. + - `str` - - `class ComputerCallOutput: …` + - `Literal["standard", "pro"]` - The output of a computer tool call. + Controls the reasoning execution mode for the request. - - `call_id: str` + When returned on a response, this is the effective execution mode. - The ID of the computer tool call that produced the output. + - `"standard"` - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"pro"` - A computer screenshot image used with the computer use tool. + - `summary: Optional[Literal["auto", "concise", "detailed"]]` - - `type: Literal["computer_screenshot"]` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `"computer_screenshot"` + - `"auto"` - - `file_id: Optional[str]` + - `"concise"` - The identifier of an uploaded file that contains the screenshot. + - `"detailed"` - - `image_url: Optional[str]` + - `safety_identifier: Optional[str]` - The URL of the screenshot image. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `type: Literal["computer_call_output"]` + - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` - The type of the computer tool call output. Always `computer_call_output`. + Specifies the processing type used for serving the request. - - `"computer_call_output"` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `id: Optional[str]` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The ID of the computer tool call output. + - `"auto"` - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + - `"default"` - The safety checks reported by the API that have been acknowledged by the developer. + - `"flex"` - - `id: str` + - `"scale"` - The ID of the pending safety check. + - `"priority"` - - `code: Optional[str]` + - `status: Optional[BetaResponseStatus]` - The type of the pending safety check. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `message: Optional[str]` + - `"completed"` - Details about the pending safety check. + - `"failed"` - - `agent: Optional[ComputerCallOutputAgent]` + - `"in_progress"` - The agent that produced this item. + - `"cancelled"` - - `agent_name: str` + - `"queued"` - The canonical name of the agent that produced this item. + - `"incomplete"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `text: Optional[BetaResponseTextConfig]` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"in_progress"` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `"completed"` + - `format: Optional[BetaResponseFormatTextConfig]` - - `"incomplete"` + An object specifying the format that the model must output. - - `class BetaResponseFunctionWebSearch: …` + Configuring `{ "type": "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). - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The default format is `{ "type": "text" }` with no additional options. - - `id: str` + **Not recommended for gpt-4o and newer models:** - The unique ID of the web search tool call. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `action: Action` + - `class Text: …` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + Default response format. Used to generate text responses. - - `class ActionSearch: …` + - `type: Literal["text"]` - Action type "search" - Performs a web search query. + The type of response format being defined. Always `text`. - - `type: Literal["search"]` + - `"text"` - The action type. + - `class BetaResponseFormatTextJSONSchemaConfig: …` - - `"search"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `queries: Optional[List[str]]` + - `name: str` - The search queries. + 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. - - `query: Optional[str]` + - `schema: Dict[str, object]` - The search query. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `sources: Optional[List[ActionSearchSource]]` + - `type: Literal["json_schema"]` - The sources used in the search. + The type of response format being defined. Always `json_schema`. - - `type: Literal["url"]` + - `"json_schema"` - The type of source. Always `url`. + - `description: Optional[str]` - - `"url"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `url: str` + - `strict: Optional[bool]` - The URL of the source. + 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). - - `class ActionOpenPage: …` + - `class JSONObject: …` - Action type "open_page" - Opens a specific URL from search results. + 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["open_page"]` + - `type: Literal["json_object"]` - The action type. + The type of response format being defined. Always `json_object`. - - `"open_page"` + - `"json_object"` - - `url: Optional[str]` + - `verbosity: Optional[Literal["low", "medium", "high"]]` - The URL opened by the model. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `class ActionFindInPage: …` + - `"low"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"medium"` - - `pattern: str` + - `"high"` - The pattern or text to search for within the page. + - `top_logprobs: Optional[int]` - - `type: Literal["find_in_page"]` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - The action type. + - `truncation: Optional[Literal["auto", "disabled"]]` - - `"find_in_page"` + The truncation strategy to use for the model response. - - `url: str` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The URL of the page searched for the pattern. + - `"auto"` - - `status: Literal["in_progress", "searching", "completed", "failed"]` + - `"disabled"` - The status of the web search tool call. + - `usage: Optional[BetaResponseUsage]` - - `"in_progress"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `"searching"` + - `input_tokens: int` - - `"completed"` + The number of input tokens. - - `"failed"` + - `input_tokens_details: InputTokensDetails` - - `type: Literal["web_search_call"]` + A detailed breakdown of the input tokens. - The type of the web search tool call. Always `web_search_call`. + - `cache_write_tokens: int` - - `"web_search_call"` + The number of input tokens that were written to the cache. - - `agent: Optional[Agent]` + - `cached_tokens: int` - The agent that produced this item. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `agent_name: str` + - `output_tokens: int` - The canonical name of the agent that produced this item. + The number of output tokens. - - `class BetaResponseFunctionToolCall: …` + - `output_tokens_details: OutputTokensDetails` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + A detailed breakdown of the output tokens. - - `arguments: str` + - `reasoning_tokens: int` - A JSON string of the arguments to pass to the function. + The number of reasoning tokens. - - `call_id: str` + - `total_tokens: int` - The unique ID of the function tool call generated by the model. + The total number of tokens used. - - `name: str` + - `user: Optional[str]` - The name of the function to run. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `type: Literal["function_call"]` + - `sequence_number: int` - The type of the function tool call. Always `function_call`. + The sequence number of this event. - - `"function_call"` + - `type: Literal["response.incomplete"]` - - `id: Optional[str]` + The type of the event. Always `response.incomplete`. - The unique ID of the function tool call. + - `"response.incomplete"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` +### Beta Response Inject Created Event - - `type: Literal["direct"]` +- `class BetaResponseInjectCreatedEvent: …` - - `"direct"` + Emitted when all injected input items were validated and committed to the + active response. - - `class CallerProgram: …` + - `response_id: str` - - `caller_id: str` + The ID of the response that accepted the input. - The call ID of the program item that produced this tool call. + - `sequence_number: int` - - `type: Literal["program"]` + The sequence number for this event. - - `"program"` + - `type: Literal["response.inject.created"]` - - `namespace: Optional[str]` + The event discriminator. Always `response.inject.created`. - The namespace of the function to run. + - `"response.inject.created"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `stream_id: Optional[str]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `"in_progress"` +### Beta Response Inject Event - - `"completed"` +- `class BetaResponseInjectEvent: …` - - `"incomplete"` + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. - - `class FunctionCallOutput: …` + - `input: List[BetaResponseInputItem]` - The output of a function tool call. + Input items to inject into the active response. - - `call_id: str` + - `class BetaEasyInputMessage: …` - The unique ID of the function tool call generated by the model. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + - `content: Union[str, BetaResponseInputMessageContentList]` - Text, image, or file output of the function tool call. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - `str` - A JSON string of the output of the function tool call. + A text input to the model. - - `List[BetaResponseFunctionCallOutputItem]` + - `List[BetaResponseInputContent]` - - `class BetaResponseInputTextContent: …` + - `class BetaResponseInputText: …` A text input to the model. @@ -69985,17 +81084,11 @@ print(compacted_response) - `"explicit"` - - `class BetaResponseInputImageContent: …` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `type: Literal["input_image"]` - - The type of the input item. Always `input_image`. + - `class BetaResponseInputImage: …` - - `"input_image"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + - `detail: Literal["low", "high", "auto", "original"]` The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. @@ -70007,6 +81100,12 @@ print(compacted_response) - `"original"` + - `type: Literal["input_image"]` + + The type of the input item. Always `input_image`. + + - `"input_image"` + - `file_id: Optional[str]` The ID of the file to be sent to the model. @@ -70025,7 +81124,7 @@ print(compacted_response) - `"explicit"` - - `class BetaResponseInputFileContent: …` + - `class BetaResponseInputFile: …` A file input to the model. @@ -70047,7 +81146,7 @@ print(compacted_response) - `file_data: Optional[str]` - The base64-encoded data of the file to be sent to the model. + The content of the file to be sent to the model. - `file_id: Optional[str]` @@ -70071,151 +81170,69 @@ print(compacted_response) - `"explicit"` - - `type: Literal["function_call_output"]` - - The type of the function tool call output. Always `function_call_output`. - - - `"function_call_output"` - - - `id: Optional[str]` - - The unique ID of the function tool call output. Populated when this item is returned via API. - - - `agent: Optional[FunctionCallOutputAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `caller: Optional[FunctionCallOutputCaller]` - - The execution context that produced this tool call. - - - `class FunctionCallOutputCallerDirect: …` - - - `type: Literal["direct"]` - - The caller type. Always `direct`. - - - `"direct"` - - - `class FunctionCallOutputCallerProgram: …` + - `role: Literal["user", "assistant", "system", "developer"]` - - `caller_id: str` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The call ID of the program item that produced this tool call. + - `"user"` - - `type: Literal["program"]` + - `"assistant"` - The caller type. Always `program`. + - `"system"` - - `"program"` + - `"developer"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `phase: Optional[Literal["commentary", "final_answer"]]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `"in_progress"` + - `"commentary"` - - `"completed"` + - `"final_answer"` - - `"incomplete"` + - `type: Optional[Literal["message"]]` - - `class AgentMessage: …` + The type of the message input. Always `message`. - A message routed between agents. + - `"message"` - - `author: str` + - `class Message: …` - The sending agent identity. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `content: List[AgentMessageContent]` + - `content: BetaResponseInputMessageContentList` - Plaintext, image, or encrypted content sent between agents. + A list of one or many input items to the model, containing different content + types. - - `class BetaResponseInputTextContent: …` + - `class BetaResponseInputText: …` A text input to the model. - - `class BetaResponseInputImageContent: …` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `class AgentMessageContentEncryptedContent: …` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `encrypted_content: str` - - Opaque encrypted content. - - - `type: Literal["encrypted_content"]` - - The type of the input item. Always `encrypted_content`. - - - `"encrypted_content"` - - - `recipient: str` - - The destination agent identity. - - - `type: Literal["agent_message"]` - - The item type. Always `agent_message`. - - - `"agent_message"` - - - `id: Optional[str]` - - The unique ID of this agent message item. - - - `agent: Optional[AgentMessageAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `class MultiAgentCall: …` - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - The multi-agent action that was executed. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `arguments: str` + - `class BetaResponseInputImage: …` - The action arguments as a JSON string. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `call_id: str` + - `class BetaResponseInputFile: …` - The unique ID linking this call to its output. + A file input to the model. - - `type: Literal["multi_agent_call"]` + - `role: Literal["user", "system", "developer"]` - The item type. Always `multi_agent_call`. + The role of the message input. One of `user`, `system`, or `developer`. - - `"multi_agent_call"` + - `"user"` - - `id: Optional[str]` + - `"system"` - The unique ID of this multi-agent call. + - `"developer"` - - `agent: Optional[MultiAgentCallAgent]` + - `agent: Optional[MessageAgent]` The agent that produced this item. @@ -70223,47 +81240,46 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput: …` - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The multi-agent action that produced this result. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"spawn_agent"` + - `"in_progress"` - - `"interrupt_agent"` + - `"completed"` - - `"list_agents"` + - `"incomplete"` - - `"send_message"` + - `type: Optional[Literal["message"]]` - - `"followup_task"` + The type of the message input. Always set to `message`. - - `"wait_agent"` + - `"message"` - - `call_id: str` + - `class BetaResponseOutputMessage: …` - The unique ID of the multi-agent call. + An output message from the model. - - `output: List[MultiAgentCallOutputOutput]` + - `id: str` - Text output returned by the multi-agent action. + The unique ID of the output message. - - `text: str` + - `content: List[Content]` - The text content. + The content of the output message. - - `type: Literal["output_text"]` + - `class BetaResponseOutputText: …` - The content type. Always `output_text`. + A text output from the model. - - `"output_text"` + - `annotations: List[Annotation]` - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + The annotations of the text output. - Citations associated with the text content. + - `class AnnotationFileCitation: …` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + A citation to a file. - `file_id: str` @@ -70279,47 +81295,51 @@ print(compacted_response) - `type: Literal["file_citation"]` - The citation type. Always `file_citation`. + The type of the file citation. Always `file_citation`. - `"file_citation"` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + - `class AnnotationURLCitation: …` + + A citation for a web resource used to generate a model response. - `end_index: int` - The index of the last character of the citation in the message. + The index of the last character of the URL citation in the message. - `start_index: int` - The index of the first character of the citation in the message. + The index of the first character of the URL citation in the message. - `title: str` - The title of the cited resource. + The title of the web resource. - `type: Literal["url_citation"]` - The citation type. Always `url_citation`. + The type of the URL citation. Always `url_citation`. - `"url_citation"` - `url: str` - The URL of the cited resource. + The URL of the web resource. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `class AnnotationContainerFileCitation: …` + + A citation for a container file used to generate a model response. - `container_id: str` - The ID of the container. + The ID of the container file. - `end_index: int` - The index of the last character of the citation in the message. + The index of the last character of the container file citation in the message. - `file_id: str` - The ID of the container file. + The ID of the file. - `filename: str` @@ -70327,1181 +81347,1151 @@ print(compacted_response) - `start_index: int` - The index of the first character of the citation in the message. + The index of the first character of the container file citation in the message. - `type: Literal["container_file_citation"]` - The citation type. Always `container_file_citation`. + The type of the container file citation. Always `container_file_citation`. - `"container_file_citation"` - - `type: Literal["multi_agent_call_output"]` + - `class AnnotationFilePath: …` - The item type. Always `multi_agent_call_output`. + A path to a file. - - `"multi_agent_call_output"` + - `file_id: str` - - `id: Optional[str]` + The ID of the file. - The unique ID of this multi-agent call output. + - `index: int` - - `agent: Optional[MultiAgentCallOutputAgent]` + The index of the file in the list of files. - The agent that produced this item. + - `type: Literal["file_path"]` - - `agent_name: str` + The type of the file path. Always `file_path`. - The canonical name of the agent that produced this item. + - `"file_path"` - - `class ToolSearchCall: …` + - `text: str` - - `arguments: object` + The text output from the model. - The arguments supplied to the tool search call. + - `type: Literal["output_text"]` - - `type: Literal["tool_search_call"]` + The type of the output text. Always `output_text`. - The item type. Always `tool_search_call`. + - `"output_text"` - - `"tool_search_call"` + - `logprobs: Optional[List[Logprob]]` - - `id: Optional[str]` + - `token: str` - The unique ID of this tool search call. + - `bytes: List[int]` - - `agent: Optional[ToolSearchCallAgent]` + - `logprob: float` - The agent that produced this item. + - `top_logprobs: List[LogprobTopLogprob]` - - `agent_name: str` + - `token: str` - The canonical name of the agent that produced this item. + - `bytes: List[int]` - - `call_id: Optional[str]` + - `logprob: float` - The unique ID of the tool search call generated by the model. + - `class BetaResponseOutputRefusal: …` - - `execution: Optional[Literal["server", "client"]]` + A refusal from the model. - Whether tool search was executed by the server or by the client. + - `refusal: str` - - `"server"` + The refusal explanation from the model. - - `"client"` + - `type: Literal["refusal"]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The type of the refusal. Always `refusal`. - The status of the tool search call. + - `"refusal"` - - `"in_progress"` + - `role: Literal["assistant"]` - - `"completed"` + The role of the output message. Always `assistant`. - - `"incomplete"` + - `"assistant"` - - `class BetaResponseToolSearchOutputItemParam: …` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `tools: List[BetaTool]` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The loaded tool definitions returned by the tool search output. + - `"in_progress"` - - `class BetaFunctionTool: …` + - `"completed"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `"incomplete"` - - `name: str` + - `type: Literal["message"]` - The name of the function to call. + The type of the output message. Always `message`. - - `parameters: Optional[Dict[str, object]]` + - `"message"` - A JSON schema object describing the parameters of the function. + - `agent: Optional[Agent]` - - `strict: Optional[bool]` + The agent that produced this item. - Whether strict parameter validation is enforced for this function tool. + - `agent_name: str` - - `type: Literal["function"]` + The canonical name of the agent that produced this item. - The type of the function tool. Always `function`. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `"function"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"commentary"` - The tool invocation context(s). + - `"final_answer"` - - `"direct"` + - `class BetaResponseFileSearchToolCall: …` - - `"programmatic"` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `defer_loading: Optional[bool]` + - `id: str` - Whether this function is deferred and loaded via tool search. + The unique ID of the file search tool call. - - `description: Optional[str]` + - `queries: List[str]` - A description of the function. Used by the model to determine whether or not to call the function. + The queries used to search for files. - - `output_schema: Optional[Dict[str, object]]` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `class BetaFileSearchTool: …` + - `"in_progress"` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `"searching"` - - `type: Literal["file_search"]` + - `"completed"` - The type of the file search tool. Always `file_search`. + - `"incomplete"` - - `"file_search"` + - `"failed"` - - `vector_store_ids: List[str]` + - `type: Literal["file_search_call"]` - The IDs of the vector stores to search. + The type of the file search tool call. Always `file_search_call`. - - `filters: Optional[Filters]` + - `"file_search_call"` - A filter to apply. + - `agent: Optional[Agent]` - - `class FiltersComparisonFilter: …` + The agent that produced this item. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `agent_name: str` - - `key: str` + The canonical name of the agent that produced this item. - The key to compare against the value. + - `results: Optional[List[Result]]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The results of the file search tool call. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + 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, booleans, or numbers. - - `"eq"` + - `str` - - `"ne"` + - `float` - - `"gt"` + - `bool` - - `"gte"` + - `file_id: Optional[str]` - - `"lt"` + The unique ID of the file. - - `"lte"` + - `filename: Optional[str]` - - `"in"` + The name of the file. - - `"nin"` + - `score: Optional[float]` - - `value: Union[str, float, bool, List[object]]` + The relevance score of the file - a value between 0 and 1. - The value to compare against the attribute key; supports string, number, or boolean types. + - `text: Optional[str]` - - `str` + The text that was retrieved from the file. - - `float` + - `class BetaResponseComputerToolCall: …` - - `bool` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `List[object]` + - `id: str` - - `class FiltersCompoundFilter: …` + The unique ID of the computer call. - Combine multiple filters using `and` or `or`. + - `call_id: str` - - `filters: List[FiltersCompoundFilterFilter]` + An identifier used when responding to the tool call with output. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `pending_safety_checks: List[PendingSafetyCheck]` - - `class FiltersCompoundFilterFilterComparisonFilter: …` + The pending safety checks for the computer call. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `id: str` - - `key: str` + The ID of the pending safety check. - The key to compare against the value. + - `code: Optional[str]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The type of the pending safety check. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `message: Optional[str]` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + Details about the pending safety check. - - `"eq"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"ne"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"gt"` + - `"in_progress"` - - `"gte"` + - `"completed"` - - `"lt"` + - `"incomplete"` - - `"lte"` + - `type: Literal["computer_call"]` - - `"in"` + The type of the computer call. Always `computer_call`. - - `"nin"` + - `"computer_call"` - - `value: Union[str, float, bool, List[object]]` + - `action: Optional[BetaComputerAction]` - The value to compare against the attribute key; supports string, number, or boolean types. + A click action. - - `str` + - `class Click: …` - - `float` + A click action. - - `bool` + - `button: Literal["left", "right", "wheel", 2 more]` - - `List[object]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `object` + - `"left"` - - `type: Literal["and", "or"]` + - `"right"` - Type of operation: `and` or `or`. + - `"wheel"` - - `"and"` + - `"back"` - - `"or"` + - `"forward"` - - `max_num_results: Optional[int]` + - `type: Literal["click"]` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + Specifies the event type. For a click action, this property is always `click`. - - `ranking_options: Optional[RankingOptions]` + - `"click"` - Ranking options for search. + - `x: int` - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + The x-coordinate where the click occurred. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `y: int` - - `embedding_weight: float` + The y-coordinate where the click occurred. - The weight of the embedding in the reciprocal ranking fusion. + - `keys: Optional[List[str]]` - - `text_weight: float` + The keys being held while clicking. - The weight of the text in the reciprocal ranking fusion. + - `class DoubleClick: …` - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + A double click action. - The ranker to use for the file search. + - `keys: Optional[List[str]]` - - `"auto"` + The keys being held while double-clicking. - - `"default-2024-11-15"` + - `type: Literal["double_click"]` - - `score_threshold: Optional[float]` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `"double_click"` - - `class BetaComputerTool: …` + - `x: int` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The x-coordinate where the double click occurred. - - `type: Literal["computer"]` + - `y: int` - The type of the computer tool. Always `computer`. + The y-coordinate where the double click occurred. - - `"computer"` + - `class Drag: …` - - `class BetaComputerUsePreviewTool: …` + A drag action. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `path: List[DragPath]` - - `display_height: int` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The height of the computer display. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `display_width: int` + - `x: int` - The width of the computer display. + The x-coordinate. - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `y: int` - The type of computer environment to control. + The y-coordinate. - - `"windows"` + - `type: Literal["drag"]` - - `"mac"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"linux"` + - `"drag"` - - `"ubuntu"` + - `keys: Optional[List[str]]` - - `"browser"` + The keys being held while dragging the mouse. - - `type: Literal["computer_use_preview"]` + - `class Keypress: …` - The type of the computer use tool. Always `computer_use_preview`. + A collection of keypresses the model would like to perform. - - `"computer_use_preview"` + - `keys: List[str]` - - `class BetaWebSearchTool: …` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `type: Literal["keypress"]` - - `type: Literal["web_search", "web_search_2025_08_26"]` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"keypress"` - - `"web_search"` + - `class Move: …` - - `"web_search_2025_08_26"` + A mouse move action. - - `filters: Optional[Filters]` + - `type: Literal["move"]` - Filters for the search. + Specifies the event type. For a move action, this property is always set to `move`. - - `allowed_domains: Optional[List[str]]` + - `"move"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `x: int` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The x-coordinate to move to. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `y: int` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The y-coordinate to move to. - - `"low"` + - `keys: Optional[List[str]]` - - `"medium"` + The keys being held while moving the mouse. - - `"high"` + - `class Screenshot: …` - - `user_location: Optional[UserLocation]` + A screenshot action. - The approximate location of the user. + - `type: Literal["screenshot"]` - - `city: Optional[str]` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"screenshot"` - - `country: Optional[str]` + - `class Scroll: …` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + A scroll action. - - `region: Optional[str]` + - `scroll_x: int` - Free text input for the region of the user, e.g. `California`. + The horizontal scroll distance. - - `timezone: Optional[str]` + - `scroll_y: int` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The vertical scroll distance. - - `type: Optional[Literal["approximate"]]` + - `type: Literal["scroll"]` - The type of location approximation. Always `approximate`. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"approximate"` + - `"scroll"` - - `class Mcp: …` + - `x: int` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The x-coordinate where the scroll occurred. - - `server_label: str` + - `y: int` - A label for this MCP server, used to identify it in tool calls. + The y-coordinate where the scroll occurred. - - `type: Literal["mcp"]` + - `keys: Optional[List[str]]` - The type of the MCP tool. Always `mcp`. + The keys being held while scrolling. - - `"mcp"` + - `class Type: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + An action to type in text. - The tool invocation context(s). + - `text: str` - - `"direct"` + The text to type. - - `"programmatic"` + - `type: Literal["type"]` - - `allowed_tools: Optional[McpAllowedTools]` + Specifies the event type. For a type action, this property is always set to `type`. - List of allowed tool names or a filter object. + - `"type"` - - `List[str]` + - `class Wait: …` - A string array of allowed tool names + A wait action. - - `class McpAllowedToolsMcpToolFilter: …` + - `type: Literal["wait"]` - A filter object to specify which tools are allowed. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `read_only: Optional[bool]` + - `"wait"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `actions: Optional[BetaComputerActionList]` - - `tool_names: Optional[List[str]]` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - List of allowed tool names. + - `class Click: …` - - `authorization: Optional[str]` + A click action. + + - `class DoubleClick: …` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + A double click action. - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + - `class Drag: …` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + A drag action. - Currently supported `connector_id` values are: + - `class Keypress: …` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + A collection of keypresses the model would like to perform. - - `"connector_dropbox"` + - `class Move: …` - - `"connector_gmail"` + A mouse move action. - - `"connector_googlecalendar"` + - `class Screenshot: …` - - `"connector_googledrive"` + A screenshot action. - - `"connector_microsoftteams"` + - `class Scroll: …` - - `"connector_outlookcalendar"` + A scroll action. - - `"connector_outlookemail"` + - `class Type: …` - - `"connector_sharepoint"` + An action to type in text. - - `defer_loading: Optional[bool]` + - `class Wait: …` - Whether this MCP tool is deferred and discovered via tool search. + A wait action. - - `headers: Optional[Dict[str, str]]` + - `agent: Optional[Agent]` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The agent that produced this item. - - `require_approval: Optional[McpRequireApproval]` + - `agent_name: str` - Specify which of the MCP server's tools require approval. + The canonical name of the agent that produced this item. - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `class ComputerCallOutput: …` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The output of a computer tool call. - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `call_id: str` - A filter object to specify which tools are allowed. + The ID of the computer tool call that produced the output. - - `read_only: Optional[bool]` + - `output: BetaResponseComputerToolCallOutputScreenshot` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + A computer screenshot image used with the computer use tool. - - `tool_names: Optional[List[str]]` + - `type: Literal["computer_screenshot"]` - List of allowed tool names. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + - `"computer_screenshot"` - A filter object to specify which tools are allowed. + - `file_id: Optional[str]` - - `read_only: Optional[bool]` + The identifier of an uploaded file that contains the screenshot. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `image_url: Optional[str]` - - `tool_names: Optional[List[str]]` + The URL of the screenshot image. - List of allowed tool names. + - `type: Literal["computer_call_output"]` - - `Literal["always", "never"]` + The type of the computer tool call output. Always `computer_call_output`. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `"computer_call_output"` - - `"always"` + - `id: Optional[str]` - - `"never"` + The ID of the computer tool call output. - - `server_description: Optional[str]` + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - Optional description of the MCP server, used to provide more context. + The safety checks reported by the API that have been acknowledged by the developer. - - `server_url: Optional[str]` + - `id: str` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The ID of the pending safety check. - - `tunnel_id: Optional[str]` + - `code: Optional[str]` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + The type of the pending safety check. - - `class CodeInterpreter: …` + - `message: Optional[str]` - A tool that runs Python code to help generate a response to a prompt. + Details about the pending safety check. - - `container: CodeInterpreterContainer` + - `agent: Optional[ComputerCallOutputAgent]` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The agent that produced this item. - - `str` + - `agent_name: str` - The container ID. + The canonical name of the agent that produced this item. - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `type: Literal["auto"]` + - `"in_progress"` - Always `auto`. + - `"completed"` - - `"auto"` + - `"incomplete"` - - `file_ids: Optional[List[str]]` + - `class BetaResponseFunctionWebSearch: …` - An optional list of uploaded files to make available to your code. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `id: str` - The memory limit for the code interpreter container. + The unique ID of the web search tool call. - - `"1g"` + - `action: Action` - - `"4g"` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `"16g"` + - `class ActionSearch: …` - - `"64g"` + Action type "search" - Performs a web search query. - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `type: Literal["search"]` - Network access policy for the container. + The action type. - - `class BetaContainerNetworkPolicyDisabled: …` + - `"search"` - - `type: Literal["disabled"]` + - `queries: Optional[List[str]]` - Disable outbound network access. Always `disabled`. + The search queries. - - `"disabled"` + - `query: Optional[str]` - - `class BetaContainerNetworkPolicyAllowlist: …` + The search query. - - `allowed_domains: List[str]` + - `sources: Optional[List[ActionSearchSource]]` - A list of allowed domains when type is `allowlist`. + The sources used in the search. - - `type: Literal["allowlist"]` + - `type: Literal["url"]` - Allow outbound network access only to specified domains. Always `allowlist`. + The type of source. Always `url`. - - `"allowlist"` + - `"url"` - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `url: str` - Optional domain-scoped secrets for allowlisted domains. + The URL of the source. - - `domain: str` + - `class ActionOpenPage: …` - The domain associated with the secret. + Action type "open_page" - Opens a specific URL from search results. - - `name: str` + - `type: Literal["open_page"]` - The name of the secret to inject for the domain. + The action type. - - `value: str` + - `"open_page"` - The secret value to inject for the domain. + - `url: Optional[str]` - - `type: Literal["code_interpreter"]` + The URL opened by the model. - The type of the code interpreter tool. Always `code_interpreter`. + - `class ActionFindInPage: …` - - `"code_interpreter"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `pattern: str` - The tool invocation context(s). + The pattern or text to search for within the page. - - `"direct"` + - `type: Literal["find_in_page"]` - - `"programmatic"` + The action type. - - `class ProgrammaticToolCalling: …` + - `"find_in_page"` - - `type: Literal["programmatic_tool_calling"]` + - `url: str` - The type of the tool. Always `programmatic_tool_calling`. + The URL of the page searched for the pattern. - - `"programmatic_tool_calling"` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - - `class ImageGeneration: …` + The status of the web search tool call. - A tool that generates images using the GPT image models. + - `"in_progress"` - - `type: Literal["image_generation"]` + - `"searching"` - The type of the image generation tool. Always `image_generation`. + - `"completed"` - - `"image_generation"` + - `"failed"` - - `action: Optional[Literal["generate", "edit", "auto"]]` + - `type: Literal["web_search_call"]` - Whether to generate a new image or edit an existing image. Default: `auto`. + The type of the web search tool call. Always `web_search_call`. - - `"generate"` + - `"web_search_call"` - - `"edit"` + - `agent: Optional[Agent]` - - `"auto"` + The agent that produced this item. - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + - `agent_name: str` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The canonical name of the agent that produced this item. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `class BetaResponseFunctionToolCall: …` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `"transparent"` + - `arguments: str` - - `"opaque"` + A JSON string of the arguments to pass to the function. - - `"auto"` + - `call_id: str` - - `input_fidelity: Optional[Literal["high", "low"]]` + The unique ID of the function tool call generated by the model. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `name: str` - - `"high"` + The name of the function to run. - - `"low"` + - `type: Literal["function_call"]` - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + The type of the function tool call. Always `function_call`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"function_call"` - - `file_id: Optional[str]` + - `id: Optional[str]` - File ID for the mask image. + The unique ID of the function tool call. - - `image_url: Optional[str]` + - `agent: Optional[Agent]` - Base64-encoded mask image. + The agent that produced this item. - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + - `agent_name: str` - The image generation model to use. Default: `gpt-image-1`. + The canonical name of the agent that produced this item. - - `str` + - `caller: Optional[Caller]` - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + The execution context that produced this tool call. - The image generation model to use. Default: `gpt-image-1`. + - `class CallerDirect: …` - - `"gpt-image-1"` + - `type: Literal["direct"]` - - `"gpt-image-1-mini"` + - `"direct"` - - `"gpt-image-2"` + - `class CallerProgram: …` - - `"gpt-image-2-2026-04-21"` + - `caller_id: str` - - `"gpt-image-1.5"` + The call ID of the program item that produced this tool call. - - `"chatgpt-image-latest"` + - `type: Literal["program"]` - - `moderation: Optional[Literal["auto", "low"]]` + - `"program"` - Moderation level for the generated image. Default: `auto`. + - `namespace: Optional[str]` - - `"auto"` + The namespace of the function to run. - - `"low"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `output_compression: Optional[int]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Compression level for the output image. Default: 100. + - `"in_progress"` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + - `"completed"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"incomplete"` - - `"png"` + - `class FunctionCallOutput: …` - - `"webp"` + The output of a function tool call. - - `"jpeg"` + - `call_id: str` - - `partial_images: Optional[int]` + The unique ID of the function tool call generated by the model. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + Text, image, or file output of the function tool call. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `str` - - `"low"` + A JSON string of the output of the function tool call. - - `"medium"` + - `List[BetaResponseFunctionCallOutputItem]` - - `"high"` + - `class BetaResponseInputTextContent: …` - - `"auto"` + A text input to the model. - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + - `text: str` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The text input to the model. - - `str` + - `type: Literal["input_text"]` - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + The type of the input item. Always `input_text`. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"input_text"` - - `"1024x1024"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"1024x1536"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"1536x1024"` + - `mode: Literal["explicit"]` - - `"auto"` + The breakpoint mode. Always `explicit`. - - `class LocalShell: …` + - `"explicit"` - A tool that allows the model to execute shell commands in a local environment. + - `class BetaResponseInputImageContent: …` - - `type: Literal["local_shell"]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The type of the local shell tool. Always `local_shell`. + - `type: Literal["input_image"]` - - `"local_shell"` + The type of the input item. Always `input_image`. - - `class BetaFunctionShellTool: …` + - `"input_image"` - A tool that allows the model to execute shell commands. + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - - `type: Literal["shell"]` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The type of the shell tool. Always `shell`. + - `"low"` - - `"shell"` + - `"high"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"auto"` - The tool invocation context(s). + - `"original"` - - `"direct"` + - `file_id: Optional[str]` - - `"programmatic"` + The ID of the file to be sent to the model. - - `environment: Optional[Environment]` + - `image_url: Optional[str]` - - `class BetaContainerAuto: …` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: Literal["container_auto"]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Automatically creates a container for this request + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"container_auto"` + - `mode: Literal["explicit"]` - - `file_ids: Optional[List[str]]` + The breakpoint mode. Always `explicit`. - An optional list of uploaded files to make available to your code. + - `"explicit"` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `class BetaResponseInputFileContent: …` - The memory limit for the container. + A file input to the model. - - `"1g"` + - `type: Literal["input_file"]` - - `"4g"` + The type of the input item. Always `input_file`. - - `"16g"` + - `"input_file"` - - `"64g"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `network_policy: Optional[NetworkPolicy]` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - Network access policy for the container. + - `"auto"` - - `class BetaContainerNetworkPolicyDisabled: …` + - `"low"` - - `class BetaContainerNetworkPolicyAllowlist: …` + - `"high"` - - `skills: Optional[List[Skill]]` + - `file_data: Optional[str]` - An optional list of skills referenced by id or inline data. + The base64-encoded data of the file to be sent to the model. - - `class BetaSkillReference: …` + - `file_id: Optional[str]` - - `skill_id: str` + The ID of the file to be sent to the model. - The ID of the referenced skill. + - `file_url: Optional[str]` - - `type: Literal["skill_reference"]` + The URL of the file to be sent to the model. - References a skill created with the /v1/skills endpoint. + - `filename: Optional[str]` - - `"skill_reference"` + The name of the file to be sent to the model. - - `version: Optional[str]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaInlineSkill: …` + - `mode: Literal["explicit"]` - - `description: str` + The breakpoint mode. Always `explicit`. - The description of the skill. + - `"explicit"` - - `name: str` + - `type: Literal["function_call_output"]` - The name of the skill. + The type of the function tool call output. Always `function_call_output`. - - `source: BetaInlineSkillSource` + - `"function_call_output"` - Inline skill payload + - `id: Optional[str]` - - `data: str` + The unique ID of the function tool call output. Populated when this item is returned via API. - Base64-encoded skill zip bundle. + - `agent: Optional[FunctionCallOutputAgent]` - - `media_type: Literal["application/zip"]` + The agent that produced this item. - The media type of the inline skill payload. Must be `application/zip`. + - `agent_name: str` - - `"application/zip"` + The canonical name of the agent that produced this item. - - `type: Literal["base64"]` + - `caller: Optional[FunctionCallOutputCaller]` - The type of the inline skill source. Must be `base64`. + The execution context that produced this tool call. - - `"base64"` + - `class FunctionCallOutputCallerDirect: …` - - `type: Literal["inline"]` + - `type: Literal["direct"]` - Defines an inline skill for this request. + The caller type. Always `direct`. - - `"inline"` + - `"direct"` - - `class BetaLocalEnvironment: …` + - `class FunctionCallOutputCallerProgram: …` - - `type: Literal["local"]` + - `caller_id: str` - Use a local computer environment. + The call ID of the program item that produced this tool call. - - `"local"` + - `type: Literal["program"]` - - `skills: Optional[List[BetaLocalSkill]]` + The caller type. Always `program`. - An optional list of skills. + - `"program"` - - `description: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The description of the skill. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `name: str` + - `"in_progress"` - The name of the skill. + - `"completed"` - - `path: str` + - `"incomplete"` - The path to the directory containing the skill. + - `class AgentMessage: …` - - `class BetaContainerReference: …` + A message routed between agents. - - `container_id: str` + - `author: str` - The ID of the referenced container. + The sending agent identity. - - `type: Literal["container_reference"]` + - `content: List[AgentMessageContent]` - References a container created with the /v1/containers endpoint + Plaintext, image, or encrypted content sent between agents. - - `"container_reference"` + - `class BetaResponseInputTextContent: …` - - `class BetaCustomTool: …` + A text input to the model. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `class BetaResponseInputImageContent: …` - - `name: str` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The name of the custom tool, used to identify it in tool calls. + - `class AgentMessageContentEncryptedContent: …` - - `type: Literal["custom"]` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The type of the custom tool. Always `custom`. + - `encrypted_content: str` - - `"custom"` + Opaque encrypted content. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["encrypted_content"]` - The tool invocation context(s). + The type of the input item. Always `encrypted_content`. - - `"direct"` + - `"encrypted_content"` - - `"programmatic"` + - `recipient: str` - - `defer_loading: Optional[bool]` + The destination agent identity. - Whether this tool should be deferred and discovered via tool search. + - `type: Literal["agent_message"]` - - `description: Optional[str]` + The item type. Always `agent_message`. - Optional description of the custom tool, used to provide more context. + - `"agent_message"` - - `format: Optional[Format]` + - `id: Optional[str]` - The input format for the custom tool. Default is unconstrained text. + The unique ID of this agent message item. - - `class FormatText: …` + - `agent: Optional[AgentMessageAgent]` - Unconstrained free-form text. + The agent that produced this item. - - `type: Literal["text"]` + - `agent_name: str` - Unconstrained text format. Always `text`. + The canonical name of the agent that produced this item. - - `"text"` + - `class MultiAgentCall: …` - - `class FormatGrammar: …` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - A grammar defined by the user. + The multi-agent action that was executed. - - `definition: str` + - `"spawn_agent"` - The grammar definition. + - `"interrupt_agent"` - - `syntax: Literal["lark", "regex"]` + - `"list_agents"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"send_message"` - - `"lark"` + - `"followup_task"` - - `"regex"` + - `"wait_agent"` - - `type: Literal["grammar"]` + - `arguments: str` - Grammar format. Always `grammar`. + The action arguments as a JSON string. - - `"grammar"` + - `call_id: str` - - `class BetaNamespaceTool: …` + The unique ID linking this call to its output. - Groups function/custom tools under a shared namespace. + - `type: Literal["multi_agent_call"]` - - `description: str` + The item type. Always `multi_agent_call`. - A description of the namespace shown to the model. + - `"multi_agent_call"` - - `name: str` + - `id: Optional[str]` - The namespace name used in tool calls (for example, `crm`). + The unique ID of this multi-agent call. - - `tools: List[Tool]` + - `agent: Optional[MultiAgentCallAgent]` - The function/custom tools available inside this namespace. + The agent that produced this item. - - `class ToolFunction: …` + - `agent_name: str` - - `name: str` + The canonical name of the agent that produced this item. - - `type: Literal["function"]` + - `class MultiAgentCallOutput: …` - - `"function"` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The multi-agent action that produced this result. - The tool invocation context(s). + - `"spawn_agent"` - - `"direct"` + - `"interrupt_agent"` - - `"programmatic"` + - `"list_agents"` - - `defer_loading: Optional[bool]` + - `"send_message"` - Whether this function should be deferred and discovered via tool search. + - `"followup_task"` - - `description: Optional[str]` + - `"wait_agent"` - - `output_schema: Optional[Dict[str, object]]` + - `call_id: str` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The unique ID of the multi-agent call. - - `parameters: Optional[object]` + - `output: List[MultiAgentCallOutputOutput]` - - `strict: Optional[bool]` + Text output returned by the multi-agent action. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `text: str` - - `class BetaCustomTool: …` + The text content. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: Literal["output_text"]` - - `type: Literal["namespace"]` + The content type. Always `output_text`. - The type of the tool. Always `namespace`. + - `"output_text"` - - `"namespace"` + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - - `class BetaToolSearchTool: …` + Citations associated with the text content. - Hosted or BYOT tool search configuration for deferred tools. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - - `type: Literal["tool_search"]` + - `file_id: str` - The type of the tool. Always `tool_search`. + The ID of the file. - - `"tool_search"` + - `filename: str` - - `description: Optional[str]` + The filename of the file cited. - Description shown to the model for a client-executed tool search tool. + - `index: int` - - `execution: Optional[Literal["server", "client"]]` + The index of the file in the list of files. - Whether tool search is executed by the server or by the client. + - `type: Literal["file_citation"]` - - `"server"` + The citation type. Always `file_citation`. - - `"client"` + - `"file_citation"` - - `parameters: Optional[object]` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` - Parameter schema for a client-executed tool search tool. + - `end_index: int` - - `class BetaWebSearchPreviewTool: …` + The index of the last character of the citation in the message. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `start_index: int` - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + The index of the first character of the citation in the message. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `title: str` - - `"web_search_preview"` + The title of the cited resource. - - `"web_search_preview_2025_03_11"` + - `type: Literal["url_citation"]` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + The citation type. Always `url_citation`. - - `"text"` + - `"url_citation"` - - `"image"` + - `url: str` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + The URL of the cited resource. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` - - `"low"` + - `container_id: str` - - `"medium"` + The ID of the container. - - `"high"` + - `end_index: int` - - `user_location: Optional[UserLocation]` + The index of the last character of the citation in the message. - The user's location. + - `file_id: str` - - `type: Literal["approximate"]` + The ID of the container file. - The type of location approximation. Always `approximate`. + - `filename: str` - - `"approximate"` + The filename of the container file cited. - - `city: Optional[str]` + - `start_index: int` - Free text input for the city of the user, e.g. `San Francisco`. + The index of the first character of the citation in the message. - - `country: Optional[str]` + - `type: Literal["container_file_citation"]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The citation type. Always `container_file_citation`. - - `region: Optional[str]` + - `"container_file_citation"` - Free text input for the region of the user, e.g. `California`. + - `type: Literal["multi_agent_call_output"]` - - `timezone: Optional[str]` + The item type. Always `multi_agent_call_output`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"multi_agent_call_output"` - - `class BetaApplyPatchTool: …` + - `id: Optional[str]` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of this multi-agent call output. - - `type: Literal["apply_patch"]` + - `agent: Optional[MultiAgentCallOutputAgent]` - The type of the tool. Always `apply_patch`. + The agent that produced this item. - - `"apply_patch"` + - `agent_name: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `class ToolSearchCall: …` - - `"direct"` + - `arguments: object` - - `"programmatic"` + The arguments supplied to the tool search call. - - `type: Literal["tool_search_output"]` + - `type: Literal["tool_search_call"]` - The item type. Always `tool_search_output`. + The item type. Always `tool_search_call`. - - `"tool_search_output"` + - `"tool_search_call"` - `id: Optional[str]` - The unique ID of this tool search output. + The unique ID of this tool search call. - - `agent: Optional[Agent]` + - `agent: Optional[ToolSearchCallAgent]` The agent that produced this item. @@ -71523,7 +82513,7 @@ print(compacted_response) - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the tool search output. + The status of the tool search call. - `"in_progress"` @@ -71531,1097 +82521,1117 @@ print(compacted_response) - `"incomplete"` - - `class AdditionalTools: …` - - - `role: Literal["developer"]` - - The role that provided the additional tools. Only `developer` is supported. - - - `"developer"` + - `class BetaResponseToolSearchOutputItemParam: …` - `tools: List[BetaTool]` - A list of additional tools made available at this item. + The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool: …` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `class BetaFileSearchTool: …` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - - `class BetaComputerTool: …` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaComputerUsePreviewTool: …` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaWebSearchTool: …` - - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `class Mcp: …` + - `name: str` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The name of the function to call. - - `class CodeInterpreter: …` + - `parameters: Optional[Dict[str, object]]` - A tool that runs Python code to help generate a response to a prompt. + A JSON schema object describing the parameters of the function. - - `class ProgrammaticToolCalling: …` + - `strict: Optional[bool]` - - `class ImageGeneration: …` + Whether strict parameter validation is enforced for this function tool. - A tool that generates images using the GPT image models. + - `type: Literal["function"]` - - `class LocalShell: …` + The type of the function tool. Always `function`. - A tool that allows the model to execute shell commands in a local environment. + - `"function"` - - `class BetaFunctionShellTool: …` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - A tool that allows the model to execute shell commands. + The tool invocation context(s). - - `class BetaCustomTool: …` + - `"direct"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"programmatic"` - - `class BetaNamespaceTool: …` + - `defer_loading: Optional[bool]` - Groups function/custom tools under a shared namespace. + Whether this function is deferred and loaded via tool search. - - `class BetaToolSearchTool: …` + - `description: Optional[str]` - Hosted or BYOT tool search configuration for deferred tools. + A description of the function. Used by the model to determine whether or not to call the function. - - `class BetaWebSearchPreviewTool: …` + - `output_schema: Optional[Dict[str, object]]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `class BetaApplyPatchTool: …` + - `class BetaFileSearchTool: …` - Allows the assistant to create, delete, or update files using unified diffs. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: Literal["additional_tools"]` + - `type: Literal["file_search"]` - The item type. Always `additional_tools`. + The type of the file search tool. Always `file_search`. - - `"additional_tools"` + - `"file_search"` - - `id: Optional[str]` + - `vector_store_ids: List[str]` - The unique ID of this additional tools item. + The IDs of the vector stores to search. - - `agent: Optional[AdditionalToolsAgent]` + - `filters: Optional[Filters]` - The agent that produced this item. + A filter to apply. - - `agent_name: str` + - `class FiltersComparisonFilter: …` - The canonical name of the agent that produced this item. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `class BetaResponseReasoningItem: …` + - `key: str` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The key to compare against the value. - - `id: str` + - `type: Literal["eq", "ne", "gt", 5 more]` - The unique identifier of the reasoning content. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `summary: List[Summary]` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - Reasoning summary content. + - `"eq"` - - `text: str` + - `"ne"` - A summary of the reasoning output from the model so far. + - `"gt"` - - `type: Literal["summary_text"]` + - `"gte"` - The type of the object. Always `summary_text`. + - `"lt"` - - `"summary_text"` + - `"lte"` - - `type: Literal["reasoning"]` + - `"in"` - The type of the object. Always `reasoning`. + - `"nin"` - - `"reasoning"` + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `agent: Optional[Agent]` + The value to compare against the attribute key; supports string, number, or boolean types. - The agent that produced this item. + - `str` - - `agent_name: str` + - `float` - The canonical name of the agent that produced this item. + - `bool` - - `content: Optional[List[Content]]` + - `List[Union[str, float]]` - Reasoning text content. + - `str` - - `text: str` + - `float` - The reasoning text from the model. + - `class FiltersCompoundFilter: …` - - `type: Literal["reasoning_text"]` + Combine multiple filters using `and` or `or`. - The type of the reasoning text. Always `reasoning_text`. + - `filters: List[FiltersCompoundFilterFilter]` - - `"reasoning_text"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `encrypted_content: Optional[str]` + - `class FiltersCompoundFilterFilterComparisonFilter: …` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `key: str` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The key to compare against the value. - - `"in_progress"` + - `type: Literal["eq", "ne", "gt", 5 more]` - - `"completed"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"incomplete"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `class BetaResponseCompactionItemParam: …` + - `"eq"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"ne"` - - `encrypted_content: str` + - `"gt"` - The encrypted content of the compaction summary. + - `"gte"` - - `type: Literal["compaction"]` + - `"lt"` - The type of the item. Always `compaction`. + - `"lte"` - - `"compaction"` + - `"in"` - - `id: Optional[str]` + - `"nin"` - The ID of the compaction item. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `agent: Optional[Agent]` + The value to compare against the attribute key; supports string, number, or boolean types. - The agent that produced this item. + - `str` - - `agent_name: str` + - `float` - The canonical name of the agent that produced this item. + - `bool` - - `class ImageGenerationCall: …` + - `List[Union[str, float]]` - An image generation request made by the model. + - `str` - - `id: str` + - `float` - The unique ID of the image generation call. + - `object` - - `result: Optional[str]` + - `type: Literal["and", "or"]` - The generated image encoded in base64. + Type of operation: `and` or `or`. - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `"and"` - The status of the image generation call. + - `"or"` - - `"in_progress"` + - `max_num_results: Optional[int]` - - `"completed"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"generating"` + - `ranking_options: Optional[RankingOptions]` - - `"failed"` + Ranking options for search. - - `type: Literal["image_generation_call"]` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - The type of the image generation call. Always `image_generation_call`. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"image_generation_call"` + - `embedding_weight: float` - - `agent: Optional[ImageGenerationCallAgent]` + The weight of the embedding in the reciprocal ranking fusion. - The agent that produced this item. + - `text_weight: float` - - `agent_name: str` + The weight of the text in the reciprocal ranking fusion. - The canonical name of the agent that produced this item. + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - - `class BetaResponseCodeInterpreterToolCall: …` + The ranker to use for the file search. - A tool call to run code. + - `"auto"` - - `id: str` + - `"default-2024-11-15"` - The unique ID of the code interpreter tool call. + - `score_threshold: Optional[float]` - - `code: Optional[str]` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The code to run, or null if not available. + - `class BetaComputerTool: …` - - `container_id: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The ID of the container used to run the code. + - `type: Literal["computer"]` - - `outputs: Optional[List[Output]]` + The type of the computer tool. Always `computer`. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"computer"` - - `class OutputLogs: …` + - `class BetaComputerUsePreviewTool: …` - The logs output from the code interpreter. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `logs: str` + - `display_height: int` - The logs output from the code interpreter. + The height of the computer display. - - `type: Literal["logs"]` + - `display_width: int` - The type of the output. Always `logs`. + The width of the computer display. - - `"logs"` + - `environment: Literal["windows", "mac", "linux", 2 more]` - - `class OutputImage: …` + The type of computer environment to control. - The image output from the code interpreter. + - `"windows"` - - `type: Literal["image"]` + - `"mac"` - The type of the output. Always `image`. + - `"linux"` - - `"image"` + - `"ubuntu"` - - `url: str` + - `"browser"` - The URL of the image output from the code interpreter. + - `type: Literal["computer_use_preview"]` - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + The type of the computer use tool. Always `computer_use_preview`. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"computer_use_preview"` - - `"in_progress"` + - `class BetaWebSearchTool: …` - - `"completed"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"incomplete"` + - `type: Literal["web_search", "web_search_2025_08_26"]` - - `"interpreting"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"failed"` + - `"web_search"` - - `type: Literal["code_interpreter_call"]` + - `"web_search_2025_08_26"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `filters: Optional[Filters]` - - `"code_interpreter_call"` + Filters for the search. - - `agent: Optional[Agent]` + - `allowed_domains: Optional[List[str]]` - The agent that produced this item. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `agent_name: str` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The canonical name of the agent that produced this item. + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `class LocalShellCall: …` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - A tool call to run a command on the local shell. + - `"low"` - - `id: str` + - `"medium"` - The unique ID of the local shell call. + - `"high"` - - `action: LocalShellCallAction` + - `user_location: Optional[UserLocation]` - Execute a shell command on the server. + The approximate location of the user. - - `command: List[str]` + - `city: Optional[str]` - The command to run. + Free text input for the city of the user, e.g. `San Francisco`. - - `env: Dict[str, str]` + - `country: Optional[str]` - Environment variables to set for the command. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `type: Literal["exec"]` + - `region: Optional[str]` - The type of the local shell action. Always `exec`. + Free text input for the region of the user, e.g. `California`. - - `"exec"` + - `timezone: Optional[str]` - - `timeout_ms: Optional[int]` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Optional timeout in milliseconds for the command. + - `type: Optional[Literal["approximate"]]` - - `user: Optional[str]` + The type of location approximation. Always `approximate`. - Optional user to run the command as. + - `"approximate"` - - `working_directory: Optional[str]` + - `class Mcp: …` - Optional working directory to run the command in. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `call_id: str` + - `server_label: str` - The unique ID of the local shell tool call generated by the model. + A label for this MCP server, used to identify it in tool calls. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `type: Literal["mcp"]` - The status of the local shell call. + The type of the MCP tool. Always `mcp`. - - `"in_progress"` + - `"mcp"` - - `"completed"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"incomplete"` + The tool invocation context(s). - - `type: Literal["local_shell_call"]` + - `"direct"` - The type of the local shell call. Always `local_shell_call`. + - `"programmatic"` - - `"local_shell_call"` + - `allowed_tools: Optional[McpAllowedTools]` - - `agent: Optional[LocalShellCallAgent]` + List of allowed tool names or a filter object. - The agent that produced this item. + - `List[str]` - - `agent_name: str` + A string array of allowed tool names - The canonical name of the agent that produced this item. + - `class McpAllowedToolsMcpToolFilter: …` - - `class LocalShellCallOutput: …` + A filter object to specify which tools are allowed. - The output of a local shell tool call. + - `read_only: Optional[bool]` - - `id: str` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The unique ID of the local shell tool call generated by the model. + - `tool_names: Optional[List[str]]` - - `output: str` + List of allowed tool names. - A JSON string of the output of the local shell tool call. + - `authorization: Optional[str]` - - `type: Literal["local_shell_call_output"]` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `"local_shell_call_output"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `agent: Optional[LocalShellCallOutputAgent]` + Currently supported `connector_id` values are: - The agent that produced this item. + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `agent_name: str` + - `"connector_dropbox"` - The canonical name of the agent that produced this item. + - `"connector_gmail"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"connector_googlecalendar"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"connector_googledrive"` - - `"in_progress"` + - `"connector_microsoftteams"` - - `"completed"` + - `"connector_outlookcalendar"` - - `"incomplete"` + - `"connector_outlookemail"` - - `class ShellCall: …` + - `"connector_sharepoint"` - A tool representing a request to execute one or more shell commands. + - `defer_loading: Optional[bool]` - - `action: ShellCallAction` + Whether this MCP tool is deferred and discovered via tool search. - The shell commands and limits that describe how to run the tool call. + - `headers: Optional[Dict[str, str]]` - - `commands: List[str]` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Ordered shell commands for the execution environment to run. + - `require_approval: Optional[McpRequireApproval]` - - `max_output_length: Optional[int]` + Specify which of the MCP server's tools require approval. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `class McpRequireApprovalMcpToolApprovalFilter: …` - - `timeout_ms: Optional[int]` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `call_id: str` + A filter object to specify which tools are allowed. - The unique ID of the shell tool call generated by the model. + - `read_only: Optional[bool]` - - `type: Literal["shell_call"]` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The type of the item. Always `shell_call`. + - `tool_names: Optional[List[str]]` - - `"shell_call"` + List of allowed tool names. - - `id: Optional[str]` + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - The unique ID of the shell tool call. Populated when this item is returned via API. + A filter object to specify which tools are allowed. - - `agent: Optional[ShellCallAgent]` + - `read_only: Optional[bool]` - The agent that produced this item. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `agent_name: str` + - `tool_names: Optional[List[str]]` - The canonical name of the agent that produced this item. + List of allowed tool names. - - `caller: Optional[ShellCallCaller]` + - `Literal["always", "never"]` - The execution context that produced this tool call. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `class ShellCallCallerDirect: …` + - `"always"` - - `type: Literal["direct"]` + - `"never"` - The caller type. Always `direct`. + - `server_description: Optional[str]` - - `"direct"` + Optional description of the MCP server, used to provide more context. - - `class ShellCallCallerProgram: …` + - `server_url: Optional[str]` - - `caller_id: str` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The call ID of the program item that produced this tool call. + - `tunnel_id: Optional[str]` - - `type: Literal["program"]` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The caller type. Always `program`. + - `class CodeInterpreter: …` - - `"program"` + A tool that runs Python code to help generate a response to a prompt. - - `environment: Optional[ShellCallEnvironment]` + - `container: CodeInterpreterContainer` - The environment to execute the shell commands in. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `class BetaLocalEnvironment: …` + - `str` - - `class BetaContainerReference: …` + The container ID. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"in_progress"` + - `type: Literal["auto"]` - - `"completed"` + Always `auto`. - - `"incomplete"` + - `"auto"` - - `class ShellCallOutput: …` + - `file_ids: Optional[List[str]]` - The streamed output items emitted by a shell tool call. + An optional list of uploaded files to make available to your code. - - `call_id: str` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The unique ID of the shell tool call generated by the model. + The memory limit for the code interpreter container. - - `output: List[BetaResponseFunctionShellCallOutputContent]` + - `"1g"` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"4g"` - - `outcome: Outcome` + - `"16g"` - The exit or timeout outcome associated with this shell call. + - `"64g"` - - `class OutcomeTimeout: …` + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - Indicates that the shell call exceeded its configured time limit. + Network access policy for the container. - - `type: Literal["timeout"]` + - `class BetaContainerNetworkPolicyDisabled: …` - The outcome type. Always `timeout`. + - `type: Literal["disabled"]` - - `"timeout"` + Disable outbound network access. Always `disabled`. - - `class OutcomeExit: …` + - `"disabled"` - Indicates that the shell commands finished and returned an exit code. + - `class BetaContainerNetworkPolicyAllowlist: …` - - `exit_code: int` + - `allowed_domains: List[str]` - The exit code returned by the shell process. + A list of allowed domains when type is `allowlist`. - - `type: Literal["exit"]` + - `type: Literal["allowlist"]` - The outcome type. Always `exit`. + Allow outbound network access only to specified domains. Always `allowlist`. - - `"exit"` + - `"allowlist"` - - `stderr: str` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - Captured stderr output for the shell call. + Optional domain-scoped secrets for allowlisted domains. - - `stdout: str` + - `domain: str` - Captured stdout output for the shell call. + The domain associated with the secret. - - `type: Literal["shell_call_output"]` + - `name: str` - The type of the item. Always `shell_call_output`. + The name of the secret to inject for the domain. - - `"shell_call_output"` + - `value: str` - - `id: Optional[str]` + The secret value to inject for the domain. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `type: Literal["code_interpreter"]` - - `agent: Optional[ShellCallOutputAgent]` + The type of the code interpreter tool. Always `code_interpreter`. - The agent that produced this item. + - `"code_interpreter"` - - `agent_name: str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The canonical name of the agent that produced this item. + The tool invocation context(s). - - `caller: Optional[ShellCallOutputCaller]` + - `"direct"` - The execution context that produced this tool call. + - `"programmatic"` - - `class ShellCallOutputCallerDirect: …` + - `class ProgrammaticToolCalling: …` - - `type: Literal["direct"]` + - `type: Literal["programmatic_tool_calling"]` - The caller type. Always `direct`. + The type of the tool. Always `programmatic_tool_calling`. - - `"direct"` + - `"programmatic_tool_calling"` - - `class ShellCallOutputCallerProgram: …` + - `class ImageGeneration: …` - - `caller_id: str` + A tool that generates images using the GPT image models. - The call ID of the program item that produced this tool call. + - `type: Literal["image_generation"]` - - `type: Literal["program"]` + The type of the image generation tool. Always `image_generation`. - The caller type. Always `program`. + - `"image_generation"` - - `"program"` + - `action: Optional[Literal["generate", "edit", "auto"]]` - - `max_output_length: Optional[int]` + Whether to generate a new image or edit an existing image. Default: `auto`. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `"generate"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"edit"` - The status of the shell call output. + - `"auto"` - - `"in_progress"` + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `"completed"` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `"incomplete"` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `class ApplyPatchCall: …` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - A tool call representing a request to create, delete, or update files using diff patches. + - `"transparent"` - - `call_id: str` + - `"opaque"` - The unique ID of the apply patch tool call generated by the model. + - `"auto"` - - `operation: ApplyPatchCallOperation` + - `input_fidelity: Optional[Literal["high", "low"]]` - The specific create, delete, or update instruction for the apply_patch tool call. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `class ApplyPatchCallOperationCreateFile: …` + - `"high"` - Instruction for creating a new file via the apply_patch tool. + - `"low"` - - `diff: str` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - Unified diff content to apply when creating the file. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `path: str` + - `file_id: Optional[str]` - Path of the file to create relative to the workspace root. + File ID for the mask image. - - `type: Literal["create_file"]` + - `image_url: Optional[str]` - The operation type. Always `create_file`. + Base64-encoded mask image. - - `"create_file"` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - - `class ApplyPatchCallOperationDeleteFile: …` + The image generation model to use. Default: `gpt-image-1`. - Instruction for deleting an existing file via the apply_patch tool. + - `str` - - `path: str` + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - Path of the file to delete relative to the workspace root. + The image generation model to use. Default: `gpt-image-1`. - - `type: Literal["delete_file"]` + - `"gpt-image-1"` - The operation type. Always `delete_file`. + - `"gpt-image-1-mini"` - - `"delete_file"` + - `"gpt-image-2"` - - `class ApplyPatchCallOperationUpdateFile: …` + - `"gpt-image-2-2026-04-21"` - Instruction for updating an existing file via the apply_patch tool. + - `"gpt-image-1.5"` - - `diff: str` + - `"chatgpt-image-latest"` - Unified diff content to apply to the existing file. + - `moderation: Optional[Literal["auto", "low"]]` - - `path: str` + Moderation level for the generated image. Default: `auto`. - Path of the file to update relative to the workspace root. + - `"auto"` - - `type: Literal["update_file"]` + - `"low"` - The operation type. Always `update_file`. + - `output_compression: Optional[int]` - - `"update_file"` + Compression level for the output image. Default: 100. - - `status: Literal["in_progress", "completed"]` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"in_progress"` + - `"png"` - - `"completed"` + - `"webp"` - - `type: Literal["apply_patch_call"]` + - `"jpeg"` - The type of the item. Always `apply_patch_call`. + - `partial_images: Optional[int]` - - `"apply_patch_call"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `id: Optional[str]` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `agent: Optional[ApplyPatchCallAgent]` + - `"low"` - The agent that produced this item. + - `"medium"` - - `agent_name: str` + - `"high"` - The canonical name of the agent that produced this item. + - `"auto"` - - `caller: Optional[ApplyPatchCallCaller]` + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - The execution context that produced this tool call. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `class ApplyPatchCallCallerDirect: …` + - `str` - - `type: Literal["direct"]` + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - The caller type. Always `direct`. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `"direct"` + - `"1024x1024"` - - `class ApplyPatchCallCallerProgram: …` + - `"1024x1536"` - - `caller_id: str` + - `"1536x1024"` - The call ID of the program item that produced this tool call. + - `"auto"` - - `type: Literal["program"]` + - `class LocalShell: …` - The caller type. Always `program`. + A tool that allows the model to execute shell commands in a local environment. - - `"program"` + - `type: Literal["local_shell"]` - - `class ApplyPatchCallOutput: …` + The type of the local shell tool. Always `local_shell`. - The streamed output emitted by an apply patch tool call. + - `"local_shell"` - - `call_id: str` + - `class BetaFunctionShellTool: …` - The unique ID of the apply patch tool call generated by the model. + A tool that allows the model to execute shell commands. - - `status: Literal["completed", "failed"]` + - `type: Literal["shell"]` - The status of the apply patch tool call output. One of `completed` or `failed`. + The type of the shell tool. Always `shell`. - - `"completed"` + - `"shell"` - - `"failed"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `type: Literal["apply_patch_call_output"]` + The tool invocation context(s). - The type of the item. Always `apply_patch_call_output`. + - `"direct"` - - `"apply_patch_call_output"` + - `"programmatic"` - - `id: Optional[str]` + - `environment: Optional[Environment]` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `class BetaContainerAuto: …` - - `agent: Optional[ApplyPatchCallOutputAgent]` + - `type: Literal["container_auto"]` - The agent that produced this item. + Automatically creates a container for this request - - `agent_name: str` + - `"container_auto"` - The canonical name of the agent that produced this item. + - `file_ids: Optional[List[str]]` - - `caller: Optional[ApplyPatchCallOutputCaller]` + An optional list of uploaded files to make available to your code. - The execution context that produced this tool call. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `class ApplyPatchCallOutputCallerDirect: …` + The memory limit for the container. - - `type: Literal["direct"]` + - `"1g"` - The caller type. Always `direct`. + - `"4g"` - - `"direct"` + - `"16g"` - - `class ApplyPatchCallOutputCallerProgram: …` + - `"64g"` - - `caller_id: str` + - `network_policy: Optional[NetworkPolicy]` - The call ID of the program item that produced this tool call. + Network access policy for the container. - - `type: Literal["program"]` + - `class BetaContainerNetworkPolicyDisabled: …` - The caller type. Always `program`. + - `class BetaContainerNetworkPolicyAllowlist: …` - - `"program"` + - `skills: Optional[List[Skill]]` - - `output: Optional[str]` + An optional list of skills referenced by id or inline data. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `class BetaSkillReference: …` - - `class McpListTools: …` + - `skill_id: str` - A list of tools available on an MCP server. + The ID of the referenced skill. - - `id: str` + - `type: Literal["skill_reference"]` - The unique ID of the list. + References a skill created with the /v1/skills endpoint. - - `server_label: str` + - `"skill_reference"` - The label of the MCP server. + - `version: Optional[str]` - - `tools: List[McpListToolsTool]` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The tools available on the server. + - `class BetaInlineSkill: …` - - `input_schema: object` + - `description: str` - The JSON schema describing the tool's input. + The description of the skill. - `name: str` - The name of the tool. - - - `annotations: Optional[object]` + The name of the skill. - Additional annotations about the tool. + - `source: BetaInlineSkillSource` - - `description: Optional[str]` + Inline skill payload - The description of the tool. + - `data: str` - - `type: Literal["mcp_list_tools"]` + Base64-encoded skill zip bundle. - The type of the item. Always `mcp_list_tools`. + - `media_type: Literal["application/zip"]` - - `"mcp_list_tools"` + The media type of the inline skill payload. Must be `application/zip`. - - `agent: Optional[McpListToolsAgent]` + - `"application/zip"` - The agent that produced this item. + - `type: Literal["base64"]` - - `agent_name: str` + The type of the inline skill source. Must be `base64`. - The canonical name of the agent that produced this item. + - `"base64"` - - `error: Optional[str]` + - `type: Literal["inline"]` - Error message if the server could not list tools. + Defines an inline skill for this request. - - `class McpApprovalRequest: …` + - `"inline"` - A request for human approval of a tool invocation. + - `class BetaLocalEnvironment: …` - - `id: str` + - `type: Literal["local"]` - The unique ID of the approval request. + Use a local computer environment. - - `arguments: str` + - `"local"` - A JSON string of arguments for the tool. + - `skills: Optional[List[BetaLocalSkill]]` - - `name: str` + An optional list of skills. - The name of the tool to run. + - `description: str` - - `server_label: str` + The description of the skill. - The label of the MCP server making the request. + - `name: str` - - `type: Literal["mcp_approval_request"]` + The name of the skill. - The type of the item. Always `mcp_approval_request`. + - `path: str` - - `"mcp_approval_request"` + The path to the directory containing the skill. - - `agent: Optional[McpApprovalRequestAgent]` + - `class BetaContainerReference: …` - The agent that produced this item. + - `container_id: str` - - `agent_name: str` + The ID of the referenced container. - The canonical name of the agent that produced this item. + - `type: Literal["container_reference"]` - - `class McpApprovalResponse: …` + References a container created with the /v1/containers endpoint - A response to an MCP approval request. + - `"container_reference"` - - `approval_request_id: str` + - `class BetaCustomTool: …` - The ID of the approval request being answered. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `approve: bool` + - `name: str` - Whether the request was approved. + The name of the custom tool, used to identify it in tool calls. - - `type: Literal["mcp_approval_response"]` + - `type: Literal["custom"]` - The type of the item. Always `mcp_approval_response`. + The type of the custom tool. Always `custom`. - - `"mcp_approval_response"` + - `"custom"` - - `id: Optional[str]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The unique ID of the approval response + The tool invocation context(s). - - `agent: Optional[McpApprovalResponseAgent]` + - `"direct"` - The agent that produced this item. + - `"programmatic"` - - `agent_name: str` + - `defer_loading: Optional[bool]` - The canonical name of the agent that produced this item. + Whether this tool should be deferred and discovered via tool search. - - `reason: Optional[str]` + - `description: Optional[str]` - Optional reason for the decision. + Optional description of the custom tool, used to provide more context. - - `class McpCall: …` + - `format: Optional[Format]` - An invocation of a tool on an MCP server. + The input format for the custom tool. Default is unconstrained text. - - `id: str` + - `class FormatText: …` - The unique ID of the tool call. + Unconstrained free-form text. - - `arguments: str` + - `type: Literal["text"]` - A JSON string of the arguments passed to the tool. + Unconstrained text format. Always `text`. - - `name: str` + - `"text"` - The name of the tool that was run. + - `class FormatGrammar: …` - - `server_label: str` + A grammar defined by the user. - The label of the MCP server running the tool. + - `definition: str` - - `type: Literal["mcp_call"]` + The grammar definition. - The type of the item. Always `mcp_call`. + - `syntax: Literal["lark", "regex"]` - - `"mcp_call"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `agent: Optional[McpCallAgent]` + - `"lark"` - The agent that produced this item. + - `"regex"` - - `agent_name: str` + - `type: Literal["grammar"]` - The canonical name of the agent that produced this item. + Grammar format. Always `grammar`. - - `approval_request_id: Optional[str]` + - `"grammar"` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `class BetaNamespaceTool: …` - - `error: Optional[str]` + Groups function/custom tools under a shared namespace. - The error from the tool call, if any. + - `description: str` - - `output: Optional[str]` + A description of the namespace shown to the model. - The output from the tool call. + - `name: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + The namespace name used in tool calls (for example, `crm`). - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `tools: List[Tool]` - - `"in_progress"` + The function/custom tools available inside this namespace. - - `"completed"` + - `class ToolFunction: …` - - `"incomplete"` + - `name: str` - - `"calling"` + - `type: Literal["function"]` - - `"failed"` + - `"function"` - - `class BetaResponseCustomToolCallOutput: …` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The output of a custom tool call from your code, being sent back to the model. + The tool invocation context(s). - - `call_id: str` + - `"direct"` - The call ID, used to map this custom tool call output to a custom tool call. + - `"programmatic"` - - `output: Union[str, List[OutputOutputContentList]]` + - `defer_loading: Optional[bool]` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Whether this function should be deferred and discovered via tool search. - - `str` + - `description: Optional[str]` - A string of the output of the custom tool call. + - `output_schema: Optional[Dict[str, object]]` - - `List[OutputOutputContentList]` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Text, image, or file output of the custom tool call. + - `parameters: Optional[object]` - - `class BetaResponseInputText: …` + - `strict: Optional[bool]` - A text input to the model. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `class BetaResponseInputImage: …` + - `class BetaCustomTool: …` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `class BetaResponseInputFile: …` + - `type: Literal["namespace"]` - A file input to the model. + The type of the tool. Always `namespace`. - - `type: Literal["custom_tool_call_output"]` + - `"namespace"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `class BetaToolSearchTool: …` - - `"custom_tool_call_output"` + Hosted or BYOT tool search configuration for deferred tools. - - `id: Optional[str]` + - `type: Literal["tool_search"]` - The unique ID of the custom tool call output in the OpenAI platform. + The type of the tool. Always `tool_search`. - - `agent: Optional[Agent]` + - `"tool_search"` - The agent that produced this item. + - `description: Optional[str]` - - `agent_name: str` + Description shown to the model for a client-executed tool search tool. - The canonical name of the agent that produced this item. + - `execution: Optional[Literal["server", "client"]]` - - `caller: Optional[Caller]` + Whether tool search is executed by the server or by the client. - The execution context that produced this tool call. + - `"server"` - - `class CallerDirect: …` + - `"client"` - - `type: Literal["direct"]` + - `parameters: Optional[object]` - The caller type. Always `direct`. + Parameter schema for a client-executed tool search tool. - - `"direct"` + - `class BetaWebSearchPreviewTool: …` - - `class CallerProgram: …` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `caller_id: str` + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - The call ID of the program item that produced this tool call. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `type: Literal["program"]` + - `"web_search_preview"` - The caller type. Always `program`. + - `"web_search_preview_2025_03_11"` - - `"program"` + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `class BetaResponseCustomToolCall: …` + - `"text"` - A call to a custom tool created by the model. + - `"image"` - - `call_id: str` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - An identifier used to map this custom tool call to a tool call output. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `input: str` + - `"low"` - The input for the custom tool call generated by the model. + - `"medium"` - - `name: str` + - `"high"` - The name of the custom tool being called. + - `user_location: Optional[UserLocation]` - - `type: Literal["custom_tool_call"]` + The user's location. - The type of the custom tool call. Always `custom_tool_call`. + - `type: Literal["approximate"]` - - `"custom_tool_call"` + The type of location approximation. Always `approximate`. - - `id: Optional[str]` + - `"approximate"` - The unique ID of the custom tool call in the OpenAI platform. + - `city: Optional[str]` - - `agent: Optional[Agent]` + Free text input for the city of the user, e.g. `San Francisco`. - The agent that produced this item. + - `country: Optional[str]` - - `agent_name: str` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The canonical name of the agent that produced this item. + - `region: Optional[str]` - - `caller: Optional[Caller]` + Free text input for the region of the user, e.g. `California`. - The execution context that produced this tool call. + - `timezone: Optional[str]` - - `class CallerDirect: …` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `type: Literal["direct"]` + - `class BetaApplyPatchTool: …` - - `"direct"` + Allows the assistant to create, delete, or update files using unified diffs. - - `class CallerProgram: …` + - `type: Literal["apply_patch"]` - - `caller_id: str` + The type of the tool. Always `apply_patch`. - The call ID of the program item that produced this tool call. + - `"apply_patch"` - - `type: Literal["program"]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"program"` + The tool invocation context(s). - - `namespace: Optional[str]` + - `"direct"` - The namespace of the custom tool being called. + - `"programmatic"` - - `class CompactionTrigger: …` + - `type: Literal["tool_search_output"]` - Compacts the current context. Must be the final input item. + The item type. Always `tool_search_output`. - - `type: Literal["compaction_trigger"]` + - `"tool_search_output"` - The type of the item. Always `compaction_trigger`. + - `id: Optional[str]` - - `"compaction_trigger"` + The unique ID of this tool search output. - - `agent: Optional[CompactionTriggerAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -72629,381 +83639,377 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ItemReference: …` + - `call_id: Optional[str]` - An internal identifier for an item to reference. + The unique ID of the tool search call generated by the model. - - `id: str` + - `execution: Optional[Literal["server", "client"]]` - The ID of the item to reference. + Whether tool search was executed by the server or by the client. - - `agent: Optional[ItemReferenceAgent]` + - `"server"` - The agent that produced this item. + - `"client"` - - `agent_name: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The canonical name of the agent that produced this item. + The status of the tool search output. - - `type: Optional[Literal["item_reference"]]` + - `"in_progress"` - The type of item to reference. Always `item_reference`. + - `"completed"` - - `"item_reference"` + - `"incomplete"` - - `class Program: …` + - `class AdditionalTools: …` - - `id: str` + - `role: Literal["developer"]` - The unique ID of this program item. + The role that provided the additional tools. Only `developer` is supported. - - `call_id: str` + - `"developer"` - The stable call ID of the program item. + - `tools: List[BetaTool]` - - `code: str` + A list of additional tools made available at this item. - The JavaScript source executed by programmatic tool calling. + - `class BetaFunctionTool: …` - - `fingerprint: str` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Opaque program replay fingerprint that must be round-tripped. + - `class BetaFileSearchTool: …` - - `type: Literal["program"]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The item type. Always `program`. + - `class BetaComputerTool: …` - - `"program"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `agent: Optional[ProgramAgent]` + - `class BetaComputerUsePreviewTool: …` - The agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `agent_name: str` + - `class BetaWebSearchTool: …` - The canonical name of the agent that produced this item. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class ProgramOutput: …` + - `class Mcp: …` - - `id: str` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The unique ID of this program output item. + - `class CodeInterpreter: …` - - `call_id: str` + A tool that runs Python code to help generate a response to a prompt. - The call ID of the program item. + - `class ProgrammaticToolCalling: …` - - `result: str` + - `class ImageGeneration: …` - The result produced by the program item. + A tool that generates images using the GPT image models. - - `status: Literal["completed", "incomplete"]` + - `class LocalShell: …` - The terminal status of the program output. + A tool that allows the model to execute shell commands in a local environment. - - `"completed"` + - `class BetaFunctionShellTool: …` - - `"incomplete"` + A tool that allows the model to execute shell commands. - - `type: Literal["program_output"]` + - `class BetaCustomTool: …` - The item type. Always `program_output`. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `"program_output"` + - `class BetaNamespaceTool: …` - - `agent: Optional[ProgramOutputAgent]` + Groups function/custom tools under a shared namespace. - The agent that produced this item. + - `class BetaToolSearchTool: …` - - `agent_name: str` + Hosted or BYOT tool search configuration for deferred tools. - The canonical name of the agent that produced this item. + - `class BetaWebSearchPreviewTool: …` - - `metadata: Optional[Dict[str, str]]` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - 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. + - `class BetaApplyPatchTool: …` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Allows the assistant to create, delete, or update files using unified diffs. - - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` + - `type: Literal["additional_tools"]` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + The item type. Always `additional_tools`. - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` + - `"additional_tools"` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `id: Optional[str]` - - `"gpt-5.6-sol"` + The unique ID of this additional tools item. - - `"gpt-5.6-terra"` + - `agent: Optional[AdditionalToolsAgent]` - - `"gpt-5.6-luna"` + The agent that produced this item. - - `"gpt-5.4"` + - `agent_name: str` - - `"gpt-5.4-mini"` + The canonical name of the agent that produced this item. - - `"gpt-5.4-nano"` + - `class BetaResponseReasoningItem: …` - - `"gpt-5.4-mini-2026-03-17"` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `"gpt-5.4-nano-2026-03-17"` + - `id: str` - - `"gpt-5.3-chat-latest"` + The unique identifier of the reasoning content. - - `"gpt-5.2"` + - `summary: List[Summary]` - - `"gpt-5.2-2025-12-11"` + Reasoning summary content. - - `"gpt-5.2-chat-latest"` + - `text: str` - - `"gpt-5.2-pro"` + A summary of the reasoning output from the model so far. - - `"gpt-5.2-pro-2025-12-11"` + - `type: Literal["summary_text"]` - - `"gpt-5.1"` + The type of the object. Always `summary_text`. - - `"gpt-5.1-2025-11-13"` + - `"summary_text"` - - `"gpt-5.1-codex"` + - `type: Literal["reasoning"]` - - `"gpt-5.1-mini"` + The type of the object. Always `reasoning`. - - `"gpt-5.1-chat-latest"` + - `"reasoning"` - - `"gpt-5"` + - `agent: Optional[Agent]` - - `"gpt-5-mini"` + The agent that produced this item. - - `"gpt-5-nano"` + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `content: Optional[List[Content]]` + + Reasoning text content. - - `"gpt-5-2025-08-07"` + - `text: str` - - `"gpt-5-mini-2025-08-07"` + The reasoning text from the model. - - `"gpt-5-nano-2025-08-07"` + - `type: Literal["reasoning_text"]` - - `"gpt-5-chat-latest"` + The type of the reasoning text. Always `reasoning_text`. - - `"gpt-4.1"` + - `"reasoning_text"` - - `"gpt-4.1-mini"` + - `encrypted_content: Optional[str]` - - `"gpt-4.1-nano"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `"gpt-4.1-2025-04-14"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"gpt-4.1-mini-2025-04-14"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"gpt-4.1-nano-2025-04-14"` + - `"in_progress"` - - `"o4-mini"` + - `"completed"` - - `"o4-mini-2025-04-16"` + - `"incomplete"` - - `"o3"` + - `class BetaResponseCompactionItemParam: …` - - `"o3-2025-04-16"` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `"o3-mini"` + - `encrypted_content: str` - - `"o3-mini-2025-01-31"` + The encrypted content of the compaction summary. - - `"o1"` + - `type: Literal["compaction"]` - - `"o1-2024-12-17"` + The type of the item. Always `compaction`. - - `"o1-preview"` + - `"compaction"` - - `"o1-preview-2024-09-12"` + - `id: Optional[str]` - - `"o1-mini"` + The ID of the compaction item. - - `"o1-mini-2024-09-12"` + - `agent: Optional[Agent]` - - `"gpt-4o"` + The agent that produced this item. - - `"gpt-4o-2024-11-20"` + - `agent_name: str` - - `"gpt-4o-2024-08-06"` + The canonical name of the agent that produced this item. - - `"gpt-4o-2024-05-13"` + - `class ImageGenerationCall: …` - - `"gpt-4o-audio-preview"` + An image generation request made by the model. - - `"gpt-4o-audio-preview-2024-10-01"` + - `id: str` - - `"gpt-4o-audio-preview-2024-12-17"` + The unique ID of the image generation call. - - `"gpt-4o-audio-preview-2025-06-03"` + - `result: Optional[str]` - - `"gpt-4o-mini-audio-preview"` + The generated image encoded in base64. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - - `"gpt-4o-search-preview"` + The status of the image generation call. - - `"gpt-4o-mini-search-preview"` + - `"in_progress"` - - `"gpt-4o-search-preview-2025-03-11"` + - `"completed"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `"generating"` - - `"chatgpt-4o-latest"` + - `"failed"` - - `"codex-mini-latest"` + - `type: Literal["image_generation_call"]` - - `"gpt-4o-mini"` + The type of the image generation call. Always `image_generation_call`. - - `"gpt-4o-mini-2024-07-18"` + - `"image_generation_call"` - - `"gpt-4-turbo"` + - `agent: Optional[ImageGenerationCallAgent]` - - `"gpt-4-turbo-2024-04-09"` + The agent that produced this item. - - `"gpt-4-0125-preview"` + - `agent_name: str` - - `"gpt-4-turbo-preview"` + The canonical name of the agent that produced this item. - - `"gpt-4-1106-preview"` + - `class BetaResponseCodeInterpreterToolCall: …` - - `"gpt-4-vision-preview"` + A tool call to run code. - - `"gpt-4"` + - `id: str` - - `"gpt-4-0314"` + The unique ID of the code interpreter tool call. - - `"gpt-4-0613"` + - `code: Optional[str]` - - `"gpt-4-32k"` + The code to run, or null if not available. - - `"gpt-4-32k-0314"` + - `container_id: str` - - `"gpt-4-32k-0613"` + The ID of the container used to run the code. - - `"gpt-3.5-turbo"` + - `outputs: Optional[List[Output]]` - - `"gpt-3.5-turbo-16k"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"gpt-3.5-turbo-0301"` + - `class OutputLogs: …` - - `"gpt-3.5-turbo-0613"` + The logs output from the code interpreter. - - `"gpt-3.5-turbo-1106"` + - `logs: str` - - `"gpt-3.5-turbo-0125"` + The logs output from the code interpreter. - - `"gpt-3.5-turbo-16k-0613"` + - `type: Literal["logs"]` - - `"o1-pro"` + The type of the output. Always `logs`. - - `"o1-pro-2025-03-19"` + - `"logs"` - - `"o3-pro"` + - `class OutputImage: …` - - `"o3-pro-2025-06-10"` + The image output from the code interpreter. - - `"o3-deep-research"` + - `type: Literal["image"]` - - `"o3-deep-research-2025-06-26"` + The type of the output. Always `image`. - - `"o4-mini-deep-research"` + - `"image"` - - `"o4-mini-deep-research-2025-06-26"` + - `url: str` - - `"computer-use-preview"` + The URL of the image output from the code interpreter. - - `"computer-use-preview-2025-03-11"` + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - - `"gpt-5-codex"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"gpt-5-pro"` + - `"in_progress"` - - `"gpt-5-pro-2025-10-06"` + - `"completed"` - - `"gpt-5.1-codex-max"` + - `"incomplete"` - - `str` + - `"interpreting"` - - `object: Literal["response"]` + - `"failed"` - The object type of this resource - always set to `response`. + - `type: Literal["code_interpreter_call"]` - - `"response"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `output: List[BetaResponseOutputItem]` + - `"code_interpreter_call"` - An array of content items generated by the model. + - `agent: Optional[Agent]` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + The agent that produced this item. - - `class BetaResponseOutputMessage: …` + - `agent_name: str` - An output message from the model. + The canonical name of the agent that produced this item. - - `class BetaResponseFileSearchToolCall: …` + - `class LocalShellCall: …` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + A tool call to run a command on the local shell. - - `class BetaResponseFunctionToolCall: …` + - `id: str` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The unique ID of the local shell call. - - `class BetaResponseFunctionToolCallOutputItem: …` + - `action: LocalShellCallAction` - - `id: str` + Execute a shell command on the server. - The unique ID of the function call tool output. + - `command: List[str]` - - `call_id: str` + The command to run. - The unique ID of the function tool call generated by the model. + - `env: Dict[str, str]` - - `output: Union[str, List[OutputOutputContentList]]` + Environment variables to set for the command. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `type: Literal["exec"]` - - `str` + The type of the local shell action. Always `exec`. - A string of the output of the function call. + - `"exec"` - - `List[OutputOutputContentList]` + - `timeout_ms: Optional[int]` - Text, image, or file output of the function call. + Optional timeout in milliseconds for the command. - - `class BetaResponseInputText: …` + - `user: Optional[str]` - A text input to the model. + Optional user to run the command as. - - `class BetaResponseInputImage: …` + - `working_directory: Optional[str]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Optional working directory to run the command in. - - `class BetaResponseInputFile: …` + - `call_id: str` - A file input to the model. + The unique ID of the local shell tool call generated by the model. - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the local shell call. - `"in_progress"` @@ -73011,13 +84017,13 @@ print(compacted_response) - `"incomplete"` - - `type: Literal["function_call_output"]` + - `type: Literal["local_shell_call"]` - The type of the function tool call output. Always `function_call_output`. + The type of the local shell call. Always `local_shell_call`. - - `"function_call_output"` + - `"local_shell_call"` - - `agent: Optional[Agent]` + - `agent: Optional[LocalShellCallAgent]` The agent that produced this item. @@ -73025,384 +84031,369 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` - - - `type: Literal["direct"]` - - The caller type. Always `direct`. - - - `"direct"` + - `class LocalShellCallOutput: …` - - `class CallerProgram: …` + The output of a local shell tool call. - - `caller_id: str` + - `id: str` - The call ID of the program item that produced this tool call. + The unique ID of the local shell tool call generated by the model. - - `type: Literal["program"]` + - `output: str` - The caller type. Always `program`. + A JSON string of the output of the local shell tool call. - - `"program"` + - `type: Literal["local_shell_call_output"]` - - `created_by: Optional[str]` + The type of the local shell tool call output. Always `local_shell_call_output`. - The identifier of the actor that created the item. + - `"local_shell_call_output"` - - `class AgentMessage: …` + - `agent: Optional[LocalShellCallOutputAgent]` - - `id: str` + The agent that produced this item. - The unique ID of the agent message. + - `agent_name: str` - - `author: str` + The canonical name of the agent that produced this item. - The sending agent identity. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `content: List[AgentMessageContent]` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Encrypted content sent between agents. + - `"in_progress"` - - `class BetaResponseInputText: …` + - `"completed"` - A text input to the model. + - `"incomplete"` - - `class BetaResponseOutputText: …` + - `class ShellCall: …` - A text output from the model. + A tool representing a request to execute one or more shell commands. - - `class AgentMessageContentText: …` + - `action: ShellCallAction` - A text content. + The shell commands and limits that describe how to run the tool call. - - `text: str` + - `commands: List[str]` - - `type: Literal["text"]` + Ordered shell commands for the execution environment to run. - - `"text"` + - `max_output_length: Optional[int]` - - `class AgentMessageContentSummaryText: …` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - A summary text from the model. + - `timeout_ms: Optional[int]` - - `text: str` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - A summary of the reasoning output from the model so far. + - `call_id: str` - - `type: Literal["summary_text"]` + The unique ID of the shell tool call generated by the model. - The type of the object. Always `summary_text`. + - `type: Literal["shell_call"]` - - `"summary_text"` + The type of the item. Always `shell_call`. - - `class AgentMessageContentReasoningText: …` + - `"shell_call"` - Reasoning text from the model. + - `id: Optional[str]` - - `text: str` + The unique ID of the shell tool call. Populated when this item is returned via API. - The reasoning text from the model. + - `agent: Optional[ShellCallAgent]` - - `type: Literal["reasoning_text"]` + The agent that produced this item. - The type of the reasoning text. Always `reasoning_text`. + - `agent_name: str` - - `"reasoning_text"` + The canonical name of the agent that produced this item. - - `class BetaResponseOutputRefusal: …` + - `caller: Optional[ShellCallCaller]` - A refusal from the model. + The execution context that produced this tool call. - - `class BetaResponseInputImage: …` + - `class ShellCallCallerDirect: …` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `type: Literal["direct"]` - - `class AgentMessageContentComputerScreenshot: …` + The caller type. Always `direct`. - A screenshot of a computer. + - `"direct"` - - `detail: Literal["low", "high", "auto", "original"]` + - `class ShellCallCallerProgram: …` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `caller_id: str` - - `"low"` + The call ID of the program item that produced this tool call. - - `"high"` + - `type: Literal["program"]` - - `"auto"` + The caller type. Always `program`. - - `"original"` + - `"program"` - - `file_id: Optional[str]` + - `environment: Optional[ShellCallEnvironment]` - The identifier of an uploaded file that contains the screenshot. + The environment to execute the shell commands in. - - `image_url: Optional[str]` + - `class BetaLocalEnvironment: …` - The URL of the screenshot image. + - `class BetaContainerReference: …` - - `type: Literal["computer_screenshot"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `"computer_screenshot"` + - `"in_progress"` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `"completed"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"incomplete"` - - `mode: Literal["explicit"]` + - `class ShellCallOutput: …` - The breakpoint mode. Always `explicit`. + The streamed output items emitted by a shell tool call. - - `"explicit"` + - `call_id: str` - - `class BetaResponseInputFile: …` + The unique ID of the shell tool call generated by the model. - A file input to the model. + - `output: List[BetaResponseFunctionShellCallOutputContent]` - - `class AgentMessageContentEncryptedContent: …` + Captured chunks of stdout and stderr output, along with their associated outcomes. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `outcome: Outcome` - - `encrypted_content: str` + The exit or timeout outcome associated with this shell call. - Opaque encrypted content. + - `class OutcomeTimeout: …` - - `type: Literal["encrypted_content"]` + Indicates that the shell call exceeded its configured time limit. - The type of the input item. Always `encrypted_content`. + - `type: Literal["timeout"]` - - `"encrypted_content"` + The outcome type. Always `timeout`. - - `recipient: str` + - `"timeout"` - The destination agent identity. + - `class OutcomeExit: …` - - `type: Literal["agent_message"]` + Indicates that the shell commands finished and returned an exit code. - The type of the item. Always `agent_message`. + - `exit_code: int` - - `"agent_message"` + The exit code returned by the shell process. - - `agent: Optional[AgentMessageAgent]` + - `type: Literal["exit"]` - The agent that produced this item. + The outcome type. Always `exit`. - - `agent_name: str` + - `"exit"` - The canonical name of the agent that produced this item. + - `stderr: str` - - `class MultiAgentCall: …` + Captured stderr output for the shell call. - - `id: str` + - `stdout: str` - The unique ID of the multi-agent call item. + Captured stdout output for the shell call. - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `type: Literal["shell_call_output"]` - The multi-agent action to execute. + The type of the item. Always `shell_call_output`. - - `"spawn_agent"` + - `"shell_call_output"` - - `"interrupt_agent"` + - `id: Optional[str]` - - `"list_agents"` + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `"send_message"` + - `agent: Optional[ShellCallOutputAgent]` - - `"followup_task"` + The agent that produced this item. - - `"wait_agent"` + - `agent_name: str` - - `arguments: str` + The canonical name of the agent that produced this item. - The JSON string of arguments generated for the action. + - `caller: Optional[ShellCallOutputCaller]` - - `call_id: str` + The execution context that produced this tool call. - The unique ID linking this call to its output. + - `class ShellCallOutputCallerDirect: …` - - `type: Literal["multi_agent_call"]` + - `type: Literal["direct"]` - The type of the multi-agent call. Always `multi_agent_call`. + The caller type. Always `direct`. - - `"multi_agent_call"` + - `"direct"` - - `agent: Optional[MultiAgentCallAgent]` + - `class ShellCallOutputCallerProgram: …` - The agent that produced this item. + - `caller_id: str` - - `agent_name: str` + The call ID of the program item that produced this tool call. - The canonical name of the agent that produced this item. + - `type: Literal["program"]` - - `class MultiAgentCallOutput: …` + The caller type. Always `program`. - - `id: str` + - `"program"` - The unique ID of the multi-agent call output item. + - `max_output_length: Optional[int]` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The multi-agent action that produced this result. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"spawn_agent"` + The status of the shell call output. - - `"interrupt_agent"` + - `"in_progress"` - - `"list_agents"` + - `"completed"` - - `"send_message"` + - `"incomplete"` - - `"followup_task"` + - `class ApplyPatchCall: …` - - `"wait_agent"` + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: str` - The unique ID of the multi-agent call. + The unique ID of the apply patch tool call generated by the model. - - `output: List[BetaResponseOutputText]` + - `operation: ApplyPatchCallOperation` - Text output returned by the multi-agent action. + The specific create, delete, or update instruction for the apply_patch tool call. - - `annotations: List[Annotation]` + - `class ApplyPatchCallOperationCreateFile: …` - The annotations of the text output. + Instruction for creating a new file via the apply_patch tool. - - `text: str` + - `diff: str` - The text output from the model. + Unified diff content to apply when creating the file. - - `type: Literal["output_text"]` + - `path: str` - The type of the output text. Always `output_text`. + Path of the file to create relative to the workspace root. - - `logprobs: Optional[List[Logprob]]` + - `type: Literal["create_file"]` - - `type: Literal["multi_agent_call_output"]` + The operation type. Always `create_file`. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"create_file"` - - `"multi_agent_call_output"` + - `class ApplyPatchCallOperationDeleteFile: …` - - `agent: Optional[MultiAgentCallOutputAgent]` + Instruction for deleting an existing file via the apply_patch tool. - The agent that produced this item. + - `path: str` - - `agent_name: str` + Path of the file to delete relative to the workspace root. - The canonical name of the agent that produced this item. + - `type: Literal["delete_file"]` - - `class BetaResponseFunctionWebSearch: …` + The operation type. Always `delete_file`. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `"delete_file"` - - `class BetaResponseComputerToolCall: …` + - `class ApplyPatchCallOperationUpdateFile: …` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Instruction for updating an existing file via the apply_patch tool. - - `class BetaResponseComputerToolCallOutputItem: …` + - `diff: str` - - `id: str` + Unified diff content to apply to the existing file. - The unique ID of the computer call tool output. + - `path: str` - - `call_id: str` + Path of the file to update relative to the workspace root. - The ID of the computer tool call that produced the output. + - `type: Literal["update_file"]` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The operation type. Always `update_file`. - A computer screenshot image used with the computer use tool. + - `"update_file"` - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + - `status: Literal["in_progress", "completed"]` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` - `"completed"` - - `"incomplete"` + - `type: Literal["apply_patch_call"]` - - `"failed"` + The type of the item. Always `apply_patch_call`. - - `"in_progress"` + - `"apply_patch_call"` - - `type: Literal["computer_call_output"]` + - `id: Optional[str]` - The type of the computer tool call output. Always `computer_call_output`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"computer_call_output"` + - `agent: Optional[ApplyPatchCallAgent]` - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + The agent that produced this item. - The safety checks reported by the API that have been acknowledged by the - developer. + - `agent_name: str` - - `id: str` + The canonical name of the agent that produced this item. - The ID of the pending safety check. + - `caller: Optional[ApplyPatchCallCaller]` - - `code: Optional[str]` + The execution context that produced this tool call. - The type of the pending safety check. + - `class ApplyPatchCallCallerDirect: …` - - `message: Optional[str]` + - `type: Literal["direct"]` - Details about the pending safety check. + The caller type. Always `direct`. - - `agent: Optional[Agent]` + - `"direct"` - The agent that produced this item. + - `class ApplyPatchCallCallerProgram: …` - - `agent_name: str` + - `caller_id: str` - The canonical name of the agent that produced this item. + The call ID of the program item that produced this tool call. - - `created_by: Optional[str]` + - `type: Literal["program"]` - The identifier of the actor that created the item. + The caller type. Always `program`. - - `class BetaResponseReasoningItem: …` + - `"program"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class ApplyPatchCallOutput: …` - - `class Program: …` + The streamed output emitted by an apply patch tool call. - - `id: str` + - `call_id: str` - The unique ID of the program item. + The unique ID of the apply patch tool call generated by the model. - - `call_id: str` + - `status: Literal["completed", "failed"]` - The stable call ID of the program item. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `code: str` + - `"completed"` - The JavaScript source executed by programmatic tool calling. + - `"failed"` - - `fingerprint: str` + - `type: Literal["apply_patch_call_output"]` - Opaque program replay fingerprint that must be round-tripped. + The type of the item. Always `apply_patch_call_output`. - - `type: Literal["program"]` + - `"apply_patch_call_output"` - The type of the item. Always `program`. + - `id: Optional[str]` - - `"program"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `agent: Optional[ProgramAgent]` + - `agent: Optional[ApplyPatchCallOutputAgent]` The agent that produced this item. @@ -73410,81 +84401,73 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ProgramOutput: …` - - - `id: str` - - The unique ID of the program output item. - - - `call_id: str` + - `caller: Optional[ApplyPatchCallOutputCaller]` - The call ID of the program item. + The execution context that produced this tool call. - - `result: str` + - `class ApplyPatchCallOutputCallerDirect: …` - The result produced by the program item. + - `type: Literal["direct"]` - - `status: Literal["completed", "incomplete"]` + The caller type. Always `direct`. - The terminal status of the program output item. + - `"direct"` - - `"completed"` + - `class ApplyPatchCallOutputCallerProgram: …` - - `"incomplete"` + - `caller_id: str` - - `type: Literal["program_output"]` + The call ID of the program item that produced this tool call. - The type of the item. Always `program_output`. + - `type: Literal["program"]` - - `"program_output"` + The caller type. Always `program`. - - `agent: Optional[ProgramOutputAgent]` + - `"program"` - The agent that produced this item. + - `output: Optional[str]` - - `agent_name: str` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - The canonical name of the agent that produced this item. + - `class McpListTools: …` - - `class BetaResponseToolSearchCall: …` + A list of tools available on an MCP server. - `id: str` - The unique ID of the tool search call item. - - - `arguments: object` + The unique ID of the list. - Arguments used for the tool search call. + - `server_label: str` - - `call_id: Optional[str]` + The label of the MCP server. - The unique ID of the tool search call generated by the model. + - `tools: List[McpListToolsTool]` - - `execution: Literal["server", "client"]` + The tools available on the server. - Whether tool search was executed by the server or by the client. + - `input_schema: object` - - `"server"` + The JSON schema describing the tool's input. - - `"client"` + - `name: str` - - `status: Literal["in_progress", "completed", "incomplete"]` + The name of the tool. - The status of the tool search call item that was recorded. + - `annotations: Optional[object]` - - `"in_progress"` + Additional annotations about the tool. - - `"completed"` + - `description: Optional[str]` - - `"incomplete"` + The description of the tool. - - `type: Literal["tool_search_call"]` + - `type: Literal["mcp_list_tools"]` - The type of the item. Always `tool_search_call`. + The type of the item. Always `mcp_list_tools`. - - `"tool_search_call"` + - `"mcp_list_tools"` - - `agent: Optional[Agent]` + - `agent: Optional[McpListToolsAgent]` The agent that produced this item. @@ -73492,113 +84475,105 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `class BetaResponseToolSearchOutputItem: …` - - - `id: str` + - `error: Optional[str]` - The unique ID of the tool search output item. + Error message if the server could not list tools. - - `call_id: Optional[str]` + - `class McpApprovalRequest: …` - The unique ID of the tool search call generated by the model. + A request for human approval of a tool invocation. - - `execution: Literal["server", "client"]` + - `id: str` - Whether tool search was executed by the server or by the client. + The unique ID of the approval request. - - `"server"` + - `arguments: str` - - `"client"` + A JSON string of arguments for the tool. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `name: str` - The status of the tool search output item that was recorded. + The name of the tool to run. - - `"in_progress"` + - `server_label: str` - - `"completed"` + The label of the MCP server making the request. - - `"incomplete"` + - `type: Literal["mcp_approval_request"]` - - `tools: List[BetaTool]` + The type of the item. Always `mcp_approval_request`. - The loaded tool definitions returned by tool search. + - `"mcp_approval_request"` - - `class BetaFunctionTool: …` + - `agent: Optional[McpApprovalRequestAgent]` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The agent that produced this item. - - `class BetaFileSearchTool: …` + - `agent_name: str` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The canonical name of the agent that produced this item. - - `class BetaComputerTool: …` + - `class McpApprovalResponse: …` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A response to an MCP approval request. - - `class BetaComputerUsePreviewTool: …` + - `approval_request_id: str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The ID of the approval request being answered. - - `class BetaWebSearchTool: …` + - `approve: bool` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Whether the request was approved. - - `class Mcp: …` + - `type: Literal["mcp_approval_response"]` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The type of the item. Always `mcp_approval_response`. - - `class CodeInterpreter: …` + - `"mcp_approval_response"` - A tool that runs Python code to help generate a response to a prompt. + - `id: Optional[str]` - - `class ProgrammaticToolCalling: …` + The unique ID of the approval response - - `class ImageGeneration: …` + - `agent: Optional[McpApprovalResponseAgent]` - A tool that generates images using the GPT image models. + The agent that produced this item. - - `class LocalShell: …` + - `agent_name: str` - A tool that allows the model to execute shell commands in a local environment. + The canonical name of the agent that produced this item. - - `class BetaFunctionShellTool: …` + - `reason: Optional[str]` - A tool that allows the model to execute shell commands. + Optional reason for the decision. - - `class BetaCustomTool: …` + - `class McpCall: …` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + An invocation of a tool on an MCP server. - - `class BetaNamespaceTool: …` + - `id: str` - Groups function/custom tools under a shared namespace. + The unique ID of the tool call. - - `class BetaToolSearchTool: …` + - `arguments: str` - Hosted or BYOT tool search configuration for deferred tools. + A JSON string of the arguments passed to the tool. - - `class BetaWebSearchPreviewTool: …` + - `name: str` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The name of the tool that was run. - - `class BetaApplyPatchTool: …` + - `server_label: str` - Allows the assistant to create, delete, or update files using unified diffs. + The label of the MCP server running the tool. - - `type: Literal["tool_search_output"]` + - `type: Literal["mcp_call"]` - The type of the item. Always `tool_search_output`. + The type of the item. Always `mcp_call`. - - `"tool_search_output"` + - `"mcp_call"` - - `agent: Optional[Agent]` + - `agent: Optional[McpCallAgent]` The agent that produced this item. @@ -73606,135 +84581,133 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. + - `approval_request_id: Optional[str]` - - `class AdditionalTools: …` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `id: str` + - `error: Optional[str]` - The unique ID of the additional tools item. + The error from the tool call, if any. - - `role: Literal["unknown", "user", "assistant", 5 more]` + - `output: Optional[str]` - The role that provided the additional tools. + The output from the tool call. - - `"unknown"` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - `"user"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"assistant"` + - `"in_progress"` - - `"system"` + - `"completed"` - - `"critic"` + - `"incomplete"` - - `"discriminator"` + - `"calling"` - - `"developer"` + - `"failed"` - - `"tool"` + - `class BetaResponseCustomToolCallOutput: …` - - `tools: List[BetaTool]` + The output of a custom tool call from your code, being sent back to the model. - The additional tool definitions made available at this item. + - `call_id: str` - - `class BetaFunctionTool: …` + The call ID, used to map this custom tool call output to a custom tool call. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `output: Union[str, List[OutputOutputContentList]]` - - `class BetaFileSearchTool: …` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `str` - - `class BetaComputerTool: …` + A string of the output of the custom tool call. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `List[OutputOutputContentList]` - - `class BetaComputerUsePreviewTool: …` + Text, image, or file output of the custom tool call. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class BetaResponseInputText: …` - - `class BetaWebSearchTool: …` + A text input to the model. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class BetaResponseInputImage: …` - - `class Mcp: …` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `class BetaResponseInputFile: …` - - `class CodeInterpreter: …` + A file input to the model. - A tool that runs Python code to help generate a response to a prompt. + - `type: Literal["custom_tool_call_output"]` - - `class ProgrammaticToolCalling: …` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `class ImageGeneration: …` + - `"custom_tool_call_output"` - A tool that generates images using the GPT image models. + - `id: Optional[str]` - - `class LocalShell: …` + The unique ID of the custom tool call output in the OpenAI platform. - A tool that allows the model to execute shell commands in a local environment. + - `agent: Optional[Agent]` - - `class BetaFunctionShellTool: …` + The agent that produced this item. - A tool that allows the model to execute shell commands. + - `agent_name: str` - - `class BetaCustomTool: …` + The canonical name of the agent that produced this item. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `caller: Optional[Caller]` - - `class BetaNamespaceTool: …` + The execution context that produced this tool call. - Groups function/custom tools under a shared namespace. + - `class CallerDirect: …` - - `class BetaToolSearchTool: …` + - `type: Literal["direct"]` - Hosted or BYOT tool search configuration for deferred tools. + The caller type. Always `direct`. - - `class BetaWebSearchPreviewTool: …` + - `"direct"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class CallerProgram: …` - - `class BetaApplyPatchTool: …` + - `caller_id: str` - Allows the assistant to create, delete, or update files using unified diffs. + The call ID of the program item that produced this tool call. - - `type: Literal["additional_tools"]` + - `type: Literal["program"]` - The type of the item. Always `additional_tools`. + The caller type. Always `program`. - - `"additional_tools"` + - `"program"` - - `agent: Optional[AdditionalToolsAgent]` + - `class BetaResponseCustomToolCall: …` - The agent that produced this item. + A call to a custom tool created by the model. - - `agent_name: str` + - `call_id: str` - The canonical name of the agent that produced this item. + An identifier used to map this custom tool call to a tool call output. - - `class BetaResponseCompactionItem: …` + - `input: str` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The input for the custom tool call generated by the model. - - `id: str` + - `name: str` - The unique ID of the compaction item. + The name of the custom tool being called. - - `encrypted_content: str` + - `type: Literal["custom_tool_call"]` - The encrypted content that was produced by compaction. + The type of the custom tool call. Always `custom_tool_call`. - - `type: Literal["compaction"]` + - `"custom_tool_call"` - The type of the item. Always `compaction`. + - `id: Optional[str]` - - `"compaction"` + The unique ID of the custom tool call in the OpenAI platform. - `agent: Optional[Agent]` @@ -73744,41 +84717,41 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` + - `caller: Optional[Caller]` - The identifier of the actor that created the item. + The execution context that produced this tool call. - - `class ImageGenerationCall: …` + - `class CallerDirect: …` - An image generation request made by the model. + - `type: Literal["direct"]` - - `id: str` + - `"direct"` - The unique ID of the image generation call. + - `class CallerProgram: …` - - `result: Optional[str]` + - `caller_id: str` - The generated image encoded in base64. + The call ID of the program item that produced this tool call. - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `type: Literal["program"]` - The status of the image generation call. + - `"program"` - - `"in_progress"` + - `namespace: Optional[str]` - - `"completed"` + The namespace of the custom tool being called. - - `"generating"` + - `class CompactionTrigger: …` - - `"failed"` + Compacts the current context. Must be the final input item. - - `type: Literal["image_generation_call"]` + - `type: Literal["compaction_trigger"]` - The type of the image generation call. Always `image_generation_call`. + The type of the item. Always `compaction_trigger`. - - `"image_generation_call"` + - `"compaction_trigger"` - - `agent: Optional[ImageGenerationCallAgent]` + - `agent: Optional[CompactionTriggerAgent]` The agent that produced this item. @@ -73786,69 +84759,89 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall: …` + - `class ItemReference: …` - A tool call to run code. + An internal identifier for an item to reference. - - `class LocalShellCall: …` + - `id: str` - A tool call to run a command on the local shell. + The ID of the item to reference. + + - `agent: Optional[ItemReferenceAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `type: Optional[Literal["item_reference"]]` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + + - `class Program: …` - `id: str` - The unique ID of the local shell call. + The unique ID of this program item. - - `action: LocalShellCallAction` + - `call_id: str` - Execute a shell command on the server. + The stable call ID of the program item. - - `command: List[str]` + - `code: str` - The command to run. + The JavaScript source executed by programmatic tool calling. - - `env: Dict[str, str]` + - `fingerprint: str` - Environment variables to set for the command. + Opaque program replay fingerprint that must be round-tripped. - - `type: Literal["exec"]` + - `type: Literal["program"]` - The type of the local shell action. Always `exec`. + The item type. Always `program`. - - `"exec"` + - `"program"` - - `timeout_ms: Optional[int]` + - `agent: Optional[ProgramAgent]` - Optional timeout in milliseconds for the command. + The agent that produced this item. - - `user: Optional[str]` + - `agent_name: str` - Optional user to run the command as. + The canonical name of the agent that produced this item. - - `working_directory: Optional[str]` + - `class ProgramOutput: …` - Optional working directory to run the command in. + - `id: str` + + The unique ID of this program output item. - `call_id: str` - The unique ID of the local shell tool call generated by the model. + The call ID of the program item. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `result: str` - The status of the local shell call. + The result produced by the program item. - - `"in_progress"` + - `status: Literal["completed", "incomplete"]` + + The terminal status of the program output. - `"completed"` - `"incomplete"` - - `type: Literal["local_shell_call"]` + - `type: Literal["program_output"]` - The type of the local shell call. Always `local_shell_call`. + The item type. Always `program_output`. - - `"local_shell_call"` + - `"program_output"` - - `agent: Optional[LocalShellCallAgent]` + - `agent: Optional[ProgramOutputAgent]` The agent that produced this item. @@ -73856,219 +84849,236 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCallOutput: …` + - `response_id: str` - The output of a local shell tool call. + The ID of the active response that should receive the input. - - `id: str` + - `type: Literal["response.inject"]` - The unique ID of the local shell tool call generated by the model. + The event discriminator. Always `response.inject`. - - `output: str` + - `"response.inject"` - A JSON string of the output of the local shell tool call. +### Beta Response Inject Failed Event - - `type: Literal["local_shell_call_output"]` +- `class BetaResponseInjectFailedEvent: …` - The type of the local shell tool call output. Always `local_shell_call_output`. + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. - - `"local_shell_call_output"` + - `error: Error` - - `agent: Optional[LocalShellCallOutputAgent]` + Information about why the input was not committed. - The agent that produced this item. + - `code: Literal["response_already_completed", "response_not_found"]` - - `agent_name: str` + A machine-readable error code. - The canonical name of the agent that produced this item. + - `"response_already_completed"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"response_not_found"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `message: str` - - `"in_progress"` + A human-readable description of the error. - - `"completed"` + - `input: List[BetaResponseInputItem]` - - `"incomplete"` + The raw input items that were not committed. - - `class BetaResponseFunctionShellToolCall: …` + - `class BetaEasyInputMessage: …` - A tool call that executes one or more shell commands in a managed environment. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `id: str` + - `content: Union[str, BetaResponseInputMessageContentList]` - The unique ID of the shell tool call. Populated when this item is returned via API. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `action: Action` + - `str` - The shell commands and limits that describe how to run the tool call. + A text input to the model. - - `commands: List[str]` + - `List[BetaResponseInputContent]` - - `max_output_length: Optional[int]` + - `class BetaResponseInputText: …` - Optional maximum number of characters to return from each command. + A text input to the model. - - `timeout_ms: Optional[int]` + - `text: str` - Optional timeout in milliseconds for the commands. + The text input to the model. - - `call_id: str` + - `type: Literal["input_text"]` - The unique ID of the shell tool call generated by the model. + The type of the input item. Always `input_text`. - - `environment: Optional[Environment]` + - `"input_text"` - Represents the use of a local environment to perform shell actions. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `class BetaResponseLocalEnvironment: …` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Represents the use of a local environment to perform shell actions. + - `mode: Literal["explicit"]` - - `type: Literal["local"]` + The breakpoint mode. Always `explicit`. - The environment type. Always `local`. + - `"explicit"` - - `"local"` + - `class BetaResponseInputImage: …` - - `class BetaResponseContainerReference: …` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Represents a container created with /v1/containers. + - `detail: Literal["low", "high", "auto", "original"]` - - `container_id: str` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: Literal["container_reference"]` + - `"low"` - The environment type. Always `container_reference`. + - `"high"` - - `"container_reference"` + - `"auto"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"original"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `type: Literal["input_image"]` - - `"in_progress"` + The type of the input item. Always `input_image`. - - `"completed"` + - `"input_image"` - - `"incomplete"` + - `file_id: Optional[str]` - - `type: Literal["shell_call"]` + The ID of the file to be sent to the model. - The type of the item. Always `shell_call`. + - `image_url: Optional[str]` - - `"shell_call"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `agent: Optional[Agent]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The agent that produced this item. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `agent_name: str` + - `mode: Literal["explicit"]` - The canonical name of the agent that produced this item. + The breakpoint mode. Always `explicit`. - - `caller: Optional[Caller]` + - `"explicit"` - The execution context that produced this tool call. + - `class BetaResponseInputFile: …` - - `class CallerDirect: …` + A file input to the model. - - `type: Literal["direct"]` + - `type: Literal["input_file"]` - - `"direct"` + The type of the input item. Always `input_file`. - - `class CallerProgram: …` + - `"input_file"` - - `caller_id: str` + - `detail: Optional[Literal["auto", "low", "high"]]` - The call ID of the program item that produced this tool call. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `type: Literal["program"]` + - `"auto"` - - `"program"` + - `"low"` - - `created_by: Optional[str]` + - `"high"` - The ID of the entity that created this tool call. + - `file_data: Optional[str]` - - `class BetaResponseFunctionShellToolCallOutput: …` + The content of the file to be sent to the model. - The output of a shell tool call that was emitted. + - `file_id: Optional[str]` - - `id: str` + The ID of the file to be sent to the model. - The unique ID of the shell call output. Populated when this item is returned via API. + - `file_url: Optional[str]` - - `call_id: str` + The URL of the file to be sent to the model. - The unique ID of the shell tool call generated by the model. + - `filename: Optional[str]` - - `max_output_length: Optional[int]` + The name of the file to be sent to the model. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `output: List[Output]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - An array of shell call output contents + - `mode: Literal["explicit"]` - - `outcome: OutputOutcome` + The breakpoint mode. Always `explicit`. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `"explicit"` - - `class OutputOutcomeTimeout: …` + - `role: Literal["user", "assistant", "system", "developer"]` - Indicates that the shell call exceeded its configured time limit. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `type: Literal["timeout"]` + - `"user"` - The outcome type. Always `timeout`. + - `"assistant"` - - `"timeout"` + - `"system"` - - `class OutputOutcomeExit: …` + - `"developer"` - Indicates that the shell commands finished and returned an exit code. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `exit_code: int` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - Exit code from the shell process. + - `"commentary"` - - `type: Literal["exit"]` + - `"final_answer"` - The outcome type. Always `exit`. + - `type: Optional[Literal["message"]]` - - `"exit"` + The type of the message input. Always `message`. - - `stderr: str` + - `"message"` - The standard error output that was captured. + - `class Message: …` - - `stdout: str` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - The standard output that was captured. + - `content: BetaResponseInputMessageContentList` - - `created_by: Optional[str]` + A list of one or many input items to the model, containing different content + types. - The identifier of the actor that created the item. + - `class BetaResponseInputText: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + A text input to the model. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `class BetaResponseInputImage: …` - - `"in_progress"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"completed"` + - `class BetaResponseInputFile: …` - - `"incomplete"` + A file input to the model. - - `type: Literal["shell_call_output"]` + - `role: Literal["user", "system", "developer"]` - The type of the shell call output. Always `shell_call_output`. + The role of the message input. One of `user`, `system`, or `developer`. - - `"shell_call_output"` + - `"user"` - - `agent: Optional[Agent]` + - `"system"` + + - `"developer"` + + - `agent: Optional[MessageAgent]` The agent that produced this item. @@ -74076,1349 +85086,1280 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The execution context that produced this tool call. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class CallerDirect: …` + - `"in_progress"` - - `type: Literal["direct"]` + - `"completed"` - - `"direct"` + - `"incomplete"` - - `class CallerProgram: …` + - `type: Optional[Literal["message"]]` - - `caller_id: str` + The type of the message input. Always set to `message`. - The call ID of the program item that produced this tool call. + - `"message"` - - `type: Literal["program"]` + - `class BetaResponseOutputMessage: …` - - `"program"` + An output message from the model. - - `created_by: Optional[str]` + - `id: str` - The identifier of the actor that created the item. + The unique ID of the output message. - - `class BetaResponseApplyPatchToolCall: …` + - `content: List[Content]` - A tool call that applies file diffs by creating, deleting, or updating files. + The content of the output message. - - `id: str` + - `class BetaResponseOutputText: …` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + A text output from the model. - - `call_id: str` + - `annotations: List[Annotation]` - The unique ID of the apply patch tool call generated by the model. + The annotations of the text output. - - `operation: Operation` + - `class AnnotationFileCitation: …` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + A citation to a file. - - `class OperationCreateFile: …` + - `file_id: str` - Instruction describing how to create a file via the apply_patch tool. + The ID of the file. - - `diff: str` + - `filename: str` - Diff to apply. + The filename of the file cited. - - `path: str` + - `index: int` - Path of the file to create. + The index of the file in the list of files. - - `type: Literal["create_file"]` + - `type: Literal["file_citation"]` - Create a new file with the provided diff. + The type of the file citation. Always `file_citation`. - - `"create_file"` + - `"file_citation"` - - `class OperationDeleteFile: …` + - `class AnnotationURLCitation: …` - Instruction describing how to delete a file via the apply_patch tool. + A citation for a web resource used to generate a model response. - - `path: str` + - `end_index: int` - Path of the file to delete. + The index of the last character of the URL citation in the message. - - `type: Literal["delete_file"]` + - `start_index: int` - Delete the specified file. + The index of the first character of the URL citation in the message. - - `"delete_file"` + - `title: str` - - `class OperationUpdateFile: …` + The title of the web resource. - Instruction describing how to update a file via the apply_patch tool. + - `type: Literal["url_citation"]` - - `diff: str` + The type of the URL citation. Always `url_citation`. - Diff to apply. + - `"url_citation"` - - `path: str` + - `url: str` - Path of the file to update. + The URL of the web resource. - - `type: Literal["update_file"]` + - `class AnnotationContainerFileCitation: …` - Update an existing file with the provided diff. + A citation for a container file used to generate a model response. - - `"update_file"` + - `container_id: str` - - `status: Literal["in_progress", "completed"]` + The ID of the container file. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `end_index: int` - - `"in_progress"` + The index of the last character of the container file citation in the message. - - `"completed"` + - `file_id: str` - - `type: Literal["apply_patch_call"]` + The ID of the file. - The type of the item. Always `apply_patch_call`. + - `filename: str` - - `"apply_patch_call"` + The filename of the container file cited. - - `agent: Optional[Agent]` + - `start_index: int` - The agent that produced this item. + The index of the first character of the container file citation in the message. - - `agent_name: str` + - `type: Literal["container_file_citation"]` - The canonical name of the agent that produced this item. + The type of the container file citation. Always `container_file_citation`. - - `caller: Optional[Caller]` + - `"container_file_citation"` - The execution context that produced this tool call. + - `class AnnotationFilePath: …` - - `class CallerDirect: …` + A path to a file. - - `type: Literal["direct"]` + - `file_id: str` - - `"direct"` + The ID of the file. - - `class CallerProgram: …` + - `index: int` - - `caller_id: str` + The index of the file in the list of files. - The call ID of the program item that produced this tool call. + - `type: Literal["file_path"]` - - `type: Literal["program"]` + The type of the file path. Always `file_path`. - - `"program"` + - `"file_path"` - - `created_by: Optional[str]` + - `text: str` - The ID of the entity that created this tool call. + The text output from the model. - - `class BetaResponseApplyPatchToolCallOutput: …` + - `type: Literal["output_text"]` - The output emitted by an apply patch tool call. + The type of the output text. Always `output_text`. - - `id: str` + - `"output_text"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `logprobs: Optional[List[Logprob]]` - - `call_id: str` + - `token: str` - The unique ID of the apply patch tool call generated by the model. + - `bytes: List[int]` - - `status: Literal["completed", "failed"]` + - `logprob: float` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `top_logprobs: List[LogprobTopLogprob]` - - `"completed"` + - `token: str` - - `"failed"` + - `bytes: List[int]` - - `type: Literal["apply_patch_call_output"]` + - `logprob: float` - The type of the item. Always `apply_patch_call_output`. + - `class BetaResponseOutputRefusal: …` - - `"apply_patch_call_output"` + A refusal from the model. - - `agent: Optional[Agent]` + - `refusal: str` - The agent that produced this item. + The refusal explanation from the model. - - `agent_name: str` + - `type: Literal["refusal"]` - The canonical name of the agent that produced this item. + The type of the refusal. Always `refusal`. - - `caller: Optional[Caller]` + - `"refusal"` - The execution context that produced this tool call. + - `role: Literal["assistant"]` - - `class CallerDirect: …` + The role of the output message. Always `assistant`. - - `type: Literal["direct"]` + - `"assistant"` - - `"direct"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `class CallerProgram: …` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `caller_id: str` + - `"in_progress"` - The call ID of the program item that produced this tool call. + - `"completed"` - - `type: Literal["program"]` + - `"incomplete"` - - `"program"` + - `type: Literal["message"]` - - `created_by: Optional[str]` + The type of the output message. Always `message`. - The ID of the entity that created this tool call output. + - `"message"` - - `output: Optional[str]` + - `agent: Optional[Agent]` - Optional textual output returned by the apply patch tool. + The agent that produced this item. - - `class McpCall: …` + - `agent_name: str` - An invocation of a tool on an MCP server. + The canonical name of the agent that produced this item. - - `id: str` + - `phase: Optional[Literal["commentary", "final_answer"]]` - The unique ID of the tool call. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `arguments: str` + - `"commentary"` - A JSON string of the arguments passed to the tool. + - `"final_answer"` - - `name: str` + - `class BetaResponseFileSearchToolCall: …` - The name of the tool that was run. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `server_label: str` + - `id: str` - The label of the MCP server running the tool. + The unique ID of the file search tool call. - - `type: Literal["mcp_call"]` + - `queries: List[str]` - The type of the item. Always `mcp_call`. + The queries used to search for files. - - `"mcp_call"` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - - `agent: Optional[McpCallAgent]` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The agent that produced this item. + - `"in_progress"` - - `agent_name: str` + - `"searching"` - The canonical name of the agent that produced this item. + - `"completed"` - - `approval_request_id: Optional[str]` + - `"incomplete"` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `"failed"` - - `error: Optional[str]` + - `type: Literal["file_search_call"]` - The error from the tool call, if any. + The type of the file search tool call. Always `file_search_call`. - - `output: Optional[str]` + - `"file_search_call"` - The output from the tool call. + - `agent: Optional[Agent]` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + The agent that produced this item. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `agent_name: str` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"completed"` + - `results: Optional[List[Result]]` - - `"incomplete"` + The results of the file search tool call. - - `"calling"` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - - `"failed"` + 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, booleans, or numbers. - - `class McpListTools: …` + - `str` - A list of tools available on an MCP server. + - `float` - - `id: str` + - `bool` - The unique ID of the list. + - `file_id: Optional[str]` - - `server_label: str` + The unique ID of the file. - The label of the MCP server. + - `filename: Optional[str]` - - `tools: List[McpListToolsTool]` + The name of the file. - The tools available on the server. + - `score: Optional[float]` - - `input_schema: object` + The relevance score of the file - a value between 0 and 1. - The JSON schema describing the tool's input. + - `text: Optional[str]` - - `name: str` + The text that was retrieved from the file. - The name of the tool. + - `class BetaResponseComputerToolCall: …` - - `annotations: Optional[object]` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - Additional annotations about the tool. + - `id: str` - - `description: Optional[str]` + The unique ID of the computer call. - The description of the tool. + - `call_id: str` - - `type: Literal["mcp_list_tools"]` + An identifier used when responding to the tool call with output. - The type of the item. Always `mcp_list_tools`. + - `pending_safety_checks: List[PendingSafetyCheck]` - - `"mcp_list_tools"` + The pending safety checks for the computer call. - - `agent: Optional[McpListToolsAgent]` + - `id: str` - The agent that produced this item. + The ID of the pending safety check. - - `agent_name: str` + - `code: Optional[str]` - The canonical name of the agent that produced this item. + The type of the pending safety check. - - `error: Optional[str]` + - `message: Optional[str]` - Error message if the server could not list tools. + Details about the pending safety check. - - `class McpApprovalRequest: …` + - `status: Literal["in_progress", "completed", "incomplete"]` - A request for human approval of a tool invocation. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `id: str` + - `"in_progress"` - The unique ID of the approval request. + - `"completed"` - - `arguments: str` + - `"incomplete"` - A JSON string of arguments for the tool. + - `type: Literal["computer_call"]` - - `name: str` + The type of the computer call. Always `computer_call`. - The name of the tool to run. + - `"computer_call"` - - `server_label: str` + - `action: Optional[BetaComputerAction]` - The label of the MCP server making the request. + A click action. - - `type: Literal["mcp_approval_request"]` + - `class Click: …` - The type of the item. Always `mcp_approval_request`. + A click action. - - `"mcp_approval_request"` + - `button: Literal["left", "right", "wheel", 2 more]` - - `agent: Optional[McpApprovalRequestAgent]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The agent that produced this item. + - `"left"` - - `agent_name: str` + - `"right"` - The canonical name of the agent that produced this item. + - `"wheel"` - - `class McpApprovalResponse: …` + - `"back"` - A response to an MCP approval request. + - `"forward"` - - `id: str` + - `type: Literal["click"]` - The unique ID of the approval response + Specifies the event type. For a click action, this property is always `click`. - - `approval_request_id: str` + - `"click"` - The ID of the approval request being answered. + - `x: int` - - `approve: bool` + The x-coordinate where the click occurred. - Whether the request was approved. + - `y: int` - - `type: Literal["mcp_approval_response"]` + The y-coordinate where the click occurred. - The type of the item. Always `mcp_approval_response`. + - `keys: Optional[List[str]]` - - `"mcp_approval_response"` + The keys being held while clicking. - - `agent: Optional[McpApprovalResponseAgent]` + - `class DoubleClick: …` - The agent that produced this item. + A double click action. - - `agent_name: str` + - `keys: Optional[List[str]]` - The canonical name of the agent that produced this item. + The keys being held while double-clicking. - - `reason: Optional[str]` + - `type: Literal["double_click"]` - Optional reason for the decision. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `class BetaResponseCustomToolCall: …` + - `"double_click"` - A call to a custom tool created by the model. + - `x: int` - - `class BetaResponseCustomToolCallOutputItem: …` + The x-coordinate where the double click occurred. - The output of a custom tool call from your code, being sent back to the model. + - `y: int` - - `id: str` + The y-coordinate where the double click occurred. - The unique ID of the custom tool call output item. + - `class Drag: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + A drag action. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `path: List[DragPath]` - - `"in_progress"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"completed"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"incomplete"` + - `x: int` - - `created_by: Optional[str]` + The x-coordinate. - The identifier of the actor that created the item. + - `y: int` - - `parallel_tool_calls: bool` + The y-coordinate. - Whether to allow the model to run tool calls in parallel. + - `type: Literal["drag"]` - - `temperature: Optional[float]` + Specifies the event type. For a drag action, this property is always set to `drag`. - 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. - We generally recommend altering this or `top_p` but not both. + - `"drag"` - - `tool_choice: ToolChoice` + - `keys: Optional[List[str]]` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + The keys being held while dragging the mouse. - - `Literal["none", "auto", "required"]` + - `class Keypress: …` - - `"none"` + A collection of keypresses the model would like to perform. - - `"auto"` + - `keys: List[str]` - - `"required"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `class BetaToolChoiceAllowed: …` + - `type: Literal["keypress"]` - Constrains the tools available to the model to a pre-defined set. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `mode: Literal["auto", "required"]` + - `"keypress"` - Constrains the tools available to the model to a pre-defined set. + - `class Move: …` - `auto` allows the model to pick from among the allowed tools and generate a - message. + A mouse move action. - `required` requires the model to call one or more of the allowed tools. + - `type: Literal["move"]` - - `"auto"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"required"` + - `"move"` - - `tools: List[Dict[str, object]]` + - `x: int` - A list of tool definitions that the model should be allowed to call. + The x-coordinate to move to. - For the Responses API, the list of tool definitions might look like: + - `y: int` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The y-coordinate to move to. - - `type: Literal["allowed_tools"]` + - `keys: Optional[List[str]]` - Allowed tool configuration type. Always `allowed_tools`. + The keys being held while moving the mouse. - - `"allowed_tools"` + - `class Screenshot: …` - - `class BetaToolChoiceTypes: …` + A screenshot action. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `type: Literal["screenshot"]` - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"screenshot"` - Allowed values are: + - `class Scroll: …` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + A scroll action. - - `"file_search"` + - `scroll_x: int` - - `"web_search_preview"` + The horizontal scroll distance. - - `"computer"` + - `scroll_y: int` - - `"computer_use_preview"` + The vertical scroll distance. - - `"computer_use"` + - `type: Literal["scroll"]` - - `"web_search_preview_2025_03_11"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"image_generation"` + - `"scroll"` - - `"code_interpreter"` + - `x: int` - - `class BetaToolChoiceFunction: …` + The x-coordinate where the scroll occurred. - Use this option to force the model to call a specific function. + - `y: int` - - `name: str` + The y-coordinate where the scroll occurred. - The name of the function to call. + - `keys: Optional[List[str]]` - - `type: Literal["function"]` + The keys being held while scrolling. - For function calling, the type is always `function`. + - `class Type: …` - - `"function"` + An action to type in text. - - `class BetaToolChoiceMcp: …` + - `text: str` - Use this option to force the model to call a specific tool on a remote MCP server. + The text to type. - - `server_label: str` + - `type: Literal["type"]` - The label of the MCP server to use. + Specifies the event type. For a type action, this property is always set to `type`. - - `type: Literal["mcp"]` + - `"type"` - For MCP tools, the type is always `mcp`. + - `class Wait: …` - - `"mcp"` + A wait action. - - `name: Optional[str]` + - `type: Literal["wait"]` - The name of the tool to call on the server. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `class BetaToolChoiceCustom: …` + - `"wait"` - Use this option to force the model to call a specific custom tool. + - `actions: Optional[BetaComputerActionList]` - - `name: str` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The name of the custom tool to call. + - `class Click: …` - - `type: Literal["custom"]` + A click action. - For custom tool calling, the type is always `custom`. + - `class DoubleClick: …` - - `"custom"` + A double click action. - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + - `class Drag: …` - - `type: Literal["programmatic_tool_calling"]` + A drag action. - The tool to call. Always `programmatic_tool_calling`. + - `class Keypress: …` - - `"programmatic_tool_calling"` + A collection of keypresses the model would like to perform. - - `class BetaToolChoiceApplyPatch: …` + - `class Move: …` - Forces the model to call the apply_patch tool when executing a tool call. + A mouse move action. - - `type: Literal["apply_patch"]` + - `class Screenshot: …` - The tool to call. Always `apply_patch`. + A screenshot action. - - `"apply_patch"` + - `class Scroll: …` - - `class BetaToolChoiceShell: …` + A scroll action. - Forces the model to call the shell tool when a tool call is required. + - `class Type: …` - - `type: Literal["shell"]` + An action to type in text. - The tool to call. Always `shell`. + - `class Wait: …` - - `"shell"` + A wait action. - - `tools: List[BetaTool]` + - `agent: Optional[Agent]` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The agent that produced this item. - We support the following categories of tools: + - `agent_name: str` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The canonical name of the agent that produced this item. - - `class BetaFunctionTool: …` + - `class ComputerCallOutput: …` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The output of a computer tool call. - - `class BetaFileSearchTool: …` + - `call_id: str` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The ID of the computer tool call that produced the output. - - `class BetaComputerTool: …` + - `output: BetaResponseComputerToolCallOutputScreenshot` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A computer screenshot image used with the computer use tool. - - `class BetaComputerUsePreviewTool: …` + - `type: Literal["computer_screenshot"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `class BetaWebSearchTool: …` + - `"computer_screenshot"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `file_id: Optional[str]` - - `class Mcp: …` + The identifier of an uploaded file that contains the screenshot. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `image_url: Optional[str]` - - `class CodeInterpreter: …` + The URL of the screenshot image. - A tool that runs Python code to help generate a response to a prompt. + - `type: Literal["computer_call_output"]` - - `class ProgrammaticToolCalling: …` + The type of the computer tool call output. Always `computer_call_output`. - - `class ImageGeneration: …` + - `"computer_call_output"` - A tool that generates images using the GPT image models. + - `id: Optional[str]` - - `class LocalShell: …` + The ID of the computer tool call output. - A tool that allows the model to execute shell commands in a local environment. + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - - `class BetaFunctionShellTool: …` + The safety checks reported by the API that have been acknowledged by the developer. - A tool that allows the model to execute shell commands. + - `id: str` - - `class BetaCustomTool: …` + The ID of the pending safety check. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `code: Optional[str]` - - `class BetaNamespaceTool: …` + The type of the pending safety check. - Groups function/custom tools under a shared namespace. + - `message: Optional[str]` - - `class BetaToolSearchTool: …` + Details about the pending safety check. - Hosted or BYOT tool search configuration for deferred tools. + - `agent: Optional[ComputerCallOutputAgent]` - - `class BetaWebSearchPreviewTool: …` + The agent that produced this item. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `agent_name: str` - - `class BetaApplyPatchTool: …` + The canonical name of the agent that produced this item. - Allows the assistant to create, delete, or update files using unified diffs. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `top_p: Optional[float]` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - 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. + - `"in_progress"` - We generally recommend altering this or `temperature` but not both. + - `"completed"` - - `background: Optional[bool]` + - `"incomplete"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `class BetaResponseFunctionWebSearch: …` - - `completed_at: Optional[float]` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `id: str` - - `conversation: Optional[Conversation]` + The unique ID of the web search tool call. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `action: Action` - - `id: str` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - The unique ID of the conversation that this response was associated with. + - `class ActionSearch: …` - - `max_output_tokens: Optional[int]` + Action type "search" - Performs a web search query. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `type: Literal["search"]` - - `max_tool_calls: Optional[int]` + The action type. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `"search"` - - `moderation: Optional[Moderation]` + - `queries: Optional[List[str]]` - Moderation results for the response input and output, if moderated completions were requested. + The search queries. - - `input: ModerationInput` + - `query: Optional[str]` - Moderation for the response input. + The search query. - - `class ModerationInputModerationResult: …` + - `sources: Optional[List[ActionSearchSource]]` - A moderation result produced for the response input or output. + The sources used in the search. - - `categories: Dict[str, bool]` + - `type: Literal["url"]` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The type of source. Always `url`. - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `"url"` - Which modalities of input are reflected by the score for each category. + - `url: str` - - `"text"` + The URL of the source. - - `"image"` + - `class ActionOpenPage: …` - - `category_scores: Dict[str, float]` + Action type "open_page" - Opens a specific URL from search results. - A dictionary of moderation categories to scores. + - `type: Literal["open_page"]` - - `flagged: bool` + The action type. - A boolean indicating whether the content was flagged by any category. + - `"open_page"` - - `model: str` + - `url: Optional[str]` - The moderation model that produced this result. + The URL opened by the model. - - `type: Literal["moderation_result"]` + - `class ActionFindInPage: …` - The object type, which was always `moderation_result` for successful moderation results. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"moderation_result"` + - `pattern: str` - - `class ModerationInputError: …` + The pattern or text to search for within the page. - An error produced while attempting moderation for the response input or output. + - `type: Literal["find_in_page"]` - - `code: str` + The action type. - The error code. + - `"find_in_page"` - - `message: str` + - `url: str` - The error message. + The URL of the page searched for the pattern. - - `type: Literal["error"]` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - The object type, which was always `error` for moderation failures. + The status of the web search tool call. - - `"error"` + - `"in_progress"` - - `output: ModerationOutput` + - `"searching"` - Moderation for the response output. + - `"completed"` - - `class ModerationOutputModerationResult: …` + - `"failed"` - A moderation result produced for the response input or output. + - `type: Literal["web_search_call"]` - - `categories: Dict[str, bool]` + The type of the web search tool call. Always `web_search_call`. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"web_search_call"` - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `agent: Optional[Agent]` - Which modalities of input are reflected by the score for each category. + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. - - `"text"` + - `class BetaResponseFunctionToolCall: …` - - `"image"` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `category_scores: Dict[str, float]` + - `arguments: str` - A dictionary of moderation categories to scores. + A JSON string of the arguments to pass to the function. - - `flagged: bool` + - `call_id: str` - A boolean indicating whether the content was flagged by any category. + The unique ID of the function tool call generated by the model. - - `model: str` + - `name: str` - The moderation model that produced this result. + The name of the function to run. - - `type: Literal["moderation_result"]` + - `type: Literal["function_call"]` - The object type, which was always `moderation_result` for successful moderation results. + The type of the function tool call. Always `function_call`. - - `"moderation_result"` + - `"function_call"` - - `class ModerationOutputError: …` + - `id: Optional[str]` - An error produced while attempting moderation for the response input or output. + The unique ID of the function tool call. - - `code: str` + - `agent: Optional[Agent]` - The error code. + The agent that produced this item. - - `message: str` + - `agent_name: str` - The error message. + The canonical name of the agent that produced this item. - - `type: Literal["error"]` + - `caller: Optional[Caller]` - The object type, which was always `error` for moderation failures. + The execution context that produced this tool call. - - `"error"` + - `class CallerDirect: …` - - `previous_response_id: Optional[str]` + - `type: Literal["direct"]` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `"direct"` - - `prompt: Optional[BetaResponsePrompt]` + - `class CallerProgram: …` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `caller_id: str` - - `id: str` + The call ID of the program item that produced this tool call. - The unique identifier of the prompt template to use. + - `type: Literal["program"]` - - `variables: Optional[Dict[str, Variables]]` + - `"program"` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `namespace: Optional[str]` - - `str` + The namespace of the function to run. - - `class BetaResponseInputText: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A text input to the model. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class BetaResponseInputImage: …` + - `"in_progress"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"completed"` - - `class BetaResponseInputFile: …` + - `"incomplete"` - A file input to the model. + - `class FunctionCallOutput: …` - - `version: Optional[str]` + The output of a function tool call. - Optional version of the prompt template. + - `call_id: str` - - `prompt_cache_key: Optional[str]` + The unique ID of the function tool call generated by the model. - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - - `prompt_cache_options: Optional[PromptCacheOptions]` + Text, image, or file output of the function tool call. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `str` - - `mode: Literal["implicit", "explicit"]` + A JSON string of the output of the function tool call. - Whether implicit prompt-cache breakpoints were enabled. + - `List[BetaResponseFunctionCallOutputItem]` - - `"implicit"` + - `class BetaResponseInputTextContent: …` - - `"explicit"` + A text input to the model. - - `ttl: Literal["30m"]` + - `text: str` - The minimum lifetime applied to each cache breakpoint. + The text input to the model. - - `"30m"` + - `type: Literal["input_text"]` - - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + The type of the input item. Always `input_text`. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `"input_text"` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `mode: Literal["explicit"]` - - `"in_memory"` + The breakpoint mode. Always `explicit`. - - `"24h"` + - `"explicit"` - - `reasoning: Optional[Reasoning]` + - `class BetaResponseInputImageContent: …` - **gpt-5 and o-series models only** + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `type: Literal["input_image"]` - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + The type of the input item. Always `input_image`. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `"input_image"` - - `"auto"` + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - - `"current_turn"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"all_turns"` + - `"low"` - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + - `"high"` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `"auto"` - - `"none"` + - `"original"` - - `"minimal"` + - `file_id: Optional[str]` - - `"low"` + The ID of the file to be sent to the model. - - `"medium"` + - `image_url: Optional[str]` - - `"high"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"xhigh"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"max"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + - `mode: Literal["explicit"]` - **Deprecated:** use `summary` instead. + The breakpoint mode. Always `explicit`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"explicit"` - - `"auto"` + - `class BetaResponseInputFileContent: …` - - `"concise"` + A file input to the model. - - `"detailed"` + - `type: Literal["input_file"]` - - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + The type of the input item. Always `input_file`. - Controls the reasoning execution mode for the request. + - `"input_file"` - When returned on a response, this is the effective execution mode. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `str` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `Literal["standard", "pro"]` + - `"auto"` - Controls the reasoning execution mode for the request. + - `"low"` - When returned on a response, this is the effective execution mode. + - `"high"` - - `"standard"` + - `file_data: Optional[str]` - - `"pro"` + The base64-encoded data of the file to be sent to the model. - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + - `file_id: Optional[str]` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The ID of the file to be sent to the model. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `file_url: Optional[str]` - - `"auto"` + The URL of the file to be sent to the model. - - `"concise"` + - `filename: Optional[str]` - - `"detailed"` + The name of the file to be sent to the model. - - `safety_identifier: Optional[str]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + - `mode: Literal["explicit"]` - Specifies the processing type used for serving the request. + The breakpoint mode. Always `explicit`. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `"explicit"` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `type: Literal["function_call_output"]` - - `"auto"` + The type of the function tool call output. Always `function_call_output`. - - `"default"` + - `"function_call_output"` - - `"flex"` + - `id: Optional[str]` - - `"scale"` + The unique ID of the function tool call output. Populated when this item is returned via API. - - `"priority"` + - `agent: Optional[FunctionCallOutputAgent]` - - `status: Optional[BetaResponseStatus]` + The agent that produced this item. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `agent_name: str` - - `"completed"` + The canonical name of the agent that produced this item. - - `"failed"` + - `caller: Optional[FunctionCallOutputCaller]` - - `"in_progress"` + The execution context that produced this tool call. - - `"cancelled"` + - `class FunctionCallOutputCallerDirect: …` - - `"queued"` + - `type: Literal["direct"]` - - `"incomplete"` + The caller type. Always `direct`. - - `text: Optional[BetaResponseTextConfig]` + - `"direct"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `class FunctionCallOutputCallerProgram: …` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `caller_id: str` - - `format: Optional[BetaResponseFormatTextConfig]` + The call ID of the program item that produced this tool call. - An object specifying the format that the model must output. + - `type: Literal["program"]` - Configuring `{ "type": "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). + The caller type. Always `program`. - The default format is `{ "type": "text" }` with no additional options. + - `"program"` - **Not recommended for gpt-4o and newer models:** + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `class Text: …` + - `"in_progress"` - Default response format. Used to generate text responses. + - `"completed"` - - `type: Literal["text"]` + - `"incomplete"` - The type of response format being defined. Always `text`. + - `class AgentMessage: …` - - `"text"` + A message routed between agents. - - `class BetaResponseFormatTextJSONSchemaConfig: …` + - `author: str` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The sending agent identity. - - `name: str` + - `content: List[AgentMessageContent]` - 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. + Plaintext, image, or encrypted content sent between agents. - - `schema: Dict[str, object]` + - `class BetaResponseInputTextContent: …` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + A text input to the model. - - `type: Literal["json_schema"]` + - `class BetaResponseInputImageContent: …` - The type of response format being defined. Always `json_schema`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `"json_schema"` + - `class AgentMessageContentEncryptedContent: …` - - `description: Optional[str]` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `encrypted_content: str` - - `strict: Optional[bool]` + Opaque encrypted content. - 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["encrypted_content"]` - - `class JSONObject: …` + The type of the input item. Always `encrypted_content`. - 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. + - `"encrypted_content"` - - `type: Literal["json_object"]` + - `recipient: str` - The type of response format being defined. Always `json_object`. + The destination agent identity. - - `"json_object"` + - `type: Literal["agent_message"]` - - `verbosity: Optional[Literal["low", "medium", "high"]]` + The item type. Always `agent_message`. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `"agent_message"` - - `"low"` + - `id: Optional[str]` - - `"medium"` + The unique ID of this agent message item. - - `"high"` + - `agent: Optional[AgentMessageAgent]` - - `top_logprobs: Optional[int]` + The agent that produced this item. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `agent_name: str` - - `truncation: Optional[Literal["auto", "disabled"]]` + The canonical name of the agent that produced this item. - The truncation strategy to use for the model response. + - `class MultiAgentCall: …` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"auto"` + The multi-agent action that was executed. - - `"disabled"` + - `"spawn_agent"` - - `usage: Optional[BetaResponseUsage]` + - `"interrupt_agent"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `"list_agents"` - - `input_tokens: int` + - `"send_message"` - The number of input tokens. + - `"followup_task"` - - `input_tokens_details: InputTokensDetails` + - `"wait_agent"` - A detailed breakdown of the input tokens. + - `arguments: str` - - `cache_write_tokens: int` + The action arguments as a JSON string. - The number of input tokens that were written to the cache. + - `call_id: str` - - `cached_tokens: int` + The unique ID linking this call to its output. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `type: Literal["multi_agent_call"]` - - `output_tokens: int` + The item type. Always `multi_agent_call`. - The number of output tokens. + - `"multi_agent_call"` - - `output_tokens_details: OutputTokensDetails` + - `id: Optional[str]` - A detailed breakdown of the output tokens. + The unique ID of this multi-agent call. - - `reasoning_tokens: int` + - `agent: Optional[MultiAgentCallAgent]` - The number of reasoning tokens. + The agent that produced this item. - - `total_tokens: int` + - `agent_name: str` - The total number of tokens used. + The canonical name of the agent that produced this item. - - `user: Optional[str]` + - `class MultiAgentCallOutput: …` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `sequence_number: int` + The multi-agent action that produced this result. - The sequence number for this event. + - `"spawn_agent"` - - `type: Literal["response.created"]` + - `"interrupt_agent"` - The type of the event. Always `response.created`. + - `"list_agents"` - - `"response.created"` + - `"send_message"` - - `agent: Optional[Agent]` + - `"followup_task"` - The agent that owns this multi-agent streaming event. + - `"wait_agent"` - - `agent_name: str` + - `call_id: str` - The canonical name of the agent that produced this item. + The unique ID of the multi-agent call. -### Beta Response Custom Tool Call + - `output: List[MultiAgentCallOutputOutput]` -- `class BetaResponseCustomToolCall: …` + Text output returned by the multi-agent action. - A call to a custom tool created by the model. + - `text: str` - - `call_id: str` + The text content. - An identifier used to map this custom tool call to a tool call output. + - `type: Literal["output_text"]` - - `input: str` + The content type. Always `output_text`. - The input for the custom tool call generated by the model. + - `"output_text"` - - `name: str` + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - The name of the custom tool being called. + Citations associated with the text content. - - `type: Literal["custom_tool_call"]` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - The type of the custom tool call. Always `custom_tool_call`. + - `file_id: str` - - `"custom_tool_call"` + The ID of the file. - - `id: Optional[str]` + - `filename: str` - The unique ID of the custom tool call in the OpenAI platform. + The filename of the file cited. - - `agent: Optional[Agent]` + - `index: int` - The agent that produced this item. + The index of the file in the list of files. - - `agent_name: str` + - `type: Literal["file_citation"]` - The canonical name of the agent that produced this item. + The citation type. Always `file_citation`. - - `caller: Optional[Caller]` + - `"file_citation"` - The execution context that produced this tool call. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` - - `class CallerDirect: …` + - `end_index: int` - - `type: Literal["direct"]` + The index of the last character of the citation in the message. - - `"direct"` + - `start_index: int` - - `class CallerProgram: …` + The index of the first character of the citation in the message. - - `caller_id: str` + - `title: str` - The call ID of the program item that produced this tool call. + The title of the cited resource. - - `type: Literal["program"]` + - `type: Literal["url_citation"]` - - `"program"` + The citation type. Always `url_citation`. - - `namespace: Optional[str]` + - `"url_citation"` - The namespace of the custom tool being called. + - `url: str` -### Beta Response Custom Tool Call Input Delta Event + The URL of the cited resource. -- `class BetaResponseCustomToolCallInputDeltaEvent: …` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` - Event representing a delta (partial update) to the input of a custom tool call. + - `container_id: str` - - `delta: str` + The ID of the container. - The incremental input data (delta) for the custom tool call. + - `end_index: int` - - `item_id: str` + The index of the last character of the citation in the message. - Unique identifier for the API item associated with this event. + - `file_id: str` - - `output_index: int` + The ID of the container file. - The index of the output this delta applies to. + - `filename: str` - - `sequence_number: int` + The filename of the container file cited. - The sequence number of this event. + - `start_index: int` - - `type: Literal["response.custom_tool_call_input.delta"]` + The index of the first character of the citation in the message. - The event type identifier. + - `type: Literal["container_file_citation"]` - - `"response.custom_tool_call_input.delta"` + The citation type. Always `container_file_citation`. - - `agent: Optional[Agent]` + - `"container_file_citation"` - The agent that owns this multi-agent streaming event. + - `type: Literal["multi_agent_call_output"]` - - `agent_name: str` + The item type. Always `multi_agent_call_output`. - The canonical name of the agent that produced this item. + - `"multi_agent_call_output"` -### Beta Response Custom Tool Call Input Done Event + - `id: Optional[str]` -- `class BetaResponseCustomToolCallInputDoneEvent: …` + The unique ID of this multi-agent call output. - Event indicating that input for a custom tool call is complete. + - `agent: Optional[MultiAgentCallOutputAgent]` - - `input: str` + The agent that produced this item. - The complete input data for the custom tool call. + - `agent_name: str` - - `item_id: str` + The canonical name of the agent that produced this item. - Unique identifier for the API item associated with this event. + - `class ToolSearchCall: …` - - `output_index: int` + - `arguments: object` - The index of the output this event applies to. + The arguments supplied to the tool search call. - - `sequence_number: int` + - `type: Literal["tool_search_call"]` - The sequence number of this event. + The item type. Always `tool_search_call`. - - `type: Literal["response.custom_tool_call_input.done"]` + - `"tool_search_call"` - The event type identifier. + - `id: Optional[str]` - - `"response.custom_tool_call_input.done"` + The unique ID of this tool search call. - - `agent: Optional[Agent]` + - `agent: Optional[ToolSearchCallAgent]` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. -### Beta Response Custom Tool Call Item + - `call_id: Optional[str]` -- `class BetaResponseCustomToolCallItem: …` + The unique ID of the tool search call generated by the model. - A call to a custom tool created by the model. + - `execution: Optional[Literal["server", "client"]]` - - `id: str` + Whether tool search was executed by the server or by the client. - The unique ID of the custom tool call item. + - `"server"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"client"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the tool search call. - `"in_progress"` @@ -75426,1339 +86367,1366 @@ print(compacted_response) - `"incomplete"` - - `created_by: Optional[str]` + - `class BetaResponseToolSearchOutputItemParam: …` - The identifier of the actor that created the item. + - `tools: List[BetaTool]` -### Beta Response Custom Tool Call Output + The loaded tool definitions returned by the tool search output. -- `class BetaResponseCustomToolCallOutput: …` + - `class BetaFunctionTool: …` - The output of a custom tool call from your code, being sent back to the model. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `call_id: str` + - `name: str` - The call ID, used to map this custom tool call output to a custom tool call. + The name of the function to call. - - `output: Union[str, List[OutputOutputContentList]]` + - `parameters: Optional[Dict[str, object]]` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + A JSON schema object describing the parameters of the function. - - `str` + - `strict: Optional[bool]` - A string of the output of the custom tool call. + Whether strict parameter validation is enforced for this function tool. - - `List[OutputOutputContentList]` + - `type: Literal["function"]` - Text, image, or file output of the custom tool call. + The type of the function tool. Always `function`. - - `class BetaResponseInputText: …` + - `"function"` - A text input to the model. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `text: str` + The tool invocation context(s). - The text input to the model. + - `"direct"` - - `type: Literal["input_text"]` + - `"programmatic"` - The type of the input item. Always `input_text`. + - `defer_loading: Optional[bool]` - - `"input_text"` + Whether this function is deferred and loaded via tool search. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `description: Optional[str]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A description of the function. Used by the model to determine whether or not to call the function. - - `mode: Literal["explicit"]` + - `output_schema: Optional[Dict[str, object]]` - The breakpoint mode. Always `explicit`. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"explicit"` + - `class BetaFileSearchTool: …` - - `class BetaResponseInputImage: …` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `type: Literal["file_search"]` - - `detail: Literal["low", "high", "auto", "original"]` + The type of the file search tool. Always `file_search`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"file_search"` - - `"low"` + - `vector_store_ids: List[str]` - - `"high"` + The IDs of the vector stores to search. - - `"auto"` + - `filters: Optional[Filters]` - - `"original"` + A filter to apply. - - `type: Literal["input_image"]` + - `class FiltersComparisonFilter: …` - The type of the input item. Always `input_image`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"input_image"` + - `key: str` - - `file_id: Optional[str]` + The key to compare against the value. - The ID of the file to be sent to the model. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `image_url: Optional[str]` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"eq"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"ne"` - - `mode: Literal["explicit"]` + - `"gt"` - The breakpoint mode. Always `explicit`. + - `"gte"` - - `"explicit"` + - `"lt"` - - `class BetaResponseInputFile: …` + - `"lte"` - A file input to the model. + - `"in"` - - `type: Literal["input_file"]` + - `"nin"` - The type of the input item. Always `input_file`. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `"input_file"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `str` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `float` - - `"auto"` + - `bool` - - `"low"` + - `List[Union[str, float]]` - - `"high"` + - `str` - - `file_data: Optional[str]` + - `float` - The content of the file to be sent to the model. + - `class FiltersCompoundFilter: …` - - `file_id: Optional[str]` + Combine multiple filters using `and` or `or`. - The ID of the file to be sent to the model. + - `filters: List[FiltersCompoundFilterFilter]` - - `file_url: Optional[str]` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The URL of the file to be sent to the model. + - `class FiltersCompoundFilterFilterComparisonFilter: …` - - `filename: Optional[str]` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The name of the file to be sent to the model. + - `key: str` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The key to compare against the value. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `mode: Literal["explicit"]` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The breakpoint mode. Always `explicit`. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `"explicit"` + - `"eq"` - - `type: Literal["custom_tool_call_output"]` + - `"ne"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"gt"` - - `"custom_tool_call_output"` + - `"gte"` - - `id: Optional[str]` + - `"lt"` - The unique ID of the custom tool call output in the OpenAI platform. + - `"lte"` - - `agent: Optional[Agent]` + - `"in"` - The agent that produced this item. + - `"nin"` - - `agent_name: str` + - `value: Union[str, float, bool, List[Union[str, float]]]` - The canonical name of the agent that produced this item. + The value to compare against the attribute key; supports string, number, or boolean types. - - `caller: Optional[Caller]` + - `str` - The execution context that produced this tool call. + - `float` - - `class CallerDirect: …` + - `bool` - - `type: Literal["direct"]` + - `List[Union[str, float]]` - The caller type. Always `direct`. + - `str` - - `"direct"` + - `float` - - `class CallerProgram: …` + - `object` - - `caller_id: str` + - `type: Literal["and", "or"]` - The call ID of the program item that produced this tool call. + Type of operation: `and` or `or`. - - `type: Literal["program"]` + - `"and"` - The caller type. Always `program`. + - `"or"` - - `"program"` + - `max_num_results: Optional[int]` -### Beta Response Custom Tool Call Output Item + The maximum number of results to return. This number should be between 1 and 50 inclusive. -- `class BetaResponseCustomToolCallOutputItem: …` + - `ranking_options: Optional[RankingOptions]` - The output of a custom tool call from your code, being sent back to the model. + Ranking options for search. - - `id: str` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - The unique ID of the custom tool call output item. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `embedding_weight: float` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The weight of the embedding in the reciprocal ranking fusion. - - `"in_progress"` + - `text_weight: float` - - `"completed"` + The weight of the text in the reciprocal ranking fusion. - - `"incomplete"` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - - `created_by: Optional[str]` + The ranker to use for the file search. - The identifier of the actor that created the item. + - `"auto"` -### Beta Response Error + - `"default-2024-11-15"` -- `class BetaResponseError: …` + - `score_threshold: Optional[float]` - An error object returned when the model fails to generate a Response. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + - `class BetaComputerTool: …` - The error code for the response. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"server_error"` + - `type: Literal["computer"]` - - `"rate_limit_exceeded"` + The type of the computer tool. Always `computer`. - - `"invalid_prompt"` + - `"computer"` - - `"bio_policy"` + - `class BetaComputerUsePreviewTool: …` - - `"vector_store_timeout"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"invalid_image"` + - `display_height: int` - - `"invalid_image_format"` + The height of the computer display. - - `"invalid_base64_image"` + - `display_width: int` - - `"invalid_image_url"` + The width of the computer display. - - `"image_too_large"` + - `environment: Literal["windows", "mac", "linux", 2 more]` - - `"image_too_small"` + The type of computer environment to control. - - `"image_parse_error"` + - `"windows"` - - `"image_content_policy_violation"` + - `"mac"` - - `"invalid_image_mode"` + - `"linux"` - - `"image_file_too_large"` + - `"ubuntu"` - - `"unsupported_image_media_type"` + - `"browser"` - - `"empty_image_file"` + - `type: Literal["computer_use_preview"]` - - `"failed_to_download_image"` + The type of the computer use tool. Always `computer_use_preview`. - - `"image_file_not_found"` + - `"computer_use_preview"` - - `message: str` + - `class BetaWebSearchTool: …` - A human-readable description of the error. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). -### Beta Response Error Event + - `type: Literal["web_search", "web_search_2025_08_26"]` -- `class BetaResponseErrorEvent: …` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - Emitted when an error occurs. + - `"web_search"` - - `code: Optional[str]` + - `"web_search_2025_08_26"` - The error code. + - `filters: Optional[Filters]` - - `message: str` + Filters for the search. - The error message. + - `allowed_domains: Optional[List[str]]` - - `param: Optional[str]` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The error parameter. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `sequence_number: int` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The sequence number of this event. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `type: Literal["error"]` + - `"low"` - The type of the event. Always `error`. + - `"medium"` - - `"error"` + - `"high"` - - `agent: Optional[Agent]` + - `user_location: Optional[UserLocation]` - The agent that owns this multi-agent streaming event. + The approximate location of the user. - - `agent_name: str` + - `city: Optional[str]` - The canonical name of the agent that produced this item. + Free text input for the city of the user, e.g. `San Francisco`. -### Beta Response Failed Event + - `country: Optional[str]` -- `class BetaResponseFailedEvent: …` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - An event that is emitted when a response fails. + - `region: Optional[str]` - - `response: BetaResponse` + Free text input for the region of the user, e.g. `California`. - The response that failed. + - `timezone: Optional[str]` - - `id: str` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Unique identifier for this Response. + - `type: Optional[Literal["approximate"]]` - - `created_at: float` + The type of location approximation. Always `approximate`. - Unix timestamp (in seconds) of when this Response was created. + - `"approximate"` - - `error: Optional[BetaResponseError]` + - `class Mcp: …` - An error object returned when the model fails to generate a Response. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + - `server_label: str` - The error code for the response. + A label for this MCP server, used to identify it in tool calls. - - `"server_error"` + - `type: Literal["mcp"]` - - `"rate_limit_exceeded"` + The type of the MCP tool. Always `mcp`. - - `"invalid_prompt"` + - `"mcp"` - - `"bio_policy"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"vector_store_timeout"` + The tool invocation context(s). - - `"invalid_image"` + - `"direct"` - - `"invalid_image_format"` + - `"programmatic"` - - `"invalid_base64_image"` + - `allowed_tools: Optional[McpAllowedTools]` - - `"invalid_image_url"` + List of allowed tool names or a filter object. - - `"image_too_large"` + - `List[str]` - - `"image_too_small"` + A string array of allowed tool names - - `"image_parse_error"` + - `class McpAllowedToolsMcpToolFilter: …` - - `"image_content_policy_violation"` + A filter object to specify which tools are allowed. - - `"invalid_image_mode"` + - `read_only: Optional[bool]` - - `"image_file_too_large"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"unsupported_image_media_type"` + - `tool_names: Optional[List[str]]` - - `"empty_image_file"` + List of allowed tool names. - - `"failed_to_download_image"` + - `authorization: Optional[str]` - - `"image_file_not_found"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `message: str` + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - A human-readable description of the error. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `incomplete_details: Optional[IncompleteDetails]` + Currently supported `connector_id` values are: - Details about why the response is incomplete. + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` + - `"connector_dropbox"` - The reason why the response is incomplete. + - `"connector_gmail"` - - `"max_output_tokens"` + - `"connector_googlecalendar"` - - `"content_filter"` + - `"connector_googledrive"` - - `instructions: Union[str, List[BetaResponseInputItem], null]` + - `"connector_microsoftteams"` - A system (or developer) message inserted into the model's context. + - `"connector_outlookcalendar"` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `"connector_outlookemail"` - - `str` + - `"connector_sharepoint"` - A text input to the model, equivalent to a text input with the - `developer` role. + - `defer_loading: Optional[bool]` - - `List[BetaResponseInputItem]` + Whether this MCP tool is deferred and discovered via tool search. - A list of one or many input items to the model, containing - different content types. + - `headers: Optional[Dict[str, str]]` - - `class BetaEasyInputMessage: …` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `require_approval: Optional[McpRequireApproval]` - - `content: Union[str, BetaResponseInputMessageContentList]` + Specify which of the MCP server's tools require approval. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `class McpRequireApprovalMcpToolApprovalFilter: …` - - `str` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - A text input to the model. + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `List[BetaResponseInputContent]` + A filter object to specify which tools are allowed. - - `class BetaResponseInputText: …` + - `read_only: Optional[bool]` - A text input to the model. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Optional[List[str]]` + + List of allowed tool names. - - `text: str` + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - The text input to the model. + A filter object to specify which tools are allowed. - - `type: Literal["input_text"]` + - `read_only: Optional[bool]` - The type of the input item. Always `input_text`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"input_text"` + - `tool_names: Optional[List[str]]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + List of allowed tool names. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Literal["always", "never"]` - - `mode: Literal["explicit"]` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - The breakpoint mode. Always `explicit`. + - `"always"` - - `"explicit"` + - `"never"` - - `class BetaResponseInputImage: …` + - `server_description: Optional[str]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Optional description of the MCP server, used to provide more context. - - `detail: Literal["low", "high", "auto", "original"]` + - `server_url: Optional[str]` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"low"` + - `tunnel_id: Optional[str]` - - `"high"` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `"auto"` + - `class CodeInterpreter: …` - - `"original"` + A tool that runs Python code to help generate a response to a prompt. - - `type: Literal["input_image"]` + - `container: CodeInterpreterContainer` - The type of the input item. Always `input_image`. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `"input_image"` + - `str` - - `file_id: Optional[str]` + The container ID. - The ID of the file to be sent to the model. + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `image_url: Optional[str]` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: Literal["auto"]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + Always `auto`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"auto"` - - `mode: Literal["explicit"]` + - `file_ids: Optional[List[str]]` - The breakpoint mode. Always `explicit`. + An optional list of uploaded files to make available to your code. - - `"explicit"` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `class BetaResponseInputFile: …` + The memory limit for the code interpreter container. - A file input to the model. + - `"1g"` - - `type: Literal["input_file"]` + - `"4g"` - The type of the input item. Always `input_file`. + - `"16g"` - - `"input_file"` + - `"64g"` - - `detail: Optional[Literal["auto", "low", "high"]]` + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + Network access policy for the container. - - `"auto"` + - `class BetaContainerNetworkPolicyDisabled: …` - - `"low"` + - `type: Literal["disabled"]` - - `"high"` + Disable outbound network access. Always `disabled`. - - `file_data: Optional[str]` + - `"disabled"` - The content of the file to be sent to the model. + - `class BetaContainerNetworkPolicyAllowlist: …` - - `file_id: Optional[str]` + - `allowed_domains: List[str]` - The ID of the file to be sent to the model. + A list of allowed domains when type is `allowlist`. - - `file_url: Optional[str]` + - `type: Literal["allowlist"]` - The URL of the file to be sent to the model. + Allow outbound network access only to specified domains. Always `allowlist`. - - `filename: Optional[str]` + - `"allowlist"` - The name of the file to be sent to the model. + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + Optional domain-scoped secrets for allowlisted domains. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `domain: str` - - `mode: Literal["explicit"]` + The domain associated with the secret. - The breakpoint mode. Always `explicit`. + - `name: str` - - `"explicit"` + The name of the secret to inject for the domain. - - `role: Literal["user", "assistant", "system", "developer"]` + - `value: str` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The secret value to inject for the domain. - - `"user"` + - `type: Literal["code_interpreter"]` - - `"assistant"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"system"` + - `"code_interpreter"` - - `"developer"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `phase: Optional[Literal["commentary"]]` + The tool invocation context(s). - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `"direct"` - - `"commentary"` + - `"programmatic"` - - `type: Optional[Literal["message"]]` + - `class ProgrammaticToolCalling: …` - The type of the message input. Always `message`. + - `type: Literal["programmatic_tool_calling"]` - - `"message"` + The type of the tool. Always `programmatic_tool_calling`. - - `class Message: …` + - `"programmatic_tool_calling"` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + - `class ImageGeneration: …` - - `content: BetaResponseInputMessageContentList` + A tool that generates images using the GPT image models. - A list of one or many input items to the model, containing different content - types. + - `type: Literal["image_generation"]` - - `class BetaResponseInputText: …` + The type of the image generation tool. Always `image_generation`. - A text input to the model. + - `"image_generation"` - - `class BetaResponseInputImage: …` + - `action: Optional[Literal["generate", "edit", "auto"]]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Whether to generate a new image or edit an existing image. Default: `auto`. - - `class BetaResponseInputFile: …` + - `"generate"` - A file input to the model. + - `"edit"` - - `role: Literal["user", "system", "developer"]` + - `"auto"` - The role of the message input. One of `user`, `system`, or `developer`. + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `"user"` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `"system"` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `"developer"` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `agent: Optional[MessageAgent]` + - `"transparent"` - The agent that produced this item. + - `"opaque"` - - `agent_name: str` + - `"auto"` - The canonical name of the agent that produced this item. + - `input_fidelity: Optional[Literal["high", "low"]]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"high"` - - `"in_progress"` + - `"low"` - - `"completed"` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - - `"incomplete"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: Optional[Literal["message"]]` + - `file_id: Optional[str]` - The type of the message input. Always set to `message`. + File ID for the mask image. - - `"message"` + - `image_url: Optional[str]` - - `class BetaResponseOutputMessage: …` + Base64-encoded mask image. - An output message from the model. + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - - `id: str` + The image generation model to use. Default: `gpt-image-1`. - The unique ID of the output message. + - `str` - - `content: List[Content]` + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - The content of the output message. + The image generation model to use. Default: `gpt-image-1`. - - `class BetaResponseOutputText: …` + - `"gpt-image-1"` - A text output from the model. + - `"gpt-image-1-mini"` - - `annotations: List[Annotation]` + - `"gpt-image-2"` - The annotations of the text output. + - `"gpt-image-2-2026-04-21"` - - `class AnnotationFileCitation: …` + - `"gpt-image-1.5"` - A citation to a file. + - `"chatgpt-image-latest"` - - `file_id: str` + - `moderation: Optional[Literal["auto", "low"]]` - The ID of the file. + Moderation level for the generated image. Default: `auto`. - - `filename: str` + - `"auto"` - The filename of the file cited. + - `"low"` - - `index: int` + - `output_compression: Optional[int]` - The index of the file in the list of files. + Compression level for the output image. Default: 100. - - `type: Literal["file_citation"]` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - The type of the file citation. Always `file_citation`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"file_citation"` + - `"png"` - - `class AnnotationURLCitation: …` + - `"webp"` - A citation for a web resource used to generate a model response. + - `"jpeg"` - - `end_index: int` + - `partial_images: Optional[int]` - The index of the last character of the URL citation in the message. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `start_index: int` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - The index of the first character of the URL citation in the message. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `title: str` + - `"low"` - The title of the web resource. + - `"medium"` - - `type: Literal["url_citation"]` + - `"high"` - The type of the URL citation. Always `url_citation`. + - `"auto"` - - `"url_citation"` + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - - `url: str` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The URL of the web resource. + - `str` - - `class AnnotationContainerFileCitation: …` + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - A citation for a container file used to generate a model response. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `container_id: str` + - `"1024x1024"` - The ID of the container file. + - `"1024x1536"` - - `end_index: int` + - `"1536x1024"` - The index of the last character of the container file citation in the message. + - `"auto"` - - `file_id: str` + - `class LocalShell: …` - The ID of the file. + A tool that allows the model to execute shell commands in a local environment. - - `filename: str` + - `type: Literal["local_shell"]` - The filename of the container file cited. + The type of the local shell tool. Always `local_shell`. - - `start_index: int` + - `"local_shell"` - The index of the first character of the container file citation in the message. + - `class BetaFunctionShellTool: …` - - `type: Literal["container_file_citation"]` + A tool that allows the model to execute shell commands. - The type of the container file citation. Always `container_file_citation`. + - `type: Literal["shell"]` - - `"container_file_citation"` + The type of the shell tool. Always `shell`. - - `class AnnotationFilePath: …` + - `"shell"` - A path to a file. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `file_id: str` + The tool invocation context(s). - The ID of the file. + - `"direct"` - - `index: int` + - `"programmatic"` - The index of the file in the list of files. + - `environment: Optional[Environment]` - - `type: Literal["file_path"]` + - `class BetaContainerAuto: …` - The type of the file path. Always `file_path`. + - `type: Literal["container_auto"]` - - `"file_path"` + Automatically creates a container for this request - - `text: str` + - `"container_auto"` - The text output from the model. + - `file_ids: Optional[List[str]]` - - `type: Literal["output_text"]` + An optional list of uploaded files to make available to your code. - The type of the output text. Always `output_text`. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `"output_text"` + The memory limit for the container. - - `logprobs: Optional[List[Logprob]]` + - `"1g"` - - `token: str` + - `"4g"` - - `bytes: List[int]` + - `"16g"` - - `logprob: float` + - `"64g"` - - `top_logprobs: List[LogprobTopLogprob]` + - `network_policy: Optional[NetworkPolicy]` - - `token: str` + Network access policy for the container. - - `bytes: List[int]` + - `class BetaContainerNetworkPolicyDisabled: …` - - `logprob: float` + - `class BetaContainerNetworkPolicyAllowlist: …` - - `class BetaResponseOutputRefusal: …` + - `skills: Optional[List[Skill]]` - A refusal from the model. + An optional list of skills referenced by id or inline data. - - `refusal: str` + - `class BetaSkillReference: …` - The refusal explanation from the model. + - `skill_id: str` - - `type: Literal["refusal"]` + The ID of the referenced skill. - The type of the refusal. Always `refusal`. + - `type: Literal["skill_reference"]` - - `"refusal"` + References a skill created with the /v1/skills endpoint. - - `role: Literal["assistant"]` + - `"skill_reference"` - The role of the output message. Always `assistant`. + - `version: Optional[str]` - - `"assistant"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `class BetaInlineSkill: …` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `description: str` - - `"in_progress"` + The description of the skill. - - `"completed"` + - `name: str` - - `"incomplete"` + The name of the skill. - - `type: Literal["message"]` + - `source: BetaInlineSkillSource` - The type of the output message. Always `message`. + Inline skill payload - - `"message"` + - `data: str` - - `agent: Optional[Agent]` + Base64-encoded skill zip bundle. - The agent that produced this item. + - `media_type: Literal["application/zip"]` - - `agent_name: str` + The media type of the inline skill payload. Must be `application/zip`. - The canonical name of the agent that produced this item. + - `"application/zip"` - - `phase: Optional[Literal["commentary"]]` + - `type: Literal["base64"]` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The type of the inline skill source. Must be `base64`. - - `"commentary"` + - `"base64"` - - `class BetaResponseFileSearchToolCall: …` + - `type: Literal["inline"]` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + Defines an inline skill for this request. - - `id: str` + - `"inline"` - The unique ID of the file search tool call. + - `class BetaLocalEnvironment: …` - - `queries: List[str]` + - `type: Literal["local"]` - The queries used to search for files. + Use a local computer environment. - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `"local"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `skills: Optional[List[BetaLocalSkill]]` - - `"in_progress"` + An optional list of skills. - - `"searching"` + - `description: str` - - `"completed"` + The description of the skill. - - `"incomplete"` + - `name: str` - - `"failed"` + The name of the skill. - - `type: Literal["file_search_call"]` + - `path: str` - The type of the file search tool call. Always `file_search_call`. + The path to the directory containing the skill. - - `"file_search_call"` + - `class BetaContainerReference: …` - - `agent: Optional[Agent]` + - `container_id: str` - The agent that produced this item. + The ID of the referenced container. - - `agent_name: str` + - `type: Literal["container_reference"]` - The canonical name of the agent that produced this item. + References a container created with the /v1/containers endpoint - - `results: Optional[List[Result]]` + - `"container_reference"` - The results of the file search tool call. + - `class BetaCustomTool: …` - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - 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, booleans, or numbers. + - `name: str` - - `str` + The name of the custom tool, used to identify it in tool calls. - - `float` + - `type: Literal["custom"]` - - `bool` + The type of the custom tool. Always `custom`. - - `file_id: Optional[str]` + - `"custom"` - The unique ID of the file. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `filename: Optional[str]` + The tool invocation context(s). - The name of the file. + - `"direct"` - - `score: Optional[float]` + - `"programmatic"` - The relevance score of the file - a value between 0 and 1. + - `defer_loading: Optional[bool]` - - `text: Optional[str]` + Whether this tool should be deferred and discovered via tool search. - The text that was retrieved from the file. + - `description: Optional[str]` - - `class BetaResponseComputerToolCall: …` + Optional description of the custom tool, used to provide more context. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `format: Optional[Format]` - - `id: str` + The input format for the custom tool. Default is unconstrained text. - The unique ID of the computer call. + - `class FormatText: …` - - `call_id: str` + Unconstrained free-form text. - An identifier used when responding to the tool call with output. + - `type: Literal["text"]` - - `pending_safety_checks: List[PendingSafetyCheck]` + Unconstrained text format. Always `text`. - The pending safety checks for the computer call. + - `"text"` - - `id: str` + - `class FormatGrammar: …` - The ID of the pending safety check. + A grammar defined by the user. - - `code: Optional[str]` + - `definition: str` - The type of the pending safety check. + The grammar definition. - - `message: Optional[str]` + - `syntax: Literal["lark", "regex"]` - Details about the pending safety check. + The syntax of the grammar definition. One of `lark` or `regex`. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"lark"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"regex"` - - `"in_progress"` + - `type: Literal["grammar"]` - - `"completed"` + Grammar format. Always `grammar`. - - `"incomplete"` + - `"grammar"` - - `type: Literal["computer_call"]` + - `class BetaNamespaceTool: …` - The type of the computer call. Always `computer_call`. + Groups function/custom tools under a shared namespace. - - `"computer_call"` + - `description: str` - - `action: Optional[BetaComputerAction]` + A description of the namespace shown to the model. - A click action. + - `name: str` - - `class Click: …` + The namespace name used in tool calls (for example, `crm`). - A click action. + - `tools: List[Tool]` - - `button: Literal["left", "right", "wheel", 2 more]` + The function/custom tools available inside this namespace. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `class ToolFunction: …` - - `"left"` + - `name: str` - - `"right"` + - `type: Literal["function"]` - - `"wheel"` + - `"function"` - - `"back"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"forward"` + The tool invocation context(s). - - `type: Literal["click"]` + - `"direct"` - Specifies the event type. For a click action, this property is always `click`. + - `"programmatic"` - - `"click"` + - `defer_loading: Optional[bool]` - - `x: int` + Whether this function should be deferred and discovered via tool search. - The x-coordinate where the click occurred. + - `description: Optional[str]` - - `y: int` + - `output_schema: Optional[Dict[str, object]]` - The y-coordinate where the click occurred. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `keys: Optional[List[str]]` + - `parameters: Optional[object]` - The keys being held while clicking. + - `strict: Optional[bool]` - - `class DoubleClick: …` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - A double click action. + - `class BetaCustomTool: …` - - `keys: Optional[List[str]]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The keys being held while double-clicking. + - `type: Literal["namespace"]` - - `type: Literal["double_click"]` + The type of the tool. Always `namespace`. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"namespace"` - - `"double_click"` + - `class BetaToolSearchTool: …` - - `x: int` + Hosted or BYOT tool search configuration for deferred tools. - The x-coordinate where the double click occurred. + - `type: Literal["tool_search"]` - - `y: int` + The type of the tool. Always `tool_search`. - The y-coordinate where the double click occurred. + - `"tool_search"` - - `class Drag: …` + - `description: Optional[str]` - A drag action. + Description shown to the model for a client-executed tool search tool. - - `path: List[DragPath]` + - `execution: Optional[Literal["server", "client"]]` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Whether tool search is executed by the server or by the client. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"server"` - - `x: int` + - `"client"` - The x-coordinate. + - `parameters: Optional[object]` - - `y: int` + Parameter schema for a client-executed tool search tool. - The y-coordinate. + - `class BetaWebSearchPreviewTool: …` - - `type: Literal["drag"]` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Specifies the event type. For a drag action, this property is always set to `drag`. + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - - `"drag"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `keys: Optional[List[str]]` + - `"web_search_preview"` - The keys being held while dragging the mouse. + - `"web_search_preview_2025_03_11"` - - `class Keypress: …` + - `search_content_types: Optional[List[Literal["text", "image"]]]` - A collection of keypresses the model would like to perform. + - `"text"` - - `keys: List[str]` + - `"image"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `type: Literal["keypress"]` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"low"` - - `"keypress"` + - `"medium"` - - `class Move: …` + - `"high"` - A mouse move action. + - `user_location: Optional[UserLocation]` - - `type: Literal["move"]` + The user's location. - Specifies the event type. For a move action, this property is always set to `move`. + - `type: Literal["approximate"]` - - `"move"` + The type of location approximation. Always `approximate`. - - `x: int` + - `"approximate"` - The x-coordinate to move to. + - `city: Optional[str]` - - `y: int` + Free text input for the city of the user, e.g. `San Francisco`. - The y-coordinate to move to. + - `country: Optional[str]` - - `keys: Optional[List[str]]` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The keys being held while moving the mouse. + - `region: Optional[str]` - - `class Screenshot: …` + Free text input for the region of the user, e.g. `California`. - A screenshot action. + - `timezone: Optional[str]` - - `type: Literal["screenshot"]` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `class BetaApplyPatchTool: …` - - `"screenshot"` + Allows the assistant to create, delete, or update files using unified diffs. - - `class Scroll: …` + - `type: Literal["apply_patch"]` - A scroll action. + The type of the tool. Always `apply_patch`. - - `scroll_x: int` + - `"apply_patch"` - The horizontal scroll distance. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `scroll_y: int` + The tool invocation context(s). - The vertical scroll distance. + - `"direct"` - - `type: Literal["scroll"]` + - `"programmatic"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `type: Literal["tool_search_output"]` - - `"scroll"` + The item type. Always `tool_search_output`. - - `x: int` + - `"tool_search_output"` - The x-coordinate where the scroll occurred. + - `id: Optional[str]` - - `y: int` + The unique ID of this tool search output. - The y-coordinate where the scroll occurred. + - `agent: Optional[Agent]` - - `keys: Optional[List[str]]` + The agent that produced this item. - The keys being held while scrolling. + - `agent_name: str` - - `class Type: …` + The canonical name of the agent that produced this item. - An action to type in text. + - `call_id: Optional[str]` - - `text: str` + The unique ID of the tool search call generated by the model. - The text to type. + - `execution: Optional[Literal["server", "client"]]` - - `type: Literal["type"]` + Whether tool search was executed by the server or by the client. - Specifies the event type. For a type action, this property is always set to `type`. + - `"server"` - - `"type"` + - `"client"` - - `class Wait: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A wait action. + The status of the tool search output. - - `type: Literal["wait"]` + - `"in_progress"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"completed"` - - `"wait"` + - `"incomplete"` - - `actions: Optional[BetaComputerActionList]` + - `class AdditionalTools: …` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `role: Literal["developer"]` - - `class Click: …` + The role that provided the additional tools. Only `developer` is supported. - A click action. + - `"developer"` - - `class DoubleClick: …` + - `tools: List[BetaTool]` - A double click action. + A list of additional tools made available at this item. - - `class Drag: …` + - `class BetaFunctionTool: …` - A drag action. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `class Keypress: …` + - `class BetaFileSearchTool: …` - A collection of keypresses the model would like to perform. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `class Move: …` + - `class BetaComputerTool: …` - A mouse move action. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class Screenshot: …` + - `class BetaComputerUsePreviewTool: …` - A screenshot action. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class Scroll: …` + - `class BetaWebSearchTool: …` - A scroll action. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class Type: …` + - `class Mcp: …` - An action to type in text. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `class Wait: …` + - `class CodeInterpreter: …` - A wait action. + A tool that runs Python code to help generate a response to a prompt. - - `agent: Optional[Agent]` + - `class ProgrammaticToolCalling: …` - The agent that produced this item. + - `class ImageGeneration: …` - - `agent_name: str` + A tool that generates images using the GPT image models. - The canonical name of the agent that produced this item. + - `class LocalShell: …` - - `class ComputerCallOutput: …` + A tool that allows the model to execute shell commands in a local environment. - The output of a computer tool call. + - `class BetaFunctionShellTool: …` - - `call_id: str` + A tool that allows the model to execute shell commands. - The ID of the computer tool call that produced the output. + - `class BetaCustomTool: …` - - `output: BetaResponseComputerToolCallOutputScreenshot` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - A computer screenshot image used with the computer use tool. + - `class BetaNamespaceTool: …` - - `type: Literal["computer_screenshot"]` + Groups function/custom tools under a shared namespace. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `class BetaToolSearchTool: …` - - `"computer_screenshot"` + Hosted or BYOT tool search configuration for deferred tools. - - `file_id: Optional[str]` + - `class BetaWebSearchPreviewTool: …` - The identifier of an uploaded file that contains the screenshot. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `image_url: Optional[str]` + - `class BetaApplyPatchTool: …` - The URL of the screenshot image. + Allows the assistant to create, delete, or update files using unified diffs. - - `type: Literal["computer_call_output"]` + - `type: Literal["additional_tools"]` - The type of the computer tool call output. Always `computer_call_output`. + The item type. Always `additional_tools`. - - `"computer_call_output"` + - `"additional_tools"` - `id: Optional[str]` - The ID of the computer tool call output. + The unique ID of this additional tools item. - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + - `agent: Optional[AdditionalToolsAgent]` - The safety checks reported by the API that have been acknowledged by the developer. + The agent that produced this item. - - `id: str` + - `agent_name: str` - The ID of the pending safety check. + The canonical name of the agent that produced this item. - - `code: Optional[str]` + - `class BetaResponseReasoningItem: …` - The type of the pending safety check. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `message: Optional[str]` + - `id: str` - Details about the pending safety check. + The unique identifier of the reasoning content. - - `agent: Optional[ComputerCallOutputAgent]` + - `summary: List[Summary]` - The agent that produced this item. + Reasoning summary content. - - `agent_name: str` + - `text: str` - The canonical name of the agent that produced this item. + A summary of the reasoning output from the model so far. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `type: Literal["summary_text"]` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The type of the object. Always `summary_text`. - - `"in_progress"` + - `"summary_text"` - - `"completed"` + - `type: Literal["reasoning"]` - - `"incomplete"` + The type of the object. Always `reasoning`. - - `class BetaResponseFunctionWebSearch: …` + - `"reasoning"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `agent: Optional[Agent]` - - `id: str` + The agent that produced this item. - The unique ID of the web search tool call. + - `agent_name: str` - - `action: Action` + The canonical name of the agent that produced this item. - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `content: Optional[List[Content]]` - - `class ActionSearch: …` + Reasoning text content. - Action type "search" - Performs a web search query. + - `text: str` - - `type: Literal["search"]` + The reasoning text from the model. - The action type. + - `type: Literal["reasoning_text"]` - - `"search"` + The type of the reasoning text. Always `reasoning_text`. - - `queries: Optional[List[str]]` + - `"reasoning_text"` - The search queries. + - `encrypted_content: Optional[str]` - - `query: Optional[str]` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The search query. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `sources: Optional[List[ActionSearchSource]]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The sources used in the search. + - `"in_progress"` - - `type: Literal["url"]` + - `"completed"` - The type of source. Always `url`. + - `"incomplete"` - - `"url"` + - `class BetaResponseCompactionItemParam: …` - - `url: str` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The URL of the source. + - `encrypted_content: str` - - `class ActionOpenPage: …` + The encrypted content of the compaction summary. - Action type "open_page" - Opens a specific URL from search results. + - `type: Literal["compaction"]` - - `type: Literal["open_page"]` + The type of the item. Always `compaction`. - The action type. + - `"compaction"` - - `"open_page"` + - `id: Optional[str]` - - `url: Optional[str]` + The ID of the compaction item. - The URL opened by the model. + - `agent: Optional[Agent]` - - `class ActionFindInPage: …` + The agent that produced this item. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `agent_name: str` - - `pattern: str` + The canonical name of the agent that produced this item. - The pattern or text to search for within the page. + - `class ImageGenerationCall: …` - - `type: Literal["find_in_page"]` + An image generation request made by the model. - The action type. + - `id: str` - - `"find_in_page"` + The unique ID of the image generation call. - - `url: str` + - `result: Optional[str]` - The URL of the page searched for the pattern. + The generated image encoded in base64. - - `status: Literal["in_progress", "searching", "completed", "failed"]` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - The status of the web search tool call. + The status of the image generation call. - `"in_progress"` - - `"searching"` - - `"completed"` + - `"generating"` + - `"failed"` - - `type: Literal["web_search_call"]` + - `type: Literal["image_generation_call"]` - The type of the web search tool call. Always `web_search_call`. + The type of the image generation call. Always `image_generation_call`. - - `"web_search_call"` + - `"image_generation_call"` - - `agent: Optional[Agent]` + - `agent: Optional[ImageGenerationCallAgent]` The agent that produced this item. @@ -76766,215 +87734,220 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall: …` + - `class BetaResponseCodeInterpreterToolCall: …` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + A tool call to run code. - - `arguments: str` + - `id: str` - A JSON string of the arguments to pass to the function. + The unique ID of the code interpreter tool call. - - `call_id: str` + - `code: Optional[str]` - The unique ID of the function tool call generated by the model. + The code to run, or null if not available. - - `name: str` + - `container_id: str` - The name of the function to run. + The ID of the container used to run the code. - - `type: Literal["function_call"]` + - `outputs: Optional[List[Output]]` - The type of the function tool call. Always `function_call`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"function_call"` + - `class OutputLogs: …` - - `id: Optional[str]` + The logs output from the code interpreter. - The unique ID of the function tool call. + - `logs: str` - - `agent: Optional[Agent]` + The logs output from the code interpreter. - The agent that produced this item. + - `type: Literal["logs"]` - - `agent_name: str` + The type of the output. Always `logs`. - The canonical name of the agent that produced this item. + - `"logs"` - - `caller: Optional[Caller]` + - `class OutputImage: …` - The execution context that produced this tool call. + The image output from the code interpreter. - - `class CallerDirect: …` + - `type: Literal["image"]` - - `type: Literal["direct"]` + The type of the output. Always `image`. - - `"direct"` + - `"image"` - - `class CallerProgram: …` + - `url: str` - - `caller_id: str` + The URL of the image output from the code interpreter. - The call ID of the program item that produced this tool call. + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - - `type: Literal["program"]` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"program"` + - `"in_progress"` - - `namespace: Optional[str]` + - `"completed"` - The namespace of the function to run. + - `"incomplete"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"interpreting"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"failed"` - - `"in_progress"` + - `type: Literal["code_interpreter_call"]` - - `"completed"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"incomplete"` + - `"code_interpreter_call"` - - `class FunctionCallOutput: …` + - `agent: Optional[Agent]` - The output of a function tool call. + The agent that produced this item. - - `call_id: str` + - `agent_name: str` - The unique ID of the function tool call generated by the model. + The canonical name of the agent that produced this item. + + - `class LocalShellCall: …` + + A tool call to run a command on the local shell. + + - `id: str` - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + The unique ID of the local shell call. - Text, image, or file output of the function tool call. + - `action: LocalShellCallAction` - - `str` + Execute a shell command on the server. - A JSON string of the output of the function tool call. + - `command: List[str]` - - `List[BetaResponseFunctionCallOutputItem]` + The command to run. - - `class BetaResponseInputTextContent: …` + - `env: Dict[str, str]` - A text input to the model. + Environment variables to set for the command. - - `text: str` + - `type: Literal["exec"]` - The text input to the model. + The type of the local shell action. Always `exec`. - - `type: Literal["input_text"]` + - `"exec"` - The type of the input item. Always `input_text`. + - `timeout_ms: Optional[int]` - - `"input_text"` + Optional timeout in milliseconds for the command. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `user: Optional[str]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Optional user to run the command as. - - `mode: Literal["explicit"]` + - `working_directory: Optional[str]` - The breakpoint mode. Always `explicit`. + Optional working directory to run the command in. - - `"explicit"` + - `call_id: str` - - `class BetaResponseInputImageContent: …` + The unique ID of the local shell tool call generated by the model. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["input_image"]` + The status of the local shell call. - The type of the input item. Always `input_image`. + - `"in_progress"` - - `"input_image"` + - `"completed"` - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + - `"incomplete"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: Literal["local_shell_call"]` - - `"low"` + The type of the local shell call. Always `local_shell_call`. - - `"high"` + - `"local_shell_call"` - - `"auto"` + - `agent: Optional[LocalShellCallAgent]` - - `"original"` + The agent that produced this item. - - `file_id: Optional[str]` + - `agent_name: str` - The ID of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `image_url: Optional[str]` + - `class LocalShellCallOutput: …` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The output of a local shell tool call. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `id: str` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The unique ID of the local shell tool call generated by the model. - - `mode: Literal["explicit"]` + - `output: str` - The breakpoint mode. Always `explicit`. + A JSON string of the output of the local shell tool call. - - `"explicit"` + - `type: Literal["local_shell_call_output"]` - - `class BetaResponseInputFileContent: …` + The type of the local shell tool call output. Always `local_shell_call_output`. - A file input to the model. + - `"local_shell_call_output"` - - `type: Literal["input_file"]` + - `agent: Optional[LocalShellCallOutputAgent]` - The type of the input item. Always `input_file`. + The agent that produced this item. - - `"input_file"` + - `agent_name: str` - - `detail: Optional[Literal["auto", "low", "high"]]` + The canonical name of the agent that produced this item. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"auto"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"low"` + - `"in_progress"` - - `"high"` + - `"completed"` - - `file_data: Optional[str]` + - `"incomplete"` - The base64-encoded data of the file to be sent to the model. + - `class ShellCall: …` - - `file_id: Optional[str]` + A tool representing a request to execute one or more shell commands. - The ID of the file to be sent to the model. + - `action: ShellCallAction` - - `file_url: Optional[str]` + The shell commands and limits that describe how to run the tool call. - The URL of the file to be sent to the model. + - `commands: List[str]` - - `filename: Optional[str]` + Ordered shell commands for the execution environment to run. - The name of the file to be sent to the model. + - `max_output_length: Optional[int]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `timeout_ms: Optional[int]` - - `mode: Literal["explicit"]` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The breakpoint mode. Always `explicit`. + - `call_id: str` - - `"explicit"` + The unique ID of the shell tool call generated by the model. - - `type: Literal["function_call_output"]` + - `type: Literal["shell_call"]` - The type of the function tool call output. Always `function_call_output`. + The type of the item. Always `shell_call`. - - `"function_call_output"` + - `"shell_call"` - `id: Optional[str]` - The unique ID of the function tool call output. Populated when this item is returned via API. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `agent: Optional[FunctionCallOutputAgent]` + - `agent: Optional[ShellCallAgent]` The agent that produced this item. @@ -76982,11 +87955,11 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[FunctionCallOutputCaller]` + - `caller: Optional[ShellCallCaller]` The execution context that produced this tool call. - - `class FunctionCallOutputCallerDirect: …` + - `class ShellCallCallerDirect: …` - `type: Literal["direct"]` @@ -76994,7 +87967,7 @@ print(compacted_response) - `"direct"` - - `class FunctionCallOutputCallerProgram: …` + - `class ShellCallCallerProgram: …` - `caller_id: str` @@ -77006,109 +87979,83 @@ print(compacted_response) - `"program"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `class AgentMessage: …` - - A message routed between agents. - - - `author: str` - - The sending agent identity. - - - `content: List[AgentMessageContent]` - - Plaintext, image, or encrypted content sent between agents. - - - `class BetaResponseInputTextContent: …` - - A text input to the model. - - - `class BetaResponseInputImageContent: …` + - `environment: Optional[ShellCallEnvironment]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The environment to execute the shell commands in. - - `class AgentMessageContentEncryptedContent: …` + - `class BetaLocalEnvironment: …` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `class BetaContainerReference: …` - - `encrypted_content: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Opaque encrypted content. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `type: Literal["encrypted_content"]` + - `"in_progress"` - The type of the input item. Always `encrypted_content`. + - `"completed"` - - `"encrypted_content"` + - `"incomplete"` - - `recipient: str` + - `class ShellCallOutput: …` - The destination agent identity. + The streamed output items emitted by a shell tool call. - - `type: Literal["agent_message"]` + - `call_id: str` - The item type. Always `agent_message`. + The unique ID of the shell tool call generated by the model. - - `"agent_message"` + - `output: List[BetaResponseFunctionShellCallOutputContent]` - - `id: Optional[str]` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The unique ID of this agent message item. + - `outcome: Outcome` - - `agent: Optional[AgentMessageAgent]` + The exit or timeout outcome associated with this shell call. - The agent that produced this item. + - `class OutcomeTimeout: …` - - `agent_name: str` + Indicates that the shell call exceeded its configured time limit. - The canonical name of the agent that produced this item. + - `type: Literal["timeout"]` - - `class MultiAgentCall: …` + The outcome type. Always `timeout`. - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `"timeout"` - The multi-agent action that was executed. + - `class OutcomeExit: …` - - `"spawn_agent"` + Indicates that the shell commands finished and returned an exit code. - - `"interrupt_agent"` + - `exit_code: int` - - `"list_agents"` + The exit code returned by the shell process. - - `"send_message"` + - `type: Literal["exit"]` - - `"followup_task"` + The outcome type. Always `exit`. - - `"wait_agent"` + - `"exit"` - - `arguments: str` + - `stderr: str` - The action arguments as a JSON string. + Captured stderr output for the shell call. - - `call_id: str` + - `stdout: str` - The unique ID linking this call to its output. + Captured stdout output for the shell call. - - `type: Literal["multi_agent_call"]` + - `type: Literal["shell_call_output"]` - The item type. Always `multi_agent_call`. + The type of the item. Always `shell_call_output`. - - `"multi_agent_call"` + - `"shell_call_output"` - `id: Optional[str]` - The unique ID of this multi-agent call. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `agent: Optional[MultiAgentCallAgent]` + - `agent: Optional[ShellCallOutputAgent]` The agent that produced this item. @@ -77116,129 +88063,125 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput: …` - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - The multi-agent action that produced this result. + - `caller: Optional[ShellCallOutputCaller]` - - `"spawn_agent"` + The execution context that produced this tool call. - - `"interrupt_agent"` + - `class ShellCallOutputCallerDirect: …` - - `"list_agents"` + - `type: Literal["direct"]` - - `"send_message"` + The caller type. Always `direct`. - - `"followup_task"` + - `"direct"` - - `"wait_agent"` + - `class ShellCallOutputCallerProgram: …` - - `call_id: str` + - `caller_id: str` - The unique ID of the multi-agent call. + The call ID of the program item that produced this tool call. - - `output: List[MultiAgentCallOutputOutput]` + - `type: Literal["program"]` - Text output returned by the multi-agent action. + The caller type. Always `program`. - - `text: str` + - `"program"` - The text content. + - `max_output_length: Optional[int]` - - `type: Literal["output_text"]` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The content type. Always `output_text`. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"output_text"` + The status of the shell call output. - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + - `"in_progress"` - Citations associated with the text content. + - `"completed"` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + - `"incomplete"` - - `file_id: str` + - `class ApplyPatchCall: …` - The ID of the file. + A tool call representing a request to create, delete, or update files using diff patches. - - `filename: str` + - `call_id: str` - The filename of the file cited. + The unique ID of the apply patch tool call generated by the model. - - `index: int` + - `operation: ApplyPatchCallOperation` - The index of the file in the list of files. + The specific create, delete, or update instruction for the apply_patch tool call. - - `type: Literal["file_citation"]` + - `class ApplyPatchCallOperationCreateFile: …` - The citation type. Always `file_citation`. + Instruction for creating a new file via the apply_patch tool. - - `"file_citation"` + - `diff: str` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + Unified diff content to apply when creating the file. - - `end_index: int` + - `path: str` - The index of the last character of the citation in the message. + Path of the file to create relative to the workspace root. - - `start_index: int` + - `type: Literal["create_file"]` - The index of the first character of the citation in the message. + The operation type. Always `create_file`. - - `title: str` + - `"create_file"` - The title of the cited resource. + - `class ApplyPatchCallOperationDeleteFile: …` - - `type: Literal["url_citation"]` + Instruction for deleting an existing file via the apply_patch tool. - The citation type. Always `url_citation`. + - `path: str` - - `"url_citation"` + Path of the file to delete relative to the workspace root. - - `url: str` + - `type: Literal["delete_file"]` - The URL of the cited resource. + The operation type. Always `delete_file`. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `"delete_file"` - - `container_id: str` + - `class ApplyPatchCallOperationUpdateFile: …` - The ID of the container. + Instruction for updating an existing file via the apply_patch tool. - - `end_index: int` + - `diff: str` - The index of the last character of the citation in the message. + Unified diff content to apply to the existing file. - - `file_id: str` + - `path: str` - The ID of the container file. + Path of the file to update relative to the workspace root. - - `filename: str` + - `type: Literal["update_file"]` - The filename of the container file cited. + The operation type. Always `update_file`. - - `start_index: int` + - `"update_file"` - The index of the first character of the citation in the message. + - `status: Literal["in_progress", "completed"]` - - `type: Literal["container_file_citation"]` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The citation type. Always `container_file_citation`. + - `"in_progress"` - - `"container_file_citation"` + - `"completed"` - - `type: Literal["multi_agent_call_output"]` + - `type: Literal["apply_patch_call"]` - The item type. Always `multi_agent_call_output`. + The type of the item. Always `apply_patch_call`. - - `"multi_agent_call_output"` + - `"apply_patch_call"` - `id: Optional[str]` - The unique ID of this multi-agent call output. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `agent: Optional[MultiAgentCallOutputAgent]` + - `agent: Optional[ApplyPatchCallAgent]` The agent that produced this item. @@ -77246,1404 +88189,1371 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ToolSearchCall: …` - - - `arguments: object` - - The arguments supplied to the tool search call. - - - `type: Literal["tool_search_call"]` + - `caller: Optional[ApplyPatchCallCaller]` - The item type. Always `tool_search_call`. + The execution context that produced this tool call. - - `"tool_search_call"` + - `class ApplyPatchCallCallerDirect: …` - - `id: Optional[str]` + - `type: Literal["direct"]` - The unique ID of this tool search call. + The caller type. Always `direct`. - - `agent: Optional[ToolSearchCallAgent]` + - `"direct"` - The agent that produced this item. + - `class ApplyPatchCallCallerProgram: …` - - `agent_name: str` + - `caller_id: str` - The canonical name of the agent that produced this item. + The call ID of the program item that produced this tool call. - - `call_id: Optional[str]` + - `type: Literal["program"]` - The unique ID of the tool search call generated by the model. + The caller type. Always `program`. - - `execution: Optional[Literal["server", "client"]]` + - `"program"` - Whether tool search was executed by the server or by the client. + - `class ApplyPatchCallOutput: …` - - `"server"` + The streamed output emitted by an apply patch tool call. - - `"client"` + - `call_id: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The unique ID of the apply patch tool call generated by the model. - The status of the tool search call. + - `status: Literal["completed", "failed"]` - - `"in_progress"` + The status of the apply patch tool call output. One of `completed` or `failed`. - `"completed"` - - `"incomplete"` + - `"failed"` - - `class BetaResponseToolSearchOutputItemParam: …` + - `type: Literal["apply_patch_call_output"]` - - `tools: List[BetaTool]` + The type of the item. Always `apply_patch_call_output`. - The loaded tool definitions returned by the tool search output. + - `"apply_patch_call_output"` - - `class BetaFunctionTool: …` + - `id: Optional[str]` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `name: str` + - `agent: Optional[ApplyPatchCallOutputAgent]` - The name of the function to call. + The agent that produced this item. - - `parameters: Optional[Dict[str, object]]` + - `agent_name: str` - A JSON schema object describing the parameters of the function. + The canonical name of the agent that produced this item. - - `strict: Optional[bool]` + - `caller: Optional[ApplyPatchCallOutputCaller]` - Whether strict parameter validation is enforced for this function tool. + The execution context that produced this tool call. - - `type: Literal["function"]` + - `class ApplyPatchCallOutputCallerDirect: …` - The type of the function tool. Always `function`. + - `type: Literal["direct"]` - - `"function"` + The caller type. Always `direct`. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"direct"` - The tool invocation context(s). + - `class ApplyPatchCallOutputCallerProgram: …` - - `"direct"` + - `caller_id: str` - - `"programmatic"` + The call ID of the program item that produced this tool call. - - `defer_loading: Optional[bool]` + - `type: Literal["program"]` - Whether this function is deferred and loaded via tool search. + The caller type. Always `program`. - - `description: Optional[str]` + - `"program"` - A description of the function. Used by the model to determine whether or not to call the function. + - `output: Optional[str]` - - `output_schema: Optional[Dict[str, object]]` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class McpListTools: …` - - `class BetaFileSearchTool: …` + A list of tools available on an MCP server. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `id: str` - - `type: Literal["file_search"]` + The unique ID of the list. - The type of the file search tool. Always `file_search`. + - `server_label: str` - - `"file_search"` + The label of the MCP server. - - `vector_store_ids: List[str]` + - `tools: List[McpListToolsTool]` - The IDs of the vector stores to search. + The tools available on the server. - - `filters: Optional[Filters]` + - `input_schema: object` - A filter to apply. + The JSON schema describing the tool's input. - - `class FiltersComparisonFilter: …` + - `name: str` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The name of the tool. - - `key: str` + - `annotations: Optional[object]` - The key to compare against the value. + Additional annotations about the tool. - - `type: Literal["eq", "ne", "gt", 5 more]` + - `description: Optional[str]` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The description of the tool. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `type: Literal["mcp_list_tools"]` - - `"eq"` + The type of the item. Always `mcp_list_tools`. - - `"ne"` + - `"mcp_list_tools"` - - `"gt"` + - `agent: Optional[McpListToolsAgent]` - - `"gte"` + The agent that produced this item. - - `"lt"` + - `agent_name: str` - - `"lte"` + The canonical name of the agent that produced this item. - - `"in"` + - `error: Optional[str]` - - `"nin"` + Error message if the server could not list tools. - - `value: Union[str, float, bool, List[object]]` + - `class McpApprovalRequest: …` - The value to compare against the attribute key; supports string, number, or boolean types. + A request for human approval of a tool invocation. - - `str` + - `id: str` - - `float` + The unique ID of the approval request. - - `bool` + - `arguments: str` - - `List[object]` + A JSON string of arguments for the tool. - - `class FiltersCompoundFilter: …` + - `name: str` - Combine multiple filters using `and` or `or`. + The name of the tool to run. - - `filters: List[FiltersCompoundFilterFilter]` + - `server_label: str` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The label of the MCP server making the request. - - `class FiltersCompoundFilterFilterComparisonFilter: …` + - `type: Literal["mcp_approval_request"]` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The type of the item. Always `mcp_approval_request`. - - `key: str` + - `"mcp_approval_request"` - The key to compare against the value. + - `agent: Optional[McpApprovalRequestAgent]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The agent that produced this item. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `agent_name: str` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The canonical name of the agent that produced this item. - - `"eq"` + - `class McpApprovalResponse: …` - - `"ne"` + A response to an MCP approval request. - - `"gt"` + - `approval_request_id: str` - - `"gte"` + The ID of the approval request being answered. - - `"lt"` + - `approve: bool` - - `"lte"` + Whether the request was approved. - - `"in"` + - `type: Literal["mcp_approval_response"]` - - `"nin"` + The type of the item. Always `mcp_approval_response`. - - `value: Union[str, float, bool, List[object]]` + - `"mcp_approval_response"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `id: Optional[str]` - - `str` + The unique ID of the approval response - - `float` + - `agent: Optional[McpApprovalResponseAgent]` - - `bool` + The agent that produced this item. - - `List[object]` + - `agent_name: str` - - `object` + The canonical name of the agent that produced this item. - - `type: Literal["and", "or"]` + - `reason: Optional[str]` - Type of operation: `and` or `or`. + Optional reason for the decision. - - `"and"` + - `class McpCall: …` - - `"or"` + An invocation of a tool on an MCP server. - - `max_num_results: Optional[int]` + - `id: str` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The unique ID of the tool call. - - `ranking_options: Optional[RankingOptions]` + - `arguments: str` - Ranking options for search. + A JSON string of the arguments passed to the tool. - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + - `name: str` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The name of the tool that was run. - - `embedding_weight: float` + - `server_label: str` - The weight of the embedding in the reciprocal ranking fusion. + The label of the MCP server running the tool. - - `text_weight: float` + - `type: Literal["mcp_call"]` - The weight of the text in the reciprocal ranking fusion. + The type of the item. Always `mcp_call`. - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + - `"mcp_call"` - The ranker to use for the file search. + - `agent: Optional[McpCallAgent]` - - `"auto"` + The agent that produced this item. - - `"default-2024-11-15"` + - `agent_name: str` - - `score_threshold: Optional[float]` + The canonical name of the agent that produced this item. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `approval_request_id: Optional[str]` - - `class BetaComputerTool: …` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `error: Optional[str]` - - `type: Literal["computer"]` + The error from the tool call, if any. - The type of the computer tool. Always `computer`. + - `output: Optional[str]` - - `"computer"` + The output from the tool call. - - `class BetaComputerUsePreviewTool: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `display_height: int` + - `"in_progress"` - The height of the computer display. + - `"completed"` - - `display_width: int` + - `"incomplete"` - The width of the computer display. + - `"calling"` - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `"failed"` - The type of computer environment to control. + - `class BetaResponseCustomToolCallOutput: …` - - `"windows"` + The output of a custom tool call from your code, being sent back to the model. - - `"mac"` + - `call_id: str` - - `"linux"` + The call ID, used to map this custom tool call output to a custom tool call. - - `"ubuntu"` + - `output: Union[str, List[OutputOutputContentList]]` - - `"browser"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `type: Literal["computer_use_preview"]` + - `str` - The type of the computer use tool. Always `computer_use_preview`. + A string of the output of the custom tool call. - - `"computer_use_preview"` + - `List[OutputOutputContentList]` - - `class BetaWebSearchTool: …` + Text, image, or file output of the custom tool call. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class BetaResponseInputText: …` - - `type: Literal["web_search", "web_search_2025_08_26"]` + A text input to the model. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `class BetaResponseInputImage: …` - - `"web_search"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"web_search_2025_08_26"` + - `class BetaResponseInputFile: …` - - `filters: Optional[Filters]` + A file input to the model. - Filters for the search. + - `type: Literal["custom_tool_call_output"]` - - `allowed_domains: Optional[List[str]]` + The type of the custom tool call output. Always `custom_tool_call_output`. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"custom_tool_call_output"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `id: Optional[str]` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + The unique ID of the custom tool call output in the OpenAI platform. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `agent: Optional[Agent]` - - `"low"` + The agent that produced this item. - - `"medium"` + - `agent_name: str` - - `"high"` + The canonical name of the agent that produced this item. - - `user_location: Optional[UserLocation]` + - `caller: Optional[Caller]` - The approximate location of the user. + The execution context that produced this tool call. - - `city: Optional[str]` + - `class CallerDirect: …` - Free text input for the city of the user, e.g. `San Francisco`. + - `type: Literal["direct"]` - - `country: Optional[str]` + The caller type. Always `direct`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"direct"` - - `region: Optional[str]` + - `class CallerProgram: …` - Free text input for the region of the user, e.g. `California`. + - `caller_id: str` - - `timezone: Optional[str]` + The call ID of the program item that produced this tool call. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: Literal["program"]` - - `type: Optional[Literal["approximate"]]` + The caller type. Always `program`. - The type of location approximation. Always `approximate`. + - `"program"` - - `"approximate"` + - `class BetaResponseCustomToolCall: …` - - `class Mcp: …` + A call to a custom tool created by the model. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `call_id: str` - - `server_label: str` + An identifier used to map this custom tool call to a tool call output. - A label for this MCP server, used to identify it in tool calls. + - `input: str` - - `type: Literal["mcp"]` + The input for the custom tool call generated by the model. - The type of the MCP tool. Always `mcp`. + - `name: str` - - `"mcp"` + The name of the custom tool being called. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["custom_tool_call"]` - The tool invocation context(s). + The type of the custom tool call. Always `custom_tool_call`. - - `"direct"` + - `"custom_tool_call"` - - `"programmatic"` + - `id: Optional[str]` - - `allowed_tools: Optional[McpAllowedTools]` + The unique ID of the custom tool call in the OpenAI platform. - List of allowed tool names or a filter object. + - `agent: Optional[Agent]` - - `List[str]` + The agent that produced this item. - A string array of allowed tool names + - `agent_name: str` - - `class McpAllowedToolsMcpToolFilter: …` + The canonical name of the agent that produced this item. - A filter object to specify which tools are allowed. + - `caller: Optional[Caller]` - - `read_only: Optional[bool]` + The execution context that produced this tool call. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `class CallerDirect: …` - - `tool_names: Optional[List[str]]` + - `type: Literal["direct"]` - List of allowed tool names. + - `"direct"` - - `authorization: Optional[str]` + - `class CallerProgram: …` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `caller_id: str` - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + The call ID of the program item that produced this tool call. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `type: Literal["program"]` - Currently supported `connector_id` values are: + - `"program"` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `namespace: Optional[str]` - - `"connector_dropbox"` + The namespace of the custom tool being called. - - `"connector_gmail"` + - `class CompactionTrigger: …` - - `"connector_googlecalendar"` + Compacts the current context. Must be the final input item. - - `"connector_googledrive"` + - `type: Literal["compaction_trigger"]` - - `"connector_microsoftteams"` + The type of the item. Always `compaction_trigger`. - - `"connector_outlookcalendar"` + - `"compaction_trigger"` - - `"connector_outlookemail"` + - `agent: Optional[CompactionTriggerAgent]` - - `"connector_sharepoint"` + The agent that produced this item. - - `defer_loading: Optional[bool]` + - `agent_name: str` - Whether this MCP tool is deferred and discovered via tool search. + The canonical name of the agent that produced this item. - - `headers: Optional[Dict[str, str]]` + - `class ItemReference: …` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + An internal identifier for an item to reference. - - `require_approval: Optional[McpRequireApproval]` + - `id: str` - Specify which of the MCP server's tools require approval. + The ID of the item to reference. - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `agent: Optional[ItemReferenceAgent]` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The agent that produced this item. - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `agent_name: str` - A filter object to specify which tools are allowed. + The canonical name of the agent that produced this item. - - `read_only: Optional[bool]` + - `type: Optional[Literal["item_reference"]]` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The type of item to reference. Always `item_reference`. - - `tool_names: Optional[List[str]]` + - `"item_reference"` - List of allowed tool names. + - `class Program: …` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + - `id: str` - A filter object to specify which tools are allowed. + The unique ID of this program item. - - `read_only: Optional[bool]` + - `call_id: str` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The stable call ID of the program item. - - `tool_names: Optional[List[str]]` + - `code: str` - List of allowed tool names. + The JavaScript source executed by programmatic tool calling. - - `Literal["always", "never"]` + - `fingerprint: str` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + Opaque program replay fingerprint that must be round-tripped. - - `"always"` + - `type: Literal["program"]` - - `"never"` + The item type. Always `program`. - - `server_description: Optional[str]` + - `"program"` - Optional description of the MCP server, used to provide more context. + - `agent: Optional[ProgramAgent]` - - `server_url: Optional[str]` + The agent that produced this item. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `agent_name: str` - - `tunnel_id: Optional[str]` + The canonical name of the agent that produced this item. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `class ProgramOutput: …` - - `class CodeInterpreter: …` + - `id: str` - A tool that runs Python code to help generate a response to a prompt. + The unique ID of this program output item. - - `container: CodeInterpreterContainer` + - `call_id: str` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The call ID of the program item. - - `str` + - `result: str` - The container ID. + The result produced by the program item. - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `status: Literal["completed", "incomplete"]` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The terminal status of the program output. - - `type: Literal["auto"]` + - `"completed"` - Always `auto`. + - `"incomplete"` - - `"auto"` + - `type: Literal["program_output"]` - - `file_ids: Optional[List[str]]` + The item type. Always `program_output`. - An optional list of uploaded files to make available to your code. + - `"program_output"` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `agent: Optional[ProgramOutputAgent]` - The memory limit for the code interpreter container. + The agent that produced this item. - - `"1g"` + - `agent_name: str` - - `"4g"` + The canonical name of the agent that produced this item. - - `"16g"` + - `response_id: str` - - `"64g"` + The ID of the response that rejected the input. - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `sequence_number: int` - Network access policy for the container. + The sequence number for this event. - - `class BetaContainerNetworkPolicyDisabled: …` + - `type: Literal["response.inject.failed"]` - - `type: Literal["disabled"]` + The event discriminator. Always `response.inject.failed`. - Disable outbound network access. Always `disabled`. + - `"response.inject.failed"` - - `"disabled"` + - `stream_id: Optional[str]` - - `class BetaContainerNetworkPolicyAllowlist: …` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `allowed_domains: List[str]` +### Beta Response Input - A list of allowed domains when type is `allowlist`. +- `List[BetaResponseInputItem]` - - `type: Literal["allowlist"]` + A list of one or many input items to the model, containing + different content types. - Allow outbound network access only to specified domains. Always `allowlist`. + - `class BetaEasyInputMessage: …` - - `"allowlist"` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `content: Union[str, BetaResponseInputMessageContentList]` - Optional domain-scoped secrets for allowlisted domains. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `domain: str` + - `str` - The domain associated with the secret. + A text input to the model. - - `name: str` + - `List[BetaResponseInputContent]` - The name of the secret to inject for the domain. + - `class BetaResponseInputText: …` - - `value: str` + A text input to the model. - The secret value to inject for the domain. + - `text: str` - - `type: Literal["code_interpreter"]` + The text input to the model. - The type of the code interpreter tool. Always `code_interpreter`. + - `type: Literal["input_text"]` - - `"code_interpreter"` + The type of the input item. Always `input_text`. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"input_text"` - The tool invocation context(s). + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"direct"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"programmatic"` + - `mode: Literal["explicit"]` - - `class ProgrammaticToolCalling: …` + The breakpoint mode. Always `explicit`. - - `type: Literal["programmatic_tool_calling"]` + - `"explicit"` - The type of the tool. Always `programmatic_tool_calling`. + - `class BetaResponseInputImage: …` - - `"programmatic_tool_calling"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class ImageGeneration: …` + - `detail: Literal["low", "high", "auto", "original"]` - A tool that generates images using the GPT image models. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: Literal["image_generation"]` + - `"low"` - The type of the image generation tool. Always `image_generation`. + - `"high"` - - `"image_generation"` + - `"auto"` - - `action: Optional[Literal["generate", "edit", "auto"]]` + - `"original"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `type: Literal["input_image"]` - - `"generate"` + The type of the input item. Always `input_image`. - - `"edit"` + - `"input_image"` - - `"auto"` + - `file_id: Optional[str]` - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + The ID of the file to be sent to the model. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `image_url: Optional[str]` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"transparent"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"opaque"` + - `mode: Literal["explicit"]` - - `"auto"` + The breakpoint mode. Always `explicit`. - - `input_fidelity: Optional[Literal["high", "low"]]` + - `"explicit"` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `class BetaResponseInputFile: …` - - `"high"` + A file input to the model. - - `"low"` + - `type: Literal["input_file"]` - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + The type of the input item. Always `input_file`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"input_file"` - - `file_id: Optional[str]` + - `detail: Optional[Literal["auto", "low", "high"]]` - File ID for the mask image. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `image_url: Optional[str]` + - `"auto"` - Base64-encoded mask image. + - `"low"` - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + - `"high"` - The image generation model to use. Default: `gpt-image-1`. + - `file_data: Optional[str]` - - `str` + The content of the file to be sent to the model. - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `file_id: Optional[str]` - The image generation model to use. Default: `gpt-image-1`. + The ID of the file to be sent to the model. - - `"gpt-image-1"` + - `file_url: Optional[str]` - - `"gpt-image-1-mini"` + The URL of the file to be sent to the model. - - `"gpt-image-2"` + - `filename: Optional[str]` - - `"gpt-image-2-2026-04-21"` + The name of the file to be sent to the model. - - `"gpt-image-1.5"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"chatgpt-image-latest"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `moderation: Optional[Literal["auto", "low"]]` + - `mode: Literal["explicit"]` - Moderation level for the generated image. Default: `auto`. + The breakpoint mode. Always `explicit`. - - `"auto"` + - `"explicit"` - - `"low"` + - `role: Literal["user", "assistant", "system", "developer"]` - - `output_compression: Optional[int]` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - Compression level for the output image. Default: 100. + - `"user"` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + - `"assistant"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"system"` - - `"png"` + - `"developer"` - - `"webp"` + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `"jpeg"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `partial_images: Optional[int]` + - `"commentary"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"final_answer"` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + - `type: Optional[Literal["message"]]` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The type of the message input. Always `message`. - - `"low"` + - `"message"` - - `"medium"` + - `class Message: …` - - `"high"` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `"auto"` + - `content: BetaResponseInputMessageContentList` - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + A list of one or many input items to the model, containing different content + types. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `class BetaResponseInputText: …` - - `str` + A text input to the model. - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `class BetaResponseInputImage: …` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"1024x1024"` + - `class BetaResponseInputFile: …` - - `"1024x1536"` + A file input to the model. - - `"1536x1024"` + - `role: Literal["user", "system", "developer"]` - - `"auto"` + The role of the message input. One of `user`, `system`, or `developer`. - - `class LocalShell: …` + - `"user"` - A tool that allows the model to execute shell commands in a local environment. + - `"system"` - - `type: Literal["local_shell"]` + - `"developer"` - The type of the local shell tool. Always `local_shell`. + - `agent: Optional[MessageAgent]` - - `"local_shell"` + The agent that produced this item. - - `class BetaFunctionShellTool: …` + - `agent_name: str` - A tool that allows the model to execute shell commands. + The canonical name of the agent that produced this item. - - `type: Literal["shell"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The type of the shell tool. Always `shell`. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"shell"` + - `"in_progress"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"completed"` - The tool invocation context(s). + - `"incomplete"` - - `"direct"` + - `type: Optional[Literal["message"]]` - - `"programmatic"` + The type of the message input. Always set to `message`. - - `environment: Optional[Environment]` + - `"message"` - - `class BetaContainerAuto: …` + - `class BetaResponseOutputMessage: …` - - `type: Literal["container_auto"]` + An output message from the model. - Automatically creates a container for this request + - `id: str` - - `"container_auto"` + The unique ID of the output message. - - `file_ids: Optional[List[str]]` + - `content: List[Content]` - An optional list of uploaded files to make available to your code. + The content of the output message. - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `class BetaResponseOutputText: …` - The memory limit for the container. + A text output from the model. - - `"1g"` + - `annotations: List[Annotation]` - - `"4g"` + The annotations of the text output. - - `"16g"` + - `class AnnotationFileCitation: …` - - `"64g"` + A citation to a file. - - `network_policy: Optional[NetworkPolicy]` + - `file_id: str` - Network access policy for the container. + The ID of the file. - - `class BetaContainerNetworkPolicyDisabled: …` + - `filename: str` - - `class BetaContainerNetworkPolicyAllowlist: …` + The filename of the file cited. - - `skills: Optional[List[Skill]]` + - `index: int` - An optional list of skills referenced by id or inline data. + The index of the file in the list of files. - - `class BetaSkillReference: …` + - `type: Literal["file_citation"]` - - `skill_id: str` + The type of the file citation. Always `file_citation`. - The ID of the referenced skill. + - `"file_citation"` - - `type: Literal["skill_reference"]` + - `class AnnotationURLCitation: …` - References a skill created with the /v1/skills endpoint. + A citation for a web resource used to generate a model response. - - `"skill_reference"` + - `end_index: int` - - `version: Optional[str]` + The index of the last character of the URL citation in the message. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `start_index: int` - - `class BetaInlineSkill: …` + The index of the first character of the URL citation in the message. - - `description: str` + - `title: str` - The description of the skill. + The title of the web resource. - - `name: str` + - `type: Literal["url_citation"]` - The name of the skill. + The type of the URL citation. Always `url_citation`. - - `source: BetaInlineSkillSource` + - `"url_citation"` - Inline skill payload + - `url: str` - - `data: str` + The URL of the web resource. - Base64-encoded skill zip bundle. + - `class AnnotationContainerFileCitation: …` - - `media_type: Literal["application/zip"]` + A citation for a container file used to generate a model response. - The media type of the inline skill payload. Must be `application/zip`. + - `container_id: str` - - `"application/zip"` + The ID of the container file. - - `type: Literal["base64"]` + - `end_index: int` - The type of the inline skill source. Must be `base64`. + The index of the last character of the container file citation in the message. - - `"base64"` + - `file_id: str` - - `type: Literal["inline"]` + The ID of the file. - Defines an inline skill for this request. + - `filename: str` - - `"inline"` + The filename of the container file cited. - - `class BetaLocalEnvironment: …` + - `start_index: int` - - `type: Literal["local"]` + The index of the first character of the container file citation in the message. - Use a local computer environment. + - `type: Literal["container_file_citation"]` - - `"local"` + The type of the container file citation. Always `container_file_citation`. - - `skills: Optional[List[BetaLocalSkill]]` + - `"container_file_citation"` - An optional list of skills. + - `class AnnotationFilePath: …` - - `description: str` + A path to a file. - The description of the skill. + - `file_id: str` - - `name: str` + The ID of the file. - The name of the skill. + - `index: int` - - `path: str` + The index of the file in the list of files. - The path to the directory containing the skill. + - `type: Literal["file_path"]` - - `class BetaContainerReference: …` + The type of the file path. Always `file_path`. - - `container_id: str` + - `"file_path"` - The ID of the referenced container. + - `text: str` - - `type: Literal["container_reference"]` + The text output from the model. - References a container created with the /v1/containers endpoint + - `type: Literal["output_text"]` - - `"container_reference"` + The type of the output text. Always `output_text`. - - `class BetaCustomTool: …` + - `"output_text"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `logprobs: Optional[List[Logprob]]` - - `name: str` + - `token: str` - The name of the custom tool, used to identify it in tool calls. + - `bytes: List[int]` - - `type: Literal["custom"]` + - `logprob: float` - The type of the custom tool. Always `custom`. + - `top_logprobs: List[LogprobTopLogprob]` - - `"custom"` + - `token: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `bytes: List[int]` - The tool invocation context(s). + - `logprob: float` - - `"direct"` + - `class BetaResponseOutputRefusal: …` - - `"programmatic"` + A refusal from the model. - - `defer_loading: Optional[bool]` + - `refusal: str` - Whether this tool should be deferred and discovered via tool search. + The refusal explanation from the model. - - `description: Optional[str]` + - `type: Literal["refusal"]` - Optional description of the custom tool, used to provide more context. + The type of the refusal. Always `refusal`. - - `format: Optional[Format]` + - `"refusal"` - The input format for the custom tool. Default is unconstrained text. + - `role: Literal["assistant"]` - - `class FormatText: …` + The role of the output message. Always `assistant`. - Unconstrained free-form text. + - `"assistant"` - - `type: Literal["text"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - Unconstrained text format. Always `text`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"text"` + - `"in_progress"` - - `class FormatGrammar: …` + - `"completed"` - A grammar defined by the user. + - `"incomplete"` - - `definition: str` + - `type: Literal["message"]` - The grammar definition. + The type of the output message. Always `message`. - - `syntax: Literal["lark", "regex"]` + - `"message"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `agent: Optional[Agent]` - - `"lark"` + The agent that produced this item. - - `"regex"` + - `agent_name: str` - - `type: Literal["grammar"]` + The canonical name of the agent that produced this item. - Grammar format. Always `grammar`. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `"grammar"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `class BetaNamespaceTool: …` + - `"commentary"` - Groups function/custom tools under a shared namespace. + - `"final_answer"` - - `description: str` + - `class BetaResponseFileSearchToolCall: …` - A description of the namespace shown to the model. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `name: str` + - `id: str` - The namespace name used in tool calls (for example, `crm`). + The unique ID of the file search tool call. - - `tools: List[Tool]` + - `queries: List[str]` - The function/custom tools available inside this namespace. + The queries used to search for files. - - `class ToolFunction: …` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - - `name: str` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `type: Literal["function"]` + - `"in_progress"` - - `"function"` + - `"searching"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"completed"` - The tool invocation context(s). + - `"incomplete"` - - `"direct"` + - `"failed"` - - `"programmatic"` + - `type: Literal["file_search_call"]` - - `defer_loading: Optional[bool]` + The type of the file search tool call. Always `file_search_call`. - Whether this function should be deferred and discovered via tool search. + - `"file_search_call"` - - `description: Optional[str]` + - `agent: Optional[Agent]` - - `output_schema: Optional[Dict[str, object]]` + The agent that produced this item. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `agent_name: str` - - `parameters: Optional[object]` + The canonical name of the agent that produced this item. - - `strict: Optional[bool]` + - `results: Optional[List[Result]]` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The results of the file search tool call. - - `class BetaCustomTool: …` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + 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, booleans, or numbers. - - `type: Literal["namespace"]` + - `str` - The type of the tool. Always `namespace`. + - `float` - - `"namespace"` + - `bool` - - `class BetaToolSearchTool: …` + - `file_id: Optional[str]` - Hosted or BYOT tool search configuration for deferred tools. + The unique ID of the file. - - `type: Literal["tool_search"]` + - `filename: Optional[str]` - The type of the tool. Always `tool_search`. + The name of the file. - - `"tool_search"` + - `score: Optional[float]` - - `description: Optional[str]` + The relevance score of the file - a value between 0 and 1. - Description shown to the model for a client-executed tool search tool. + - `text: Optional[str]` - - `execution: Optional[Literal["server", "client"]]` + The text that was retrieved from the file. - Whether tool search is executed by the server or by the client. + - `class BetaResponseComputerToolCall: …` - - `"server"` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `"client"` + - `id: str` - - `parameters: Optional[object]` + The unique ID of the computer call. - Parameter schema for a client-executed tool search tool. + - `call_id: str` - - `class BetaWebSearchPreviewTool: …` + An identifier used when responding to the tool call with output. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `pending_safety_checks: List[PendingSafetyCheck]` - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + The pending safety checks for the computer call. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `id: str` - - `"web_search_preview"` + The ID of the pending safety check. - - `"web_search_preview_2025_03_11"` + - `code: Optional[str]` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + The type of the pending safety check. - - `"text"` + - `message: Optional[str]` - - `"image"` + Details about the pending safety check. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"low"` + - `"in_progress"` - - `"medium"` + - `"completed"` - - `"high"` + - `"incomplete"` - - `user_location: Optional[UserLocation]` + - `type: Literal["computer_call"]` - The user's location. + The type of the computer call. Always `computer_call`. - - `type: Literal["approximate"]` + - `"computer_call"` - The type of location approximation. Always `approximate`. + - `action: Optional[BetaComputerAction]` - - `"approximate"` + A click action. - - `city: Optional[str]` + - `class Click: …` - Free text input for the city of the user, e.g. `San Francisco`. + A click action. - - `country: Optional[str]` + - `button: Literal["left", "right", "wheel", 2 more]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `region: Optional[str]` + - `"left"` - Free text input for the region of the user, e.g. `California`. + - `"right"` - - `timezone: Optional[str]` + - `"wheel"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"back"` - - `class BetaApplyPatchTool: …` + - `"forward"` - Allows the assistant to create, delete, or update files using unified diffs. + - `type: Literal["click"]` - - `type: Literal["apply_patch"]` + Specifies the event type. For a click action, this property is always `click`. - The type of the tool. Always `apply_patch`. + - `"click"` - - `"apply_patch"` + - `x: int` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The x-coordinate where the click occurred. - The tool invocation context(s). + - `y: int` - - `"direct"` + The y-coordinate where the click occurred. - - `"programmatic"` + - `keys: Optional[List[str]]` - - `type: Literal["tool_search_output"]` + The keys being held while clicking. - The item type. Always `tool_search_output`. + - `class DoubleClick: …` - - `"tool_search_output"` + A double click action. - - `id: Optional[str]` + - `keys: Optional[List[str]]` - The unique ID of this tool search output. + The keys being held while double-clicking. - - `agent: Optional[Agent]` + - `type: Literal["double_click"]` - The agent that produced this item. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `agent_name: str` + - `"double_click"` - The canonical name of the agent that produced this item. + - `x: int` - - `call_id: Optional[str]` + The x-coordinate where the double click occurred. - The unique ID of the tool search call generated by the model. + - `y: int` - - `execution: Optional[Literal["server", "client"]]` + The y-coordinate where the double click occurred. - Whether tool search was executed by the server or by the client. + - `class Drag: …` - - `"server"` + A drag action. - - `"client"` + - `path: List[DragPath]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The status of the tool search output. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"in_progress"` + - `x: int` - - `"completed"` + The x-coordinate. - - `"incomplete"` + - `y: int` - - `class AdditionalTools: …` + The y-coordinate. - - `role: Literal["developer"]` + - `type: Literal["drag"]` - The role that provided the additional tools. Only `developer` is supported. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"developer"` + - `"drag"` - - `tools: List[BetaTool]` + - `keys: Optional[List[str]]` - A list of additional tools made available at this item. + The keys being held while dragging the mouse. - - `class BetaFunctionTool: …` + - `class Keypress: …` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + A collection of keypresses the model would like to perform. - - `class BetaFileSearchTool: …` + - `keys: List[str]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `class BetaComputerTool: …` + - `type: Literal["keypress"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `class BetaComputerUsePreviewTool: …` + - `"keypress"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class Move: …` - - `class BetaWebSearchTool: …` + A mouse move action. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `type: Literal["move"]` - - `class Mcp: …` + Specifies the event type. For a move action, this property is always set to `move`. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"move"` - - `class CodeInterpreter: …` + - `x: int` - A tool that runs Python code to help generate a response to a prompt. + The x-coordinate to move to. - - `class ProgrammaticToolCalling: …` + - `y: int` - - `class ImageGeneration: …` + The y-coordinate to move to. - A tool that generates images using the GPT image models. + - `keys: Optional[List[str]]` - - `class LocalShell: …` + The keys being held while moving the mouse. - A tool that allows the model to execute shell commands in a local environment. + - `class Screenshot: …` - - `class BetaFunctionShellTool: …` + A screenshot action. - A tool that allows the model to execute shell commands. + - `type: Literal["screenshot"]` - - `class BetaCustomTool: …` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"screenshot"` - - `class BetaNamespaceTool: …` + - `class Scroll: …` - Groups function/custom tools under a shared namespace. + A scroll action. - - `class BetaToolSearchTool: …` + - `scroll_x: int` - Hosted or BYOT tool search configuration for deferred tools. + The horizontal scroll distance. - - `class BetaWebSearchPreviewTool: …` + - `scroll_y: int` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The vertical scroll distance. - - `class BetaApplyPatchTool: …` + - `type: Literal["scroll"]` - Allows the assistant to create, delete, or update files using unified diffs. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `type: Literal["additional_tools"]` + - `"scroll"` - The item type. Always `additional_tools`. + - `x: int` - - `"additional_tools"` + The x-coordinate where the scroll occurred. - - `id: Optional[str]` + - `y: int` - The unique ID of this additional tools item. + The y-coordinate where the scroll occurred. - - `agent: Optional[AdditionalToolsAgent]` + - `keys: Optional[List[str]]` - The agent that produced this item. + The keys being held while scrolling. - - `agent_name: str` + - `class Type: …` - The canonical name of the agent that produced this item. + An action to type in text. - - `class BetaResponseReasoningItem: …` + - `text: str` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The text to type. - - `id: str` + - `type: Literal["type"]` - The unique identifier of the reasoning content. + Specifies the event type. For a type action, this property is always set to `type`. - - `summary: List[Summary]` + - `"type"` - Reasoning summary content. + - `class Wait: …` - - `text: str` + A wait action. - A summary of the reasoning output from the model so far. + - `type: Literal["wait"]` - - `type: Literal["summary_text"]` + Specifies the event type. For a wait action, this property is always set to `wait`. - The type of the object. Always `summary_text`. + - `"wait"` - - `"summary_text"` + - `actions: Optional[BetaComputerActionList]` - - `type: Literal["reasoning"]` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The type of the object. Always `reasoning`. + - `class Click: …` - - `"reasoning"` + A click action. - - `agent: Optional[Agent]` + - `class DoubleClick: …` - The agent that produced this item. + A double click action. - - `agent_name: str` + - `class Drag: …` - The canonical name of the agent that produced this item. + A drag action. - - `content: Optional[List[Content]]` + - `class Keypress: …` - Reasoning text content. + A collection of keypresses the model would like to perform. - - `text: str` + - `class Move: …` - The reasoning text from the model. + A mouse move action. - - `type: Literal["reasoning_text"]` + - `class Screenshot: …` - The type of the reasoning text. Always `reasoning_text`. + A screenshot action. - - `"reasoning_text"` + - `class Scroll: …` - - `encrypted_content: Optional[str]` + A scroll action. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `class Type: …` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + An action to type in text. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class Wait: …` - - `"in_progress"` + A wait action. - - `"completed"` + - `agent: Optional[Agent]` - - `"incomplete"` + The agent that produced this item. - - `class BetaResponseCompactionItemParam: …` + - `agent_name: str` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The canonical name of the agent that produced this item. - - `encrypted_content: str` + - `class ComputerCallOutput: …` - The encrypted content of the compaction summary. + The output of a computer tool call. - - `type: Literal["compaction"]` + - `call_id: str` - The type of the item. Always `compaction`. + The ID of the computer tool call that produced the output. - - `"compaction"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `id: Optional[str]` + A computer screenshot image used with the computer use tool. - The ID of the compaction item. + - `type: Literal["computer_screenshot"]` - - `agent: Optional[Agent]` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The agent that produced this item. + - `"computer_screenshot"` - - `agent_name: str` + - `file_id: Optional[str]` - The canonical name of the agent that produced this item. + The identifier of an uploaded file that contains the screenshot. - - `class ImageGenerationCall: …` + - `image_url: Optional[str]` - An image generation request made by the model. + The URL of the screenshot image. - - `id: str` + - `type: Literal["computer_call_output"]` - The unique ID of the image generation call. + The type of the computer tool call output. Always `computer_call_output`. - - `result: Optional[str]` + - `"computer_call_output"` - The generated image encoded in base64. + - `id: Optional[str]` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + The ID of the computer tool call output. - The status of the image generation call. + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - - `"in_progress"` + The safety checks reported by the API that have been acknowledged by the developer. - - `"completed"` + - `id: str` - - `"generating"` + The ID of the pending safety check. - - `"failed"` + - `code: Optional[str]` - - `type: Literal["image_generation_call"]` + The type of the pending safety check. - The type of the image generation call. Always `image_generation_call`. + - `message: Optional[str]` - - `"image_generation_call"` + Details about the pending safety check. - - `agent: Optional[ImageGenerationCallAgent]` + - `agent: Optional[ComputerCallOutputAgent]` The agent that produced this item. @@ -78651,142 +89561,148 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A tool call to run code. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `id: str` + - `"in_progress"` - The unique ID of the code interpreter tool call. + - `"completed"` - - `code: Optional[str]` + - `"incomplete"` - The code to run, or null if not available. + - `class BetaResponseFunctionWebSearch: …` - - `container_id: str` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The ID of the container used to run the code. + - `id: str` - - `outputs: Optional[List[Output]]` + The unique ID of the web search tool call. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `action: Action` - - `class OutputLogs: …` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - The logs output from the code interpreter. + - `class ActionSearch: …` - - `logs: str` + Action type "search" - Performs a web search query. - The logs output from the code interpreter. + - `type: Literal["search"]` - - `type: Literal["logs"]` + The action type. - The type of the output. Always `logs`. + - `"search"` - - `"logs"` + - `queries: Optional[List[str]]` - - `class OutputImage: …` + The search queries. - The image output from the code interpreter. + - `query: Optional[str]` - - `type: Literal["image"]` + The search query. - The type of the output. Always `image`. + - `sources: Optional[List[ActionSearchSource]]` - - `"image"` + The sources used in the search. + + - `type: Literal["url"]` + + The type of source. Always `url`. + + - `"url"` - `url: str` - The URL of the image output from the code interpreter. + The URL of the source. - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + - `class ActionOpenPage: …` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + Action type "open_page" - Opens a specific URL from search results. - - `"in_progress"` + - `type: Literal["open_page"]` - - `"completed"` + The action type. - - `"incomplete"` + - `"open_page"` - - `"interpreting"` + - `url: Optional[str]` - - `"failed"` + The URL opened by the model. - - `type: Literal["code_interpreter_call"]` + - `class ActionFindInPage: …` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"code_interpreter_call"` + - `pattern: str` - - `agent: Optional[Agent]` + The pattern or text to search for within the page. - The agent that produced this item. + - `type: Literal["find_in_page"]` - - `agent_name: str` + The action type. - The canonical name of the agent that produced this item. + - `"find_in_page"` - - `class LocalShellCall: …` + - `url: str` - A tool call to run a command on the local shell. + The URL of the page searched for the pattern. - - `id: str` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - The unique ID of the local shell call. + The status of the web search tool call. - - `action: LocalShellCallAction` + - `"in_progress"` - Execute a shell command on the server. + - `"searching"` - - `command: List[str]` + - `"completed"` - The command to run. + - `"failed"` - - `env: Dict[str, str]` + - `type: Literal["web_search_call"]` - Environment variables to set for the command. + The type of the web search tool call. Always `web_search_call`. - - `type: Literal["exec"]` + - `"web_search_call"` - The type of the local shell action. Always `exec`. + - `agent: Optional[Agent]` - - `"exec"` + The agent that produced this item. - - `timeout_ms: Optional[int]` + - `agent_name: str` - Optional timeout in milliseconds for the command. + The canonical name of the agent that produced this item. - - `user: Optional[str]` + - `class BetaResponseFunctionToolCall: …` - Optional user to run the command as. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `working_directory: Optional[str]` + - `arguments: str` - Optional working directory to run the command in. + A JSON string of the arguments to pass to the function. - `call_id: str` - The unique ID of the local shell tool call generated by the model. - - - `status: Literal["in_progress", "completed", "incomplete"]` + The unique ID of the function tool call generated by the model. - The status of the local shell call. + - `name: str` - - `"in_progress"` + The name of the function to run. - - `"completed"` + - `type: Literal["function_call"]` - - `"incomplete"` + The type of the function tool call. Always `function_call`. - - `type: Literal["local_shell_call"]` + - `"function_call"` - The type of the local shell call. Always `local_shell_call`. + - `id: Optional[str]` - - `"local_shell_call"` + The unique ID of the function tool call. - - `agent: Optional[LocalShellCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -78794,35 +89710,34 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCallOutput: …` - - The output of a local shell tool call. + - `caller: Optional[Caller]` - - `id: str` + The execution context that produced this tool call. - The unique ID of the local shell tool call generated by the model. + - `class CallerDirect: …` - - `output: str` + - `type: Literal["direct"]` - A JSON string of the output of the local shell tool call. + - `"direct"` - - `type: Literal["local_shell_call_output"]` + - `class CallerProgram: …` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `caller_id: str` - - `"local_shell_call_output"` + The call ID of the program item that produced this tool call. - - `agent: Optional[LocalShellCallOutputAgent]` + - `type: Literal["program"]` - The agent that produced this item. + - `"program"` - - `agent_name: str` + - `namespace: Optional[str]` - The canonical name of the agent that produced this item. + The namespace of the function to run. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -78830,149 +89745,145 @@ print(compacted_response) - `"incomplete"` - - `class ShellCall: …` - - A tool representing a request to execute one or more shell commands. - - - `action: ShellCallAction` + - `class FunctionCallOutput: …` - The shell commands and limits that describe how to run the tool call. + The output of a function tool call. - - `commands: List[str]` + - `call_id: str` - Ordered shell commands for the execution environment to run. + The unique ID of the function tool call generated by the model. - - `max_output_length: Optional[int]` + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Text, image, or file output of the function tool call. - - `timeout_ms: Optional[int]` + - `str` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + A JSON string of the output of the function tool call. - - `call_id: str` + - `List[BetaResponseFunctionCallOutputItem]` - The unique ID of the shell tool call generated by the model. + - `class BetaResponseInputTextContent: …` - - `type: Literal["shell_call"]` + A text input to the model. - The type of the item. Always `shell_call`. + - `text: str` - - `"shell_call"` + The text input to the model. - - `id: Optional[str]` + - `type: Literal["input_text"]` - The unique ID of the shell tool call. Populated when this item is returned via API. + The type of the input item. Always `input_text`. - - `agent: Optional[ShellCallAgent]` + - `"input_text"` - The agent that produced this item. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `agent_name: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The canonical name of the agent that produced this item. + - `mode: Literal["explicit"]` - - `caller: Optional[ShellCallCaller]` + The breakpoint mode. Always `explicit`. - The execution context that produced this tool call. + - `"explicit"` - - `class ShellCallCallerDirect: …` + - `class BetaResponseInputImageContent: …` - - `type: Literal["direct"]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The caller type. Always `direct`. + - `type: Literal["input_image"]` - - `"direct"` + The type of the input item. Always `input_image`. - - `class ShellCallCallerProgram: …` + - `"input_image"` - - `caller_id: str` + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - The call ID of the program item that produced this tool call. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: Literal["program"]` + - `"low"` - The caller type. Always `program`. + - `"high"` - - `"program"` + - `"auto"` - - `environment: Optional[ShellCallEnvironment]` + - `"original"` - The environment to execute the shell commands in. + - `file_id: Optional[str]` - - `class BetaLocalEnvironment: …` + The ID of the file to be sent to the model. - - `class BetaContainerReference: …` + - `image_url: Optional[str]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"in_progress"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"completed"` + - `mode: Literal["explicit"]` - - `"incomplete"` + The breakpoint mode. Always `explicit`. - - `class ShellCallOutput: …` + - `"explicit"` - The streamed output items emitted by a shell tool call. + - `class BetaResponseInputFileContent: …` - - `call_id: str` + A file input to the model. - The unique ID of the shell tool call generated by the model. + - `type: Literal["input_file"]` - - `output: List[BetaResponseFunctionShellCallOutputContent]` + The type of the input item. Always `input_file`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"input_file"` - - `outcome: Outcome` + - `detail: Optional[Literal["auto", "low", "high"]]` - The exit or timeout outcome associated with this shell call. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `class OutcomeTimeout: …` + - `"auto"` - Indicates that the shell call exceeded its configured time limit. + - `"low"` - - `type: Literal["timeout"]` + - `"high"` - The outcome type. Always `timeout`. + - `file_data: Optional[str]` - - `"timeout"` + The base64-encoded data of the file to be sent to the model. - - `class OutcomeExit: …` + - `file_id: Optional[str]` - Indicates that the shell commands finished and returned an exit code. + The ID of the file to be sent to the model. - - `exit_code: int` + - `file_url: Optional[str]` - The exit code returned by the shell process. + The URL of the file to be sent to the model. - - `type: Literal["exit"]` + - `filename: Optional[str]` - The outcome type. Always `exit`. + The name of the file to be sent to the model. - - `"exit"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `stderr: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Captured stderr output for the shell call. + - `mode: Literal["explicit"]` - - `stdout: str` + The breakpoint mode. Always `explicit`. - Captured stdout output for the shell call. + - `"explicit"` - - `type: Literal["shell_call_output"]` + - `type: Literal["function_call_output"]` - The type of the item. Always `shell_call_output`. + The type of the function tool call output. Always `function_call_output`. - - `"shell_call_output"` + - `"function_call_output"` - `id: Optional[str]` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `agent: Optional[ShellCallOutputAgent]` + - `agent: Optional[FunctionCallOutputAgent]` The agent that produced this item. @@ -78980,11 +89891,11 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ShellCallOutputCaller]` + - `caller: Optional[FunctionCallOutputCaller]` The execution context that produced this tool call. - - `class ShellCallOutputCallerDirect: …` + - `class FunctionCallOutputCallerDirect: …` - `type: Literal["direct"]` @@ -78992,7 +89903,7 @@ print(compacted_response) - `"direct"` - - `class ShellCallOutputCallerProgram: …` + - `class FunctionCallOutputCallerProgram: …` - `caller_id: str` @@ -79004,13 +89915,9 @@ print(compacted_response) - `"program"` - - `max_output_length: Optional[int]` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the shell call output. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -79018,87 +89925,99 @@ print(compacted_response) - `"incomplete"` - - `class ApplyPatchCall: …` + - `class AgentMessage: …` - A tool call representing a request to create, delete, or update files using diff patches. + A message routed between agents. - - `call_id: str` + - `author: str` - The unique ID of the apply patch tool call generated by the model. + The sending agent identity. - - `operation: ApplyPatchCallOperation` + - `content: List[AgentMessageContent]` - The specific create, delete, or update instruction for the apply_patch tool call. + Plaintext, image, or encrypted content sent between agents. - - `class ApplyPatchCallOperationCreateFile: …` + - `class BetaResponseInputTextContent: …` - Instruction for creating a new file via the apply_patch tool. + A text input to the model. - - `diff: str` + - `class BetaResponseInputImageContent: …` - Unified diff content to apply when creating the file. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `path: str` + - `class AgentMessageContentEncryptedContent: …` - Path of the file to create relative to the workspace root. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `type: Literal["create_file"]` + - `encrypted_content: str` - The operation type. Always `create_file`. + Opaque encrypted content. - - `"create_file"` + - `type: Literal["encrypted_content"]` - - `class ApplyPatchCallOperationDeleteFile: …` + The type of the input item. Always `encrypted_content`. - Instruction for deleting an existing file via the apply_patch tool. + - `"encrypted_content"` - - `path: str` + - `recipient: str` - Path of the file to delete relative to the workspace root. + The destination agent identity. - - `type: Literal["delete_file"]` + - `type: Literal["agent_message"]` - The operation type. Always `delete_file`. + The item type. Always `agent_message`. - - `"delete_file"` + - `"agent_message"` - - `class ApplyPatchCallOperationUpdateFile: …` + - `id: Optional[str]` - Instruction for updating an existing file via the apply_patch tool. + The unique ID of this agent message item. - - `diff: str` + - `agent: Optional[AgentMessageAgent]` - Unified diff content to apply to the existing file. + The agent that produced this item. - - `path: str` + - `agent_name: str` - Path of the file to update relative to the workspace root. + The canonical name of the agent that produced this item. - - `type: Literal["update_file"]` + - `class MultiAgentCall: …` - The operation type. Always `update_file`. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"update_file"` + The multi-agent action that was executed. - - `status: Literal["in_progress", "completed"]` + - `"spawn_agent"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"interrupt_agent"` - - `"in_progress"` + - `"list_agents"` - - `"completed"` + - `"send_message"` - - `type: Literal["apply_patch_call"]` + - `"followup_task"` - The type of the item. Always `apply_patch_call`. + - `"wait_agent"` - - `"apply_patch_call"` + - `arguments: str` + + The action arguments as a JSON string. + + - `call_id: str` + + The unique ID linking this call to its output. + + - `type: Literal["multi_agent_call"]` + + The item type. Always `multi_agent_call`. + + - `"multi_agent_call"` - `id: Optional[str]` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of this multi-agent call. - - `agent: Optional[ApplyPatchCallAgent]` + - `agent: Optional[MultiAgentCallAgent]` The agent that produced this item. @@ -79106,131 +90025,129 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ApplyPatchCallCaller]` - - The execution context that produced this tool call. + - `class MultiAgentCallOutput: …` - - `class ApplyPatchCallCallerDirect: …` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `type: Literal["direct"]` + The multi-agent action that produced this result. - The caller type. Always `direct`. + - `"spawn_agent"` - - `"direct"` + - `"interrupt_agent"` - - `class ApplyPatchCallCallerProgram: …` + - `"list_agents"` - - `caller_id: str` + - `"send_message"` - The call ID of the program item that produced this tool call. + - `"followup_task"` - - `type: Literal["program"]` + - `"wait_agent"` - The caller type. Always `program`. + - `call_id: str` - - `"program"` + The unique ID of the multi-agent call. - - `class ApplyPatchCallOutput: …` + - `output: List[MultiAgentCallOutputOutput]` - The streamed output emitted by an apply patch tool call. + Text output returned by the multi-agent action. - - `call_id: str` + - `text: str` - The unique ID of the apply patch tool call generated by the model. + The text content. - - `status: Literal["completed", "failed"]` + - `type: Literal["output_text"]` - The status of the apply patch tool call output. One of `completed` or `failed`. + The content type. Always `output_text`. - - `"completed"` + - `"output_text"` - - `"failed"` + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - - `type: Literal["apply_patch_call_output"]` + Citations associated with the text content. - The type of the item. Always `apply_patch_call_output`. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - - `"apply_patch_call_output"` + - `file_id: str` - - `id: Optional[str]` + The ID of the file. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `filename: str` - - `agent: Optional[ApplyPatchCallOutputAgent]` + The filename of the file cited. - The agent that produced this item. + - `index: int` - - `agent_name: str` + The index of the file in the list of files. - The canonical name of the agent that produced this item. + - `type: Literal["file_citation"]` - - `caller: Optional[ApplyPatchCallOutputCaller]` + The citation type. Always `file_citation`. - The execution context that produced this tool call. + - `"file_citation"` - - `class ApplyPatchCallOutputCallerDirect: …` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` - - `type: Literal["direct"]` + - `end_index: int` - The caller type. Always `direct`. + The index of the last character of the citation in the message. - - `"direct"` + - `start_index: int` - - `class ApplyPatchCallOutputCallerProgram: …` + The index of the first character of the citation in the message. - - `caller_id: str` + - `title: str` - The call ID of the program item that produced this tool call. + The title of the cited resource. - - `type: Literal["program"]` + - `type: Literal["url_citation"]` - The caller type. Always `program`. + The citation type. Always `url_citation`. - - `"program"` + - `"url_citation"` - - `output: Optional[str]` + - `url: str` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The URL of the cited resource. - - `class McpListTools: …` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` - A list of tools available on an MCP server. + - `container_id: str` - - `id: str` + The ID of the container. - The unique ID of the list. + - `end_index: int` - - `server_label: str` + The index of the last character of the citation in the message. - The label of the MCP server. + - `file_id: str` - - `tools: List[McpListToolsTool]` + The ID of the container file. - The tools available on the server. + - `filename: str` - - `input_schema: object` + The filename of the container file cited. - The JSON schema describing the tool's input. + - `start_index: int` - - `name: str` + The index of the first character of the citation in the message. - The name of the tool. + - `type: Literal["container_file_citation"]` - - `annotations: Optional[object]` + The citation type. Always `container_file_citation`. - Additional annotations about the tool. + - `"container_file_citation"` - - `description: Optional[str]` + - `type: Literal["multi_agent_call_output"]` - The description of the tool. + The item type. Always `multi_agent_call_output`. - - `type: Literal["mcp_list_tools"]` + - `"multi_agent_call_output"` - The type of the item. Always `mcp_list_tools`. + - `id: Optional[str]` - - `"mcp_list_tools"` + The unique ID of this multi-agent call output. - - `agent: Optional[McpListToolsAgent]` + - `agent: Optional[MultiAgentCallOutputAgent]` The agent that produced this item. @@ -79238,37 +90155,23 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `error: Optional[str]` - - Error message if the server could not list tools. - - - `class McpApprovalRequest: …` - - A request for human approval of a tool invocation. - - - `id: str` - - The unique ID of the approval request. - - - `arguments: str` - - A JSON string of arguments for the tool. + - `class ToolSearchCall: …` - - `name: str` + - `arguments: object` - The name of the tool to run. + The arguments supplied to the tool search call. - - `server_label: str` + - `type: Literal["tool_search_call"]` - The label of the MCP server making the request. + The item type. Always `tool_search_call`. - - `type: Literal["mcp_approval_request"]` + - `"tool_search_call"` - The type of the item. Always `mcp_approval_request`. + - `id: Optional[str]` - - `"mcp_approval_request"` + The unique ID of this tool search call. - - `agent: Optional[McpApprovalRequestAgent]` + - `agent: Optional[ToolSearchCallAgent]` The agent that produced this item. @@ -79276,1106 +90179,1137 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class McpApprovalResponse: …` + - `call_id: Optional[str]` - A response to an MCP approval request. + The unique ID of the tool search call generated by the model. - - `approval_request_id: str` + - `execution: Optional[Literal["server", "client"]]` - The ID of the approval request being answered. + Whether tool search was executed by the server or by the client. - - `approve: bool` + - `"server"` - Whether the request was approved. + - `"client"` - - `type: Literal["mcp_approval_response"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The type of the item. Always `mcp_approval_response`. + The status of the tool search call. - - `"mcp_approval_response"` + - `"in_progress"` - - `id: Optional[str]` + - `"completed"` - The unique ID of the approval response + - `"incomplete"` - - `agent: Optional[McpApprovalResponseAgent]` + - `class BetaResponseToolSearchOutputItemParam: …` - The agent that produced this item. + - `tools: List[BetaTool]` - - `agent_name: str` + The loaded tool definitions returned by the tool search output. - The canonical name of the agent that produced this item. + - `class BetaFunctionTool: …` - - `reason: Optional[str]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Optional reason for the decision. + - `name: str` - - `class McpCall: …` + The name of the function to call. - An invocation of a tool on an MCP server. + - `parameters: Optional[Dict[str, object]]` - - `id: str` + A JSON schema object describing the parameters of the function. - The unique ID of the tool call. + - `strict: Optional[bool]` - - `arguments: str` + Whether strict parameter validation is enforced for this function tool. - A JSON string of the arguments passed to the tool. + - `type: Literal["function"]` - - `name: str` + The type of the function tool. Always `function`. - The name of the tool that was run. + - `"function"` - - `server_label: str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The label of the MCP server running the tool. + The tool invocation context(s). - - `type: Literal["mcp_call"]` + - `"direct"` - The type of the item. Always `mcp_call`. + - `"programmatic"` - - `"mcp_call"` + - `defer_loading: Optional[bool]` - - `agent: Optional[McpCallAgent]` + Whether this function is deferred and loaded via tool search. - The agent that produced this item. + - `description: Optional[str]` - - `agent_name: str` + A description of the function. Used by the model to determine whether or not to call the function. - The canonical name of the agent that produced this item. + - `output_schema: Optional[Dict[str, object]]` - - `approval_request_id: Optional[str]` + A JSON schema object describing the JSON value encoded in string outputs for this function. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `class BetaFileSearchTool: …` - - `error: Optional[str]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The error from the tool call, if any. + - `type: Literal["file_search"]` - - `output: Optional[str]` + The type of the file search tool. Always `file_search`. - The output from the tool call. + - `"file_search"` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `vector_store_ids: List[str]` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The IDs of the vector stores to search. - - `"in_progress"` + - `filters: Optional[Filters]` - - `"completed"` + A filter to apply. - - `"incomplete"` + - `class FiltersComparisonFilter: …` - - `"calling"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"failed"` + - `key: str` - - `class BetaResponseCustomToolCallOutput: …` + The key to compare against the value. - The output of a custom tool call from your code, being sent back to the model. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `call_id: str` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The call ID, used to map this custom tool call output to a custom tool call. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `output: Union[str, List[OutputOutputContentList]]` + - `"eq"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"ne"` - - `str` + - `"gt"` - A string of the output of the custom tool call. + - `"gte"` - - `List[OutputOutputContentList]` + - `"lt"` - Text, image, or file output of the custom tool call. + - `"lte"` - - `class BetaResponseInputText: …` + - `"in"` - A text input to the model. + - `"nin"` - - `class BetaResponseInputImage: …` + - `value: Union[str, float, bool, List[Union[str, float]]]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The value to compare against the attribute key; supports string, number, or boolean types. - - `class BetaResponseInputFile: …` + - `str` - A file input to the model. + - `float` - - `type: Literal["custom_tool_call_output"]` + - `bool` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `List[Union[str, float]]` - - `"custom_tool_call_output"` + - `str` - - `id: Optional[str]` + - `float` - The unique ID of the custom tool call output in the OpenAI platform. + - `class FiltersCompoundFilter: …` - - `agent: Optional[Agent]` + Combine multiple filters using `and` or `or`. - The agent that produced this item. + - `filters: List[FiltersCompoundFilterFilter]` - - `agent_name: str` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The canonical name of the agent that produced this item. + - `class FiltersCompoundFilterFilterComparisonFilter: …` - - `caller: Optional[Caller]` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The execution context that produced this tool call. + - `key: str` - - `class CallerDirect: …` + The key to compare against the value. - - `type: Literal["direct"]` + - `type: Literal["eq", "ne", "gt", 5 more]` - The caller type. Always `direct`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"direct"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `class CallerProgram: …` + - `"eq"` - - `caller_id: str` + - `"ne"` - The call ID of the program item that produced this tool call. + - `"gt"` - - `type: Literal["program"]` + - `"gte"` - The caller type. Always `program`. + - `"lt"` - - `"program"` + - `"lte"` - - `class BetaResponseCustomToolCall: …` + - `"in"` - A call to a custom tool created by the model. + - `"nin"` - - `call_id: str` + - `value: Union[str, float, bool, List[Union[str, float]]]` - An identifier used to map this custom tool call to a tool call output. + The value to compare against the attribute key; supports string, number, or boolean types. - - `input: str` + - `str` - The input for the custom tool call generated by the model. + - `float` - - `name: str` + - `bool` - The name of the custom tool being called. + - `List[Union[str, float]]` - - `type: Literal["custom_tool_call"]` + - `str` - The type of the custom tool call. Always `custom_tool_call`. + - `float` - - `"custom_tool_call"` + - `object` - - `id: Optional[str]` + - `type: Literal["and", "or"]` - The unique ID of the custom tool call in the OpenAI platform. + Type of operation: `and` or `or`. - - `agent: Optional[Agent]` + - `"and"` - The agent that produced this item. + - `"or"` - - `agent_name: str` + - `max_num_results: Optional[int]` - The canonical name of the agent that produced this item. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `caller: Optional[Caller]` + - `ranking_options: Optional[RankingOptions]` - The execution context that produced this tool call. + Ranking options for search. - - `class CallerDirect: …` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - `type: Literal["direct"]` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"direct"` + - `embedding_weight: float` - - `class CallerProgram: …` + The weight of the embedding in the reciprocal ranking fusion. - - `caller_id: str` + - `text_weight: float` - The call ID of the program item that produced this tool call. + The weight of the text in the reciprocal ranking fusion. - - `type: Literal["program"]` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - - `"program"` + The ranker to use for the file search. - - `namespace: Optional[str]` + - `"auto"` - The namespace of the custom tool being called. + - `"default-2024-11-15"` - - `class CompactionTrigger: …` + - `score_threshold: Optional[float]` - Compacts the current context. Must be the final input item. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `type: Literal["compaction_trigger"]` + - `class BetaComputerTool: …` - The type of the item. Always `compaction_trigger`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"compaction_trigger"` + - `type: Literal["computer"]` - - `agent: Optional[CompactionTriggerAgent]` + The type of the computer tool. Always `computer`. - The agent that produced this item. + - `"computer"` - - `agent_name: str` + - `class BetaComputerUsePreviewTool: …` - The canonical name of the agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class ItemReference: …` + - `display_height: int` - An internal identifier for an item to reference. + The height of the computer display. - - `id: str` + - `display_width: int` - The ID of the item to reference. + The width of the computer display. - - `agent: Optional[ItemReferenceAgent]` + - `environment: Literal["windows", "mac", "linux", 2 more]` - The agent that produced this item. + The type of computer environment to control. - - `agent_name: str` + - `"windows"` - The canonical name of the agent that produced this item. + - `"mac"` - - `type: Optional[Literal["item_reference"]]` + - `"linux"` - The type of item to reference. Always `item_reference`. + - `"ubuntu"` - - `"item_reference"` + - `"browser"` - - `class Program: …` + - `type: Literal["computer_use_preview"]` - - `id: str` + The type of the computer use tool. Always `computer_use_preview`. - The unique ID of this program item. + - `"computer_use_preview"` - - `call_id: str` + - `class BetaWebSearchTool: …` - The stable call ID of the program item. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `code: str` + - `type: Literal["web_search", "web_search_2025_08_26"]` - The JavaScript source executed by programmatic tool calling. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `fingerprint: str` + - `"web_search"` - Opaque program replay fingerprint that must be round-tripped. + - `"web_search_2025_08_26"` - - `type: Literal["program"]` + - `filters: Optional[Filters]` - The item type. Always `program`. + Filters for the search. - - `"program"` + - `allowed_domains: Optional[List[str]]` - - `agent: Optional[ProgramAgent]` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The agent that produced this item. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `agent_name: str` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The canonical name of the agent that produced this item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `class ProgramOutput: …` + - `"low"` - - `id: str` + - `"medium"` - The unique ID of this program output item. + - `"high"` - - `call_id: str` + - `user_location: Optional[UserLocation]` - The call ID of the program item. + The approximate location of the user. - - `result: str` + - `city: Optional[str]` - The result produced by the program item. + Free text input for the city of the user, e.g. `San Francisco`. - - `status: Literal["completed", "incomplete"]` + - `country: Optional[str]` - The terminal status of the program output. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"completed"` + - `region: Optional[str]` - - `"incomplete"` + Free text input for the region of the user, e.g. `California`. - - `type: Literal["program_output"]` + - `timezone: Optional[str]` - The item type. Always `program_output`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"program_output"` + - `type: Optional[Literal["approximate"]]` - - `agent: Optional[ProgramOutputAgent]` + The type of location approximation. Always `approximate`. - The agent that produced this item. + - `"approximate"` - - `agent_name: str` + - `class Mcp: …` - The canonical name of the agent that produced this item. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `metadata: Optional[Dict[str, str]]` + - `server_label: str` - 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. + A label for this MCP server, used to identify it in tool calls. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: Literal["mcp"]` - - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` + The type of the MCP tool. Always `mcp`. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `"mcp"` - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + The tool invocation context(s). - - `"gpt-5.6-sol"` + - `"direct"` - - `"gpt-5.6-terra"` + - `"programmatic"` - - `"gpt-5.6-luna"` + - `allowed_tools: Optional[McpAllowedTools]` - - `"gpt-5.4"` + List of allowed tool names or a filter object. - - `"gpt-5.4-mini"` + - `List[str]` - - `"gpt-5.4-nano"` + A string array of allowed tool names - - `"gpt-5.4-mini-2026-03-17"` + - `class McpAllowedToolsMcpToolFilter: …` - - `"gpt-5.4-nano-2026-03-17"` + A filter object to specify which tools are allowed. - - `"gpt-5.3-chat-latest"` + - `read_only: Optional[bool]` - - `"gpt-5.2"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"gpt-5.2-2025-12-11"` + - `tool_names: Optional[List[str]]` - - `"gpt-5.2-chat-latest"` + List of allowed tool names. - - `"gpt-5.2-pro"` + - `authorization: Optional[str]` - - `"gpt-5.2-pro-2025-12-11"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `"gpt-5.1"` + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `"gpt-5.1-2025-11-13"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `"gpt-5.1-codex"` + Currently supported `connector_id` values are: - - `"gpt-5.1-mini"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `"gpt-5.1-chat-latest"` + - `"connector_dropbox"` - - `"gpt-5"` + - `"connector_gmail"` - - `"gpt-5-mini"` + - `"connector_googlecalendar"` - - `"gpt-5-nano"` + - `"connector_googledrive"` - - `"gpt-5-2025-08-07"` + - `"connector_microsoftteams"` - - `"gpt-5-mini-2025-08-07"` + - `"connector_outlookcalendar"` - - `"gpt-5-nano-2025-08-07"` + - `"connector_outlookemail"` - - `"gpt-5-chat-latest"` + - `"connector_sharepoint"` - - `"gpt-4.1"` + - `defer_loading: Optional[bool]` - - `"gpt-4.1-mini"` + Whether this MCP tool is deferred and discovered via tool search. - - `"gpt-4.1-nano"` + - `headers: Optional[Dict[str, str]]` - - `"gpt-4.1-2025-04-14"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"gpt-4.1-mini-2025-04-14"` + - `require_approval: Optional[McpRequireApproval]` - - `"gpt-4.1-nano-2025-04-14"` + Specify which of the MCP server's tools require approval. - - `"o4-mini"` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - - `"o4-mini-2025-04-16"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"o3"` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `"o3-2025-04-16"` + A filter object to specify which tools are allowed. - - `"o3-mini"` + - `read_only: Optional[bool]` - - `"o3-mini-2025-01-31"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"o1"` + - `tool_names: Optional[List[str]]` - - `"o1-2024-12-17"` + List of allowed tool names. - - `"o1-preview"` + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - - `"o1-preview-2024-09-12"` + A filter object to specify which tools are allowed. - - `"o1-mini"` + - `read_only: Optional[bool]` - - `"o1-mini-2024-09-12"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"gpt-4o"` + - `tool_names: Optional[List[str]]` - - `"gpt-4o-2024-11-20"` + List of allowed tool names. - - `"gpt-4o-2024-08-06"` + - `Literal["always", "never"]` - - `"gpt-4o-2024-05-13"` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `"gpt-4o-audio-preview"` + - `"always"` - - `"gpt-4o-audio-preview-2024-10-01"` + - `"never"` - - `"gpt-4o-audio-preview-2024-12-17"` + - `server_description: Optional[str]` - - `"gpt-4o-audio-preview-2025-06-03"` + Optional description of the MCP server, used to provide more context. - - `"gpt-4o-mini-audio-preview"` + - `server_url: Optional[str]` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"gpt-4o-search-preview"` + - `tunnel_id: Optional[str]` - - `"gpt-4o-mini-search-preview"` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `"gpt-4o-search-preview-2025-03-11"` + - `class CodeInterpreter: …` - - `"gpt-4o-mini-search-preview-2025-03-11"` + A tool that runs Python code to help generate a response to a prompt. - - `"chatgpt-4o-latest"` + - `container: CodeInterpreterContainer` - - `"codex-mini-latest"` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `"gpt-4o-mini"` + - `str` - - `"gpt-4o-mini-2024-07-18"` + The container ID. - - `"gpt-4-turbo"` + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `"gpt-4-turbo-2024-04-09"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"gpt-4-0125-preview"` + - `type: Literal["auto"]` - - `"gpt-4-turbo-preview"` + Always `auto`. - - `"gpt-4-1106-preview"` + - `"auto"` - - `"gpt-4-vision-preview"` + - `file_ids: Optional[List[str]]` - - `"gpt-4"` + An optional list of uploaded files to make available to your code. - - `"gpt-4-0314"` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `"gpt-4-0613"` + The memory limit for the code interpreter container. - - `"gpt-4-32k"` + - `"1g"` - - `"gpt-4-32k-0314"` + - `"4g"` - - `"gpt-4-32k-0613"` + - `"16g"` - - `"gpt-3.5-turbo"` + - `"64g"` - - `"gpt-3.5-turbo-16k"` + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - - `"gpt-3.5-turbo-0301"` + Network access policy for the container. - - `"gpt-3.5-turbo-0613"` + - `class BetaContainerNetworkPolicyDisabled: …` - - `"gpt-3.5-turbo-1106"` + - `type: Literal["disabled"]` - - `"gpt-3.5-turbo-0125"` + Disable outbound network access. Always `disabled`. - - `"gpt-3.5-turbo-16k-0613"` + - `"disabled"` - - `"o1-pro"` + - `class BetaContainerNetworkPolicyAllowlist: …` - - `"o1-pro-2025-03-19"` + - `allowed_domains: List[str]` - - `"o3-pro"` + A list of allowed domains when type is `allowlist`. - - `"o3-pro-2025-06-10"` + - `type: Literal["allowlist"]` - - `"o3-deep-research"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"o3-deep-research-2025-06-26"` + - `"allowlist"` - - `"o4-mini-deep-research"` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `"o4-mini-deep-research-2025-06-26"` + Optional domain-scoped secrets for allowlisted domains. - - `"computer-use-preview"` + - `domain: str` - - `"computer-use-preview-2025-03-11"` + The domain associated with the secret. - - `"gpt-5-codex"` + - `name: str` - - `"gpt-5-pro"` + The name of the secret to inject for the domain. - - `"gpt-5-pro-2025-10-06"` + - `value: str` - - `"gpt-5.1-codex-max"` + The secret value to inject for the domain. - - `str` + - `type: Literal["code_interpreter"]` - - `object: Literal["response"]` + The type of the code interpreter tool. Always `code_interpreter`. - The object type of this resource - always set to `response`. + - `"code_interpreter"` - - `"response"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `output: List[BetaResponseOutputItem]` + The tool invocation context(s). - An array of content items generated by the model. + - `"direct"` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `"programmatic"` - - `class BetaResponseOutputMessage: …` + - `class ProgrammaticToolCalling: …` - An output message from the model. + - `type: Literal["programmatic_tool_calling"]` - - `class BetaResponseFileSearchToolCall: …` + The type of the tool. Always `programmatic_tool_calling`. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"programmatic_tool_calling"` - - `class BetaResponseFunctionToolCall: …` + - `class ImageGeneration: …` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + A tool that generates images using the GPT image models. - - `class BetaResponseFunctionToolCallOutputItem: …` + - `type: Literal["image_generation"]` - - `id: str` + The type of the image generation tool. Always `image_generation`. - The unique ID of the function call tool output. + - `"image_generation"` - - `call_id: str` + - `action: Optional[Literal["generate", "edit", "auto"]]` - The unique ID of the function tool call generated by the model. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `output: Union[str, List[OutputOutputContentList]]` + - `"generate"` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `"edit"` - - `str` + - `"auto"` - A string of the output of the function call. + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `List[OutputOutputContentList]` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - Text, image, or file output of the function call. + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `class BetaResponseInputText: …` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - A text input to the model. + - `"transparent"` - - `class BetaResponseInputImage: …` + - `"opaque"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"auto"` - - `class BetaResponseInputFile: …` + - `input_fidelity: Optional[Literal["high", "low"]]` - A file input to the model. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"high"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"low"` - - `"in_progress"` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - - `"completed"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"incomplete"` + - `file_id: Optional[str]` - - `type: Literal["function_call_output"]` + File ID for the mask image. - The type of the function tool call output. Always `function_call_output`. + - `image_url: Optional[str]` - - `"function_call_output"` + Base64-encoded mask image. - - `agent: Optional[Agent]` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - The agent that produced this item. + The image generation model to use. Default: `gpt-image-1`. - - `agent_name: str` + - `str` - The canonical name of the agent that produced this item. + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `caller: Optional[Caller]` + The image generation model to use. Default: `gpt-image-1`. - The execution context that produced this tool call. + - `"gpt-image-1"` - - `class CallerDirect: …` + - `"gpt-image-1-mini"` - - `type: Literal["direct"]` + - `"gpt-image-2"` - The caller type. Always `direct`. + - `"gpt-image-2-2026-04-21"` - - `"direct"` + - `"gpt-image-1.5"` - - `class CallerProgram: …` + - `"chatgpt-image-latest"` - - `caller_id: str` + - `moderation: Optional[Literal["auto", "low"]]` - The call ID of the program item that produced this tool call. + Moderation level for the generated image. Default: `auto`. - - `type: Literal["program"]` + - `"auto"` + + - `"low"` + + - `output_compression: Optional[int]` - The caller type. Always `program`. + Compression level for the output image. Default: 100. - - `"program"` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `created_by: Optional[str]` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The identifier of the actor that created the item. + - `"png"` - - `class AgentMessage: …` + - `"webp"` - - `id: str` + - `"jpeg"` - The unique ID of the agent message. + - `partial_images: Optional[int]` - - `author: str` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The sending agent identity. + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - - `content: List[AgentMessageContent]` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Encrypted content sent between agents. + - `"low"` - - `class BetaResponseInputText: …` + - `"medium"` - A text input to the model. + - `"high"` - - `class BetaResponseOutputText: …` + - `"auto"` - A text output from the model. + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - - `class AgentMessageContentText: …` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - A text content. + - `str` - - `text: str` + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `type: Literal["text"]` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `"text"` + - `"1024x1024"` - - `class AgentMessageContentSummaryText: …` + - `"1024x1536"` - A summary text from the model. + - `"1536x1024"` - - `text: str` + - `"auto"` - A summary of the reasoning output from the model so far. + - `class LocalShell: …` - - `type: Literal["summary_text"]` + A tool that allows the model to execute shell commands in a local environment. - The type of the object. Always `summary_text`. + - `type: Literal["local_shell"]` - - `"summary_text"` + The type of the local shell tool. Always `local_shell`. - - `class AgentMessageContentReasoningText: …` + - `"local_shell"` - Reasoning text from the model. + - `class BetaFunctionShellTool: …` - - `text: str` + A tool that allows the model to execute shell commands. - The reasoning text from the model. + - `type: Literal["shell"]` - - `type: Literal["reasoning_text"]` + The type of the shell tool. Always `shell`. - The type of the reasoning text. Always `reasoning_text`. + - `"shell"` - - `"reasoning_text"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `class BetaResponseOutputRefusal: …` + The tool invocation context(s). - A refusal from the model. + - `"direct"` - - `class BetaResponseInputImage: …` + - `"programmatic"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `environment: Optional[Environment]` - - `class AgentMessageContentComputerScreenshot: …` + - `class BetaContainerAuto: …` - A screenshot of a computer. + - `type: Literal["container_auto"]` - - `detail: Literal["low", "high", "auto", "original"]` + Automatically creates a container for this request - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"container_auto"` - - `"low"` + - `file_ids: Optional[List[str]]` - - `"high"` + An optional list of uploaded files to make available to your code. - - `"auto"` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `"original"` + The memory limit for the container. - - `file_id: Optional[str]` + - `"1g"` - The identifier of an uploaded file that contains the screenshot. + - `"4g"` - - `image_url: Optional[str]` + - `"16g"` - The URL of the screenshot image. + - `"64g"` - - `type: Literal["computer_screenshot"]` + - `network_policy: Optional[NetworkPolicy]` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Network access policy for the container. - - `"computer_screenshot"` + - `class BetaContainerNetworkPolicyDisabled: …` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `class BetaContainerNetworkPolicyAllowlist: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `skills: Optional[List[Skill]]` - - `mode: Literal["explicit"]` + An optional list of skills referenced by id or inline data. - The breakpoint mode. Always `explicit`. + - `class BetaSkillReference: …` - - `"explicit"` + - `skill_id: str` - - `class BetaResponseInputFile: …` + The ID of the referenced skill. - A file input to the model. + - `type: Literal["skill_reference"]` - - `class AgentMessageContentEncryptedContent: …` + References a skill created with the /v1/skills endpoint. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"skill_reference"` - - `encrypted_content: str` + - `version: Optional[str]` - Opaque encrypted content. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `type: Literal["encrypted_content"]` + - `class BetaInlineSkill: …` - The type of the input item. Always `encrypted_content`. + - `description: str` - - `"encrypted_content"` + The description of the skill. - - `recipient: str` + - `name: str` - The destination agent identity. + The name of the skill. - - `type: Literal["agent_message"]` + - `source: BetaInlineSkillSource` - The type of the item. Always `agent_message`. + Inline skill payload - - `"agent_message"` + - `data: str` - - `agent: Optional[AgentMessageAgent]` + Base64-encoded skill zip bundle. - The agent that produced this item. + - `media_type: Literal["application/zip"]` - - `agent_name: str` + The media type of the inline skill payload. Must be `application/zip`. - The canonical name of the agent that produced this item. + - `"application/zip"` - - `class MultiAgentCall: …` + - `type: Literal["base64"]` - - `id: str` + The type of the inline skill source. Must be `base64`. - The unique ID of the multi-agent call item. + - `"base64"` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `type: Literal["inline"]` - The multi-agent action to execute. + Defines an inline skill for this request. - - `"spawn_agent"` + - `"inline"` - - `"interrupt_agent"` + - `class BetaLocalEnvironment: …` - - `"list_agents"` + - `type: Literal["local"]` - - `"send_message"` + Use a local computer environment. - - `"followup_task"` + - `"local"` - - `"wait_agent"` + - `skills: Optional[List[BetaLocalSkill]]` - - `arguments: str` + An optional list of skills. - The JSON string of arguments generated for the action. + - `description: str` - - `call_id: str` + The description of the skill. - The unique ID linking this call to its output. + - `name: str` - - `type: Literal["multi_agent_call"]` + The name of the skill. - The type of the multi-agent call. Always `multi_agent_call`. + - `path: str` - - `"multi_agent_call"` + The path to the directory containing the skill. - - `agent: Optional[MultiAgentCallAgent]` + - `class BetaContainerReference: …` - The agent that produced this item. + - `container_id: str` - - `agent_name: str` + The ID of the referenced container. - The canonical name of the agent that produced this item. + - `type: Literal["container_reference"]` - - `class MultiAgentCallOutput: …` + References a container created with the /v1/containers endpoint - - `id: str` + - `"container_reference"` - The unique ID of the multi-agent call output item. + - `class BetaCustomTool: …` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The multi-agent action that produced this result. + - `name: str` - - `"spawn_agent"` + The name of the custom tool, used to identify it in tool calls. - - `"interrupt_agent"` + - `type: Literal["custom"]` - - `"list_agents"` + The type of the custom tool. Always `custom`. - - `"send_message"` + - `"custom"` - - `"followup_task"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"wait_agent"` + The tool invocation context(s). - - `call_id: str` + - `"direct"` - The unique ID of the multi-agent call. + - `"programmatic"` - - `output: List[BetaResponseOutputText]` + - `defer_loading: Optional[bool]` - Text output returned by the multi-agent action. + Whether this tool should be deferred and discovered via tool search. - - `annotations: List[Annotation]` + - `description: Optional[str]` - The annotations of the text output. + Optional description of the custom tool, used to provide more context. - - `text: str` + - `format: Optional[Format]` - The text output from the model. + The input format for the custom tool. Default is unconstrained text. - - `type: Literal["output_text"]` + - `class FormatText: …` - The type of the output text. Always `output_text`. + Unconstrained free-form text. - - `logprobs: Optional[List[Logprob]]` + - `type: Literal["text"]` - - `type: Literal["multi_agent_call_output"]` + Unconstrained text format. Always `text`. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"text"` - - `"multi_agent_call_output"` + - `class FormatGrammar: …` - - `agent: Optional[MultiAgentCallOutputAgent]` + A grammar defined by the user. - The agent that produced this item. + - `definition: str` - - `agent_name: str` + The grammar definition. - The canonical name of the agent that produced this item. + - `syntax: Literal["lark", "regex"]` - - `class BetaResponseFunctionWebSearch: …` + The syntax of the grammar definition. One of `lark` or `regex`. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `"lark"` - - `class BetaResponseComputerToolCall: …` + - `"regex"` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `type: Literal["grammar"]` - - `class BetaResponseComputerToolCallOutputItem: …` + Grammar format. Always `grammar`. - - `id: str` + - `"grammar"` - The unique ID of the computer call tool output. + - `class BetaNamespaceTool: …` - - `call_id: str` + Groups function/custom tools under a shared namespace. - The ID of the computer tool call that produced the output. + - `description: str` - - `output: BetaResponseComputerToolCallOutputScreenshot` + A description of the namespace shown to the model. - A computer screenshot image used with the computer use tool. + - `name: str` - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + The namespace name used in tool calls (for example, `crm`). - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `tools: List[Tool]` - - `"completed"` + The function/custom tools available inside this namespace. - - `"incomplete"` + - `class ToolFunction: …` - - `"failed"` + - `name: str` - - `"in_progress"` + - `type: Literal["function"]` - - `type: Literal["computer_call_output"]` + - `"function"` - The type of the computer tool call output. Always `computer_call_output`. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"computer_call_output"` + The tool invocation context(s). - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + - `"direct"` - The safety checks reported by the API that have been acknowledged by the - developer. + - `"programmatic"` - - `id: str` + - `defer_loading: Optional[bool]` - The ID of the pending safety check. + Whether this function should be deferred and discovered via tool search. - - `code: Optional[str]` + - `description: Optional[str]` - The type of the pending safety check. + - `output_schema: Optional[Dict[str, object]]` - - `message: Optional[str]` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Details about the pending safety check. + - `parameters: Optional[object]` - - `agent: Optional[Agent]` + - `strict: Optional[bool]` - The agent that produced this item. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `agent_name: str` + - `class BetaCustomTool: …` - The canonical name of the agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `created_by: Optional[str]` + - `type: Literal["namespace"]` - The identifier of the actor that created the item. + The type of the tool. Always `namespace`. - - `class BetaResponseReasoningItem: …` + - `"namespace"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class BetaToolSearchTool: …` - - `class Program: …` + Hosted or BYOT tool search configuration for deferred tools. - - `id: str` + - `type: Literal["tool_search"]` - The unique ID of the program item. + The type of the tool. Always `tool_search`. - - `call_id: str` + - `"tool_search"` - The stable call ID of the program item. + - `description: Optional[str]` - - `code: str` + Description shown to the model for a client-executed tool search tool. - The JavaScript source executed by programmatic tool calling. + - `execution: Optional[Literal["server", "client"]]` - - `fingerprint: str` + Whether tool search is executed by the server or by the client. - Opaque program replay fingerprint that must be round-tripped. + - `"server"` - - `type: Literal["program"]` + - `"client"` - The type of the item. Always `program`. + - `parameters: Optional[object]` - - `"program"` + Parameter schema for a client-executed tool search tool. - - `agent: Optional[ProgramAgent]` + - `class BetaWebSearchPreviewTool: …` - The agent that produced this item. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `agent_name: str` + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - The canonical name of the agent that produced this item. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `class ProgramOutput: …` + - `"web_search_preview"` - - `id: str` + - `"web_search_preview_2025_03_11"` - The unique ID of the program output item. + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `call_id: str` + - `"text"` - The call ID of the program item. + - `"image"` - - `result: str` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The result produced by the program item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `status: Literal["completed", "incomplete"]` + - `"low"` - The terminal status of the program output item. + - `"medium"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `user_location: Optional[UserLocation]` - - `type: Literal["program_output"]` + The user's location. - The type of the item. Always `program_output`. + - `type: Literal["approximate"]` - - `"program_output"` + The type of location approximation. Always `approximate`. - - `agent: Optional[ProgramOutputAgent]` + - `"approximate"` - The agent that produced this item. + - `city: Optional[str]` - - `agent_name: str` + Free text input for the city of the user, e.g. `San Francisco`. - The canonical name of the agent that produced this item. + - `country: Optional[str]` - - `class BetaResponseToolSearchCall: …` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `id: str` + - `region: Optional[str]` - The unique ID of the tool search call item. + Free text input for the region of the user, e.g. `California`. - - `arguments: object` + - `timezone: Optional[str]` - Arguments used for the tool search call. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `call_id: Optional[str]` + - `class BetaApplyPatchTool: …` - The unique ID of the tool search call generated by the model. + Allows the assistant to create, delete, or update files using unified diffs. - - `execution: Literal["server", "client"]` + - `type: Literal["apply_patch"]` - Whether tool search was executed by the server or by the client. + The type of the tool. Always `apply_patch`. - - `"server"` + - `"apply_patch"` - - `"client"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `status: Literal["in_progress", "completed", "incomplete"]` + The tool invocation context(s). - The status of the tool search call item that was recorded. + - `"direct"` - - `"in_progress"` + - `"programmatic"` - - `"completed"` + - `type: Literal["tool_search_output"]` - - `"incomplete"` + The item type. Always `tool_search_output`. - - `type: Literal["tool_search_call"]` + - `"tool_search_output"` - The type of the item. Always `tool_search_call`. + - `id: Optional[str]` - - `"tool_search_call"` + The unique ID of this tool search output. - `agent: Optional[Agent]` @@ -80385,21 +91319,11 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `class BetaResponseToolSearchOutputItem: …` - - - `id: str` - - The unique ID of the tool search output item. - - `call_id: Optional[str]` The unique ID of the tool search call generated by the model. - - `execution: Literal["server", "client"]` + - `execution: Optional[Literal["server", "client"]]` Whether tool search was executed by the server or by the client. @@ -80407,9 +91331,9 @@ print(compacted_response) - `"client"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the tool search output item that was recorded. + The status of the tool search output. - `"in_progress"` @@ -80417,9 +91341,17 @@ print(compacted_response) - `"incomplete"` + - `class AdditionalTools: …` + + - `role: Literal["developer"]` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + - `tools: List[BetaTool]` - The loaded tool definitions returned by tool search. + A list of additional tools made available at this item. - `class BetaFunctionTool: …` @@ -80485,13 +91417,17 @@ print(compacted_response) Allows the assistant to create, delete, or update files using unified diffs. - - `type: Literal["tool_search_output"]` + - `type: Literal["additional_tools"]` - The type of the item. Always `tool_search_output`. + The item type. Always `additional_tools`. - - `"tool_search_output"` + - `"additional_tools"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of this additional tools item. + + - `agent: Optional[AdditionalToolsAgent]` The agent that produced this item. @@ -80499,111 +91435,132 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. + - `class BetaResponseReasoningItem: …` - - `class AdditionalTools: …` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: str` - The unique ID of the additional tools item. + The unique identifier of the reasoning content. - - `role: Literal["unknown", "user", "assistant", 5 more]` + - `summary: List[Summary]` - The role that provided the additional tools. + Reasoning summary content. - - `"unknown"` + - `text: str` - - `"user"` + A summary of the reasoning output from the model so far. - - `"assistant"` + - `type: Literal["summary_text"]` - - `"system"` + The type of the object. Always `summary_text`. - - `"critic"` + - `"summary_text"` - - `"discriminator"` + - `type: Literal["reasoning"]` - - `"developer"` + The type of the object. Always `reasoning`. - - `"tool"` + - `"reasoning"` - - `tools: List[BetaTool]` + - `agent: Optional[Agent]` - The additional tool definitions made available at this item. + The agent that produced this item. - - `class BetaFunctionTool: …` + - `agent_name: str` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The canonical name of the agent that produced this item. - - `class BetaFileSearchTool: …` + - `content: Optional[List[Content]]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + Reasoning text content. - - `class BetaComputerTool: …` + - `text: str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The reasoning text from the model. - - `class BetaComputerUsePreviewTool: …` + - `type: Literal["reasoning_text"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the reasoning text. Always `reasoning_text`. - - `class BetaWebSearchTool: …` + - `"reasoning_text"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `encrypted_content: Optional[str]` - - `class Mcp: …` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `class CodeInterpreter: …` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A tool that runs Python code to help generate a response to a prompt. + - `"in_progress"` - - `class ProgrammaticToolCalling: …` + - `"completed"` - - `class ImageGeneration: …` + - `"incomplete"` - A tool that generates images using the GPT image models. + - `class BetaResponseCompactionItemParam: …` - - `class LocalShell: …` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - A tool that allows the model to execute shell commands in a local environment. + - `encrypted_content: str` - - `class BetaFunctionShellTool: …` + The encrypted content of the compaction summary. - A tool that allows the model to execute shell commands. + - `type: Literal["compaction"]` - - `class BetaCustomTool: …` + The type of the item. Always `compaction`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"compaction"` - - `class BetaNamespaceTool: …` + - `id: Optional[str]` - Groups function/custom tools under a shared namespace. + The ID of the compaction item. - - `class BetaToolSearchTool: …` + - `agent: Optional[Agent]` - Hosted or BYOT tool search configuration for deferred tools. + The agent that produced this item. - - `class BetaWebSearchPreviewTool: …` + - `agent_name: str` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The canonical name of the agent that produced this item. - - `class BetaApplyPatchTool: …` + - `class ImageGenerationCall: …` - Allows the assistant to create, delete, or update files using unified diffs. + An image generation request made by the model. - - `type: Literal["additional_tools"]` + - `id: str` - The type of the item. Always `additional_tools`. + The unique ID of the image generation call. - - `"additional_tools"` + - `result: Optional[str]` - - `agent: Optional[AdditionalToolsAgent]` + The generated image encoded in base64. + + - `status: Literal["in_progress", "completed", "generating", "failed"]` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: Literal["image_generation_call"]` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `agent: Optional[ImageGenerationCallAgent]` The agent that produced this item. @@ -80611,67 +91568,76 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem: …` + - `class BetaResponseCodeInterpreterToolCall: …` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A tool call to run code. - `id: str` - The unique ID of the compaction item. + The unique ID of the code interpreter tool call. - - `encrypted_content: str` + - `code: Optional[str]` - The encrypted content that was produced by compaction. + The code to run, or null if not available. - - `type: Literal["compaction"]` + - `container_id: str` - The type of the item. Always `compaction`. + The ID of the container used to run the code. - - `"compaction"` + - `outputs: Optional[List[Output]]` - - `agent: Optional[Agent]` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The agent that produced this item. + - `class OutputLogs: …` - - `agent_name: str` + The logs output from the code interpreter. - The canonical name of the agent that produced this item. + - `logs: str` - - `created_by: Optional[str]` + The logs output from the code interpreter. - The identifier of the actor that created the item. + - `type: Literal["logs"]` - - `class ImageGenerationCall: …` + The type of the output. Always `logs`. - An image generation request made by the model. + - `"logs"` - - `id: str` + - `class OutputImage: …` - The unique ID of the image generation call. + The image output from the code interpreter. - - `result: Optional[str]` + - `type: Literal["image"]` - The generated image encoded in base64. + The type of the output. Always `image`. - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `"image"` - The status of the image generation call. + - `url: str` + + The URL of the image output from the code interpreter. + + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `"in_progress"` - `"completed"` - - `"generating"` + - `"incomplete"` + + - `"interpreting"` - `"failed"` - - `type: Literal["image_generation_call"]` + - `type: Literal["code_interpreter_call"]` - The type of the image generation call. Always `image_generation_call`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"image_generation_call"` + - `"code_interpreter_call"` - - `agent: Optional[ImageGenerationCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -80679,10 +91645,6 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall: …` - - A tool call to run code. - - `class LocalShellCall: …` A tool call to run a command on the local shell. @@ -80785,75 +91747,41 @@ print(compacted_response) - `"incomplete"` - - `class BetaResponseFunctionShellToolCall: …` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: str` + - `class ShellCall: …` - The unique ID of the shell tool call. Populated when this item is returned via API. + A tool representing a request to execute one or more shell commands. - - `action: Action` + - `action: ShellCallAction` The shell commands and limits that describe how to run the tool call. - `commands: List[str]` + Ordered shell commands for the execution environment to run. + - `max_output_length: Optional[int]` - Optional maximum number of characters to return from each command. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `timeout_ms: Optional[int]` - Optional timeout in milliseconds for the commands. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - `call_id: str` The unique ID of the shell tool call generated by the model. - - `environment: Optional[Environment]` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment: …` - - Represents the use of a local environment to perform shell actions. - - - `type: Literal["local"]` - - The environment type. Always `local`. - - - `"local"` - - - `class BetaResponseContainerReference: …` - - Represents a container created with /v1/containers. - - - `container_id: str` - - - `type: Literal["container_reference"]` - - The environment type. Always `container_reference`. - - - `"container_reference"` - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `type: Literal["shell_call"]` The type of the item. Always `shell_call`. - `"shell_call"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: Optional[ShellCallAgent]` The agent that produced this item. @@ -80861,17 +91789,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ShellCallCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ShellCallCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ShellCallCallerProgram: …` - `caller_id: str` @@ -80879,37 +91809,45 @@ print(compacted_response) - `type: Literal["program"]` + The caller type. Always `program`. + - `"program"` - - `created_by: Optional[str]` + - `environment: Optional[ShellCallEnvironment]` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `class BetaResponseFunctionShellToolCallOutput: …` + - `class BetaLocalEnvironment: …` - The output of a shell tool call that was emitted. + - `class BetaContainerReference: …` - - `id: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The unique ID of the shell call output. Populated when this item is returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `call_id: str` + - `"in_progress"` - The unique ID of the shell tool call generated by the model. + - `"completed"` - - `max_output_length: Optional[int]` + - `"incomplete"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `class ShellCallOutput: …` - - `output: List[Output]` + The streamed output items emitted by a shell tool call. - An array of shell call output contents + - `call_id: str` - - `outcome: OutputOutcome` + The unique ID of the shell tool call generated by the model. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `output: List[BetaResponseFunctionShellCallOutputContent]` - - `class OutputOutcomeTimeout: …` + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: Outcome` + + The exit or timeout outcome associated with this shell call. + + - `class OutcomeTimeout: …` Indicates that the shell call exceeded its configured time limit. @@ -80919,13 +91857,13 @@ print(compacted_response) - `"timeout"` - - `class OutputOutcomeExit: …` + - `class OutcomeExit: …` Indicates that the shell commands finished and returned an exit code. - `exit_code: int` - Exit code from the shell process. + The exit code returned by the shell process. - `type: Literal["exit"]` @@ -80935,33 +91873,23 @@ print(compacted_response) - `stderr: str` - The standard error output that was captured. + Captured stderr output for the shell call. - `stdout: str` - The standard output that was captured. - - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` + Captured stdout output for the shell call. - `type: Literal["shell_call_output"]` - The type of the shell call output. Always `shell_call_output`. + The type of the item. Always `shell_call_output`. - `"shell_call_output"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: Optional[ShellCallOutputAgent]` The agent that produced this item. @@ -80969,17 +91897,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ShellCallOutputCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ShellCallOutputCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ShellCallOutputCallerProgram: …` - `caller_id: str` @@ -80987,75 +91917,83 @@ print(compacted_response) - `type: Literal["program"]` + The caller type. Always `program`. + - `"program"` - - `created_by: Optional[str]` + - `max_output_length: Optional[int]` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseApplyPatchToolCall: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A tool call that applies file diffs by creating, deleting, or updating files. + The status of the shell call output. - - `id: str` + - `"in_progress"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"completed"` + + - `"incomplete"` + + - `class ApplyPatchCall: …` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: str` The unique ID of the apply patch tool call generated by the model. - - `operation: Operation` + - `operation: ApplyPatchCallOperation` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - - `class OperationCreateFile: …` + - `class ApplyPatchCallOperationCreateFile: …` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `diff: str` - Diff to apply. + Unified diff content to apply when creating the file. - `path: str` - Path of the file to create. + Path of the file to create relative to the workspace root. - `type: Literal["create_file"]` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `"create_file"` - - `class OperationDeleteFile: …` + - `class ApplyPatchCallOperationDeleteFile: …` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `path: str` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `type: Literal["delete_file"]` - Delete the specified file. + The operation type. Always `delete_file`. - `"delete_file"` - - `class OperationUpdateFile: …` + - `class ApplyPatchCallOperationUpdateFile: …` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `diff: str` - Diff to apply. + Unified diff content to apply to the existing file. - `path: str` - Path of the file to update. + Path of the file to update relative to the workspace root. - `type: Literal["update_file"]` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `"update_file"` @@ -81073,7 +92011,11 @@ print(compacted_response) - `"apply_patch_call"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallAgent]` The agent that produced this item. @@ -81081,17 +92023,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ApplyPatchCallCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ApplyPatchCallCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ApplyPatchCallCallerProgram: …` - `caller_id: str` @@ -81099,19 +92043,13 @@ print(compacted_response) - `type: Literal["program"]` - - `"program"` - - - `created_by: Optional[str]` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput: …` + The caller type. Always `program`. - The output emitted by an apply patch tool call. + - `"program"` - - `id: str` + - `class ApplyPatchCallOutput: …` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The streamed output emitted by an apply patch tool call. - `call_id: str` @@ -81131,7 +92069,11 @@ print(compacted_response) - `"apply_patch_call_output"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallOutputAgent]` The agent that produced this item. @@ -81139,33 +92081,151 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ApplyPatchCallOutputCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ApplyPatchCallOutputCallerDirect: …` + + - `type: Literal["direct"]` + + The caller type. Always `direct`. + + - `"direct"` + + - `class ApplyPatchCallOutputCallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `output: Optional[str]` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `class McpListTools: …` + + A list of tools available on an MCP server. + + - `id: str` + + The unique ID of the list. + + - `server_label: str` + + The label of the MCP server. + + - `tools: List[McpListToolsTool]` + + The tools available on the server. + + - `input_schema: object` + + The JSON schema describing the tool's input. + + - `name: str` + + The name of the tool. + + - `annotations: Optional[object]` + + Additional annotations about the tool. + + - `description: Optional[str]` + + The description of the tool. + + - `type: Literal["mcp_list_tools"]` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `agent: Optional[McpListToolsAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `error: Optional[str]` + + Error message if the server could not list tools. + + - `class McpApprovalRequest: …` + + A request for human approval of a tool invocation. + + - `id: str` + + The unique ID of the approval request. + + - `arguments: str` + + A JSON string of arguments for the tool. + + - `name: str` + + The name of the tool to run. + + - `server_label: str` + + The label of the MCP server making the request. + + - `type: Literal["mcp_approval_request"]` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `agent: Optional[McpApprovalRequestAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse: …` + + A response to an MCP approval request. + + - `approval_request_id: str` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. - - `type: Literal["direct"]` + - `type: Literal["mcp_approval_response"]` - - `"direct"` + The type of the item. Always `mcp_approval_response`. - - `class CallerProgram: …` + - `"mcp_approval_response"` - - `caller_id: str` + - `id: Optional[str]` - The call ID of the program item that produced this tool call. + The unique ID of the approval response - - `type: Literal["program"]` + - `agent: Optional[McpApprovalResponseAgent]` - - `"program"` + The agent that produced this item. - - `created_by: Optional[str]` + - `agent_name: str` - The ID of the entity that created this tool call output. + The canonical name of the agent that produced this item. - - `output: Optional[str]` + - `reason: Optional[str]` - Optional textual output returned by the apply patch tool. + Optional reason for the decision. - `class McpCall: …` @@ -81228,45 +92288,50 @@ print(compacted_response) - `"failed"` - - `class McpListTools: …` + - `class BetaResponseCustomToolCallOutput: …` - A list of tools available on an MCP server. + The output of a custom tool call from your code, being sent back to the model. - - `id: str` + - `call_id: str` - The unique ID of the list. + The call ID, used to map this custom tool call output to a custom tool call. - - `server_label: str` + - `output: Union[str, List[OutputOutputContentList]]` - The label of the MCP server. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `tools: List[McpListToolsTool]` + - `str` - The tools available on the server. + A string of the output of the custom tool call. - - `input_schema: object` + - `List[OutputOutputContentList]` - The JSON schema describing the tool's input. + Text, image, or file output of the custom tool call. - - `name: str` + - `class BetaResponseInputText: …` - The name of the tool. + A text input to the model. - - `annotations: Optional[object]` + - `class BetaResponseInputImage: …` - Additional annotations about the tool. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `description: Optional[str]` + - `class BetaResponseInputFile: …` - The description of the tool. + A file input to the model. - - `type: Literal["mcp_list_tools"]` + - `type: Literal["custom_tool_call_output"]` - The type of the item. Always `mcp_list_tools`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"mcp_list_tools"` + - `"custom_tool_call_output"` - - `agent: Optional[McpListToolsAgent]` + - `id: Optional[str]` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: Optional[Agent]` The agent that produced this item. @@ -81274,997 +92339,943 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `error: Optional[str]` + - `caller: Optional[Caller]` - Error message if the server could not list tools. + The execution context that produced this tool call. - - `class McpApprovalRequest: …` + - `class CallerDirect: …` - A request for human approval of a tool invocation. + - `type: Literal["direct"]` - - `id: str` + The caller type. Always `direct`. - The unique ID of the approval request. + - `"direct"` - - `arguments: str` + - `class CallerProgram: …` - A JSON string of arguments for the tool. + - `caller_id: str` - - `name: str` + The call ID of the program item that produced this tool call. - The name of the tool to run. + - `type: Literal["program"]` - - `server_label: str` + The caller type. Always `program`. - The label of the MCP server making the request. + - `"program"` - - `type: Literal["mcp_approval_request"]` + - `class BetaResponseCustomToolCall: …` - The type of the item. Always `mcp_approval_request`. + A call to a custom tool created by the model. - - `"mcp_approval_request"` + - `call_id: str` - - `agent: Optional[McpApprovalRequestAgent]` + An identifier used to map this custom tool call to a tool call output. - The agent that produced this item. + - `input: str` - - `agent_name: str` + The input for the custom tool call generated by the model. - The canonical name of the agent that produced this item. + - `name: str` - - `class McpApprovalResponse: …` + The name of the custom tool being called. - A response to an MCP approval request. + - `type: Literal["custom_tool_call"]` - - `id: str` + The type of the custom tool call. Always `custom_tool_call`. - The unique ID of the approval response + - `"custom_tool_call"` - - `approval_request_id: str` + - `id: Optional[str]` - The ID of the approval request being answered. + The unique ID of the custom tool call in the OpenAI platform. - - `approve: bool` + - `agent: Optional[Agent]` - Whether the request was approved. + The agent that produced this item. - - `type: Literal["mcp_approval_response"]` + - `agent_name: str` - The type of the item. Always `mcp_approval_response`. + The canonical name of the agent that produced this item. - - `"mcp_approval_response"` + - `caller: Optional[Caller]` - - `agent: Optional[McpApprovalResponseAgent]` + The execution context that produced this tool call. - The agent that produced this item. + - `class CallerDirect: …` - - `agent_name: str` + - `type: Literal["direct"]` - The canonical name of the agent that produced this item. + - `"direct"` - - `reason: Optional[str]` + - `class CallerProgram: …` - Optional reason for the decision. + - `caller_id: str` - - `class BetaResponseCustomToolCall: …` + The call ID of the program item that produced this tool call. - A call to a custom tool created by the model. + - `type: Literal["program"]` - - `class BetaResponseCustomToolCallOutputItem: …` + - `"program"` - The output of a custom tool call from your code, being sent back to the model. + - `namespace: Optional[str]` - - `id: str` + The namespace of the custom tool being called. - The unique ID of the custom tool call output item. + - `class CompactionTrigger: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + Compacts the current context. Must be the final input item. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: Literal["compaction_trigger"]` - - `"in_progress"` + The type of the item. Always `compaction_trigger`. - - `"completed"` + - `"compaction_trigger"` - - `"incomplete"` + - `agent: Optional[CompactionTriggerAgent]` - - `created_by: Optional[str]` + The agent that produced this item. - The identifier of the actor that created the item. + - `agent_name: str` - - `parallel_tool_calls: bool` + The canonical name of the agent that produced this item. - Whether to allow the model to run tool calls in parallel. + - `class ItemReference: …` - - `temperature: Optional[float]` + An internal identifier for an item to reference. - 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. - We generally recommend altering this or `top_p` but not both. + - `id: str` - - `tool_choice: ToolChoice` + The ID of the item to reference. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `agent: Optional[ItemReferenceAgent]` - - `Literal["none", "auto", "required"]` + The agent that produced this item. - - `"none"` + - `agent_name: str` - - `"auto"` + The canonical name of the agent that produced this item. - - `"required"` + - `type: Optional[Literal["item_reference"]]` - - `class BetaToolChoiceAllowed: …` + The type of item to reference. Always `item_reference`. - Constrains the tools available to the model to a pre-defined set. + - `"item_reference"` - - `mode: Literal["auto", "required"]` + - `class Program: …` - Constrains the tools available to the model to a pre-defined set. + - `id: str` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The unique ID of this program item. - `required` requires the model to call one or more of the allowed tools. + - `call_id: str` - - `"auto"` + The stable call ID of the program item. - - `"required"` + - `code: str` - - `tools: List[Dict[str, object]]` + The JavaScript source executed by programmatic tool calling. - A list of tool definitions that the model should be allowed to call. + - `fingerprint: str` - For the Responses API, the list of tool definitions might look like: + Opaque program replay fingerprint that must be round-tripped. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `type: Literal["program"]` - - `type: Literal["allowed_tools"]` + The item type. Always `program`. - Allowed tool configuration type. Always `allowed_tools`. + - `"program"` - - `"allowed_tools"` + - `agent: Optional[ProgramAgent]` - - `class BetaToolChoiceTypes: …` + The agent that produced this item. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `agent_name: str` - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + The canonical name of the agent that produced this item. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `class ProgramOutput: …` - Allowed values are: + - `id: str` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The unique ID of this program output item. - - `"file_search"` + - `call_id: str` - - `"web_search_preview"` + The call ID of the program item. - - `"computer"` + - `result: str` - - `"computer_use_preview"` + The result produced by the program item. - - `"computer_use"` + - `status: Literal["completed", "incomplete"]` - - `"web_search_preview_2025_03_11"` + The terminal status of the program output. - - `"image_generation"` + - `"completed"` - - `"code_interpreter"` + - `"incomplete"` - - `class BetaToolChoiceFunction: …` + - `type: Literal["program_output"]` - Use this option to force the model to call a specific function. + The item type. Always `program_output`. - - `name: str` + - `"program_output"` - The name of the function to call. + - `agent: Optional[ProgramOutputAgent]` - - `type: Literal["function"]` + The agent that produced this item. - For function calling, the type is always `function`. + - `agent_name: str` - - `"function"` + The canonical name of the agent that produced this item. - - `class BetaToolChoiceMcp: …` +### Beta Response Input Audio - Use this option to force the model to call a specific tool on a remote MCP server. +- `class BetaResponseInputAudio: …` - - `server_label: str` + An audio input to the model. - The label of the MCP server to use. + - `input_audio: InputAudio` - - `type: Literal["mcp"]` + - `data: str` - For MCP tools, the type is always `mcp`. + Base64-encoded audio data. - - `"mcp"` + - `format: Literal["mp3", "wav"]` - - `name: Optional[str]` + The format of the audio data. Currently supported formats are `mp3` and + `wav`. - The name of the tool to call on the server. + - `"mp3"` - - `class BetaToolChoiceCustom: …` + - `"wav"` - Use this option to force the model to call a specific custom tool. + - `type: Literal["input_audio"]` - - `name: str` + The type of the input item. Always `input_audio`. - The name of the custom tool to call. + - `"input_audio"` - - `type: Literal["custom"]` +### Beta Response Input Content - For custom tool calling, the type is always `custom`. +- `BetaResponseInputContent` - - `"custom"` + A text input to the model. - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + - `class BetaResponseInputText: …` - - `type: Literal["programmatic_tool_calling"]` + A text input to the model. - The tool to call. Always `programmatic_tool_calling`. + - `text: str` - - `"programmatic_tool_calling"` + The text input to the model. - - `class BetaToolChoiceApplyPatch: …` + - `type: Literal["input_text"]` - Forces the model to call the apply_patch tool when executing a tool call. + The type of the input item. Always `input_text`. - - `type: Literal["apply_patch"]` + - `"input_text"` - The tool to call. Always `apply_patch`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"apply_patch"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaToolChoiceShell: …` + - `mode: Literal["explicit"]` - Forces the model to call the shell tool when a tool call is required. + The breakpoint mode. Always `explicit`. - - `type: Literal["shell"]` + - `"explicit"` - The tool to call. Always `shell`. + - `class BetaResponseInputImage: …` - - `"shell"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `tools: List[BetaTool]` + - `detail: Literal["low", "high", "auto", "original"]` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - We support the following categories of tools: + - `"low"` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `"high"` - - `class BetaFunctionTool: …` + - `"auto"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `"original"` - - `class BetaFileSearchTool: …` + - `type: Literal["input_image"]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The type of the input item. Always `input_image`. - - `class BetaComputerTool: …` + - `"input_image"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `file_id: Optional[str]` - - `class BetaComputerUsePreviewTool: …` + The ID of the file to be sent to the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `image_url: Optional[str]` - - `class BetaWebSearchTool: …` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `class Mcp: …` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `mode: Literal["explicit"]` - - `class CodeInterpreter: …` + The breakpoint mode. Always `explicit`. - A tool that runs Python code to help generate a response to a prompt. + - `"explicit"` - - `class ProgrammaticToolCalling: …` + - `class BetaResponseInputFile: …` - - `class ImageGeneration: …` + A file input to the model. - A tool that generates images using the GPT image models. + - `type: Literal["input_file"]` - - `class LocalShell: …` + The type of the input item. Always `input_file`. - A tool that allows the model to execute shell commands in a local environment. + - `"input_file"` - - `class BetaFunctionShellTool: …` + - `detail: Optional[Literal["auto", "low", "high"]]` - A tool that allows the model to execute shell commands. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `class BetaCustomTool: …` + - `"auto"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"low"` - - `class BetaNamespaceTool: …` + - `"high"` - Groups function/custom tools under a shared namespace. + - `file_data: Optional[str]` - - `class BetaToolSearchTool: …` + The content of the file to be sent to the model. - Hosted or BYOT tool search configuration for deferred tools. + - `file_id: Optional[str]` - - `class BetaWebSearchPreviewTool: …` + The ID of the file to be sent to the model. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `file_url: Optional[str]` - - `class BetaApplyPatchTool: …` + The URL of the file to be sent to the model. - Allows the assistant to create, delete, or update files using unified diffs. + - `filename: Optional[str]` - - `top_p: Optional[float]` + The name of the file to be sent to the model. - 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. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - We generally recommend altering this or `temperature` but not both. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `background: Optional[bool]` + - `mode: Literal["explicit"]` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The breakpoint mode. Always `explicit`. - - `completed_at: Optional[float]` + - `"explicit"` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. +### Beta Response Input File - - `conversation: Optional[Conversation]` +- `class BetaResponseInputFile: …` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + A file input to the model. - - `id: str` + - `type: Literal["input_file"]` - The unique ID of the conversation that this response was associated with. + The type of the input item. Always `input_file`. - - `max_output_tokens: Optional[int]` + - `"input_file"` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `detail: Optional[Literal["auto", "low", "high"]]` - - `max_tool_calls: Optional[int]` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `"auto"` - - `moderation: Optional[Moderation]` + - `"low"` - Moderation results for the response input and output, if moderated completions were requested. + - `"high"` - - `input: ModerationInput` + - `file_data: Optional[str]` - Moderation for the response input. + The content of the file to be sent to the model. - - `class ModerationInputModerationResult: …` + - `file_id: Optional[str]` - A moderation result produced for the response input or output. + The ID of the file to be sent to the model. - - `categories: Dict[str, bool]` + - `file_url: Optional[str]` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The URL of the file to be sent to the model. - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `filename: Optional[str]` - Which modalities of input are reflected by the score for each category. + The name of the file to be sent to the model. - - `"text"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"image"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `category_scores: Dict[str, float]` + - `mode: Literal["explicit"]` - A dictionary of moderation categories to scores. + The breakpoint mode. Always `explicit`. - - `flagged: bool` + - `"explicit"` - A boolean indicating whether the content was flagged by any category. +### Beta Response Input File Content - - `model: str` +- `class BetaResponseInputFileContent: …` - The moderation model that produced this result. + A file input to the model. - - `type: Literal["moderation_result"]` + - `type: Literal["input_file"]` - The object type, which was always `moderation_result` for successful moderation results. + The type of the input item. Always `input_file`. - - `"moderation_result"` + - `"input_file"` - - `class ModerationInputError: …` + - `detail: Optional[Literal["auto", "low", "high"]]` - An error produced while attempting moderation for the response input or output. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `code: str` + - `"auto"` - The error code. + - `"low"` - - `message: str` + - `"high"` - The error message. + - `file_data: Optional[str]` - - `type: Literal["error"]` + The base64-encoded data of the file to be sent to the model. - The object type, which was always `error` for moderation failures. + - `file_id: Optional[str]` - - `"error"` + The ID of the file to be sent to the model. - - `output: ModerationOutput` + - `file_url: Optional[str]` - Moderation for the response output. + The URL of the file to be sent to the model. - - `class ModerationOutputModerationResult: …` + - `filename: Optional[str]` - A moderation result produced for the response input or output. + The name of the file to be sent to the model. - - `categories: Dict[str, bool]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `mode: Literal["explicit"]` - Which modalities of input are reflected by the score for each category. + The breakpoint mode. Always `explicit`. - - `"text"` + - `"explicit"` - - `"image"` +### Beta Response Input Image - - `category_scores: Dict[str, float]` +- `class BetaResponseInputImage: …` - A dictionary of moderation categories to scores. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `flagged: bool` + - `detail: Literal["low", "high", "auto", "original"]` - A boolean indicating whether the content was flagged by any category. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `model: str` + - `"low"` - The moderation model that produced this result. + - `"high"` - - `type: Literal["moderation_result"]` + - `"auto"` - The object type, which was always `moderation_result` for successful moderation results. + - `"original"` - - `"moderation_result"` + - `type: Literal["input_image"]` - - `class ModerationOutputError: …` + The type of the input item. Always `input_image`. - An error produced while attempting moderation for the response input or output. + - `"input_image"` - - `code: str` + - `file_id: Optional[str]` - The error code. + The ID of the file to be sent to the model. - - `message: str` + - `image_url: Optional[str]` - The error message. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: Literal["error"]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The object type, which was always `error` for moderation failures. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"error"` + - `mode: Literal["explicit"]` - - `previous_response_id: Optional[str]` + The breakpoint mode. Always `explicit`. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `"explicit"` - - `prompt: Optional[BetaResponsePrompt]` +### Beta Response Input Image Content - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). +- `class BetaResponseInputImageContent: …` - - `id: str` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The unique identifier of the prompt template to use. + - `type: Literal["input_image"]` - - `variables: Optional[Dict[str, Variables]]` + The type of the input item. Always `input_image`. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `"input_image"` - - `str` + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - - `class BetaResponseInputText: …` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - A text input to the model. + - `"low"` - - `class BetaResponseInputImage: …` + - `"high"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"auto"` - - `class BetaResponseInputFile: …` + - `"original"` - A file input to the model. + - `file_id: Optional[str]` - - `version: Optional[str]` + The ID of the file to be sent to the model. - Optional version of the prompt template. + - `image_url: Optional[str]` - - `prompt_cache_key: Optional[str]` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `prompt_cache_options: Optional[PromptCacheOptions]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `mode: Literal["explicit"]` - - `mode: Literal["implicit", "explicit"]` + The breakpoint mode. Always `explicit`. - Whether implicit prompt-cache breakpoints were enabled. + - `"explicit"` - - `"implicit"` +### Beta Response Input Item - - `"explicit"` +- `BetaResponseInputItem` - - `ttl: Literal["30m"]` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - The minimum lifetime applied to each cache breakpoint. + - `class BetaEasyInputMessage: …` - - `"30m"` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + - `content: Union[str, BetaResponseInputMessageContentList]` - Deprecated. Use `prompt_cache_options.ttl` instead. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `str` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + A text input to the model. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `List[BetaResponseInputContent]` - - `"in_memory"` + - `class BetaResponseInputText: …` - - `"24h"` + A text input to the model. - - `reasoning: Optional[Reasoning]` + - `text: str` - **gpt-5 and o-series models only** + The text input to the model. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `type: Literal["input_text"]` - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + The type of the input item. Always `input_text`. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `"input_text"` - - `"auto"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"current_turn"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"all_turns"` + - `mode: Literal["explicit"]` - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + The breakpoint mode. Always `explicit`. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `"explicit"` - - `"none"` + - `class BetaResponseInputImage: …` - - `"minimal"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"low"` + - `detail: Literal["low", "high", "auto", "original"]` - - `"medium"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` - `"high"` - - `"xhigh"` + - `"auto"` - - `"max"` + - `"original"` - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + - `type: Literal["input_image"]` - **Deprecated:** use `summary` instead. + The type of the input item. Always `input_image`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"input_image"` - - `"auto"` + - `file_id: Optional[str]` - - `"concise"` + The ID of the file to be sent to the model. - - `"detailed"` + - `image_url: Optional[str]` - - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Controls the reasoning execution mode for the request. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - When returned on a response, this is the effective execution mode. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `str` + - `mode: Literal["explicit"]` - - `Literal["standard", "pro"]` + The breakpoint mode. Always `explicit`. - Controls the reasoning execution mode for the request. + - `"explicit"` - When returned on a response, this is the effective execution mode. + - `class BetaResponseInputFile: …` - - `"standard"` + A file input to the model. - - `"pro"` + - `type: Literal["input_file"]` - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + The type of the input item. Always `input_file`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"input_file"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `detail: Optional[Literal["auto", "low", "high"]]` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - `"auto"` - - `"concise"` + - `"low"` - - `"detailed"` + - `"high"` - - `safety_identifier: Optional[str]` + - `file_data: Optional[str]` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The content of the file to be sent to the model. - - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + - `file_id: Optional[str]` - Specifies the processing type used for serving the request. + The ID of the file to be sent to the model. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `file_url: Optional[str]` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + The URL of the file to be sent to the model. - - `"auto"` + - `filename: Optional[str]` - - `"default"` + The name of the file to be sent to the model. - - `"flex"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"scale"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"priority"` + - `mode: Literal["explicit"]` - - `status: Optional[BetaResponseStatus]` + The breakpoint mode. Always `explicit`. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `"explicit"` - - `"completed"` + - `role: Literal["user", "assistant", "system", "developer"]` - - `"failed"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `"in_progress"` + - `"user"` - - `"cancelled"` + - `"assistant"` - - `"queued"` + - `"system"` - - `"incomplete"` + - `"developer"` - - `text: Optional[BetaResponseTextConfig]` + - `phase: Optional[Literal["commentary", "final_answer"]]` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `"commentary"` - - `format: Optional[BetaResponseFormatTextConfig]` + - `"final_answer"` - An object specifying the format that the model must output. + - `type: Optional[Literal["message"]]` - Configuring `{ "type": "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). + The type of the message input. Always `message`. - The default format is `{ "type": "text" }` with no additional options. + - `"message"` - **Not recommended for gpt-4o and newer models:** + - `class Message: …` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `class Text: …` + - `content: BetaResponseInputMessageContentList` - Default response format. Used to generate text responses. + A list of one or many input items to the model, containing different content + types. - - `type: Literal["text"]` + - `class BetaResponseInputText: …` - The type of response format being defined. Always `text`. + A text input to the model. - - `"text"` + - `class BetaResponseInputImage: …` - - `class BetaResponseFormatTextJSONSchemaConfig: …` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `class BetaResponseInputFile: …` - - `name: str` + A file input to the model. - 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. + - `role: Literal["user", "system", "developer"]` - - `schema: Dict[str, object]` + The role of the message input. One of `user`, `system`, or `developer`. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"user"` - - `type: Literal["json_schema"]` + - `"system"` - The type of response format being defined. Always `json_schema`. + - `"developer"` - - `"json_schema"` + - `agent: Optional[MessageAgent]` - - `description: Optional[str]` + The agent that produced this item. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `agent_name: str` - - `strict: Optional[bool]` + The canonical name of the agent that produced this item. - 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). + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `class JSONObject: …` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - 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. + - `"in_progress"` - - `type: Literal["json_object"]` + - `"completed"` - The type of response format being defined. Always `json_object`. + - `"incomplete"` - - `"json_object"` + - `type: Optional[Literal["message"]]` - - `verbosity: Optional[Literal["low", "medium", "high"]]` + The type of the message input. Always set to `message`. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `"message"` - - `"low"` + - `class BetaResponseOutputMessage: …` - - `"medium"` + An output message from the model. - - `"high"` + - `id: str` - - `top_logprobs: Optional[int]` + The unique ID of the output message. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `content: List[Content]` - - `truncation: Optional[Literal["auto", "disabled"]]` + The content of the output message. - The truncation strategy to use for the model response. + - `class BetaResponseOutputText: …` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + A text output from the model. - - `"auto"` + - `annotations: List[Annotation]` - - `"disabled"` + The annotations of the text output. - - `usage: Optional[BetaResponseUsage]` + - `class AnnotationFileCitation: …` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + A citation to a file. - - `input_tokens: int` + - `file_id: str` - The number of input tokens. + The ID of the file. - - `input_tokens_details: InputTokensDetails` + - `filename: str` - A detailed breakdown of the input tokens. + The filename of the file cited. - - `cache_write_tokens: int` + - `index: int` - The number of input tokens that were written to the cache. + The index of the file in the list of files. - - `cached_tokens: int` + - `type: Literal["file_citation"]` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The type of the file citation. Always `file_citation`. - - `output_tokens: int` + - `"file_citation"` - The number of output tokens. + - `class AnnotationURLCitation: …` - - `output_tokens_details: OutputTokensDetails` + A citation for a web resource used to generate a model response. - A detailed breakdown of the output tokens. + - `end_index: int` - - `reasoning_tokens: int` + The index of the last character of the URL citation in the message. - The number of reasoning tokens. + - `start_index: int` - - `total_tokens: int` + The index of the first character of the URL citation in the message. - The total number of tokens used. + - `title: str` - - `user: Optional[str]` + The title of the web resource. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `type: Literal["url_citation"]` - - `sequence_number: int` + The type of the URL citation. Always `url_citation`. - The sequence number of this event. + - `"url_citation"` - - `type: Literal["response.failed"]` + - `url: str` - The type of the event. Always `response.failed`. + The URL of the web resource. - - `"response.failed"` + - `class AnnotationContainerFileCitation: …` - - `agent: Optional[Agent]` + A citation for a container file used to generate a model response. - The agent that owns this multi-agent streaming event. + - `container_id: str` - - `agent_name: str` + The ID of the container file. - The canonical name of the agent that produced this item. + - `end_index: int` -### Beta Response File Search Call Completed Event + The index of the last character of the container file citation in the message. -- `class BetaResponseFileSearchCallCompletedEvent: …` + - `file_id: str` - Emitted when a file search call is completed (results found). + The ID of the file. - - `item_id: str` + - `filename: str` - The ID of the output item that the file search call is initiated. + The filename of the container file cited. - - `output_index: int` + - `start_index: int` - The index of the output item that the file search call is initiated. + The index of the first character of the container file citation in the message. - - `sequence_number: int` + - `type: Literal["container_file_citation"]` - The sequence number of this event. + The type of the container file citation. Always `container_file_citation`. - - `type: Literal["response.file_search_call.completed"]` + - `"container_file_citation"` - The type of the event. Always `response.file_search_call.completed`. + - `class AnnotationFilePath: …` - - `"response.file_search_call.completed"` + A path to a file. - - `agent: Optional[Agent]` + - `file_id: str` - The agent that owns this multi-agent streaming event. + The ID of the file. - - `agent_name: str` + - `index: int` - The canonical name of the agent that produced this item. + The index of the file in the list of files. -### Beta Response File Search Call In Progress Event + - `type: Literal["file_path"]` -- `class BetaResponseFileSearchCallInProgressEvent: …` + The type of the file path. Always `file_path`. - Emitted when a file search call is initiated. + - `"file_path"` + + - `text: str` + + The text output from the model. + + - `type: Literal["output_text"]` + + The type of the output text. Always `output_text`. + + - `"output_text"` + + - `logprobs: Optional[List[Logprob]]` - - `item_id: str` + - `token: str` - The ID of the output item that the file search call is initiated. + - `bytes: List[int]` - - `output_index: int` + - `logprob: float` - The index of the output item that the file search call is initiated. + - `top_logprobs: List[LogprobTopLogprob]` - - `sequence_number: int` + - `token: str` - The sequence number of this event. + - `bytes: List[int]` - - `type: Literal["response.file_search_call.in_progress"]` + - `logprob: float` - The type of the event. Always `response.file_search_call.in_progress`. + - `class BetaResponseOutputRefusal: …` - - `"response.file_search_call.in_progress"` + A refusal from the model. - - `agent: Optional[Agent]` + - `refusal: str` - The agent that owns this multi-agent streaming event. + The refusal explanation from the model. - - `agent_name: str` + - `type: Literal["refusal"]` - The canonical name of the agent that produced this item. + The type of the refusal. Always `refusal`. -### Beta Response File Search Call Searching Event + - `"refusal"` -- `class BetaResponseFileSearchCallSearchingEvent: …` + - `role: Literal["assistant"]` - Emitted when a file search is currently searching. + The role of the output message. Always `assistant`. - - `item_id: str` + - `"assistant"` - The ID of the output item that the file search call is initiated. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `output_index: int` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The index of the output item that the file search call is searching. + - `"in_progress"` - - `sequence_number: int` + - `"completed"` - The sequence number of this event. + - `"incomplete"` - - `type: Literal["response.file_search_call.searching"]` + - `type: Literal["message"]` - The type of the event. Always `response.file_search_call.searching`. + The type of the output message. Always `message`. - - `"response.file_search_call.searching"` + - `"message"` - `agent: Optional[Agent]` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. -### Beta Response File Search Tool Call + - `phase: Optional[Literal["commentary", "final_answer"]]` -- `class BetaResponseFileSearchToolCall: …` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `class BetaResponseFileSearchToolCall: …` The results of a file search tool call. See the [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. @@ -82340,534 +93351,497 @@ print(compacted_response) The text that was retrieved from the file. -### Beta Response Format Text Config - -- `BetaResponseFormatTextConfig` - - An object specifying the format that the model must output. - - Configuring `{ "type": "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). - - The default format is `{ "type": "text" }` with no additional options. - - **Not recommended for gpt-4o and newer models:** - - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. - - - `class Text: …` - - Default response format. Used to generate text responses. - - - `type: Literal["text"]` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `class BetaResponseFormatTextJSONSchemaConfig: …` - - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - - `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. + - `class BetaResponseComputerToolCall: …` - - `schema: Dict[str, object]` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `id: str` - - `type: Literal["json_schema"]` + The unique ID of the computer call. - The type of response format being defined. Always `json_schema`. + - `call_id: str` - - `"json_schema"` + An identifier used when responding to the tool call with output. - - `description: Optional[str]` + - `pending_safety_checks: List[PendingSafetyCheck]` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The pending safety checks for the computer call. - - `strict: Optional[bool]` + - `id: str` - 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). + The ID of the pending safety check. - - `class JSONObject: …` + - `code: Optional[str]` - 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. + The type of the pending safety check. - - `type: Literal["json_object"]` + - `message: Optional[str]` - The type of response format being defined. Always `json_object`. + Details about the pending safety check. - - `"json_object"` + - `status: Literal["in_progress", "completed", "incomplete"]` -### Beta Response Format Text JSON Schema Config + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -- `class BetaResponseFormatTextJSONSchemaConfig: …` + - `"in_progress"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"completed"` - - `name: str` + - `"incomplete"` - 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. + - `type: Literal["computer_call"]` - - `schema: Dict[str, object]` + The type of the computer call. Always `computer_call`. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"computer_call"` - - `type: Literal["json_schema"]` + - `action: Optional[BetaComputerAction]` - The type of response format being defined. Always `json_schema`. + A click action. - - `"json_schema"` + - `class Click: …` - - `description: Optional[str]` + A click action. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `button: Literal["left", "right", "wheel", 2 more]` - - `strict: Optional[bool]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - 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). + - `"left"` -### Beta Response Function Call Arguments Delta Event + - `"right"` -- `class BetaResponseFunctionCallArgumentsDeltaEvent: …` + - `"wheel"` - Emitted when there is a partial function-call arguments delta. + - `"back"` - - `delta: str` + - `"forward"` - The function-call arguments delta that is added. + - `type: Literal["click"]` - - `item_id: str` + Specifies the event type. For a click action, this property is always `click`. - The ID of the output item that the function-call arguments delta is added to. + - `"click"` - - `output_index: int` + - `x: int` - The index of the output item that the function-call arguments delta is added to. + The x-coordinate where the click occurred. - - `sequence_number: int` + - `y: int` - The sequence number of this event. + The y-coordinate where the click occurred. - - `type: Literal["response.function_call_arguments.delta"]` + - `keys: Optional[List[str]]` - The type of the event. Always `response.function_call_arguments.delta`. + The keys being held while clicking. - - `"response.function_call_arguments.delta"` + - `class DoubleClick: …` - - `agent: Optional[Agent]` + A double click action. - The agent that owns this multi-agent streaming event. + - `keys: Optional[List[str]]` - - `agent_name: str` + The keys being held while double-clicking. - The canonical name of the agent that produced this item. + - `type: Literal["double_click"]` -### Beta Response Function Call Arguments Done Event + Specifies the event type. For a double click action, this property is always set to `double_click`. -- `class BetaResponseFunctionCallArgumentsDoneEvent: …` + - `"double_click"` - Emitted when function-call arguments are finalized. + - `x: int` - - `arguments: str` + The x-coordinate where the double click occurred. - The function-call arguments. + - `y: int` - - `item_id: str` + The y-coordinate where the double click occurred. - The ID of the item. + - `class Drag: …` - - `name: str` + A drag action. - The name of the function that was called. + - `path: List[DragPath]` - - `output_index: int` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The index of the output item. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `sequence_number: int` + - `x: int` - The sequence number of this event. + The x-coordinate. - - `type: Literal["response.function_call_arguments.done"]` + - `y: int` - - `"response.function_call_arguments.done"` + The y-coordinate. - - `agent: Optional[Agent]` + - `type: Literal["drag"]` - The agent that owns this multi-agent streaming event. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `agent_name: str` + - `"drag"` - The canonical name of the agent that produced this item. + - `keys: Optional[List[str]]` -### Beta Response Function Call Output Item + The keys being held while dragging the mouse. -- `BetaResponseFunctionCallOutputItem` + - `class Keypress: …` - A piece of message content, such as text, an image, or a file. + A collection of keypresses the model would like to perform. - - `class BetaResponseInputTextContent: …` + - `keys: List[str]` - A text input to the model. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `text: str` + - `type: Literal["keypress"]` - The text input to the model. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `type: Literal["input_text"]` + - `"keypress"` - The type of the input item. Always `input_text`. + - `class Move: …` - - `"input_text"` + A mouse move action. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["move"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Specifies the event type. For a move action, this property is always set to `move`. - - `mode: Literal["explicit"]` + - `"move"` - The breakpoint mode. Always `explicit`. + - `x: int` - - `"explicit"` + The x-coordinate to move to. - - `class BetaResponseInputImageContent: …` + - `y: int` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The y-coordinate to move to. - - `type: Literal["input_image"]` + - `keys: Optional[List[str]]` - The type of the input item. Always `input_image`. + The keys being held while moving the mouse. - - `"input_image"` + - `class Screenshot: …` - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + A screenshot action. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: Literal["screenshot"]` - - `"low"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"high"` + - `"screenshot"` - - `"auto"` + - `class Scroll: …` - - `"original"` + A scroll action. - - `file_id: Optional[str]` + - `scroll_x: int` - The ID of the file to be sent to the model. + The horizontal scroll distance. - - `image_url: Optional[str]` + - `scroll_y: int` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The vertical scroll distance. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["scroll"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `mode: Literal["explicit"]` + - `"scroll"` - The breakpoint mode. Always `explicit`. + - `x: int` - - `"explicit"` + The x-coordinate where the scroll occurred. - - `class BetaResponseInputFileContent: …` + - `y: int` - A file input to the model. + The y-coordinate where the scroll occurred. - - `type: Literal["input_file"]` + - `keys: Optional[List[str]]` - The type of the input item. Always `input_file`. + The keys being held while scrolling. - - `"input_file"` + - `class Type: …` - - `detail: Optional[Literal["auto", "low", "high"]]` + An action to type in text. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `text: str` - - `"auto"` + The text to type. - - `"low"` + - `type: Literal["type"]` - - `"high"` + Specifies the event type. For a type action, this property is always set to `type`. - - `file_data: Optional[str]` + - `"type"` - The base64-encoded data of the file to be sent to the model. + - `class Wait: …` - - `file_id: Optional[str]` + A wait action. - The ID of the file to be sent to the model. + - `type: Literal["wait"]` - - `file_url: Optional[str]` + Specifies the event type. For a wait action, this property is always set to `wait`. - The URL of the file to be sent to the model. + - `"wait"` - - `filename: Optional[str]` + - `actions: Optional[BetaComputerActionList]` - The name of the file to be sent to the model. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `class Click: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A click action. - - `mode: Literal["explicit"]` + - `class DoubleClick: …` - The breakpoint mode. Always `explicit`. + A double click action. - - `"explicit"` + - `class Drag: …` -### Beta Response Function Call Output Item List + A drag action. -- `List[BetaResponseFunctionCallOutputItem]` + - `class Keypress: …` - An array of content outputs (text, image, file) for the function tool call. + A collection of keypresses the model would like to perform. - - `class BetaResponseInputTextContent: …` + - `class Move: …` - A text input to the model. + A mouse move action. - - `text: str` + - `class Screenshot: …` - The text input to the model. + A screenshot action. - - `type: Literal["input_text"]` + - `class Scroll: …` - The type of the input item. Always `input_text`. + A scroll action. - - `"input_text"` + - `class Type: …` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + An action to type in text. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class Wait: …` - - `mode: Literal["explicit"]` + A wait action. - The breakpoint mode. Always `explicit`. + - `agent: Optional[Agent]` - - `"explicit"` + The agent that produced this item. - - `class BetaResponseInputImageContent: …` + - `agent_name: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The canonical name of the agent that produced this item. - - `type: Literal["input_image"]` + - `class ComputerCallOutput: …` - The type of the input item. Always `input_image`. + The output of a computer tool call. - - `"input_image"` + - `call_id: str` - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + The ID of the computer tool call that produced the output. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `"low"` + A computer screenshot image used with the computer use tool. - - `"high"` + - `type: Literal["computer_screenshot"]` - - `"auto"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `"original"` + - `"computer_screenshot"` - `file_id: Optional[str]` - The ID of the file to be sent to the model. + The identifier of an uploaded file that contains the screenshot. - `image_url: Optional[str]` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The URL of the screenshot image. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["computer_call_output"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The type of the computer tool call output. Always `computer_call_output`. - - `mode: Literal["explicit"]` + - `"computer_call_output"` - The breakpoint mode. Always `explicit`. + - `id: Optional[str]` - - `"explicit"` + The ID of the computer tool call output. - - `class BetaResponseInputFileContent: …` + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - A file input to the model. + The safety checks reported by the API that have been acknowledged by the developer. - - `type: Literal["input_file"]` + - `id: str` - The type of the input item. Always `input_file`. + The ID of the pending safety check. - - `"input_file"` + - `code: Optional[str]` - - `detail: Optional[Literal["auto", "low", "high"]]` + The type of the pending safety check. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `message: Optional[str]` - - `"auto"` + Details about the pending safety check. - - `"low"` + - `agent: Optional[ComputerCallOutputAgent]` - - `"high"` + The agent that produced this item. - - `file_data: Optional[str]` + - `agent_name: str` - The base64-encoded data of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `file_id: Optional[str]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The ID of the file to be sent to the model. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `file_url: Optional[str]` + - `"in_progress"` - The URL of the file to be sent to the model. + - `"completed"` - - `filename: Optional[str]` + - `"incomplete"` - The name of the file to be sent to the model. + - `class BetaResponseFunctionWebSearch: …` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `id: str` - - `mode: Literal["explicit"]` + The unique ID of the web search tool call. - The breakpoint mode. Always `explicit`. + - `action: Action` - - `"explicit"` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). -### Beta Response Function Shell Call Output Content + - `class ActionSearch: …` -- `class BetaResponseFunctionShellCallOutputContent: …` + Action type "search" - Performs a web search query. - Captured stdout and stderr for a portion of a shell tool call output. + - `type: Literal["search"]` - - `outcome: Outcome` + The action type. - The exit or timeout outcome associated with this shell call. + - `"search"` - - `class OutcomeTimeout: …` + - `queries: Optional[List[str]]` - Indicates that the shell call exceeded its configured time limit. + The search queries. - - `type: Literal["timeout"]` + - `query: Optional[str]` - The outcome type. Always `timeout`. + The search query. - - `"timeout"` + - `sources: Optional[List[ActionSearchSource]]` - - `class OutcomeExit: …` + The sources used in the search. - Indicates that the shell commands finished and returned an exit code. + - `type: Literal["url"]` - - `exit_code: int` + The type of source. Always `url`. - The exit code returned by the shell process. + - `"url"` - - `type: Literal["exit"]` + - `url: str` - The outcome type. Always `exit`. + The URL of the source. - - `"exit"` + - `class ActionOpenPage: …` - - `stderr: str` + Action type "open_page" - Opens a specific URL from search results. - Captured stderr output for the shell call. + - `type: Literal["open_page"]` - - `stdout: str` + The action type. - Captured stdout output for the shell call. + - `"open_page"` -### Beta Response Function Shell Tool Call + - `url: Optional[str]` -- `class BetaResponseFunctionShellToolCall: …` + The URL opened by the model. - A tool call that executes one or more shell commands in a managed environment. + - `class ActionFindInPage: …` - - `id: str` + Action type "find_in_page": Searches for a pattern within a loaded page. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `pattern: str` - - `action: Action` + The pattern or text to search for within the page. - The shell commands and limits that describe how to run the tool call. + - `type: Literal["find_in_page"]` - - `commands: List[str]` + The action type. - - `max_output_length: Optional[int]` + - `"find_in_page"` - Optional maximum number of characters to return from each command. + - `url: str` - - `timeout_ms: Optional[int]` + The URL of the page searched for the pattern. - Optional timeout in milliseconds for the commands. + - `status: Literal["in_progress", "searching", "completed", "failed"]` - - `call_id: str` + The status of the web search tool call. - The unique ID of the shell tool call generated by the model. + - `"in_progress"` - - `environment: Optional[Environment]` + - `"searching"` - Represents the use of a local environment to perform shell actions. + - `"completed"` - - `class BetaResponseLocalEnvironment: …` + - `"failed"` - Represents the use of a local environment to perform shell actions. + - `type: Literal["web_search_call"]` - - `type: Literal["local"]` + The type of the web search tool call. Always `web_search_call`. - The environment type. Always `local`. + - `"web_search_call"` - - `"local"` + - `agent: Optional[Agent]` - - `class BetaResponseContainerReference: …` + The agent that produced this item. - Represents a container created with /v1/containers. + - `agent_name: str` - - `container_id: str` + The canonical name of the agent that produced this item. - - `type: Literal["container_reference"]` + - `class BetaResponseFunctionToolCall: …` - The environment type. Always `container_reference`. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `"container_reference"` + - `arguments: str` - - `status: Literal["in_progress", "completed", "incomplete"]` + A JSON string of the arguments to pass to the function. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `call_id: str` - - `"in_progress"` + The unique ID of the function tool call generated by the model. - - `"completed"` + - `name: str` - - `"incomplete"` + The name of the function to run. - - `type: Literal["shell_call"]` + - `type: Literal["function_call"]` - The type of the item. Always `shell_call`. + The type of the function tool call. Always `function_call`. - - `"shell_call"` + - `"function_call"` + + - `id: Optional[str]` + + The unique ID of the function tool call. - `agent: Optional[Agent]` @@ -82897,150 +93871,160 @@ print(compacted_response) - `"program"` - - `created_by: Optional[str]` + - `namespace: Optional[str]` - The ID of the entity that created this tool call. + The namespace of the function to run. -### Beta Response Function Shell Tool Call Output + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` -- `class BetaResponseFunctionShellToolCallOutput: …` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The output of a shell tool call that was emitted. + - `"in_progress"` - - `id: str` + - `"completed"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `"incomplete"` + + - `class FunctionCallOutput: …` + + The output of a function tool call. - `call_id: str` - The unique ID of the shell tool call generated by the model. + The unique ID of the function tool call generated by the model. - - `max_output_length: Optional[int]` + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + Text, image, or file output of the function tool call. - - `output: List[Output]` + - `str` - An array of shell call output contents + A JSON string of the output of the function tool call. - - `outcome: OutputOutcome` + - `List[BetaResponseFunctionCallOutputItem]` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `class BetaResponseInputTextContent: …` - - `class OutputOutcomeTimeout: …` + A text input to the model. - Indicates that the shell call exceeded its configured time limit. + - `text: str` - - `type: Literal["timeout"]` + The text input to the model. - The outcome type. Always `timeout`. + - `type: Literal["input_text"]` - - `"timeout"` + The type of the input item. Always `input_text`. - - `class OutputOutcomeExit: …` + - `"input_text"` - Indicates that the shell commands finished and returned an exit code. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `exit_code: int` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Exit code from the shell process. + - `mode: Literal["explicit"]` - - `type: Literal["exit"]` + The breakpoint mode. Always `explicit`. - The outcome type. Always `exit`. + - `"explicit"` - - `"exit"` + - `class BetaResponseInputImageContent: …` - - `stderr: str` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The standard error output that was captured. + - `type: Literal["input_image"]` - - `stdout: str` + The type of the input item. Always `input_image`. - The standard output that was captured. + - `"input_image"` - - `created_by: Optional[str]` + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - The identifier of the actor that created the item. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"low"` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `"high"` - - `"in_progress"` + - `"auto"` - - `"completed"` + - `"original"` - - `"incomplete"` + - `file_id: Optional[str]` - - `type: Literal["shell_call_output"]` + The ID of the file to be sent to the model. - The type of the shell call output. Always `shell_call_output`. + - `image_url: Optional[str]` - - `"shell_call_output"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `agent: Optional[Agent]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The agent that produced this item. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `agent_name: str` + - `mode: Literal["explicit"]` - The canonical name of the agent that produced this item. + The breakpoint mode. Always `explicit`. - - `caller: Optional[Caller]` + - `"explicit"` - The execution context that produced this tool call. + - `class BetaResponseInputFileContent: …` - - `class CallerDirect: …` + A file input to the model. - - `type: Literal["direct"]` + - `type: Literal["input_file"]` - - `"direct"` + The type of the input item. Always `input_file`. - - `class CallerProgram: …` + - `"input_file"` - - `caller_id: str` + - `detail: Optional[Literal["auto", "low", "high"]]` - The call ID of the program item that produced this tool call. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `type: Literal["program"]` + - `"auto"` - - `"program"` + - `"low"` - - `created_by: Optional[str]` + - `"high"` - The identifier of the actor that created the item. + - `file_data: Optional[str]` -### Beta Response Function Tool Call + The base64-encoded data of the file to be sent to the model. -- `class BetaResponseFunctionToolCall: …` + - `file_id: Optional[str]` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The ID of the file to be sent to the model. - - `arguments: str` + - `file_url: Optional[str]` - A JSON string of the arguments to pass to the function. + The URL of the file to be sent to the model. - - `call_id: str` + - `filename: Optional[str]` - The unique ID of the function tool call generated by the model. + The name of the file to be sent to the model. - - `name: str` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The name of the function to run. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `type: Literal["function_call"]` + - `mode: Literal["explicit"]` - The type of the function tool call. Always `function_call`. + The breakpoint mode. Always `explicit`. - - `"function_call"` + - `"explicit"` + + - `type: Literal["function_call_output"]` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` - `id: Optional[str]` - The unique ID of the function tool call. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `agent: Optional[Agent]` + - `agent: Optional[FunctionCallOutputAgent]` The agent that produced this item. @@ -83048,17 +94032,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[FunctionCallOutputCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class FunctionCallOutputCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class FunctionCallOutputCallerProgram: …` - `caller_id: str` @@ -83066,16 +94052,13 @@ print(compacted_response) - `type: Literal["program"]` - - `"program"` - - - `namespace: Optional[str]` + The caller type. Always `program`. - The namespace of the function to run. + - `"program"` - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -83083,185 +94066,229 @@ print(compacted_response) - `"incomplete"` -### Beta Response Function Tool Call Item + - `class AgentMessage: …` -- `class BetaResponseFunctionToolCallItem: …` + A message routed between agents. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `author: str` - - `id: str` + The sending agent identity. - The unique ID of the function tool call. + - `content: List[AgentMessageContent]` - - `status: Literal["in_progress", "completed", "incomplete"]` + Plaintext, image, or encrypted content sent between agents. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class BetaResponseInputTextContent: …` - - `"in_progress"` + A text input to the model. - - `"completed"` + - `class BetaResponseInputImageContent: …` - - `"incomplete"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `created_by: Optional[str]` + - `class AgentMessageContentEncryptedContent: …` - The identifier of the actor that created the item. + Opaque encrypted content that Responses API decrypts inside trusted model execution. -### Beta Response Function Tool Call Output Item + - `encrypted_content: str` -- `class BetaResponseFunctionToolCallOutputItem: …` + Opaque encrypted content. - - `id: str` + - `type: Literal["encrypted_content"]` - The unique ID of the function call tool output. + The type of the input item. Always `encrypted_content`. + + - `"encrypted_content"` + + - `recipient: str` + + The destination agent identity. + + - `type: Literal["agent_message"]` + + The item type. Always `agent_message`. + + - `"agent_message"` + + - `id: Optional[str]` + + The unique ID of this agent message item. + + - `agent: Optional[AgentMessageAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCall: …` + + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + + The multi-agent action that was executed. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: str` + + The action arguments as a JSON string. - `call_id: str` - The unique ID of the function tool call generated by the model. + The unique ID linking this call to its output. - - `output: Union[str, List[OutputOutputContentList]]` + - `type: Literal["multi_agent_call"]` - The output from the function call generated by your code. - Can be a string or an list of output content. + The item type. Always `multi_agent_call`. - - `str` + - `"multi_agent_call"` - A string of the output of the function call. + - `id: Optional[str]` - - `List[OutputOutputContentList]` + The unique ID of this multi-agent call. - Text, image, or file output of the function call. + - `agent: Optional[MultiAgentCallAgent]` - - `class BetaResponseInputText: …` + The agent that produced this item. - A text input to the model. + - `agent_name: str` - - `text: str` + The canonical name of the agent that produced this item. - The text input to the model. + - `class MultiAgentCallOutput: …` - - `type: Literal["input_text"]` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - The type of the input item. Always `input_text`. + The multi-agent action that produced this result. - - `"input_text"` + - `"spawn_agent"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"interrupt_agent"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"list_agents"` - - `mode: Literal["explicit"]` + - `"send_message"` - The breakpoint mode. Always `explicit`. + - `"followup_task"` - - `"explicit"` + - `"wait_agent"` - - `class BetaResponseInputImage: …` + - `call_id: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The unique ID of the multi-agent call. - - `detail: Literal["low", "high", "auto", "original"]` + - `output: List[MultiAgentCallOutputOutput]` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Text output returned by the multi-agent action. - - `"low"` + - `text: str` - - `"high"` + The text content. - - `"auto"` + - `type: Literal["output_text"]` - - `"original"` + The content type. Always `output_text`. - - `type: Literal["input_image"]` + - `"output_text"` - The type of the input item. Always `input_image`. + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - - `"input_image"` + Citations associated with the text content. - - `file_id: Optional[str]` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - The ID of the file to be sent to the model. + - `file_id: str` - - `image_url: Optional[str]` + The ID of the file. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `filename: str` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The filename of the file cited. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `index: int` - - `mode: Literal["explicit"]` + The index of the file in the list of files. - The breakpoint mode. Always `explicit`. + - `type: Literal["file_citation"]` - - `"explicit"` + The citation type. Always `file_citation`. - - `class BetaResponseInputFile: …` + - `"file_citation"` - A file input to the model. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` - - `type: Literal["input_file"]` + - `end_index: int` - The type of the input item. Always `input_file`. + The index of the last character of the citation in the message. - - `"input_file"` + - `start_index: int` - - `detail: Optional[Literal["auto", "low", "high"]]` + The index of the first character of the citation in the message. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `title: str` - - `"auto"` + The title of the cited resource. - - `"low"` + - `type: Literal["url_citation"]` - - `"high"` + The citation type. Always `url_citation`. - - `file_data: Optional[str]` + - `"url_citation"` - The content of the file to be sent to the model. + - `url: str` - - `file_id: Optional[str]` + The URL of the cited resource. - The ID of the file to be sent to the model. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` - - `file_url: Optional[str]` + - `container_id: str` - The URL of the file to be sent to the model. + The ID of the container. - - `filename: Optional[str]` + - `end_index: int` - The name of the file to be sent to the model. + The index of the last character of the citation in the message. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `file_id: str` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The ID of the container file. - - `mode: Literal["explicit"]` + - `filename: str` - The breakpoint mode. Always `explicit`. + The filename of the container file cited. - - `"explicit"` + - `start_index: int` - - `status: Literal["in_progress", "completed", "incomplete"]` + The index of the first character of the citation in the message. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: Literal["container_file_citation"]` - - `"in_progress"` + The citation type. Always `container_file_citation`. - - `"completed"` + - `"container_file_citation"` - - `"incomplete"` + - `type: Literal["multi_agent_call_output"]` - - `type: Literal["function_call_output"]` + The item type. Always `multi_agent_call_output`. - The type of the function tool call output. Always `function_call_output`. + - `"multi_agent_call_output"` - - `"function_call_output"` + - `id: Optional[str]` - - `agent: Optional[Agent]` + The unique ID of this multi-agent call output. + + - `agent: Optional[MultiAgentCallOutputAgent]` The agent that produced this item. @@ -83269,1140 +94296,1161 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `class ToolSearchCall: …` - The execution context that produced this tool call. + - `arguments: object` - - `class CallerDirect: …` + The arguments supplied to the tool search call. - - `type: Literal["direct"]` + - `type: Literal["tool_search_call"]` - The caller type. Always `direct`. + The item type. Always `tool_search_call`. - - `"direct"` + - `"tool_search_call"` - - `class CallerProgram: …` + - `id: Optional[str]` - - `caller_id: str` + The unique ID of this tool search call. - The call ID of the program item that produced this tool call. + - `agent: Optional[ToolSearchCallAgent]` - - `type: Literal["program"]` + The agent that produced this item. - The caller type. Always `program`. + - `agent_name: str` + + The canonical name of the agent that produced this item. - - `"program"` + - `call_id: Optional[str]` - - `created_by: Optional[str]` + The unique ID of the tool search call generated by the model. - The identifier of the actor that created the item. + - `execution: Optional[Literal["server", "client"]]` -### Beta Response Function Web Search + Whether tool search was executed by the server or by the client. -- `class BetaResponseFunctionWebSearch: …` + - `"server"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `"client"` - - `id: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The unique ID of the web search tool call. + The status of the tool search call. - - `action: Action` + - `"in_progress"` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `"completed"` - - `class ActionSearch: …` + - `"incomplete"` - Action type "search" - Performs a web search query. + - `class BetaResponseToolSearchOutputItemParam: …` - - `type: Literal["search"]` + - `tools: List[BetaTool]` - The action type. + The loaded tool definitions returned by the tool search output. - - `"search"` + - `class BetaFunctionTool: …` - - `queries: Optional[List[str]]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The search queries. + - `name: str` - - `query: Optional[str]` + The name of the function to call. - The search query. + - `parameters: Optional[Dict[str, object]]` - - `sources: Optional[List[ActionSearchSource]]` + A JSON schema object describing the parameters of the function. - The sources used in the search. + - `strict: Optional[bool]` - - `type: Literal["url"]` + Whether strict parameter validation is enforced for this function tool. - The type of source. Always `url`. + - `type: Literal["function"]` - - `"url"` + The type of the function tool. Always `function`. - - `url: str` + - `"function"` - The URL of the source. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `class ActionOpenPage: …` + The tool invocation context(s). - Action type "open_page" - Opens a specific URL from search results. + - `"direct"` - - `type: Literal["open_page"]` + - `"programmatic"` - The action type. + - `defer_loading: Optional[bool]` - - `"open_page"` + Whether this function is deferred and loaded via tool search. - - `url: Optional[str]` + - `description: Optional[str]` - The URL opened by the model. + A description of the function. Used by the model to determine whether or not to call the function. - - `class ActionFindInPage: …` + - `output_schema: Optional[Dict[str, object]]` - Action type "find_in_page": Searches for a pattern within a loaded page. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `pattern: str` + - `class BetaFileSearchTool: …` - The pattern or text to search for within the page. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: Literal["find_in_page"]` + - `type: Literal["file_search"]` - The action type. + The type of the file search tool. Always `file_search`. - - `"find_in_page"` + - `"file_search"` - - `url: str` + - `vector_store_ids: List[str]` - The URL of the page searched for the pattern. + The IDs of the vector stores to search. - - `status: Literal["in_progress", "searching", "completed", "failed"]` + - `filters: Optional[Filters]` - The status of the web search tool call. + A filter to apply. - - `"in_progress"` + - `class FiltersComparisonFilter: …` - - `"searching"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"completed"` + - `key: str` - - `"failed"` + The key to compare against the value. - - `type: Literal["web_search_call"]` + - `type: Literal["eq", "ne", "gt", 5 more]` - The type of the web search tool call. Always `web_search_call`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"web_search_call"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `agent: Optional[Agent]` + - `"eq"` - The agent that produced this item. + - `"ne"` - - `agent_name: str` + - `"gt"` - The canonical name of the agent that produced this item. + - `"gte"` -### Beta Response Image Gen Call Completed Event + - `"lt"` -- `class BetaResponseImageGenCallCompletedEvent: …` + - `"lte"` - Emitted when an image generation tool call has completed and the final image is available. + - `"in"` - - `item_id: str` + - `"nin"` - The unique identifier of the image generation item being processed. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `output_index: int` + The value to compare against the attribute key; supports string, number, or boolean types. - The index of the output item in the response's output array. + - `str` - - `sequence_number: int` + - `float` - The sequence number of this event. + - `bool` - - `type: Literal["response.image_generation_call.completed"]` + - `List[Union[str, float]]` - The type of the event. Always 'response.image_generation_call.completed'. + - `str` - - `"response.image_generation_call.completed"` + - `float` - - `agent: Optional[Agent]` + - `class FiltersCompoundFilter: …` - The agent that owns this multi-agent streaming event. + Combine multiple filters using `and` or `or`. - - `agent_name: str` + - `filters: List[FiltersCompoundFilterFilter]` - The canonical name of the agent that produced this item. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. -### Beta Response Image Gen Call Generating Event + - `class FiltersCompoundFilterFilterComparisonFilter: …` -- `class BetaResponseImageGenCallGeneratingEvent: …` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Emitted when an image generation tool call is actively generating an image (intermediate state). + - `key: str` - - `item_id: str` + The key to compare against the value. - The unique identifier of the image generation item being processed. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `output_index: int` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The index of the output item in the response's output array. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `sequence_number: int` + - `"eq"` - The sequence number of the image generation item being processed. + - `"ne"` - - `type: Literal["response.image_generation_call.generating"]` + - `"gt"` - The type of the event. Always 'response.image_generation_call.generating'. + - `"gte"` - - `"response.image_generation_call.generating"` + - `"lt"` - - `agent: Optional[Agent]` + - `"lte"` - The agent that owns this multi-agent streaming event. + - `"in"` - - `agent_name: str` + - `"nin"` - The canonical name of the agent that produced this item. + - `value: Union[str, float, bool, List[Union[str, float]]]` -### Beta Response Image Gen Call In Progress Event + The value to compare against the attribute key; supports string, number, or boolean types. -- `class BetaResponseImageGenCallInProgressEvent: …` + - `str` - Emitted when an image generation tool call is in progress. + - `float` - - `item_id: str` + - `bool` - The unique identifier of the image generation item being processed. + - `List[Union[str, float]]` - - `output_index: int` + - `str` - The index of the output item in the response's output array. + - `float` - - `sequence_number: int` + - `object` - The sequence number of the image generation item being processed. + - `type: Literal["and", "or"]` - - `type: Literal["response.image_generation_call.in_progress"]` + Type of operation: `and` or `or`. - The type of the event. Always 'response.image_generation_call.in_progress'. + - `"and"` - - `"response.image_generation_call.in_progress"` + - `"or"` - - `agent: Optional[Agent]` + - `max_num_results: Optional[int]` - The agent that owns this multi-agent streaming event. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `agent_name: str` + - `ranking_options: Optional[RankingOptions]` - The canonical name of the agent that produced this item. + Ranking options for search. -### Beta Response Image Gen Call Partial Image Event + - `hybrid_search: Optional[RankingOptionsHybridSearch]` -- `class BetaResponseImageGenCallPartialImageEvent: …` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - Emitted when a partial image is available during image generation streaming. + - `embedding_weight: float` - - `item_id: str` + The weight of the embedding in the reciprocal ranking fusion. - The unique identifier of the image generation item being processed. + - `text_weight: float` - - `output_index: int` + The weight of the text in the reciprocal ranking fusion. - The index of the output item in the response's output array. + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - - `partial_image_b64: str` + The ranker to use for the file search. - Base64-encoded partial image data, suitable for rendering as an image. + - `"auto"` - - `partial_image_index: int` + - `"default-2024-11-15"` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + - `score_threshold: Optional[float]` - - `sequence_number: int` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The sequence number of the image generation item being processed. + - `class BetaComputerTool: …` - - `type: Literal["response.image_generation_call.partial_image"]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the event. Always 'response.image_generation_call.partial_image'. + - `type: Literal["computer"]` - - `"response.image_generation_call.partial_image"` + The type of the computer tool. Always `computer`. - - `agent: Optional[Agent]` + - `"computer"` - The agent that owns this multi-agent streaming event. + - `class BetaComputerUsePreviewTool: …` - - `agent_name: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The canonical name of the agent that produced this item. + - `display_height: int` -### Beta Response In Progress Event + The height of the computer display. -- `class BetaResponseInProgressEvent: …` + - `display_width: int` - Emitted when the response is in progress. + The width of the computer display. - - `response: BetaResponse` + - `environment: Literal["windows", "mac", "linux", 2 more]` - The response that is in progress. + The type of computer environment to control. - - `id: str` + - `"windows"` - Unique identifier for this Response. + - `"mac"` - - `created_at: float` + - `"linux"` - Unix timestamp (in seconds) of when this Response was created. + - `"ubuntu"` - - `error: Optional[BetaResponseError]` + - `"browser"` - An error object returned when the model fails to generate a Response. + - `type: Literal["computer_use_preview"]` - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + The type of the computer use tool. Always `computer_use_preview`. - The error code for the response. + - `"computer_use_preview"` - - `"server_error"` + - `class BetaWebSearchTool: …` - - `"rate_limit_exceeded"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"invalid_prompt"` + - `type: Literal["web_search", "web_search_2025_08_26"]` - - `"bio_policy"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"vector_store_timeout"` + - `"web_search"` - - `"invalid_image"` + - `"web_search_2025_08_26"` - - `"invalid_image_format"` + - `filters: Optional[Filters]` - - `"invalid_base64_image"` + Filters for the search. - - `"invalid_image_url"` + - `allowed_domains: Optional[List[str]]` - - `"image_too_large"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `"image_too_small"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"image_parse_error"` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `"image_content_policy_violation"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `"invalid_image_mode"` + - `"low"` - - `"image_file_too_large"` + - `"medium"` - - `"unsupported_image_media_type"` + - `"high"` - - `"empty_image_file"` + - `user_location: Optional[UserLocation]` - - `"failed_to_download_image"` + The approximate location of the user. - - `"image_file_not_found"` + - `city: Optional[str]` - - `message: str` + Free text input for the city of the user, e.g. `San Francisco`. - A human-readable description of the error. + - `country: Optional[str]` - - `incomplete_details: Optional[IncompleteDetails]` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Details about why the response is incomplete. + - `region: Optional[str]` - - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` + Free text input for the region of the user, e.g. `California`. - The reason why the response is incomplete. + - `timezone: Optional[str]` - - `"max_output_tokens"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"content_filter"` + - `type: Optional[Literal["approximate"]]` - - `instructions: Union[str, List[BetaResponseInputItem], null]` + The type of location approximation. Always `approximate`. - A system (or developer) message inserted into the model's context. + - `"approximate"` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `class Mcp: …` - - `str` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - A text input to the model, equivalent to a text input with the - `developer` role. + - `server_label: str` - - `List[BetaResponseInputItem]` + A label for this MCP server, used to identify it in tool calls. - A list of one or many input items to the model, containing - different content types. + - `type: Literal["mcp"]` - - `class BetaEasyInputMessage: …` + The type of the MCP tool. Always `mcp`. - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `"mcp"` - - `content: Union[str, BetaResponseInputMessageContentList]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The tool invocation context(s). - - `str` + - `"direct"` - A text input to the model. + - `"programmatic"` - - `List[BetaResponseInputContent]` + - `allowed_tools: Optional[McpAllowedTools]` - - `class BetaResponseInputText: …` + List of allowed tool names or a filter object. - A text input to the model. + - `List[str]` - - `text: str` + A string array of allowed tool names - The text input to the model. + - `class McpAllowedToolsMcpToolFilter: …` - - `type: Literal["input_text"]` + A filter object to specify which tools are allowed. - The type of the input item. Always `input_text`. + - `read_only: Optional[bool]` - - `"input_text"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `tool_names: Optional[List[str]]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + List of allowed tool names. - - `mode: Literal["explicit"]` + - `authorization: Optional[str]` - The breakpoint mode. Always `explicit`. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `"explicit"` + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `class BetaResponseInputImage: …` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Currently supported `connector_id` values are: - - `detail: Literal["low", "high", "auto", "original"]` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"connector_dropbox"` - - `"low"` + - `"connector_gmail"` - - `"high"` + - `"connector_googlecalendar"` - - `"auto"` + - `"connector_googledrive"` - - `"original"` + - `"connector_microsoftteams"` - - `type: Literal["input_image"]` + - `"connector_outlookcalendar"` - The type of the input item. Always `input_image`. + - `"connector_outlookemail"` - - `"input_image"` + - `"connector_sharepoint"` - - `file_id: Optional[str]` + - `defer_loading: Optional[bool]` - The ID of the file to be sent to the model. + Whether this MCP tool is deferred and discovered via tool search. - - `image_url: Optional[str]` + - `headers: Optional[Dict[str, str]]` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `require_approval: Optional[McpRequireApproval]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Specify which of the MCP server's tools require approval. - - `mode: Literal["explicit"]` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - The breakpoint mode. Always `explicit`. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"explicit"` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `class BetaResponseInputFile: …` + A filter object to specify which tools are allowed. - A file input to the model. + - `read_only: Optional[bool]` - - `type: Literal["input_file"]` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The type of the input item. Always `input_file`. + - `tool_names: Optional[List[str]]` - - `"input_file"` + List of allowed tool names. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + A filter object to specify which tools are allowed. - - `"auto"` + - `read_only: Optional[bool]` - - `"low"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"high"` + - `tool_names: Optional[List[str]]` - - `file_data: Optional[str]` + List of allowed tool names. - The content of the file to be sent to the model. + - `Literal["always", "never"]` - - `file_id: Optional[str]` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - The ID of the file to be sent to the model. + - `"always"` - - `file_url: Optional[str]` + - `"never"` - The URL of the file to be sent to the model. + - `server_description: Optional[str]` - - `filename: Optional[str]` + Optional description of the MCP server, used to provide more context. - The name of the file to be sent to the model. + - `server_url: Optional[str]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `tunnel_id: Optional[str]` - - `mode: Literal["explicit"]` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The breakpoint mode. Always `explicit`. + - `class CodeInterpreter: …` - - `"explicit"` + A tool that runs Python code to help generate a response to a prompt. - - `role: Literal["user", "assistant", "system", "developer"]` + - `container: CodeInterpreterContainer` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `"user"` + - `str` - - `"assistant"` + The container ID. - - `"system"` + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `"developer"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `phase: Optional[Literal["commentary"]]` + - `type: Literal["auto"]` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + Always `auto`. - - `"commentary"` + - `"auto"` - - `type: Optional[Literal["message"]]` + - `file_ids: Optional[List[str]]` - The type of the message input. Always `message`. + An optional list of uploaded files to make available to your code. - - `"message"` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `class Message: …` + The memory limit for the code interpreter container. - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + - `"1g"` - - `content: BetaResponseInputMessageContentList` + - `"4g"` - A list of one or many input items to the model, containing different content - types. + - `"16g"` - - `class BetaResponseInputText: …` + - `"64g"` - A text input to the model. + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - - `class BetaResponseInputImage: …` + Network access policy for the container. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class BetaContainerNetworkPolicyDisabled: …` - - `class BetaResponseInputFile: …` + - `type: Literal["disabled"]` - A file input to the model. + Disable outbound network access. Always `disabled`. - - `role: Literal["user", "system", "developer"]` + - `"disabled"` - The role of the message input. One of `user`, `system`, or `developer`. + - `class BetaContainerNetworkPolicyAllowlist: …` - - `"user"` + - `allowed_domains: List[str]` - - `"system"` + A list of allowed domains when type is `allowlist`. - - `"developer"` + - `type: Literal["allowlist"]` - - `agent: Optional[MessageAgent]` + Allow outbound network access only to specified domains. Always `allowlist`. - The agent that produced this item. + - `"allowlist"` - - `agent_name: str` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - The canonical name of the agent that produced this item. + Optional domain-scoped secrets for allowlisted domains. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `domain: str` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The domain associated with the secret. - - `"in_progress"` + - `name: str` - - `"completed"` + The name of the secret to inject for the domain. - - `"incomplete"` + - `value: str` - - `type: Optional[Literal["message"]]` + The secret value to inject for the domain. - The type of the message input. Always set to `message`. + - `type: Literal["code_interpreter"]` - - `"message"` + The type of the code interpreter tool. Always `code_interpreter`. - - `class BetaResponseOutputMessage: …` + - `"code_interpreter"` - An output message from the model. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `id: str` + The tool invocation context(s). - The unique ID of the output message. + - `"direct"` - - `content: List[Content]` + - `"programmatic"` - The content of the output message. + - `class ProgrammaticToolCalling: …` - - `class BetaResponseOutputText: …` + - `type: Literal["programmatic_tool_calling"]` - A text output from the model. + The type of the tool. Always `programmatic_tool_calling`. - - `annotations: List[Annotation]` + - `"programmatic_tool_calling"` - The annotations of the text output. + - `class ImageGeneration: …` - - `class AnnotationFileCitation: …` + A tool that generates images using the GPT image models. - A citation to a file. + - `type: Literal["image_generation"]` - - `file_id: str` + The type of the image generation tool. Always `image_generation`. - The ID of the file. + - `"image_generation"` - - `filename: str` + - `action: Optional[Literal["generate", "edit", "auto"]]` - The filename of the file cited. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `index: int` + - `"generate"` - The index of the file in the list of files. + - `"edit"` - - `type: Literal["file_citation"]` + - `"auto"` - The type of the file citation. Always `file_citation`. + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `"file_citation"` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `class AnnotationURLCitation: …` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - A citation for a web resource used to generate a model response. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `end_index: int` + - `"transparent"` - The index of the last character of the URL citation in the message. + - `"opaque"` - - `start_index: int` + - `"auto"` - The index of the first character of the URL citation in the message. + - `input_fidelity: Optional[Literal["high", "low"]]` - - `title: str` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The title of the web resource. + - `"high"` - - `type: Literal["url_citation"]` + - `"low"` - The type of the URL citation. Always `url_citation`. + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - - `"url_citation"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `url: str` + - `file_id: Optional[str]` - The URL of the web resource. + File ID for the mask image. - - `class AnnotationContainerFileCitation: …` + - `image_url: Optional[str]` - A citation for a container file used to generate a model response. + Base64-encoded mask image. - - `container_id: str` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - The ID of the container file. + The image generation model to use. Default: `gpt-image-1`. - - `end_index: int` + - `str` - The index of the last character of the container file citation in the message. + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `file_id: str` + The image generation model to use. Default: `gpt-image-1`. - The ID of the file. + - `"gpt-image-1"` - - `filename: str` + - `"gpt-image-1-mini"` - The filename of the container file cited. + - `"gpt-image-2"` - - `start_index: int` + - `"gpt-image-2-2026-04-21"` - The index of the first character of the container file citation in the message. + - `"gpt-image-1.5"` - - `type: Literal["container_file_citation"]` + - `"chatgpt-image-latest"` - The type of the container file citation. Always `container_file_citation`. + - `moderation: Optional[Literal["auto", "low"]]` - - `"container_file_citation"` + Moderation level for the generated image. Default: `auto`. - - `class AnnotationFilePath: …` + - `"auto"` - A path to a file. + - `"low"` - - `file_id: str` + - `output_compression: Optional[int]` - The ID of the file. + Compression level for the output image. Default: 100. - - `index: int` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - The index of the file in the list of files. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `type: Literal["file_path"]` + - `"png"` - The type of the file path. Always `file_path`. + - `"webp"` - - `"file_path"` + - `"jpeg"` - - `text: str` + - `partial_images: Optional[int]` - The text output from the model. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: Literal["output_text"]` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - The type of the output text. Always `output_text`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"output_text"` + - `"low"` - - `logprobs: Optional[List[Logprob]]` + - `"medium"` - - `token: str` + - `"high"` - - `bytes: List[int]` + - `"auto"` - - `logprob: float` + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - - `top_logprobs: List[LogprobTopLogprob]` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `token: str` + - `str` - - `bytes: List[int]` + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `logprob: float` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `class BetaResponseOutputRefusal: …` + - `"1024x1024"` - A refusal from the model. + - `"1024x1536"` - - `refusal: str` + - `"1536x1024"` - The refusal explanation from the model. + - `"auto"` - - `type: Literal["refusal"]` + - `class LocalShell: …` - The type of the refusal. Always `refusal`. + A tool that allows the model to execute shell commands in a local environment. - - `"refusal"` + - `type: Literal["local_shell"]` - - `role: Literal["assistant"]` + The type of the local shell tool. Always `local_shell`. - The role of the output message. Always `assistant`. + - `"local_shell"` - - `"assistant"` + - `class BetaFunctionShellTool: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + A tool that allows the model to execute shell commands. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `type: Literal["shell"]` - - `"in_progress"` + The type of the shell tool. Always `shell`. - - `"completed"` + - `"shell"` - - `"incomplete"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `type: Literal["message"]` + The tool invocation context(s). - The type of the output message. Always `message`. + - `"direct"` - - `"message"` + - `"programmatic"` - - `agent: Optional[Agent]` + - `environment: Optional[Environment]` - The agent that produced this item. + - `class BetaContainerAuto: …` - - `agent_name: str` + - `type: Literal["container_auto"]` - The canonical name of the agent that produced this item. + Automatically creates a container for this request - - `phase: Optional[Literal["commentary"]]` + - `"container_auto"` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `file_ids: Optional[List[str]]` - - `"commentary"` + An optional list of uploaded files to make available to your code. - - `class BetaResponseFileSearchToolCall: …` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + The memory limit for the container. - - `id: str` + - `"1g"` - The unique ID of the file search tool call. + - `"4g"` - - `queries: List[str]` + - `"16g"` - The queries used to search for files. + - `"64g"` - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `network_policy: Optional[NetworkPolicy]` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Network access policy for the container. - - `"in_progress"` + - `class BetaContainerNetworkPolicyDisabled: …` - - `"searching"` + - `class BetaContainerNetworkPolicyAllowlist: …` - - `"completed"` + - `skills: Optional[List[Skill]]` - - `"incomplete"` + An optional list of skills referenced by id or inline data. - - `"failed"` + - `class BetaSkillReference: …` - - `type: Literal["file_search_call"]` + - `skill_id: str` - The type of the file search tool call. Always `file_search_call`. + The ID of the referenced skill. - - `"file_search_call"` + - `type: Literal["skill_reference"]` - - `agent: Optional[Agent]` + References a skill created with the /v1/skills endpoint. - The agent that produced this item. + - `"skill_reference"` - - `agent_name: str` + - `version: Optional[str]` - The canonical name of the agent that produced this item. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `results: Optional[List[Result]]` + - `class BetaInlineSkill: …` - The results of the file search tool call. + - `description: str` - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + The description of the skill. - 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, booleans, or numbers. + - `name: str` - - `str` + The name of the skill. - - `float` + - `source: BetaInlineSkillSource` - - `bool` + Inline skill payload - - `file_id: Optional[str]` + - `data: str` - The unique ID of the file. + Base64-encoded skill zip bundle. - - `filename: Optional[str]` + - `media_type: Literal["application/zip"]` - The name of the file. + The media type of the inline skill payload. Must be `application/zip`. - - `score: Optional[float]` + - `"application/zip"` - The relevance score of the file - a value between 0 and 1. + - `type: Literal["base64"]` - - `text: Optional[str]` + The type of the inline skill source. Must be `base64`. - The text that was retrieved from the file. + - `"base64"` - - `class BetaResponseComputerToolCall: …` + - `type: Literal["inline"]` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Defines an inline skill for this request. - - `id: str` + - `"inline"` - The unique ID of the computer call. + - `class BetaLocalEnvironment: …` - - `call_id: str` + - `type: Literal["local"]` - An identifier used when responding to the tool call with output. + Use a local computer environment. - - `pending_safety_checks: List[PendingSafetyCheck]` + - `"local"` - The pending safety checks for the computer call. + - `skills: Optional[List[BetaLocalSkill]]` - - `id: str` + An optional list of skills. - The ID of the pending safety check. + - `description: str` - - `code: Optional[str]` + The description of the skill. - The type of the pending safety check. + - `name: str` - - `message: Optional[str]` + The name of the skill. - Details about the pending safety check. + - `path: str` - - `status: Literal["in_progress", "completed", "incomplete"]` + The path to the directory containing the skill. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class BetaContainerReference: …` - - `"in_progress"` + - `container_id: str` - - `"completed"` + The ID of the referenced container. - - `"incomplete"` + - `type: Literal["container_reference"]` - - `type: Literal["computer_call"]` + References a container created with the /v1/containers endpoint - The type of the computer call. Always `computer_call`. + - `"container_reference"` - - `"computer_call"` + - `class BetaCustomTool: …` - - `action: Optional[BetaComputerAction]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - A click action. + - `name: str` - - `class Click: …` + The name of the custom tool, used to identify it in tool calls. - A click action. + - `type: Literal["custom"]` - - `button: Literal["left", "right", "wheel", 2 more]` + The type of the custom tool. Always `custom`. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"custom"` - - `"left"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"right"` + The tool invocation context(s). - - `"wheel"` + - `"direct"` - - `"back"` + - `"programmatic"` - - `"forward"` + - `defer_loading: Optional[bool]` - - `type: Literal["click"]` + Whether this tool should be deferred and discovered via tool search. - Specifies the event type. For a click action, this property is always `click`. + - `description: Optional[str]` - - `"click"` + Optional description of the custom tool, used to provide more context. - - `x: int` + - `format: Optional[Format]` - The x-coordinate where the click occurred. + The input format for the custom tool. Default is unconstrained text. - - `y: int` + - `class FormatText: …` - The y-coordinate where the click occurred. + Unconstrained free-form text. - - `keys: Optional[List[str]]` + - `type: Literal["text"]` - The keys being held while clicking. + Unconstrained text format. Always `text`. - - `class DoubleClick: …` + - `"text"` - A double click action. + - `class FormatGrammar: …` - - `keys: Optional[List[str]]` + A grammar defined by the user. - The keys being held while double-clicking. + - `definition: str` - - `type: Literal["double_click"]` + The grammar definition. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `syntax: Literal["lark", "regex"]` - - `"double_click"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `x: int` + - `"lark"` - The x-coordinate where the double click occurred. + - `"regex"` - - `y: int` + - `type: Literal["grammar"]` - The y-coordinate where the double click occurred. + Grammar format. Always `grammar`. - - `class Drag: …` + - `"grammar"` - A drag action. + - `class BetaNamespaceTool: …` - - `path: List[DragPath]` + Groups function/custom tools under a shared namespace. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `description: str` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + A description of the namespace shown to the model. - - `x: int` + - `name: str` - The x-coordinate. + The namespace name used in tool calls (for example, `crm`). - - `y: int` + - `tools: List[Tool]` - The y-coordinate. + The function/custom tools available inside this namespace. - - `type: Literal["drag"]` + - `class ToolFunction: …` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `name: str` - - `"drag"` + - `type: Literal["function"]` - - `keys: Optional[List[str]]` + - `"function"` - The keys being held while dragging the mouse. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `class Keypress: …` + The tool invocation context(s). - A collection of keypresses the model would like to perform. + - `"direct"` - - `keys: List[str]` + - `"programmatic"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `defer_loading: Optional[bool]` - - `type: Literal["keypress"]` + Whether this function should be deferred and discovered via tool search. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `description: Optional[str]` - - `"keypress"` + - `output_schema: Optional[Dict[str, object]]` - - `class Move: …` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - A mouse move action. + - `parameters: Optional[object]` - - `type: Literal["move"]` + - `strict: Optional[bool]` - Specifies the event type. For a move action, this property is always set to `move`. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `"move"` + - `class BetaCustomTool: …` - - `x: int` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The x-coordinate to move to. + - `type: Literal["namespace"]` - - `y: int` + The type of the tool. Always `namespace`. - The y-coordinate to move to. + - `"namespace"` - - `keys: Optional[List[str]]` + - `class BetaToolSearchTool: …` - The keys being held while moving the mouse. + Hosted or BYOT tool search configuration for deferred tools. - - `class Screenshot: …` + - `type: Literal["tool_search"]` - A screenshot action. + The type of the tool. Always `tool_search`. - - `type: Literal["screenshot"]` + - `"tool_search"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `description: Optional[str]` - - `"screenshot"` + Description shown to the model for a client-executed tool search tool. - - `class Scroll: …` + - `execution: Optional[Literal["server", "client"]]` - A scroll action. + Whether tool search is executed by the server or by the client. - - `scroll_x: int` + - `"server"` - The horizontal scroll distance. + - `"client"` - - `scroll_y: int` + - `parameters: Optional[object]` - The vertical scroll distance. + Parameter schema for a client-executed tool search tool. - - `type: Literal["scroll"]` + - `class BetaWebSearchPreviewTool: …` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"scroll"` + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - - `x: int` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The x-coordinate where the scroll occurred. + - `"web_search_preview"` - - `y: int` + - `"web_search_preview_2025_03_11"` - The y-coordinate where the scroll occurred. + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `keys: Optional[List[str]]` + - `"text"` - The keys being held while scrolling. + - `"image"` - - `class Type: …` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - An action to type in text. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `text: str` + - `"low"` - The text to type. + - `"medium"` - - `type: Literal["type"]` + - `"high"` - Specifies the event type. For a type action, this property is always set to `type`. + - `user_location: Optional[UserLocation]` - - `"type"` + The user's location. - - `class Wait: …` + - `type: Literal["approximate"]` - A wait action. + The type of location approximation. Always `approximate`. - - `type: Literal["wait"]` + - `"approximate"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `city: Optional[str]` - - `"wait"` + Free text input for the city of the user, e.g. `San Francisco`. - - `actions: Optional[BetaComputerActionList]` + - `country: Optional[str]` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `class Click: …` + - `region: Optional[str]` - A click action. + Free text input for the region of the user, e.g. `California`. - - `class DoubleClick: …` + - `timezone: Optional[str]` - A double click action. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `class Drag: …` + - `class BetaApplyPatchTool: …` - A drag action. + Allows the assistant to create, delete, or update files using unified diffs. - - `class Keypress: …` + - `type: Literal["apply_patch"]` - A collection of keypresses the model would like to perform. + The type of the tool. Always `apply_patch`. - - `class Move: …` + - `"apply_patch"` - A mouse move action. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `class Screenshot: …` + The tool invocation context(s). - A screenshot action. + - `"direct"` - - `class Scroll: …` + - `"programmatic"` - A scroll action. + - `type: Literal["tool_search_output"]` - - `class Type: …` + The item type. Always `tool_search_output`. - An action to type in text. + - `"tool_search_output"` - - `class Wait: …` + - `id: Optional[str]` - A wait action. + The unique ID of this tool search output. - `agent: Optional[Agent]` @@ -84412,207 +95460,208 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ComputerCallOutput: …` - - The output of a computer tool call. + - `call_id: Optional[str]` - - `call_id: str` + The unique ID of the tool search call generated by the model. - The ID of the computer tool call that produced the output. + - `execution: Optional[Literal["server", "client"]]` - - `output: BetaResponseComputerToolCallOutputScreenshot` + Whether tool search was executed by the server or by the client. - A computer screenshot image used with the computer use tool. + - `"server"` - - `type: Literal["computer_screenshot"]` + - `"client"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"computer_screenshot"` + The status of the tool search output. - - `file_id: Optional[str]` + - `"in_progress"` - The identifier of an uploaded file that contains the screenshot. + - `"completed"` - - `image_url: Optional[str]` + - `"incomplete"` - The URL of the screenshot image. + - `class AdditionalTools: …` - - `type: Literal["computer_call_output"]` + - `role: Literal["developer"]` - The type of the computer tool call output. Always `computer_call_output`. + The role that provided the additional tools. Only `developer` is supported. - - `"computer_call_output"` + - `"developer"` - - `id: Optional[str]` + - `tools: List[BetaTool]` - The ID of the computer tool call output. + A list of additional tools made available at this item. - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + - `class BetaFunctionTool: …` - The safety checks reported by the API that have been acknowledged by the developer. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `id: str` + - `class BetaFileSearchTool: …` - The ID of the pending safety check. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `code: Optional[str]` + - `class BetaComputerTool: …` - The type of the pending safety check. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `message: Optional[str]` + - `class BetaComputerUsePreviewTool: …` - Details about the pending safety check. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `agent: Optional[ComputerCallOutputAgent]` + - `class BetaWebSearchTool: …` - The agent that produced this item. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `agent_name: str` + - `class Mcp: …` - The canonical name of the agent that produced this item. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `class CodeInterpreter: …` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + A tool that runs Python code to help generate a response to a prompt. - - `"in_progress"` + - `class ProgrammaticToolCalling: …` - - `"completed"` + - `class ImageGeneration: …` - - `"incomplete"` + A tool that generates images using the GPT image models. - - `class BetaResponseFunctionWebSearch: …` + - `class LocalShell: …` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + A tool that allows the model to execute shell commands in a local environment. - - `id: str` + - `class BetaFunctionShellTool: …` - The unique ID of the web search tool call. + A tool that allows the model to execute shell commands. - - `action: Action` + - `class BetaCustomTool: …` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `class ActionSearch: …` + - `class BetaNamespaceTool: …` - Action type "search" - Performs a web search query. + Groups function/custom tools under a shared namespace. - - `type: Literal["search"]` + - `class BetaToolSearchTool: …` - The action type. + Hosted or BYOT tool search configuration for deferred tools. - - `"search"` + - `class BetaWebSearchPreviewTool: …` - - `queries: Optional[List[str]]` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The search queries. + - `class BetaApplyPatchTool: …` - - `query: Optional[str]` + Allows the assistant to create, delete, or update files using unified diffs. - The search query. + - `type: Literal["additional_tools"]` - - `sources: Optional[List[ActionSearchSource]]` + The item type. Always `additional_tools`. - The sources used in the search. + - `"additional_tools"` - - `type: Literal["url"]` + - `id: Optional[str]` - The type of source. Always `url`. + The unique ID of this additional tools item. - - `"url"` + - `agent: Optional[AdditionalToolsAgent]` - - `url: str` + The agent that produced this item. - The URL of the source. + - `agent_name: str` - - `class ActionOpenPage: …` + The canonical name of the agent that produced this item. - Action type "open_page" - Opens a specific URL from search results. + - `class BetaResponseReasoningItem: …` - - `type: Literal["open_page"]` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - The action type. + - `id: str` - - `"open_page"` + The unique identifier of the reasoning content. - - `url: Optional[str]` + - `summary: List[Summary]` - The URL opened by the model. + Reasoning summary content. - - `class ActionFindInPage: …` + - `text: str` - Action type "find_in_page": Searches for a pattern within a loaded page. + A summary of the reasoning output from the model so far. - - `pattern: str` + - `type: Literal["summary_text"]` - The pattern or text to search for within the page. + The type of the object. Always `summary_text`. - - `type: Literal["find_in_page"]` + - `"summary_text"` - The action type. + - `type: Literal["reasoning"]` - - `"find_in_page"` + The type of the object. Always `reasoning`. - - `url: str` + - `"reasoning"` - The URL of the page searched for the pattern. + - `agent: Optional[Agent]` - - `status: Literal["in_progress", "searching", "completed", "failed"]` + The agent that produced this item. - The status of the web search tool call. + - `agent_name: str` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"searching"` + - `content: Optional[List[Content]]` - - `"completed"` + Reasoning text content. - - `"failed"` + - `text: str` - - `type: Literal["web_search_call"]` + The reasoning text from the model. - The type of the web search tool call. Always `web_search_call`. + - `type: Literal["reasoning_text"]` - - `"web_search_call"` + The type of the reasoning text. Always `reasoning_text`. - - `agent: Optional[Agent]` + - `"reasoning_text"` - The agent that produced this item. + - `encrypted_content: Optional[str]` - - `agent_name: str` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The canonical name of the agent that produced this item. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `class BetaResponseFunctionToolCall: …` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"in_progress"` - - `arguments: str` + - `"completed"` - A JSON string of the arguments to pass to the function. + - `"incomplete"` - - `call_id: str` + - `class BetaResponseCompactionItemParam: …` - The unique ID of the function tool call generated by the model. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `name: str` + - `encrypted_content: str` - The name of the function to run. + The encrypted content of the compaction summary. - - `type: Literal["function_call"]` + - `type: Literal["compaction"]` - The type of the function tool call. Always `function_call`. + The type of the item. Always `compaction`. - - `"function_call"` + - `"compaction"` - `id: Optional[str]` - The unique ID of the function tool call. + The ID of the compaction item. - `agent: Optional[Agent]` @@ -84622,180 +95671,180 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `class ImageGenerationCall: …` - The execution context that produced this tool call. + An image generation request made by the model. - - `class CallerDirect: …` + - `id: str` - - `type: Literal["direct"]` + The unique ID of the image generation call. - - `"direct"` + - `result: Optional[str]` - - `class CallerProgram: …` + The generated image encoded in base64. - - `caller_id: str` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - The call ID of the program item that produced this tool call. + The status of the image generation call. - - `type: Literal["program"]` + - `"in_progress"` - - `"program"` + - `"completed"` - - `namespace: Optional[str]` + - `"generating"` - The namespace of the function to run. + - `"failed"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `type: Literal["image_generation_call"]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the image generation call. Always `image_generation_call`. - - `"in_progress"` + - `"image_generation_call"` - - `"completed"` + - `agent: Optional[ImageGenerationCallAgent]` - - `"incomplete"` + The agent that produced this item. - - `class FunctionCallOutput: …` + - `agent_name: str` - The output of a function tool call. + The canonical name of the agent that produced this item. - - `call_id: str` + - `class BetaResponseCodeInterpreterToolCall: …` - The unique ID of the function tool call generated by the model. + A tool call to run code. - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + - `id: str` - Text, image, or file output of the function tool call. + The unique ID of the code interpreter tool call. - - `str` + - `code: Optional[str]` - A JSON string of the output of the function tool call. + The code to run, or null if not available. - - `List[BetaResponseFunctionCallOutputItem]` + - `container_id: str` - - `class BetaResponseInputTextContent: …` + The ID of the container used to run the code. - A text input to the model. + - `outputs: Optional[List[Output]]` - - `text: str` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The text input to the model. + - `class OutputLogs: …` - - `type: Literal["input_text"]` + The logs output from the code interpreter. - The type of the input item. Always `input_text`. + - `logs: str` - - `"input_text"` + The logs output from the code interpreter. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["logs"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The type of the output. Always `logs`. - - `mode: Literal["explicit"]` + - `"logs"` - The breakpoint mode. Always `explicit`. + - `class OutputImage: …` - - `"explicit"` + The image output from the code interpreter. - - `class BetaResponseInputImageContent: …` + - `type: Literal["image"]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The type of the output. Always `image`. - - `type: Literal["input_image"]` + - `"image"` - The type of the input item. Always `input_image`. + - `url: str` - - `"input_image"` + The URL of the image output from the code interpreter. - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"low"` + - `"in_progress"` - - `"high"` + - `"completed"` - - `"auto"` + - `"incomplete"` - - `"original"` + - `"interpreting"` - - `file_id: Optional[str]` + - `"failed"` - The ID of the file to be sent to the model. + - `type: Literal["code_interpreter_call"]` - - `image_url: Optional[str]` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"code_interpreter_call"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `agent: Optional[Agent]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The agent that produced this item. - - `mode: Literal["explicit"]` + - `agent_name: str` - The breakpoint mode. Always `explicit`. + The canonical name of the agent that produced this item. - - `"explicit"` + - `class LocalShellCall: …` - - `class BetaResponseInputFileContent: …` + A tool call to run a command on the local shell. - A file input to the model. + - `id: str` - - `type: Literal["input_file"]` + The unique ID of the local shell call. - The type of the input item. Always `input_file`. + - `action: LocalShellCallAction` - - `"input_file"` + Execute a shell command on the server. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `command: List[str]` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The command to run. - - `"auto"` + - `env: Dict[str, str]` - - `"low"` + Environment variables to set for the command. - - `"high"` + - `type: Literal["exec"]` - - `file_data: Optional[str]` + The type of the local shell action. Always `exec`. - The base64-encoded data of the file to be sent to the model. + - `"exec"` - - `file_id: Optional[str]` + - `timeout_ms: Optional[int]` - The ID of the file to be sent to the model. + Optional timeout in milliseconds for the command. - - `file_url: Optional[str]` + - `user: Optional[str]` - The URL of the file to be sent to the model. + Optional user to run the command as. - - `filename: Optional[str]` + - `working_directory: Optional[str]` - The name of the file to be sent to the model. + Optional working directory to run the command in. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `call_id: str` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The unique ID of the local shell tool call generated by the model. - - `mode: Literal["explicit"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The breakpoint mode. Always `explicit`. + The status of the local shell call. - - `"explicit"` + - `"in_progress"` - - `type: Literal["function_call_output"]` + - `"completed"` - The type of the function tool call output. Always `function_call_output`. + - `"incomplete"` - - `"function_call_output"` + - `type: Literal["local_shell_call"]` - - `id: Optional[str]` + The type of the local shell call. Always `local_shell_call`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"local_shell_call"` - - `agent: Optional[FunctionCallOutputAgent]` + - `agent: Optional[LocalShellCallAgent]` The agent that produced this item. @@ -84803,33 +95852,35 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[FunctionCallOutputCaller]` + - `class LocalShellCallOutput: …` - The execution context that produced this tool call. + The output of a local shell tool call. - - `class FunctionCallOutputCallerDirect: …` + - `id: str` - - `type: Literal["direct"]` + The unique ID of the local shell tool call generated by the model. - The caller type. Always `direct`. + - `output: str` - - `"direct"` + A JSON string of the output of the local shell tool call. - - `class FunctionCallOutputCallerProgram: …` + - `type: Literal["local_shell_call_output"]` - - `caller_id: str` + The type of the local shell tool call output. Always `local_shell_call_output`. - The call ID of the program item that produced this tool call. + - `"local_shell_call_output"` - - `type: Literal["program"]` + - `agent: Optional[LocalShellCallOutputAgent]` - The caller type. Always `program`. + The agent that produced this item. - - `"program"` + - `agent_name: str` + + The canonical name of the agent that produced this item. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -84837,1501 +95888,1457 @@ print(compacted_response) - `"incomplete"` - - `class AgentMessage: …` + - `class ShellCall: …` - A message routed between agents. + A tool representing a request to execute one or more shell commands. - - `author: str` + - `action: ShellCallAction` - The sending agent identity. + The shell commands and limits that describe how to run the tool call. - - `content: List[AgentMessageContent]` + - `commands: List[str]` - Plaintext, image, or encrypted content sent between agents. + Ordered shell commands for the execution environment to run. - - `class BetaResponseInputTextContent: …` + - `max_output_length: Optional[int]` - A text input to the model. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `class BetaResponseInputImageContent: …` + - `timeout_ms: Optional[int]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `class AgentMessageContentEncryptedContent: …` + - `call_id: str` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The unique ID of the shell tool call generated by the model. - - `encrypted_content: str` + - `type: Literal["shell_call"]` - Opaque encrypted content. + The type of the item. Always `shell_call`. - - `type: Literal["encrypted_content"]` + - `"shell_call"` - The type of the input item. Always `encrypted_content`. + - `id: Optional[str]` - - `"encrypted_content"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `recipient: str` + - `agent: Optional[ShellCallAgent]` - The destination agent identity. + The agent that produced this item. - - `type: Literal["agent_message"]` + - `agent_name: str` - The item type. Always `agent_message`. + The canonical name of the agent that produced this item. - - `"agent_message"` + - `caller: Optional[ShellCallCaller]` - - `id: Optional[str]` + The execution context that produced this tool call. - The unique ID of this agent message item. + - `class ShellCallCallerDirect: …` - - `agent: Optional[AgentMessageAgent]` + - `type: Literal["direct"]` - The agent that produced this item. + The caller type. Always `direct`. - - `agent_name: str` + - `"direct"` - The canonical name of the agent that produced this item. + - `class ShellCallCallerProgram: …` - - `class MultiAgentCall: …` + - `caller_id: str` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The call ID of the program item that produced this tool call. - The multi-agent action that was executed. + - `type: Literal["program"]` - - `"spawn_agent"` + The caller type. Always `program`. - - `"interrupt_agent"` + - `"program"` - - `"list_agents"` + - `environment: Optional[ShellCallEnvironment]` - - `"send_message"` + The environment to execute the shell commands in. - - `"followup_task"` + - `class BetaLocalEnvironment: …` - - `"wait_agent"` + - `class BetaContainerReference: …` - - `arguments: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The action arguments as a JSON string. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `call_id: str` + - `"in_progress"` - The unique ID linking this call to its output. + - `"completed"` - - `type: Literal["multi_agent_call"]` + - `"incomplete"` - The item type. Always `multi_agent_call`. + - `class ShellCallOutput: …` - - `"multi_agent_call"` + The streamed output items emitted by a shell tool call. - - `id: Optional[str]` + - `call_id: str` - The unique ID of this multi-agent call. + The unique ID of the shell tool call generated by the model. - - `agent: Optional[MultiAgentCallAgent]` + - `output: List[BetaResponseFunctionShellCallOutputContent]` - The agent that produced this item. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `agent_name: str` + - `outcome: Outcome` - The canonical name of the agent that produced this item. + The exit or timeout outcome associated with this shell call. - - `class MultiAgentCallOutput: …` + - `class OutcomeTimeout: …` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + Indicates that the shell call exceeded its configured time limit. - The multi-agent action that produced this result. + - `type: Literal["timeout"]` - - `"spawn_agent"` + The outcome type. Always `timeout`. - - `"interrupt_agent"` + - `"timeout"` - - `"list_agents"` + - `class OutcomeExit: …` - - `"send_message"` + Indicates that the shell commands finished and returned an exit code. - - `"followup_task"` + - `exit_code: int` - - `"wait_agent"` + The exit code returned by the shell process. - - `call_id: str` + - `type: Literal["exit"]` - The unique ID of the multi-agent call. + The outcome type. Always `exit`. - - `output: List[MultiAgentCallOutputOutput]` + - `"exit"` - Text output returned by the multi-agent action. + - `stderr: str` - - `text: str` + Captured stderr output for the shell call. - The text content. + - `stdout: str` - - `type: Literal["output_text"]` + Captured stdout output for the shell call. - The content type. Always `output_text`. + - `type: Literal["shell_call_output"]` - - `"output_text"` + The type of the item. Always `shell_call_output`. - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + - `"shell_call_output"` - Citations associated with the text content. + - `id: Optional[str]` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `file_id: str` + - `agent: Optional[ShellCallOutputAgent]` - The ID of the file. + The agent that produced this item. - - `filename: str` + - `agent_name: str` - The filename of the file cited. + The canonical name of the agent that produced this item. - - `index: int` + - `caller: Optional[ShellCallOutputCaller]` - The index of the file in the list of files. + The execution context that produced this tool call. - - `type: Literal["file_citation"]` + - `class ShellCallOutputCallerDirect: …` - The citation type. Always `file_citation`. + - `type: Literal["direct"]` - - `"file_citation"` + The caller type. Always `direct`. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + - `"direct"` - - `end_index: int` + - `class ShellCallOutputCallerProgram: …` - The index of the last character of the citation in the message. + - `caller_id: str` - - `start_index: int` + The call ID of the program item that produced this tool call. - The index of the first character of the citation in the message. + - `type: Literal["program"]` - - `title: str` + The caller type. Always `program`. - The title of the cited resource. + - `"program"` - - `type: Literal["url_citation"]` + - `max_output_length: Optional[int]` - The citation type. Always `url_citation`. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `"url_citation"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `url: str` + The status of the shell call output. - The URL of the cited resource. + - `"in_progress"` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `"completed"` - - `container_id: str` + - `"incomplete"` - The ID of the container. + - `class ApplyPatchCall: …` - - `end_index: int` + A tool call representing a request to create, delete, or update files using diff patches. - The index of the last character of the citation in the message. + - `call_id: str` - - `file_id: str` + The unique ID of the apply patch tool call generated by the model. - The ID of the container file. + - `operation: ApplyPatchCallOperation` - - `filename: str` + The specific create, delete, or update instruction for the apply_patch tool call. - The filename of the container file cited. + - `class ApplyPatchCallOperationCreateFile: …` - - `start_index: int` + Instruction for creating a new file via the apply_patch tool. - The index of the first character of the citation in the message. + - `diff: str` - - `type: Literal["container_file_citation"]` + Unified diff content to apply when creating the file. - The citation type. Always `container_file_citation`. + - `path: str` - - `"container_file_citation"` + Path of the file to create relative to the workspace root. - - `type: Literal["multi_agent_call_output"]` + - `type: Literal["create_file"]` - The item type. Always `multi_agent_call_output`. + The operation type. Always `create_file`. - - `"multi_agent_call_output"` + - `"create_file"` - - `id: Optional[str]` + - `class ApplyPatchCallOperationDeleteFile: …` - The unique ID of this multi-agent call output. + Instruction for deleting an existing file via the apply_patch tool. - - `agent: Optional[MultiAgentCallOutputAgent]` + - `path: str` - The agent that produced this item. + Path of the file to delete relative to the workspace root. - - `agent_name: str` + - `type: Literal["delete_file"]` - The canonical name of the agent that produced this item. + The operation type. Always `delete_file`. - - `class ToolSearchCall: …` + - `"delete_file"` - - `arguments: object` + - `class ApplyPatchCallOperationUpdateFile: …` - The arguments supplied to the tool search call. + Instruction for updating an existing file via the apply_patch tool. - - `type: Literal["tool_search_call"]` + - `diff: str` - The item type. Always `tool_search_call`. + Unified diff content to apply to the existing file. - - `"tool_search_call"` + - `path: str` - - `id: Optional[str]` + Path of the file to update relative to the workspace root. - The unique ID of this tool search call. + - `type: Literal["update_file"]` - - `agent: Optional[ToolSearchCallAgent]` + The operation type. Always `update_file`. - The agent that produced this item. + - `"update_file"` - - `agent_name: str` + - `status: Literal["in_progress", "completed"]` - The canonical name of the agent that produced this item. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `call_id: Optional[str]` + - `"in_progress"` - The unique ID of the tool search call generated by the model. + - `"completed"` - - `execution: Optional[Literal["server", "client"]]` + - `type: Literal["apply_patch_call"]` - Whether tool search was executed by the server or by the client. + The type of the item. Always `apply_patch_call`. - - `"server"` + - `"apply_patch_call"` - - `"client"` + - `id: Optional[str]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The status of the tool search call. + - `agent: Optional[ApplyPatchCallAgent]` - - `"in_progress"` + The agent that produced this item. - - `"completed"` + - `agent_name: str` - - `"incomplete"` + The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchOutputItemParam: …` + - `caller: Optional[ApplyPatchCallCaller]` - - `tools: List[BetaTool]` + The execution context that produced this tool call. - The loaded tool definitions returned by the tool search output. + - `class ApplyPatchCallCallerDirect: …` - - `class BetaFunctionTool: …` + - `type: Literal["direct"]` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The caller type. Always `direct`. - - `name: str` + - `"direct"` - The name of the function to call. + - `class ApplyPatchCallCallerProgram: …` - - `parameters: Optional[Dict[str, object]]` + - `caller_id: str` - A JSON schema object describing the parameters of the function. + The call ID of the program item that produced this tool call. - - `strict: Optional[bool]` + - `type: Literal["program"]` - Whether strict parameter validation is enforced for this function tool. + The caller type. Always `program`. - - `type: Literal["function"]` + - `"program"` - The type of the function tool. Always `function`. + - `class ApplyPatchCallOutput: …` - - `"function"` + The streamed output emitted by an apply patch tool call. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `call_id: str` - The tool invocation context(s). + The unique ID of the apply patch tool call generated by the model. - - `"direct"` + - `status: Literal["completed", "failed"]` - - `"programmatic"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `defer_loading: Optional[bool]` + - `"completed"` - Whether this function is deferred and loaded via tool search. + - `"failed"` - - `description: Optional[str]` + - `type: Literal["apply_patch_call_output"]` - A description of the function. Used by the model to determine whether or not to call the function. + The type of the item. Always `apply_patch_call_output`. - - `output_schema: Optional[Dict[str, object]]` + - `"apply_patch_call_output"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `id: Optional[str]` - - `class BetaFileSearchTool: …` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `agent: Optional[ApplyPatchCallOutputAgent]` - - `type: Literal["file_search"]` + The agent that produced this item. - The type of the file search tool. Always `file_search`. + - `agent_name: str` - - `"file_search"` + The canonical name of the agent that produced this item. - - `vector_store_ids: List[str]` + - `caller: Optional[ApplyPatchCallOutputCaller]` - The IDs of the vector stores to search. + The execution context that produced this tool call. - - `filters: Optional[Filters]` + - `class ApplyPatchCallOutputCallerDirect: …` - A filter to apply. + - `type: Literal["direct"]` - - `class FiltersComparisonFilter: …` + The caller type. Always `direct`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"direct"` - - `key: str` + - `class ApplyPatchCallOutputCallerProgram: …` - The key to compare against the value. + - `caller_id: str` - - `type: Literal["eq", "ne", "gt", 5 more]` + The call ID of the program item that produced this tool call. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `type: Literal["program"]` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The caller type. Always `program`. - - `"eq"` + - `"program"` - - `"ne"` + - `output: Optional[str]` - - `"gt"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `"gte"` + - `class McpListTools: …` - - `"lt"` + A list of tools available on an MCP server. - - `"lte"` + - `id: str` - - `"in"` + The unique ID of the list. - - `"nin"` + - `server_label: str` - - `value: Union[str, float, bool, List[object]]` + The label of the MCP server. - The value to compare against the attribute key; supports string, number, or boolean types. + - `tools: List[McpListToolsTool]` - - `str` + The tools available on the server. - - `float` + - `input_schema: object` - - `bool` + The JSON schema describing the tool's input. - - `List[object]` + - `name: str` - - `class FiltersCompoundFilter: …` + The name of the tool. - Combine multiple filters using `and` or `or`. + - `annotations: Optional[object]` - - `filters: List[FiltersCompoundFilterFilter]` + Additional annotations about the tool. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `description: Optional[str]` - - `class FiltersCompoundFilterFilterComparisonFilter: …` + The description of the tool. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: Literal["mcp_list_tools"]` - - `key: str` + The type of the item. Always `mcp_list_tools`. - The key to compare against the value. + - `"mcp_list_tools"` - - `type: Literal["eq", "ne", "gt", 5 more]` + - `agent: Optional[McpListToolsAgent]` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The agent that produced this item. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `agent_name: str` - - `"eq"` + The canonical name of the agent that produced this item. - - `"ne"` + - `error: Optional[str]` - - `"gt"` + Error message if the server could not list tools. - - `"gte"` + - `class McpApprovalRequest: …` - - `"lt"` + A request for human approval of a tool invocation. - - `"lte"` + - `id: str` - - `"in"` + The unique ID of the approval request. - - `"nin"` + - `arguments: str` - - `value: Union[str, float, bool, List[object]]` + A JSON string of arguments for the tool. - The value to compare against the attribute key; supports string, number, or boolean types. + - `name: str` - - `str` + The name of the tool to run. - - `float` + - `server_label: str` - - `bool` + The label of the MCP server making the request. + + - `type: Literal["mcp_approval_request"]` - - `List[object]` + The type of the item. Always `mcp_approval_request`. - - `object` + - `"mcp_approval_request"` - - `type: Literal["and", "or"]` + - `agent: Optional[McpApprovalRequestAgent]` - Type of operation: `and` or `or`. + The agent that produced this item. - - `"and"` + - `agent_name: str` - - `"or"` + The canonical name of the agent that produced this item. - - `max_num_results: Optional[int]` + - `class McpApprovalResponse: …` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + A response to an MCP approval request. - - `ranking_options: Optional[RankingOptions]` + - `approval_request_id: str` - Ranking options for search. + The ID of the approval request being answered. - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + - `approve: bool` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + Whether the request was approved. - - `embedding_weight: float` + - `type: Literal["mcp_approval_response"]` - The weight of the embedding in the reciprocal ranking fusion. + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `id: Optional[str]` - - `text_weight: float` + The unique ID of the approval response - The weight of the text in the reciprocal ranking fusion. + - `agent: Optional[McpApprovalResponseAgent]` - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + The agent that produced this item. - The ranker to use for the file search. + - `agent_name: str` - - `"auto"` + The canonical name of the agent that produced this item. - - `"default-2024-11-15"` + - `reason: Optional[str]` - - `score_threshold: Optional[float]` + Optional reason for the decision. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `class McpCall: …` - - `class BetaComputerTool: …` + An invocation of a tool on an MCP server. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `id: str` - - `type: Literal["computer"]` + The unique ID of the tool call. - The type of the computer tool. Always `computer`. + - `arguments: str` - - `"computer"` + A JSON string of the arguments passed to the tool. - - `class BetaComputerUsePreviewTool: …` + - `name: str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The name of the tool that was run. - - `display_height: int` + - `server_label: str` - The height of the computer display. + The label of the MCP server running the tool. - - `display_width: int` + - `type: Literal["mcp_call"]` - The width of the computer display. + The type of the item. Always `mcp_call`. - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `"mcp_call"` - The type of computer environment to control. + - `agent: Optional[McpCallAgent]` - - `"windows"` + The agent that produced this item. - - `"mac"` + - `agent_name: str` - - `"linux"` + The canonical name of the agent that produced this item. - - `"ubuntu"` + - `approval_request_id: Optional[str]` - - `"browser"` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `type: Literal["computer_use_preview"]` + - `error: Optional[str]` - The type of the computer use tool. Always `computer_use_preview`. + The error from the tool call, if any. - - `"computer_use_preview"` + - `output: Optional[str]` - - `class BetaWebSearchTool: …` + The output from the tool call. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - `type: Literal["web_search", "web_search_2025_08_26"]` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"in_progress"` - - `"web_search"` + - `"completed"` - - `"web_search_2025_08_26"` + - `"incomplete"` - - `filters: Optional[Filters]` + - `"calling"` - Filters for the search. + - `"failed"` - - `allowed_domains: Optional[List[str]]` + - `class BetaResponseCustomToolCallOutput: …` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The output of a custom tool call from your code, being sent back to the model. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `call_id: str` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + The call ID, used to map this custom tool call output to a custom tool call. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `output: Union[str, List[OutputOutputContentList]]` - - `"low"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"medium"` + - `str` - - `"high"` + A string of the output of the custom tool call. - - `user_location: Optional[UserLocation]` + - `List[OutputOutputContentList]` - The approximate location of the user. + Text, image, or file output of the custom tool call. - - `city: Optional[str]` + - `class BetaResponseInputText: …` - Free text input for the city of the user, e.g. `San Francisco`. + A text input to the model. - - `country: Optional[str]` + - `class BetaResponseInputImage: …` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `region: Optional[str]` + - `class BetaResponseInputFile: …` - Free text input for the region of the user, e.g. `California`. + A file input to the model. - - `timezone: Optional[str]` + - `type: Literal["custom_tool_call_output"]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `type: Optional[Literal["approximate"]]` + - `"custom_tool_call_output"` - The type of location approximation. Always `approximate`. + - `id: Optional[str]` - - `"approximate"` + The unique ID of the custom tool call output in the OpenAI platform. - - `class Mcp: …` + - `agent: Optional[Agent]` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The agent that produced this item. - - `server_label: str` + - `agent_name: str` - A label for this MCP server, used to identify it in tool calls. + The canonical name of the agent that produced this item. - - `type: Literal["mcp"]` + - `caller: Optional[Caller]` - The type of the MCP tool. Always `mcp`. + The execution context that produced this tool call. - - `"mcp"` + - `class CallerDirect: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["direct"]` - The tool invocation context(s). + The caller type. Always `direct`. - `"direct"` - - `"programmatic"` - - - `allowed_tools: Optional[McpAllowedTools]` + - `class CallerProgram: …` - List of allowed tool names or a filter object. + - `caller_id: str` - - `List[str]` + The call ID of the program item that produced this tool call. - A string array of allowed tool names + - `type: Literal["program"]` - - `class McpAllowedToolsMcpToolFilter: …` + The caller type. Always `program`. - A filter object to specify which tools are allowed. + - `"program"` - - `read_only: Optional[bool]` + - `class BetaResponseCustomToolCall: …` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + A call to a custom tool created by the model. - - `tool_names: Optional[List[str]]` + - `call_id: str` - List of allowed tool names. + An identifier used to map this custom tool call to a tool call output. - - `authorization: Optional[str]` + - `input: str` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The input for the custom tool call generated by the model. - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + - `name: str` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The name of the custom tool being called. - Currently supported `connector_id` values are: + - `type: Literal["custom_tool_call"]` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The type of the custom tool call. Always `custom_tool_call`. - - `"connector_dropbox"` + - `"custom_tool_call"` - - `"connector_gmail"` + - `id: Optional[str]` - - `"connector_googlecalendar"` + The unique ID of the custom tool call in the OpenAI platform. - - `"connector_googledrive"` + - `agent: Optional[Agent]` - - `"connector_microsoftteams"` + The agent that produced this item. - - `"connector_outlookcalendar"` + - `agent_name: str` - - `"connector_outlookemail"` + The canonical name of the agent that produced this item. - - `"connector_sharepoint"` + - `caller: Optional[Caller]` - - `defer_loading: Optional[bool]` + The execution context that produced this tool call. - Whether this MCP tool is deferred and discovered via tool search. + - `class CallerDirect: …` - - `headers: Optional[Dict[str, str]]` + - `type: Literal["direct"]` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"direct"` - - `require_approval: Optional[McpRequireApproval]` + - `class CallerProgram: …` - Specify which of the MCP server's tools require approval. + - `caller_id: str` - - `class McpRequireApprovalMcpToolApprovalFilter: …` + The call ID of the program item that produced this tool call. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `type: Literal["program"]` - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `"program"` - A filter object to specify which tools are allowed. + - `namespace: Optional[str]` - - `read_only: Optional[bool]` + The namespace of the custom tool being called. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `class CompactionTrigger: …` - - `tool_names: Optional[List[str]]` + Compacts the current context. Must be the final input item. - List of allowed tool names. + - `type: Literal["compaction_trigger"]` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + The type of the item. Always `compaction_trigger`. - A filter object to specify which tools are allowed. + - `"compaction_trigger"` - - `read_only: Optional[bool]` + - `agent: Optional[CompactionTriggerAgent]` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The agent that produced this item. - - `tool_names: Optional[List[str]]` + - `agent_name: str` - List of allowed tool names. + The canonical name of the agent that produced this item. - - `Literal["always", "never"]` + - `class ItemReference: …` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + An internal identifier for an item to reference. - - `"always"` + - `id: str` - - `"never"` + The ID of the item to reference. - - `server_description: Optional[str]` + - `agent: Optional[ItemReferenceAgent]` - Optional description of the MCP server, used to provide more context. + The agent that produced this item. - - `server_url: Optional[str]` + - `agent_name: str` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The canonical name of the agent that produced this item. - - `tunnel_id: Optional[str]` + - `type: Optional[Literal["item_reference"]]` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + The type of item to reference. Always `item_reference`. - - `class CodeInterpreter: …` + - `"item_reference"` - A tool that runs Python code to help generate a response to a prompt. + - `class Program: …` - - `container: CodeInterpreterContainer` + - `id: str` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The unique ID of this program item. - - `str` + - `call_id: str` - The container ID. + The stable call ID of the program item. - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `code: str` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The JavaScript source executed by programmatic tool calling. - - `type: Literal["auto"]` + - `fingerprint: str` - Always `auto`. + Opaque program replay fingerprint that must be round-tripped. - - `"auto"` + - `type: Literal["program"]` - - `file_ids: Optional[List[str]]` + The item type. Always `program`. - An optional list of uploaded files to make available to your code. + - `"program"` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `agent: Optional[ProgramAgent]` - The memory limit for the code interpreter container. + The agent that produced this item. - - `"1g"` + - `agent_name: str` - - `"4g"` + The canonical name of the agent that produced this item. - - `"16g"` + - `class ProgramOutput: …` - - `"64g"` + - `id: str` - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + The unique ID of this program output item. - Network access policy for the container. + - `call_id: str` - - `class BetaContainerNetworkPolicyDisabled: …` + The call ID of the program item. - - `type: Literal["disabled"]` + - `result: str` - Disable outbound network access. Always `disabled`. + The result produced by the program item. - - `"disabled"` + - `status: Literal["completed", "incomplete"]` - - `class BetaContainerNetworkPolicyAllowlist: …` + The terminal status of the program output. - - `allowed_domains: List[str]` + - `"completed"` - A list of allowed domains when type is `allowlist`. + - `"incomplete"` - - `type: Literal["allowlist"]` + - `type: Literal["program_output"]` - Allow outbound network access only to specified domains. Always `allowlist`. + The item type. Always `program_output`. - - `"allowlist"` + - `"program_output"` - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `agent: Optional[ProgramOutputAgent]` - Optional domain-scoped secrets for allowlisted domains. + The agent that produced this item. - - `domain: str` + - `agent_name: str` - The domain associated with the secret. + The canonical name of the agent that produced this item. - - `name: str` +### Beta Response Input Message Content List - The name of the secret to inject for the domain. +- `List[BetaResponseInputContent]` - - `value: str` + A list of one or many input items to the model, containing different content + types. - The secret value to inject for the domain. + - `class BetaResponseInputText: …` - - `type: Literal["code_interpreter"]` + A text input to the model. - The type of the code interpreter tool. Always `code_interpreter`. + - `text: str` - - `"code_interpreter"` + The text input to the model. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["input_text"]` - The tool invocation context(s). + The type of the input item. Always `input_text`. - - `"direct"` + - `"input_text"` - - `"programmatic"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `class ProgrammaticToolCalling: …` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `type: Literal["programmatic_tool_calling"]` + - `mode: Literal["explicit"]` - The type of the tool. Always `programmatic_tool_calling`. + The breakpoint mode. Always `explicit`. - - `"programmatic_tool_calling"` + - `"explicit"` - - `class ImageGeneration: …` + - `class BetaResponseInputImage: …` - A tool that generates images using the GPT image models. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `type: Literal["image_generation"]` + - `detail: Literal["low", "high", "auto", "original"]` - The type of the image generation tool. Always `image_generation`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"image_generation"` + - `"low"` - - `action: Optional[Literal["generate", "edit", "auto"]]` + - `"high"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"auto"` - - `"generate"` + - `"original"` - - `"edit"` + - `type: Literal["input_image"]` - - `"auto"` + The type of the input item. Always `input_image`. - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + - `"input_image"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `file_id: Optional[str]` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The ID of the file to be sent to the model. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `image_url: Optional[str]` - - `"transparent"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"opaque"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"auto"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `input_fidelity: Optional[Literal["high", "low"]]` + - `mode: Literal["explicit"]` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + The breakpoint mode. Always `explicit`. - - `"high"` + - `"explicit"` - - `"low"` + - `class BetaResponseInputFile: …` - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + A file input to the model. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `type: Literal["input_file"]` - - `file_id: Optional[str]` + The type of the input item. Always `input_file`. - File ID for the mask image. + - `"input_file"` - - `image_url: Optional[str]` + - `detail: Optional[Literal["auto", "low", "high"]]` - Base64-encoded mask image. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + - `"auto"` - The image generation model to use. Default: `gpt-image-1`. + - `"low"` - - `str` + - `"high"` - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `file_data: Optional[str]` - The image generation model to use. Default: `gpt-image-1`. + The content of the file to be sent to the model. - - `"gpt-image-1"` + - `file_id: Optional[str]` - - `"gpt-image-1-mini"` + The ID of the file to be sent to the model. - - `"gpt-image-2"` + - `file_url: Optional[str]` - - `"gpt-image-2-2026-04-21"` + The URL of the file to be sent to the model. - - `"gpt-image-1.5"` + - `filename: Optional[str]` - - `"chatgpt-image-latest"` + The name of the file to be sent to the model. - - `moderation: Optional[Literal["auto", "low"]]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Moderation level for the generated image. Default: `auto`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"auto"` + - `mode: Literal["explicit"]` - - `"low"` + The breakpoint mode. Always `explicit`. - - `output_compression: Optional[int]` + - `"explicit"` - Compression level for the output image. Default: 100. +### Beta Response Input Message Item - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` +- `class BetaResponseInputMessageItem: …` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `id: str` - - `"png"` + The unique ID of the message input. - - `"webp"` + - `content: BetaResponseInputMessageContentList` - - `"jpeg"` + A list of one or many input items to the model, containing different content + types. - - `partial_images: Optional[int]` + - `class BetaResponseInputText: …` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + A text input to the model. - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + - `text: str` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The text input to the model. - - `"low"` + - `type: Literal["input_text"]` - - `"medium"` + The type of the input item. Always `input_text`. - - `"high"` + - `"input_text"` - - `"auto"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `mode: Literal["explicit"]` - - `str` + The breakpoint mode. Always `explicit`. - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `"explicit"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `class BetaResponseInputImage: …` - - `"1024x1024"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"1024x1536"` + - `detail: Literal["low", "high", "auto", "original"]` - - `"1536x1024"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"auto"` + - `"low"` - - `class LocalShell: …` + - `"high"` - A tool that allows the model to execute shell commands in a local environment. + - `"auto"` - - `type: Literal["local_shell"]` + - `"original"` - The type of the local shell tool. Always `local_shell`. + - `type: Literal["input_image"]` - - `"local_shell"` + The type of the input item. Always `input_image`. - - `class BetaFunctionShellTool: …` + - `"input_image"` - A tool that allows the model to execute shell commands. + - `file_id: Optional[str]` - - `type: Literal["shell"]` + The ID of the file to be sent to the model. - The type of the shell tool. Always `shell`. + - `image_url: Optional[str]` - - `"shell"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The tool invocation context(s). + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"direct"` + - `mode: Literal["explicit"]` - - `"programmatic"` + The breakpoint mode. Always `explicit`. - - `environment: Optional[Environment]` + - `"explicit"` - - `class BetaContainerAuto: …` + - `class BetaResponseInputFile: …` - - `type: Literal["container_auto"]` + A file input to the model. - Automatically creates a container for this request + - `type: Literal["input_file"]` - - `"container_auto"` + The type of the input item. Always `input_file`. - - `file_ids: Optional[List[str]]` + - `"input_file"` - An optional list of uploaded files to make available to your code. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The memory limit for the container. + - `"auto"` - - `"1g"` + - `"low"` - - `"4g"` + - `"high"` - - `"16g"` + - `file_data: Optional[str]` - - `"64g"` + The content of the file to be sent to the model. - - `network_policy: Optional[NetworkPolicy]` + - `file_id: Optional[str]` - Network access policy for the container. + The ID of the file to be sent to the model. - - `class BetaContainerNetworkPolicyDisabled: …` + - `file_url: Optional[str]` - - `class BetaContainerNetworkPolicyAllowlist: …` + The URL of the file to be sent to the model. - - `skills: Optional[List[Skill]]` + - `filename: Optional[str]` - An optional list of skills referenced by id or inline data. + The name of the file to be sent to the model. - - `class BetaSkillReference: …` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `skill_id: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The ID of the referenced skill. + - `mode: Literal["explicit"]` - - `type: Literal["skill_reference"]` + The breakpoint mode. Always `explicit`. - References a skill created with the /v1/skills endpoint. + - `"explicit"` - - `"skill_reference"` + - `role: Literal["user", "system", "developer"]` - - `version: Optional[str]` + The role of the message input. One of `user`, `system`, or `developer`. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"user"` - - `class BetaInlineSkill: …` + - `"system"` - - `description: str` + - `"developer"` - The description of the skill. + - `type: Literal["message"]` - - `name: str` + The type of the message input. Always set to `message`. - The name of the skill. + - `"message"` - - `source: BetaInlineSkillSource` + - `agent: Optional[Agent]` - Inline skill payload + The agent that produced this item. - - `data: str` + - `agent_name: str` - Base64-encoded skill zip bundle. + The canonical name of the agent that produced this item. - - `media_type: Literal["application/zip"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The media type of the inline skill payload. Must be `application/zip`. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"application/zip"` + - `"in_progress"` - - `type: Literal["base64"]` + - `"completed"` - The type of the inline skill source. Must be `base64`. + - `"incomplete"` - - `"base64"` +### Beta Response Input Text - - `type: Literal["inline"]` +- `class BetaResponseInputText: …` - Defines an inline skill for this request. + A text input to the model. - - `"inline"` + - `text: str` - - `class BetaLocalEnvironment: …` + The text input to the model. - - `type: Literal["local"]` + - `type: Literal["input_text"]` - Use a local computer environment. + The type of the input item. Always `input_text`. - - `"local"` + - `"input_text"` - - `skills: Optional[List[BetaLocalSkill]]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - An optional list of skills. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `description: str` + - `mode: Literal["explicit"]` - The description of the skill. + The breakpoint mode. Always `explicit`. - - `name: str` + - `"explicit"` - The name of the skill. +### Beta Response Input Text Content - - `path: str` +- `class BetaResponseInputTextContent: …` - The path to the directory containing the skill. + A text input to the model. - - `class BetaContainerReference: …` + - `text: str` - - `container_id: str` + The text input to the model. - The ID of the referenced container. + - `type: Literal["input_text"]` - - `type: Literal["container_reference"]` + The type of the input item. Always `input_text`. - References a container created with the /v1/containers endpoint + - `"input_text"` - - `"container_reference"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `class BetaCustomTool: …` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `mode: Literal["explicit"]` - - `name: str` + The breakpoint mode. Always `explicit`. - The name of the custom tool, used to identify it in tool calls. + - `"explicit"` - - `type: Literal["custom"]` +### Beta Response Item - The type of the custom tool. Always `custom`. +- `BetaResponseItem` - - `"custom"` + Content item used to generate a response. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `class BetaResponseInputMessageItem: …` - The tool invocation context(s). + - `id: str` - - `"direct"` + The unique ID of the message input. - - `"programmatic"` + - `content: BetaResponseInputMessageContentList` - - `defer_loading: Optional[bool]` + A list of one or many input items to the model, containing different content + types. - Whether this tool should be deferred and discovered via tool search. + - `class BetaResponseInputText: …` - - `description: Optional[str]` + A text input to the model. - Optional description of the custom tool, used to provide more context. + - `text: str` - - `format: Optional[Format]` + The text input to the model. - The input format for the custom tool. Default is unconstrained text. + - `type: Literal["input_text"]` - - `class FormatText: …` + The type of the input item. Always `input_text`. - Unconstrained free-form text. + - `"input_text"` - - `type: Literal["text"]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Unconstrained text format. Always `text`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"text"` + - `mode: Literal["explicit"]` - - `class FormatGrammar: …` + The breakpoint mode. Always `explicit`. - A grammar defined by the user. + - `"explicit"` - - `definition: str` + - `class BetaResponseInputImage: …` - The grammar definition. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `syntax: Literal["lark", "regex"]` + - `detail: Literal["low", "high", "auto", "original"]` - The syntax of the grammar definition. One of `lark` or `regex`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"lark"` + - `"low"` - - `"regex"` + - `"high"` - - `type: Literal["grammar"]` + - `"auto"` - Grammar format. Always `grammar`. + - `"original"` - - `"grammar"` + - `type: Literal["input_image"]` - - `class BetaNamespaceTool: …` + The type of the input item. Always `input_image`. - Groups function/custom tools under a shared namespace. + - `"input_image"` - - `description: str` + - `file_id: Optional[str]` - A description of the namespace shown to the model. + The ID of the file to be sent to the model. - - `name: str` + - `image_url: Optional[str]` - The namespace name used in tool calls (for example, `crm`). + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `tools: List[Tool]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The function/custom tools available inside this namespace. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class ToolFunction: …` + - `mode: Literal["explicit"]` - - `name: str` + The breakpoint mode. Always `explicit`. - - `type: Literal["function"]` + - `"explicit"` - - `"function"` + - `class BetaResponseInputFile: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + A file input to the model. - The tool invocation context(s). + - `type: Literal["input_file"]` - - `"direct"` + The type of the input item. Always `input_file`. - - `"programmatic"` + - `"input_file"` - - `defer_loading: Optional[bool]` + - `detail: Optional[Literal["auto", "low", "high"]]` - Whether this function should be deferred and discovered via tool search. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `description: Optional[str]` + - `"auto"` - - `output_schema: Optional[Dict[str, object]]` + - `"low"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `"high"` - - `parameters: Optional[object]` + - `file_data: Optional[str]` - - `strict: Optional[bool]` + The content of the file to be sent to the model. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `file_id: Optional[str]` - - `class BetaCustomTool: …` + The ID of the file to be sent to the model. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `file_url: Optional[str]` - - `type: Literal["namespace"]` + The URL of the file to be sent to the model. - The type of the tool. Always `namespace`. + - `filename: Optional[str]` - - `"namespace"` + The name of the file to be sent to the model. - - `class BetaToolSearchTool: …` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Hosted or BYOT tool search configuration for deferred tools. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `type: Literal["tool_search"]` + - `mode: Literal["explicit"]` - The type of the tool. Always `tool_search`. + The breakpoint mode. Always `explicit`. - - `"tool_search"` + - `"explicit"` - - `description: Optional[str]` + - `role: Literal["user", "system", "developer"]` - Description shown to the model for a client-executed tool search tool. + The role of the message input. One of `user`, `system`, or `developer`. - - `execution: Optional[Literal["server", "client"]]` + - `"user"` - Whether tool search is executed by the server or by the client. + - `"system"` - - `"server"` + - `"developer"` - - `"client"` + - `type: Literal["message"]` - - `parameters: Optional[object]` + The type of the message input. Always set to `message`. - Parameter schema for a client-executed tool search tool. + - `"message"` - - `class BetaWebSearchPreviewTool: …` + - `agent: Optional[Agent]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The agent that produced this item. - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + - `agent_name: str` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The canonical name of the agent that produced this item. - - `"web_search_preview"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"web_search_preview_2025_03_11"` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `search_content_types: Optional[List[Literal["text", "image"]]]` + - `"in_progress"` - - `"text"` + - `"completed"` - - `"image"` + - `"incomplete"` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `class BetaResponseOutputMessage: …` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + An output message from the model. - - `"low"` + - `id: str` - - `"medium"` + The unique ID of the output message. - - `"high"` + - `content: List[Content]` - - `user_location: Optional[UserLocation]` + The content of the output message. - The user's location. + - `class BetaResponseOutputText: …` - - `type: Literal["approximate"]` + A text output from the model. - The type of location approximation. Always `approximate`. + - `annotations: List[Annotation]` - - `"approximate"` + The annotations of the text output. - - `city: Optional[str]` + - `class AnnotationFileCitation: …` - Free text input for the city of the user, e.g. `San Francisco`. + A citation to a file. - - `country: Optional[str]` + - `file_id: str` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The ID of the file. - - `region: Optional[str]` + - `filename: str` - Free text input for the region of the user, e.g. `California`. + The filename of the file cited. - - `timezone: Optional[str]` + - `index: int` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The index of the file in the list of files. - - `class BetaApplyPatchTool: …` + - `type: Literal["file_citation"]` - Allows the assistant to create, delete, or update files using unified diffs. + The type of the file citation. Always `file_citation`. - - `type: Literal["apply_patch"]` + - `"file_citation"` - The type of the tool. Always `apply_patch`. + - `class AnnotationURLCitation: …` - - `"apply_patch"` + A citation for a web resource used to generate a model response. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `end_index: int` - The tool invocation context(s). + The index of the last character of the URL citation in the message. - - `"direct"` + - `start_index: int` - - `"programmatic"` + The index of the first character of the URL citation in the message. - - `type: Literal["tool_search_output"]` + - `title: str` - The item type. Always `tool_search_output`. + The title of the web resource. - - `"tool_search_output"` + - `type: Literal["url_citation"]` - - `id: Optional[str]` + The type of the URL citation. Always `url_citation`. - The unique ID of this tool search output. + - `"url_citation"` - - `agent: Optional[Agent]` + - `url: str` - The agent that produced this item. + The URL of the web resource. - - `agent_name: str` + - `class AnnotationContainerFileCitation: …` - The canonical name of the agent that produced this item. + A citation for a container file used to generate a model response. - - `call_id: Optional[str]` + - `container_id: str` - The unique ID of the tool search call generated by the model. + The ID of the container file. - - `execution: Optional[Literal["server", "client"]]` + - `end_index: int` - Whether tool search was executed by the server or by the client. + The index of the last character of the container file citation in the message. - - `"server"` + - `file_id: str` - - `"client"` + The ID of the file. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `filename: str` - The status of the tool search output. + The filename of the container file cited. - - `"in_progress"` + - `start_index: int` - - `"completed"` + The index of the first character of the container file citation in the message. - - `"incomplete"` + - `type: Literal["container_file_citation"]` - - `class AdditionalTools: …` + The type of the container file citation. Always `container_file_citation`. - - `role: Literal["developer"]` + - `"container_file_citation"` - The role that provided the additional tools. Only `developer` is supported. + - `class AnnotationFilePath: …` - - `"developer"` + A path to a file. - - `tools: List[BetaTool]` + - `file_id: str` - A list of additional tools made available at this item. + The ID of the file. - - `class BetaFunctionTool: …` + - `index: int` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The index of the file in the list of files. - - `class BetaFileSearchTool: …` + - `type: Literal["file_path"]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The type of the file path. Always `file_path`. - - `class BetaComputerTool: …` + - `"file_path"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `text: str` - - `class BetaComputerUsePreviewTool: …` + The text output from the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: Literal["output_text"]` - - `class BetaWebSearchTool: …` + The type of the output text. Always `output_text`. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"output_text"` - - `class Mcp: …` + - `logprobs: Optional[List[Logprob]]` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `token: str` - - `class CodeInterpreter: …` + - `bytes: List[int]` - A tool that runs Python code to help generate a response to a prompt. + - `logprob: float` - - `class ProgrammaticToolCalling: …` + - `top_logprobs: List[LogprobTopLogprob]` - - `class ImageGeneration: …` + - `token: str` - A tool that generates images using the GPT image models. + - `bytes: List[int]` - - `class LocalShell: …` + - `logprob: float` - A tool that allows the model to execute shell commands in a local environment. + - `class BetaResponseOutputRefusal: …` - - `class BetaFunctionShellTool: …` + A refusal from the model. - A tool that allows the model to execute shell commands. + - `refusal: str` - - `class BetaCustomTool: …` + The refusal explanation from the model. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: Literal["refusal"]` - - `class BetaNamespaceTool: …` + The type of the refusal. Always `refusal`. - Groups function/custom tools under a shared namespace. + - `"refusal"` - - `class BetaToolSearchTool: …` + - `role: Literal["assistant"]` - Hosted or BYOT tool search configuration for deferred tools. + The role of the output message. Always `assistant`. - - `class BetaWebSearchPreviewTool: …` + - `"assistant"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `status: Literal["in_progress", "completed", "incomplete"]` - - `class BetaApplyPatchTool: …` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Allows the assistant to create, delete, or update files using unified diffs. + - `"in_progress"` - - `type: Literal["additional_tools"]` + - `"completed"` - The item type. Always `additional_tools`. + - `"incomplete"` - - `"additional_tools"` + - `type: Literal["message"]` - - `id: Optional[str]` + The type of the output message. Always `message`. - The unique ID of this additional tools item. + - `"message"` - - `agent: Optional[AdditionalToolsAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -86339,36 +97346,49 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseReasoningItem: …` + - `phase: Optional[Literal["commentary", "final_answer"]]` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `class BetaResponseFileSearchToolCall: …` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: str` - The unique identifier of the reasoning content. + The unique ID of the file search tool call. - - `summary: List[Summary]` + - `queries: List[str]` - Reasoning summary content. + The queries used to search for files. - - `text: str` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - A summary of the reasoning output from the model so far. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `type: Literal["summary_text"]` + - `"in_progress"` - The type of the object. Always `summary_text`. + - `"searching"` - - `"summary_text"` + - `"completed"` - - `type: Literal["reasoning"]` + - `"incomplete"` - The type of the object. Always `reasoning`. + - `"failed"` - - `"reasoning"` + - `type: Literal["file_search_call"]` + + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` - `agent: Optional[Agent]` @@ -86378,314 +97398,323 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `content: Optional[List[Content]]` + - `results: Optional[List[Result]]` - Reasoning text content. + The results of the file search tool call. - - `text: str` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - The reasoning text from the model. + 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, booleans, or numbers. - - `type: Literal["reasoning_text"]` + - `str` - The type of the reasoning text. Always `reasoning_text`. + - `float` - - `"reasoning_text"` + - `bool` - - `encrypted_content: Optional[str]` + - `file_id: Optional[str]` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The unique ID of the file. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `filename: Optional[str]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The name of the file. - - `"in_progress"` + - `score: Optional[float]` - - `"completed"` + The relevance score of the file - a value between 0 and 1. - - `"incomplete"` + - `text: Optional[str]` - - `class BetaResponseCompactionItemParam: …` + The text that was retrieved from the file. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `class BetaResponseComputerToolCall: …` - - `encrypted_content: str` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The encrypted content of the compaction summary. + - `id: str` - - `type: Literal["compaction"]` + The unique ID of the computer call. - The type of the item. Always `compaction`. + - `call_id: str` - - `"compaction"` + An identifier used when responding to the tool call with output. - - `id: Optional[str]` + - `pending_safety_checks: List[PendingSafetyCheck]` - The ID of the compaction item. + The pending safety checks for the computer call. - - `agent: Optional[Agent]` + - `id: str` - The agent that produced this item. + The ID of the pending safety check. - - `agent_name: str` + - `code: Optional[str]` - The canonical name of the agent that produced this item. + The type of the pending safety check. - - `class ImageGenerationCall: …` + - `message: Optional[str]` - An image generation request made by the model. + Details about the pending safety check. - - `id: str` + - `status: Literal["in_progress", "completed", "incomplete"]` - The unique ID of the image generation call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `result: Optional[str]` + - `"in_progress"` - The generated image encoded in base64. + - `"completed"` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `"incomplete"` - The status of the image generation call. + - `type: Literal["computer_call"]` - - `"in_progress"` + The type of the computer call. Always `computer_call`. - - `"completed"` + - `"computer_call"` - - `"generating"` + - `action: Optional[BetaComputerAction]` - - `"failed"` + A click action. - - `type: Literal["image_generation_call"]` + - `class Click: …` - The type of the image generation call. Always `image_generation_call`. + A click action. - - `"image_generation_call"` + - `button: Literal["left", "right", "wheel", 2 more]` - - `agent: Optional[ImageGenerationCallAgent]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The agent that produced this item. + - `"left"` - - `agent_name: str` + - `"right"` - The canonical name of the agent that produced this item. + - `"wheel"` - - `class BetaResponseCodeInterpreterToolCall: …` + - `"back"` - A tool call to run code. + - `"forward"` - - `id: str` + - `type: Literal["click"]` - The unique ID of the code interpreter tool call. + Specifies the event type. For a click action, this property is always `click`. - - `code: Optional[str]` + - `"click"` - The code to run, or null if not available. + - `x: int` - - `container_id: str` + The x-coordinate where the click occurred. - The ID of the container used to run the code. + - `y: int` - - `outputs: Optional[List[Output]]` + The y-coordinate where the click occurred. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `keys: Optional[List[str]]` - - `class OutputLogs: …` + The keys being held while clicking. - The logs output from the code interpreter. + - `class DoubleClick: …` - - `logs: str` + A double click action. - The logs output from the code interpreter. + - `keys: Optional[List[str]]` - - `type: Literal["logs"]` + The keys being held while double-clicking. - The type of the output. Always `logs`. + - `type: Literal["double_click"]` - - `"logs"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `class OutputImage: …` + - `"double_click"` - The image output from the code interpreter. + - `x: int` - - `type: Literal["image"]` + The x-coordinate where the double click occurred. - The type of the output. Always `image`. + - `y: int` - - `"image"` + The y-coordinate where the double click occurred. - - `url: str` + - `class Drag: …` - The URL of the image output from the code interpreter. + A drag action. - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + - `path: List[DragPath]` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"in_progress"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"completed"` + - `x: int` - - `"incomplete"` + The x-coordinate. - - `"interpreting"` + - `y: int` - - `"failed"` + The y-coordinate. - - `type: Literal["code_interpreter_call"]` + - `type: Literal["drag"]` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"code_interpreter_call"` + - `"drag"` - - `agent: Optional[Agent]` + - `keys: Optional[List[str]]` - The agent that produced this item. + The keys being held while dragging the mouse. - - `agent_name: str` + - `class Keypress: …` - The canonical name of the agent that produced this item. + A collection of keypresses the model would like to perform. - - `class LocalShellCall: …` + - `keys: List[str]` - A tool call to run a command on the local shell. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `id: str` + - `type: Literal["keypress"]` - The unique ID of the local shell call. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `action: LocalShellCallAction` + - `"keypress"` - Execute a shell command on the server. + - `class Move: …` - - `command: List[str]` + A mouse move action. - The command to run. + - `type: Literal["move"]` - - `env: Dict[str, str]` + Specifies the event type. For a move action, this property is always set to `move`. - Environment variables to set for the command. + - `"move"` - - `type: Literal["exec"]` + - `x: int` - The type of the local shell action. Always `exec`. + The x-coordinate to move to. - - `"exec"` + - `y: int` - - `timeout_ms: Optional[int]` + The y-coordinate to move to. - Optional timeout in milliseconds for the command. + - `keys: Optional[List[str]]` - - `user: Optional[str]` + The keys being held while moving the mouse. - Optional user to run the command as. + - `class Screenshot: …` - - `working_directory: Optional[str]` + A screenshot action. - Optional working directory to run the command in. + - `type: Literal["screenshot"]` - - `call_id: str` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The unique ID of the local shell tool call generated by the model. + - `"screenshot"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `class Scroll: …` - The status of the local shell call. + A scroll action. - - `"in_progress"` + - `scroll_x: int` - - `"completed"` + The horizontal scroll distance. - - `"incomplete"` + - `scroll_y: int` - - `type: Literal["local_shell_call"]` + The vertical scroll distance. - The type of the local shell call. Always `local_shell_call`. + - `type: Literal["scroll"]` - - `"local_shell_call"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `agent: Optional[LocalShellCallAgent]` + - `"scroll"` - The agent that produced this item. + - `x: int` - - `agent_name: str` + The x-coordinate where the scroll occurred. - The canonical name of the agent that produced this item. + - `y: int` - - `class LocalShellCallOutput: …` + The y-coordinate where the scroll occurred. - The output of a local shell tool call. + - `keys: Optional[List[str]]` - - `id: str` + The keys being held while scrolling. - The unique ID of the local shell tool call generated by the model. + - `class Type: …` - - `output: str` + An action to type in text. - A JSON string of the output of the local shell tool call. + - `text: str` - - `type: Literal["local_shell_call_output"]` + The text to type. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `type: Literal["type"]` - - `"local_shell_call_output"` + Specifies the event type. For a type action, this property is always set to `type`. - - `agent: Optional[LocalShellCallOutputAgent]` + - `"type"` - The agent that produced this item. + - `class Wait: …` - - `agent_name: str` + A wait action. - The canonical name of the agent that produced this item. + - `type: Literal["wait"]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + Specifies the event type. For a wait action, this property is always set to `wait`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"wait"` - - `"in_progress"` + - `actions: Optional[BetaComputerActionList]` - - `"completed"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"incomplete"` + - `class Click: …` - - `class ShellCall: …` + A click action. - A tool representing a request to execute one or more shell commands. + - `class DoubleClick: …` - - `action: ShellCallAction` + A double click action. - The shell commands and limits that describe how to run the tool call. + - `class Drag: …` - - `commands: List[str]` + A drag action. - Ordered shell commands for the execution environment to run. + - `class Keypress: …` - - `max_output_length: Optional[int]` + A collection of keypresses the model would like to perform. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `class Move: …` - - `timeout_ms: Optional[int]` + A mouse move action. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `class Screenshot: …` - - `call_id: str` + A screenshot action. - The unique ID of the shell tool call generated by the model. + - `class Scroll: …` - - `type: Literal["shell_call"]` + A scroll action. - The type of the item. Always `shell_call`. + - `class Type: …` - - `"shell_call"` + An action to type in text. - - `id: Optional[str]` + - `class Wait: …` - The unique ID of the shell tool call. Populated when this item is returned via API. + A wait action. - - `agent: Optional[ShellCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -86693,233 +97722,264 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ShellCallCaller]` + - `class BetaResponseComputerToolCallOutputItem: …` - The execution context that produced this tool call. + - `id: str` - - `class ShellCallCallerDirect: …` + The unique ID of the computer call tool output. - - `type: Literal["direct"]` + - `call_id: str` - The caller type. Always `direct`. + The ID of the computer tool call that produced the output. - - `"direct"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `class ShellCallCallerProgram: …` + A computer screenshot image used with the computer use tool. - - `caller_id: str` + - `type: Literal["computer_screenshot"]` - The call ID of the program item that produced this tool call. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `type: Literal["program"]` + - `"computer_screenshot"` - The caller type. Always `program`. + - `file_id: Optional[str]` - - `"program"` + The identifier of an uploaded file that contains the screenshot. - - `environment: Optional[ShellCallEnvironment]` + - `image_url: Optional[str]` - The environment to execute the shell commands in. + The URL of the screenshot image. - - `class BetaLocalEnvironment: …` + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - `class BetaContainerReference: …` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"completed"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"incomplete"` + + - `"failed"` - `"in_progress"` - - `"completed"` + - `type: Literal["computer_call_output"]` - - `"incomplete"` + The type of the computer tool call output. Always `computer_call_output`. - - `class ShellCallOutput: …` + - `"computer_call_output"` - The streamed output items emitted by a shell tool call. + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - - `call_id: str` + The safety checks reported by the API that have been acknowledged by the + developer. - The unique ID of the shell tool call generated by the model. + - `id: str` - - `output: List[BetaResponseFunctionShellCallOutputContent]` + The ID of the pending safety check. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `code: Optional[str]` - - `outcome: Outcome` + The type of the pending safety check. - The exit or timeout outcome associated with this shell call. + - `message: Optional[str]` - - `class OutcomeTimeout: …` + Details about the pending safety check. - Indicates that the shell call exceeded its configured time limit. + - `agent: Optional[Agent]` - - `type: Literal["timeout"]` + The agent that produced this item. - The outcome type. Always `timeout`. + - `agent_name: str` - - `"timeout"` + The canonical name of the agent that produced this item. - - `class OutcomeExit: …` + - `created_by: Optional[str]` - Indicates that the shell commands finished and returned an exit code. + The identifier of the actor that created the item. - - `exit_code: int` + - `class BetaResponseFunctionWebSearch: …` - The exit code returned by the shell process. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `type: Literal["exit"]` + - `id: str` - The outcome type. Always `exit`. + The unique ID of the web search tool call. - - `"exit"` + - `action: Action` - - `stderr: str` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - Captured stderr output for the shell call. + - `class ActionSearch: …` - - `stdout: str` + Action type "search" - Performs a web search query. - Captured stdout output for the shell call. + - `type: Literal["search"]` - - `type: Literal["shell_call_output"]` + The action type. - The type of the item. Always `shell_call_output`. + - `"search"` - - `"shell_call_output"` + - `queries: Optional[List[str]]` - - `id: Optional[str]` + The search queries. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `query: Optional[str]` - - `agent: Optional[ShellCallOutputAgent]` + The search query. - The agent that produced this item. + - `sources: Optional[List[ActionSearchSource]]` - - `agent_name: str` + The sources used in the search. - The canonical name of the agent that produced this item. + - `type: Literal["url"]` - - `caller: Optional[ShellCallOutputCaller]` + The type of source. Always `url`. - The execution context that produced this tool call. + - `"url"` - - `class ShellCallOutputCallerDirect: …` + - `url: str` - - `type: Literal["direct"]` + The URL of the source. - The caller type. Always `direct`. + - `class ActionOpenPage: …` - - `"direct"` + Action type "open_page" - Opens a specific URL from search results. - - `class ShellCallOutputCallerProgram: …` + - `type: Literal["open_page"]` - - `caller_id: str` + The action type. - The call ID of the program item that produced this tool call. + - `"open_page"` - - `type: Literal["program"]` + - `url: Optional[str]` - The caller type. Always `program`. + The URL opened by the model. - - `"program"` + - `class ActionFindInPage: …` - - `max_output_length: Optional[int]` + Action type "find_in_page": Searches for a pattern within a loaded page. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `pattern: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The pattern or text to search for within the page. - The status of the shell call output. + - `type: Literal["find_in_page"]` + + The action type. + + - `"find_in_page"` + + - `url: str` + + The URL of the page searched for the pattern. + + - `status: Literal["in_progress", "searching", "completed", "failed"]` + + The status of the web search tool call. - `"in_progress"` + - `"searching"` + - `"completed"` - - `"incomplete"` + - `"failed"` - - `class ApplyPatchCall: …` + - `type: Literal["web_search_call"]` - A tool call representing a request to create, delete, or update files using diff patches. + The type of the web search tool call. Always `web_search_call`. - - `call_id: str` + - `"web_search_call"` - The unique ID of the apply patch tool call generated by the model. + - `agent: Optional[Agent]` - - `operation: ApplyPatchCallOperation` + The agent that produced this item. - The specific create, delete, or update instruction for the apply_patch tool call. + - `agent_name: str` - - `class ApplyPatchCallOperationCreateFile: …` + The canonical name of the agent that produced this item. - Instruction for creating a new file via the apply_patch tool. + - `class BetaResponseFunctionToolCallItem: …` - - `diff: str` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - Unified diff content to apply when creating the file. + - `id: str` - - `path: str` + The unique ID of the function tool call. - Path of the file to create relative to the workspace root. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["create_file"]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The operation type. Always `create_file`. + - `"in_progress"` - - `"create_file"` + - `"completed"` - - `class ApplyPatchCallOperationDeleteFile: …` + - `"incomplete"` - Instruction for deleting an existing file via the apply_patch tool. + - `created_by: Optional[str]` - - `path: str` + The identifier of the actor that created the item. - Path of the file to delete relative to the workspace root. + - `class BetaResponseFunctionToolCallOutputItem: …` - - `type: Literal["delete_file"]` + - `id: str` - The operation type. Always `delete_file`. + The unique ID of the function call tool output. - - `"delete_file"` + - `call_id: str` - - `class ApplyPatchCallOperationUpdateFile: …` + The unique ID of the function tool call generated by the model. - Instruction for updating an existing file via the apply_patch tool. + - `output: Union[str, List[OutputOutputContentList]]` - - `diff: str` + The output from the function call generated by your code. + Can be a string or an list of output content. - Unified diff content to apply to the existing file. + - `str` - - `path: str` + A string of the output of the function call. - Path of the file to update relative to the workspace root. + - `List[OutputOutputContentList]` - - `type: Literal["update_file"]` + Text, image, or file output of the function call. - The operation type. Always `update_file`. + - `class BetaResponseInputText: …` - - `"update_file"` + A text input to the model. - - `status: Literal["in_progress", "completed"]` + - `class BetaResponseInputImage: …` - The status of the apply patch tool call. One of `in_progress` or `completed`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` - `"completed"` - - `type: Literal["apply_patch_call"]` - - The type of the item. Always `apply_patch_call`. + - `"incomplete"` - - `"apply_patch_call"` + - `type: Literal["function_call_output"]` - - `id: Optional[str]` + The type of the function tool call output. Always `function_call_output`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"function_call_output"` - - `agent: Optional[ApplyPatchCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -86927,11 +97987,11 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ApplyPatchCallCaller]` + - `caller: Optional[Caller]` The execution context that produced this tool call. - - `class ApplyPatchCallCallerDirect: …` + - `class CallerDirect: …` - `type: Literal["direct"]` @@ -86939,7 +97999,7 @@ print(compacted_response) - `"direct"` - - `class ApplyPatchCallCallerProgram: …` + - `class CallerProgram: …` - `caller_id: str` @@ -86951,145 +98011,147 @@ print(compacted_response) - `"program"` - - `class ApplyPatchCallOutput: …` + - `created_by: Optional[str]` - The streamed output emitted by an apply patch tool call. + The identifier of the actor that created the item. - - `call_id: str` + - `class AgentMessage: …` - The unique ID of the apply patch tool call generated by the model. + - `id: str` - - `status: Literal["completed", "failed"]` + The unique ID of the agent message. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `author: str` - - `"completed"` + The sending agent identity. - - `"failed"` + - `content: List[AgentMessageContent]` - - `type: Literal["apply_patch_call_output"]` + Encrypted content sent between agents. - The type of the item. Always `apply_patch_call_output`. + - `class BetaResponseInputText: …` - - `"apply_patch_call_output"` + A text input to the model. - - `id: Optional[str]` + - `class BetaResponseOutputText: …` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + A text output from the model. - - `agent: Optional[ApplyPatchCallOutputAgent]` + - `class AgentMessageContentText: …` - The agent that produced this item. + A text content. - - `agent_name: str` + - `text: str` - The canonical name of the agent that produced this item. + - `type: Literal["text"]` - - `caller: Optional[ApplyPatchCallOutputCaller]` + - `"text"` - The execution context that produced this tool call. + - `class AgentMessageContentSummaryText: …` - - `class ApplyPatchCallOutputCallerDirect: …` + A summary text from the model. - - `type: Literal["direct"]` + - `text: str` - The caller type. Always `direct`. + A summary of the reasoning output from the model so far. - - `"direct"` + - `type: Literal["summary_text"]` - - `class ApplyPatchCallOutputCallerProgram: …` + The type of the object. Always `summary_text`. - - `caller_id: str` + - `"summary_text"` - The call ID of the program item that produced this tool call. + - `class AgentMessageContentReasoningText: …` - - `type: Literal["program"]` + Reasoning text from the model. - The caller type. Always `program`. + - `text: str` - - `"program"` + The reasoning text from the model. - - `output: Optional[str]` + - `type: Literal["reasoning_text"]` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The type of the reasoning text. Always `reasoning_text`. - - `class McpListTools: …` + - `"reasoning_text"` - A list of tools available on an MCP server. + - `class BetaResponseOutputRefusal: …` - - `id: str` + A refusal from the model. - The unique ID of the list. + - `class BetaResponseInputImage: …` - - `server_label: str` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The label of the MCP server. + - `class AgentMessageContentComputerScreenshot: …` - - `tools: List[McpListToolsTool]` + A screenshot of a computer. - The tools available on the server. + - `detail: Literal["low", "high", "auto", "original"]` - - `input_schema: object` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The JSON schema describing the tool's input. + - `"low"` - - `name: str` + - `"high"` - The name of the tool. + - `"auto"` - - `annotations: Optional[object]` + - `"original"` - Additional annotations about the tool. + - `file_id: Optional[str]` - - `description: Optional[str]` + The identifier of an uploaded file that contains the screenshot. - The description of the tool. + - `image_url: Optional[str]` - - `type: Literal["mcp_list_tools"]` + The URL of the screenshot image. - The type of the item. Always `mcp_list_tools`. + - `type: Literal["computer_screenshot"]` - - `"mcp_list_tools"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `agent: Optional[McpListToolsAgent]` + - `"computer_screenshot"` - The agent that produced this item. + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - - `agent_name: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The canonical name of the agent that produced this item. + - `mode: Literal["explicit"]` - - `error: Optional[str]` + The breakpoint mode. Always `explicit`. - Error message if the server could not list tools. + - `"explicit"` - - `class McpApprovalRequest: …` + - `class BetaResponseInputFile: …` - A request for human approval of a tool invocation. + A file input to the model. - - `id: str` + - `class AgentMessageContentEncryptedContent: …` - The unique ID of the approval request. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `arguments: str` + - `encrypted_content: str` - A JSON string of arguments for the tool. + Opaque encrypted content. - - `name: str` + - `type: Literal["encrypted_content"]` - The name of the tool to run. + The type of the input item. Always `encrypted_content`. - - `server_label: str` + - `"encrypted_content"` - The label of the MCP server making the request. + - `recipient: str` - - `type: Literal["mcp_approval_request"]` + The destination agent identity. - The type of the item. Always `mcp_approval_request`. + - `type: Literal["agent_message"]` - - `"mcp_approval_request"` + The type of the item. Always `agent_message`. - - `agent: Optional[McpApprovalRequestAgent]` + - `"agent_message"` + + - `agent: Optional[AgentMessageAgent]` The agent that produced this item. @@ -87097,29 +98159,43 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class McpApprovalResponse: …` + - `class MultiAgentCall: …` - A response to an MCP approval request. + - `id: str` - - `approval_request_id: str` + The unique ID of the multi-agent call item. - The ID of the approval request being answered. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `approve: bool` + The multi-agent action to execute. - Whether the request was approved. + - `"spawn_agent"` - - `type: Literal["mcp_approval_response"]` + - `"interrupt_agent"` - The type of the item. Always `mcp_approval_response`. + - `"list_agents"` - - `"mcp_approval_response"` + - `"send_message"` - - `id: Optional[str]` + - `"followup_task"` - The unique ID of the approval response + - `"wait_agent"` - - `agent: Optional[McpApprovalResponseAgent]` + - `arguments: str` + + The JSON string of arguments generated for the action. + + - `call_id: str` + + The unique ID linking this call to its output. + + - `type: Literal["multi_agent_call"]` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `"multi_agent_call"` + + - `agent: Optional[MultiAgentCallAgent]` The agent that produced this item. @@ -87127,37 +98203,57 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `reason: Optional[str]` + - `class MultiAgentCallOutput: …` - Optional reason for the decision. + - `id: str` - - `class McpCall: …` + The unique ID of the multi-agent call output item. - An invocation of a tool on an MCP server. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `id: str` + The multi-agent action that produced this result. - The unique ID of the tool call. + - `"spawn_agent"` - - `arguments: str` + - `"interrupt_agent"` - A JSON string of the arguments passed to the tool. + - `"list_agents"` - - `name: str` + - `"send_message"` - The name of the tool that was run. + - `"followup_task"` - - `server_label: str` + - `"wait_agent"` - The label of the MCP server running the tool. + - `call_id: str` - - `type: Literal["mcp_call"]` + The unique ID of the multi-agent call. - The type of the item. Always `mcp_call`. + - `output: List[BetaResponseOutputText]` - - `"mcp_call"` + Text output returned by the multi-agent action. - - `agent: Optional[McpCallAgent]` + - `annotations: List[Annotation]` + + The annotations of the text output. + + - `text: str` + + The text output from the model. + + - `type: Literal["output_text"]` + + The type of the output text. Always `output_text`. + + - `logprobs: Optional[List[Logprob]]` + + - `type: Literal["multi_agent_call_output"]` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `"multi_agent_call_output"` + + - `agent: Optional[MultiAgentCallOutputAgent]` The agent that produced this item. @@ -87165,22 +98261,31 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `approval_request_id: Optional[str]` + - `class BetaResponseToolSearchCall: …` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `id: str` - - `error: Optional[str]` + The unique ID of the tool search call item. - The error from the tool call, if any. + - `arguments: object` - - `output: Optional[str]` + Arguments used for the tool search call. - The output from the tool call. + - `call_id: Optional[str]` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + The unique ID of the tool search call generated by the model. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `execution: Literal["server", "client"]` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the tool search call item that was recorded. - `"in_progress"` @@ -87188,1123 +98293,1149 @@ print(compacted_response) - `"incomplete"` - - `"calling"` + - `type: Literal["tool_search_call"]` - - `"failed"` + The type of the item. Always `tool_search_call`. - - `class BetaResponseCustomToolCallOutput: …` + - `"tool_search_call"` - The output of a custom tool call from your code, being sent back to the model. + - `agent: Optional[Agent]` - - `call_id: str` + The agent that produced this item. - The call ID, used to map this custom tool call output to a custom tool call. + - `agent_name: str` - - `output: Union[str, List[OutputOutputContentList]]` + The canonical name of the agent that produced this item. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `created_by: Optional[str]` - - `str` + The identifier of the actor that created the item. - A string of the output of the custom tool call. + - `class BetaResponseToolSearchOutputItem: …` - - `List[OutputOutputContentList]` + - `id: str` - Text, image, or file output of the custom tool call. + The unique ID of the tool search output item. - - `class BetaResponseInputText: …` + - `call_id: Optional[str]` - A text input to the model. + The unique ID of the tool search call generated by the model. - - `class BetaResponseInputImage: …` + - `execution: Literal["server", "client"]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Whether tool search was executed by the server or by the client. - - `class BetaResponseInputFile: …` + - `"server"` - A file input to the model. + - `"client"` - - `type: Literal["custom_tool_call_output"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The type of the custom tool call output. Always `custom_tool_call_output`. + The status of the tool search output item that was recorded. - - `"custom_tool_call_output"` + - `"in_progress"` - - `id: Optional[str]` + - `"completed"` - The unique ID of the custom tool call output in the OpenAI platform. + - `"incomplete"` - - `agent: Optional[Agent]` + - `tools: List[BetaTool]` - The agent that produced this item. + The loaded tool definitions returned by tool search. - - `agent_name: str` + - `class BetaFunctionTool: …` - The canonical name of the agent that produced this item. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `caller: Optional[Caller]` + - `name: str` - The execution context that produced this tool call. + The name of the function to call. - - `class CallerDirect: …` + - `parameters: Optional[Dict[str, object]]` - - `type: Literal["direct"]` + A JSON schema object describing the parameters of the function. - The caller type. Always `direct`. + - `strict: Optional[bool]` - - `"direct"` + Whether strict parameter validation is enforced for this function tool. - - `class CallerProgram: …` + - `type: Literal["function"]` - - `caller_id: str` + The type of the function tool. Always `function`. - The call ID of the program item that produced this tool call. + - `"function"` - - `type: Literal["program"]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The caller type. Always `program`. + The tool invocation context(s). - - `"program"` + - `"direct"` - - `class BetaResponseCustomToolCall: …` + - `"programmatic"` - A call to a custom tool created by the model. + - `defer_loading: Optional[bool]` - - `call_id: str` + Whether this function is deferred and loaded via tool search. - An identifier used to map this custom tool call to a tool call output. + - `description: Optional[str]` - - `input: str` + A description of the function. Used by the model to determine whether or not to call the function. - The input for the custom tool call generated by the model. + - `output_schema: Optional[Dict[str, object]]` - - `name: str` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The name of the custom tool being called. + - `class BetaFileSearchTool: …` - - `type: Literal["custom_tool_call"]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The type of the custom tool call. Always `custom_tool_call`. + - `type: Literal["file_search"]` - - `"custom_tool_call"` + The type of the file search tool. Always `file_search`. - - `id: Optional[str]` + - `"file_search"` - The unique ID of the custom tool call in the OpenAI platform. + - `vector_store_ids: List[str]` - - `agent: Optional[Agent]` + The IDs of the vector stores to search. - The agent that produced this item. + - `filters: Optional[Filters]` - - `agent_name: str` + A filter to apply. - The canonical name of the agent that produced this item. + - `class FiltersComparisonFilter: …` - - `caller: Optional[Caller]` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The execution context that produced this tool call. + - `key: str` - - `class CallerDirect: …` + The key to compare against the value. - - `type: Literal["direct"]` + - `type: Literal["eq", "ne", "gt", 5 more]` - - `"direct"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `class CallerProgram: …` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `caller_id: str` + - `"eq"` - The call ID of the program item that produced this tool call. + - `"ne"` - - `type: Literal["program"]` + - `"gt"` + + - `"gte"` - - `"program"` + - `"lt"` - - `namespace: Optional[str]` + - `"lte"` - The namespace of the custom tool being called. + - `"in"` - - `class CompactionTrigger: …` + - `"nin"` - Compacts the current context. Must be the final input item. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `type: Literal["compaction_trigger"]` + The value to compare against the attribute key; supports string, number, or boolean types. - The type of the item. Always `compaction_trigger`. + - `str` - - `"compaction_trigger"` + - `float` - - `agent: Optional[CompactionTriggerAgent]` + - `bool` - The agent that produced this item. + - `List[Union[str, float]]` - - `agent_name: str` + - `str` - The canonical name of the agent that produced this item. + - `float` - - `class ItemReference: …` + - `class FiltersCompoundFilter: …` - An internal identifier for an item to reference. + Combine multiple filters using `and` or `or`. - - `id: str` + - `filters: List[FiltersCompoundFilterFilter]` - The ID of the item to reference. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `agent: Optional[ItemReferenceAgent]` + - `class FiltersCompoundFilterFilterComparisonFilter: …` - The agent that produced this item. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `agent_name: str` + - `key: str` - The canonical name of the agent that produced this item. + The key to compare against the value. - - `type: Optional[Literal["item_reference"]]` + - `type: Literal["eq", "ne", "gt", 5 more]` - The type of item to reference. Always `item_reference`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"item_reference"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `class Program: …` + - `"eq"` - - `id: str` + - `"ne"` - The unique ID of this program item. + - `"gt"` - - `call_id: str` + - `"gte"` - The stable call ID of the program item. + - `"lt"` - - `code: str` + - `"lte"` - The JavaScript source executed by programmatic tool calling. + - `"in"` - - `fingerprint: str` + - `"nin"` - Opaque program replay fingerprint that must be round-tripped. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `type: Literal["program"]` + The value to compare against the attribute key; supports string, number, or boolean types. - The item type. Always `program`. + - `str` - - `"program"` + - `float` - - `agent: Optional[ProgramAgent]` + - `bool` - The agent that produced this item. + - `List[Union[str, float]]` - - `agent_name: str` + - `str` - The canonical name of the agent that produced this item. + - `float` - - `class ProgramOutput: …` + - `object` - - `id: str` + - `type: Literal["and", "or"]` - The unique ID of this program output item. + Type of operation: `and` or `or`. - - `call_id: str` + - `"and"` - The call ID of the program item. + - `"or"` - - `result: str` + - `max_num_results: Optional[int]` - The result produced by the program item. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `status: Literal["completed", "incomplete"]` + - `ranking_options: Optional[RankingOptions]` - The terminal status of the program output. + Ranking options for search. - - `"completed"` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - `"incomplete"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `type: Literal["program_output"]` + - `embedding_weight: float` - The item type. Always `program_output`. + The weight of the embedding in the reciprocal ranking fusion. - - `"program_output"` + - `text_weight: float` - - `agent: Optional[ProgramOutputAgent]` + The weight of the text in the reciprocal ranking fusion. - The agent that produced this item. + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - - `agent_name: str` + The ranker to use for the file search. - The canonical name of the agent that produced this item. + - `"auto"` - - `metadata: Optional[Dict[str, str]]` + - `"default-2024-11-15"` - 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. + - `score_threshold: Optional[float]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` + - `class BetaComputerTool: …` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` + - `type: Literal["computer"]` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + The type of the computer tool. Always `computer`. - - `"gpt-5.6-sol"` + - `"computer"` - - `"gpt-5.6-terra"` + - `class BetaComputerUsePreviewTool: …` - - `"gpt-5.6-luna"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-5.4"` + - `display_height: int` - - `"gpt-5.4-mini"` + The height of the computer display. - - `"gpt-5.4-nano"` + - `display_width: int` - - `"gpt-5.4-mini-2026-03-17"` + The width of the computer display. - - `"gpt-5.4-nano-2026-03-17"` + - `environment: Literal["windows", "mac", "linux", 2 more]` - - `"gpt-5.3-chat-latest"` + The type of computer environment to control. - - `"gpt-5.2"` + - `"windows"` - - `"gpt-5.2-2025-12-11"` + - `"mac"` - - `"gpt-5.2-chat-latest"` + - `"linux"` - - `"gpt-5.2-pro"` + - `"ubuntu"` - - `"gpt-5.2-pro-2025-12-11"` + - `"browser"` - - `"gpt-5.1"` + - `type: Literal["computer_use_preview"]` - - `"gpt-5.1-2025-11-13"` + The type of the computer use tool. Always `computer_use_preview`. - - `"gpt-5.1-codex"` + - `"computer_use_preview"` - - `"gpt-5.1-mini"` + - `class BetaWebSearchTool: …` - - `"gpt-5.1-chat-latest"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"gpt-5"` + - `type: Literal["web_search", "web_search_2025_08_26"]` - - `"gpt-5-mini"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"gpt-5-nano"` + - `"web_search"` - - `"gpt-5-2025-08-07"` + - `"web_search_2025_08_26"` - - `"gpt-5-mini-2025-08-07"` + - `filters: Optional[Filters]` - - `"gpt-5-nano-2025-08-07"` + Filters for the search. - - `"gpt-5-chat-latest"` + - `allowed_domains: Optional[List[str]]` - - `"gpt-4.1"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `"gpt-4.1-mini"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"gpt-4.1-nano"` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `"gpt-4.1-2025-04-14"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `"gpt-4.1-mini-2025-04-14"` + - `"low"` - - `"gpt-4.1-nano-2025-04-14"` + - `"medium"` - - `"o4-mini"` + - `"high"` - - `"o4-mini-2025-04-16"` + - `user_location: Optional[UserLocation]` - - `"o3"` + The approximate location of the user. - - `"o3-2025-04-16"` + - `city: Optional[str]` - - `"o3-mini"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"o3-mini-2025-01-31"` + - `country: Optional[str]` - - `"o1"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"o1-2024-12-17"` + - `region: Optional[str]` - - `"o1-preview"` + Free text input for the region of the user, e.g. `California`. - - `"o1-preview-2024-09-12"` + - `timezone: Optional[str]` - - `"o1-mini"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"o1-mini-2024-09-12"` + - `type: Optional[Literal["approximate"]]` - - `"gpt-4o"` + The type of location approximation. Always `approximate`. - - `"gpt-4o-2024-11-20"` + - `"approximate"` - - `"gpt-4o-2024-08-06"` + - `class Mcp: …` - - `"gpt-4o-2024-05-13"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"gpt-4o-audio-preview"` + - `server_label: str` - - `"gpt-4o-audio-preview-2024-10-01"` + A label for this MCP server, used to identify it in tool calls. - - `"gpt-4o-audio-preview-2024-12-17"` + - `type: Literal["mcp"]` - - `"gpt-4o-audio-preview-2025-06-03"` + The type of the MCP tool. Always `mcp`. - - `"gpt-4o-mini-audio-preview"` + - `"mcp"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"gpt-4o-search-preview"` + The tool invocation context(s). - - `"gpt-4o-mini-search-preview"` + - `"direct"` - - `"gpt-4o-search-preview-2025-03-11"` + - `"programmatic"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `allowed_tools: Optional[McpAllowedTools]` - - `"chatgpt-4o-latest"` + List of allowed tool names or a filter object. - - `"codex-mini-latest"` + - `List[str]` - - `"gpt-4o-mini"` + A string array of allowed tool names - - `"gpt-4o-mini-2024-07-18"` + - `class McpAllowedToolsMcpToolFilter: …` - - `"gpt-4-turbo"` + A filter object to specify which tools are allowed. - - `"gpt-4-turbo-2024-04-09"` + - `read_only: Optional[bool]` - - `"gpt-4-0125-preview"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"gpt-4-turbo-preview"` + - `tool_names: Optional[List[str]]` - - `"gpt-4-1106-preview"` + List of allowed tool names. - - `"gpt-4-vision-preview"` + - `authorization: Optional[str]` - - `"gpt-4"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `"gpt-4-0314"` + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `"gpt-4-0613"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `"gpt-4-32k"` + Currently supported `connector_id` values are: - - `"gpt-4-32k-0314"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `"gpt-4-32k-0613"` + - `"connector_dropbox"` - - `"gpt-3.5-turbo"` + - `"connector_gmail"` - - `"gpt-3.5-turbo-16k"` + - `"connector_googlecalendar"` - - `"gpt-3.5-turbo-0301"` + - `"connector_googledrive"` - - `"gpt-3.5-turbo-0613"` + - `"connector_microsoftteams"` - - `"gpt-3.5-turbo-1106"` + - `"connector_outlookcalendar"` - - `"gpt-3.5-turbo-0125"` + - `"connector_outlookemail"` - - `"gpt-3.5-turbo-16k-0613"` + - `"connector_sharepoint"` - - `"o1-pro"` + - `defer_loading: Optional[bool]` - - `"o1-pro-2025-03-19"` + Whether this MCP tool is deferred and discovered via tool search. - - `"o3-pro"` + - `headers: Optional[Dict[str, str]]` - - `"o3-pro-2025-06-10"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"o3-deep-research"` + - `require_approval: Optional[McpRequireApproval]` - - `"o3-deep-research-2025-06-26"` + Specify which of the MCP server's tools require approval. - - `"o4-mini-deep-research"` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - - `"o4-mini-deep-research-2025-06-26"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"computer-use-preview"` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `"computer-use-preview-2025-03-11"` + A filter object to specify which tools are allowed. - - `"gpt-5-codex"` + - `read_only: Optional[bool]` - - `"gpt-5-pro"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"gpt-5-pro-2025-10-06"` + - `tool_names: Optional[List[str]]` - - `"gpt-5.1-codex-max"` + List of allowed tool names. - - `str` + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - - `object: Literal["response"]` + A filter object to specify which tools are allowed. - The object type of this resource - always set to `response`. + - `read_only: Optional[bool]` - - `"response"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `output: List[BetaResponseOutputItem]` + - `tool_names: Optional[List[str]]` - An array of content items generated by the model. + List of allowed tool names. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `Literal["always", "never"]` - - `class BetaResponseOutputMessage: …` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - An output message from the model. + - `"always"` - - `class BetaResponseFileSearchToolCall: …` + - `"never"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `server_description: Optional[str]` - - `class BetaResponseFunctionToolCall: …` + Optional description of the MCP server, used to provide more context. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `server_url: Optional[str]` - - `class BetaResponseFunctionToolCallOutputItem: …` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `id: str` + - `tunnel_id: Optional[str]` - The unique ID of the function call tool output. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `call_id: str` + - `class CodeInterpreter: …` - The unique ID of the function tool call generated by the model. + A tool that runs Python code to help generate a response to a prompt. - - `output: Union[str, List[OutputOutputContentList]]` + - `container: CodeInterpreterContainer` - The output from the function call generated by your code. - Can be a string or an list of output content. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - `str` - A string of the output of the function call. - - - `List[OutputOutputContentList]` + The container ID. - Text, image, or file output of the function call. + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `class BetaResponseInputText: …` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - A text input to the model. + - `type: Literal["auto"]` - - `class BetaResponseInputImage: …` + Always `auto`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"auto"` - - `class BetaResponseInputFile: …` + - `file_ids: Optional[List[str]]` - A file input to the model. + An optional list of uploaded files to make available to your code. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The memory limit for the code interpreter container. - - `"in_progress"` + - `"1g"` - - `"completed"` + - `"4g"` - - `"incomplete"` + - `"16g"` - - `type: Literal["function_call_output"]` + - `"64g"` - The type of the function tool call output. Always `function_call_output`. + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - - `"function_call_output"` + Network access policy for the container. - - `agent: Optional[Agent]` + - `class BetaContainerNetworkPolicyDisabled: …` - The agent that produced this item. + - `type: Literal["disabled"]` - - `agent_name: str` + Disable outbound network access. Always `disabled`. - The canonical name of the agent that produced this item. + - `"disabled"` - - `caller: Optional[Caller]` + - `class BetaContainerNetworkPolicyAllowlist: …` - The execution context that produced this tool call. + - `allowed_domains: List[str]` - - `class CallerDirect: …` + A list of allowed domains when type is `allowlist`. - - `type: Literal["direct"]` + - `type: Literal["allowlist"]` - The caller type. Always `direct`. + Allow outbound network access only to specified domains. Always `allowlist`. - - `"direct"` + - `"allowlist"` - - `class CallerProgram: …` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `caller_id: str` + Optional domain-scoped secrets for allowlisted domains. - The call ID of the program item that produced this tool call. + - `domain: str` - - `type: Literal["program"]` + The domain associated with the secret. - The caller type. Always `program`. + - `name: str` - - `"program"` + The name of the secret to inject for the domain. - - `created_by: Optional[str]` + - `value: str` - The identifier of the actor that created the item. + The secret value to inject for the domain. - - `class AgentMessage: …` + - `type: Literal["code_interpreter"]` - - `id: str` + The type of the code interpreter tool. Always `code_interpreter`. - The unique ID of the agent message. + - `"code_interpreter"` - - `author: str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The sending agent identity. + The tool invocation context(s). - - `content: List[AgentMessageContent]` + - `"direct"` - Encrypted content sent between agents. + - `"programmatic"` - - `class BetaResponseInputText: …` + - `class ProgrammaticToolCalling: …` - A text input to the model. + - `type: Literal["programmatic_tool_calling"]` - - `class BetaResponseOutputText: …` + The type of the tool. Always `programmatic_tool_calling`. - A text output from the model. + - `"programmatic_tool_calling"` - - `class AgentMessageContentText: …` + - `class ImageGeneration: …` - A text content. + A tool that generates images using the GPT image models. - - `text: str` + - `type: Literal["image_generation"]` - - `type: Literal["text"]` + The type of the image generation tool. Always `image_generation`. - - `"text"` + - `"image_generation"` - - `class AgentMessageContentSummaryText: …` + - `action: Optional[Literal["generate", "edit", "auto"]]` - A summary text from the model. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `text: str` + - `"generate"` - A summary of the reasoning output from the model so far. + - `"edit"` - - `type: Literal["summary_text"]` + - `"auto"` - The type of the object. Always `summary_text`. + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `"summary_text"` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `class AgentMessageContentReasoningText: …` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - Reasoning text from the model. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `text: str` + - `"transparent"` - The reasoning text from the model. + - `"opaque"` - - `type: Literal["reasoning_text"]` + - `"auto"` - The type of the reasoning text. Always `reasoning_text`. + - `input_fidelity: Optional[Literal["high", "low"]]` - - `"reasoning_text"` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `class BetaResponseOutputRefusal: …` + - `"high"` - A refusal from the model. + - `"low"` - - `class BetaResponseInputImage: …` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `class AgentMessageContentComputerScreenshot: …` + - `file_id: Optional[str]` - A screenshot of a computer. + File ID for the mask image. - - `detail: Literal["low", "high", "auto", "original"]` + - `image_url: Optional[str]` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Base64-encoded mask image. - - `"low"` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - - `"high"` + The image generation model to use. Default: `gpt-image-1`. - - `"auto"` + - `str` - - `"original"` + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `file_id: Optional[str]` + The image generation model to use. Default: `gpt-image-1`. - The identifier of an uploaded file that contains the screenshot. + - `"gpt-image-1"` - - `image_url: Optional[str]` + - `"gpt-image-1-mini"` - The URL of the screenshot image. + - `"gpt-image-2"` - - `type: Literal["computer_screenshot"]` + - `"gpt-image-2-2026-04-21"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"gpt-image-1.5"` - - `"computer_screenshot"` + - `"chatgpt-image-latest"` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `moderation: Optional[Literal["auto", "low"]]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Moderation level for the generated image. Default: `auto`. - - `mode: Literal["explicit"]` + - `"auto"` - The breakpoint mode. Always `explicit`. + - `"low"` - - `"explicit"` + - `output_compression: Optional[int]` - - `class BetaResponseInputFile: …` + Compression level for the output image. Default: 100. - A file input to the model. + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `class AgentMessageContentEncryptedContent: …` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"png"` - - `encrypted_content: str` + - `"webp"` - Opaque encrypted content. + - `"jpeg"` - - `type: Literal["encrypted_content"]` + - `partial_images: Optional[int]` - The type of the input item. Always `encrypted_content`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"encrypted_content"` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - - `recipient: str` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The destination agent identity. + - `"low"` - - `type: Literal["agent_message"]` + - `"medium"` - The type of the item. Always `agent_message`. + - `"high"` - - `"agent_message"` + - `"auto"` - - `agent: Optional[AgentMessageAgent]` + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - The agent that produced this item. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `agent_name: str` + - `str` - The canonical name of the agent that produced this item. + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `class MultiAgentCall: …` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `id: str` + - `"1024x1024"` - The unique ID of the multi-agent call item. + - `"1024x1536"` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `"1536x1024"` - The multi-agent action to execute. + - `"auto"` - - `"spawn_agent"` + - `class LocalShell: …` - - `"interrupt_agent"` + A tool that allows the model to execute shell commands in a local environment. - - `"list_agents"` + - `type: Literal["local_shell"]` - - `"send_message"` + The type of the local shell tool. Always `local_shell`. - - `"followup_task"` + - `"local_shell"` - - `"wait_agent"` + - `class BetaFunctionShellTool: …` - - `arguments: str` + A tool that allows the model to execute shell commands. - The JSON string of arguments generated for the action. + - `type: Literal["shell"]` - - `call_id: str` + The type of the shell tool. Always `shell`. - The unique ID linking this call to its output. + - `"shell"` - - `type: Literal["multi_agent_call"]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The type of the multi-agent call. Always `multi_agent_call`. + The tool invocation context(s). - - `"multi_agent_call"` + - `"direct"` - - `agent: Optional[MultiAgentCallAgent]` + - `"programmatic"` - The agent that produced this item. + - `environment: Optional[Environment]` - - `agent_name: str` + - `class BetaContainerAuto: …` - The canonical name of the agent that produced this item. + - `type: Literal["container_auto"]` - - `class MultiAgentCallOutput: …` + Automatically creates a container for this request - - `id: str` + - `"container_auto"` - The unique ID of the multi-agent call output item. + - `file_ids: Optional[List[str]]` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + An optional list of uploaded files to make available to your code. - The multi-agent action that produced this result. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `"spawn_agent"` + The memory limit for the container. - - `"interrupt_agent"` + - `"1g"` - - `"list_agents"` + - `"4g"` - - `"send_message"` + - `"16g"` - - `"followup_task"` + - `"64g"` - - `"wait_agent"` + - `network_policy: Optional[NetworkPolicy]` - - `call_id: str` + Network access policy for the container. - The unique ID of the multi-agent call. + - `class BetaContainerNetworkPolicyDisabled: …` - - `output: List[BetaResponseOutputText]` + - `class BetaContainerNetworkPolicyAllowlist: …` - Text output returned by the multi-agent action. + - `skills: Optional[List[Skill]]` - - `annotations: List[Annotation]` + An optional list of skills referenced by id or inline data. - The annotations of the text output. + - `class BetaSkillReference: …` - - `text: str` + - `skill_id: str` - The text output from the model. + The ID of the referenced skill. - - `type: Literal["output_text"]` + - `type: Literal["skill_reference"]` - The type of the output text. Always `output_text`. + References a skill created with the /v1/skills endpoint. - - `logprobs: Optional[List[Logprob]]` + - `"skill_reference"` - - `type: Literal["multi_agent_call_output"]` + - `version: Optional[str]` - The type of the multi-agent result. Always `multi_agent_call_output`. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `"multi_agent_call_output"` + - `class BetaInlineSkill: …` - - `agent: Optional[MultiAgentCallOutputAgent]` + - `description: str` - The agent that produced this item. + The description of the skill. - - `agent_name: str` + - `name: str` - The canonical name of the agent that produced this item. + The name of the skill. - - `class BetaResponseFunctionWebSearch: …` + - `source: BetaInlineSkillSource` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + Inline skill payload - - `class BetaResponseComputerToolCall: …` + - `data: str` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Base64-encoded skill zip bundle. - - `class BetaResponseComputerToolCallOutputItem: …` + - `media_type: Literal["application/zip"]` - - `id: str` + The media type of the inline skill payload. Must be `application/zip`. - The unique ID of the computer call tool output. + - `"application/zip"` - - `call_id: str` + - `type: Literal["base64"]` - The ID of the computer tool call that produced the output. + The type of the inline skill source. Must be `base64`. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"base64"` - A computer screenshot image used with the computer use tool. + - `type: Literal["inline"]` - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + Defines an inline skill for this request. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"inline"` - - `"completed"` + - `class BetaLocalEnvironment: …` - - `"incomplete"` + - `type: Literal["local"]` - - `"failed"` + Use a local computer environment. - - `"in_progress"` + - `"local"` - - `type: Literal["computer_call_output"]` + - `skills: Optional[List[BetaLocalSkill]]` - The type of the computer tool call output. Always `computer_call_output`. + An optional list of skills. - - `"computer_call_output"` + - `description: str` - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + The description of the skill. - The safety checks reported by the API that have been acknowledged by the - developer. + - `name: str` - - `id: str` + The name of the skill. - The ID of the pending safety check. + - `path: str` - - `code: Optional[str]` + The path to the directory containing the skill. - The type of the pending safety check. + - `class BetaContainerReference: …` - - `message: Optional[str]` + - `container_id: str` - Details about the pending safety check. + The ID of the referenced container. - - `agent: Optional[Agent]` + - `type: Literal["container_reference"]` - The agent that produced this item. + References a container created with the /v1/containers endpoint - - `agent_name: str` + - `"container_reference"` - The canonical name of the agent that produced this item. + - `class BetaCustomTool: …` - - `created_by: Optional[str]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The identifier of the actor that created the item. + - `name: str` - - `class BetaResponseReasoningItem: …` + The name of the custom tool, used to identify it in tool calls. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `type: Literal["custom"]` - - `class Program: …` + The type of the custom tool. Always `custom`. - - `id: str` + - `"custom"` - The unique ID of the program item. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `call_id: str` + The tool invocation context(s). - The stable call ID of the program item. + - `"direct"` - - `code: str` + - `"programmatic"` - The JavaScript source executed by programmatic tool calling. + - `defer_loading: Optional[bool]` - - `fingerprint: str` + Whether this tool should be deferred and discovered via tool search. - Opaque program replay fingerprint that must be round-tripped. + - `description: Optional[str]` - - `type: Literal["program"]` + Optional description of the custom tool, used to provide more context. - The type of the item. Always `program`. + - `format: Optional[Format]` - - `"program"` + The input format for the custom tool. Default is unconstrained text. - - `agent: Optional[ProgramAgent]` + - `class FormatText: …` - The agent that produced this item. + Unconstrained free-form text. - - `agent_name: str` + - `type: Literal["text"]` - The canonical name of the agent that produced this item. + Unconstrained text format. Always `text`. - - `class ProgramOutput: …` + - `"text"` - - `id: str` + - `class FormatGrammar: …` - The unique ID of the program output item. + A grammar defined by the user. - - `call_id: str` + - `definition: str` - The call ID of the program item. + The grammar definition. - - `result: str` + - `syntax: Literal["lark", "regex"]` - The result produced by the program item. + The syntax of the grammar definition. One of `lark` or `regex`. - - `status: Literal["completed", "incomplete"]` + - `"lark"` - The terminal status of the program output item. + - `"regex"` - - `"completed"` + - `type: Literal["grammar"]` - - `"incomplete"` + Grammar format. Always `grammar`. - - `type: Literal["program_output"]` + - `"grammar"` - The type of the item. Always `program_output`. + - `class BetaNamespaceTool: …` - - `"program_output"` + Groups function/custom tools under a shared namespace. - - `agent: Optional[ProgramOutputAgent]` + - `description: str` - The agent that produced this item. + A description of the namespace shown to the model. - - `agent_name: str` + - `name: str` - The canonical name of the agent that produced this item. + The namespace name used in tool calls (for example, `crm`). - - `class BetaResponseToolSearchCall: …` + - `tools: List[Tool]` - - `id: str` + The function/custom tools available inside this namespace. - The unique ID of the tool search call item. + - `class ToolFunction: …` - - `arguments: object` + - `name: str` - Arguments used for the tool search call. + - `type: Literal["function"]` - - `call_id: Optional[str]` + - `"function"` - The unique ID of the tool search call generated by the model. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `execution: Literal["server", "client"]` + The tool invocation context(s). - Whether tool search was executed by the server or by the client. + - `"direct"` - - `"server"` + - `"programmatic"` - - `"client"` + - `defer_loading: Optional[bool]` - - `status: Literal["in_progress", "completed", "incomplete"]` + Whether this function should be deferred and discovered via tool search. - The status of the tool search call item that was recorded. + - `description: Optional[str]` - - `"in_progress"` + - `output_schema: Optional[Dict[str, object]]` - - `"completed"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"incomplete"` + - `parameters: Optional[object]` - - `type: Literal["tool_search_call"]` + - `strict: Optional[bool]` - The type of the item. Always `tool_search_call`. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `"tool_search_call"` + - `class BetaCustomTool: …` - - `agent: Optional[Agent]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The agent that produced this item. + - `type: Literal["namespace"]` - - `agent_name: str` + The type of the tool. Always `namespace`. - The canonical name of the agent that produced this item. + - `"namespace"` - - `created_by: Optional[str]` + - `class BetaToolSearchTool: …` - The identifier of the actor that created the item. + Hosted or BYOT tool search configuration for deferred tools. - - `class BetaResponseToolSearchOutputItem: …` + - `type: Literal["tool_search"]` - - `id: str` + The type of the tool. Always `tool_search`. - The unique ID of the tool search output item. + - `"tool_search"` - - `call_id: Optional[str]` + - `description: Optional[str]` - The unique ID of the tool search call generated by the model. + Description shown to the model for a client-executed tool search tool. - - `execution: Literal["server", "client"]` + - `execution: Optional[Literal["server", "client"]]` - Whether tool search was executed by the server or by the client. + Whether tool search is executed by the server or by the client. - `"server"` - `"client"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `parameters: Optional[object]` - The status of the tool search output item that was recorded. + Parameter schema for a client-executed tool search tool. - - `"in_progress"` + - `class BetaWebSearchPreviewTool: …` - - `"completed"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"incomplete"` + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - - `tools: List[BetaTool]` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The loaded tool definitions returned by tool search. + - `"web_search_preview"` - - `class BetaFunctionTool: …` + - `"web_search_preview_2025_03_11"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `class BetaFileSearchTool: …` + - `"text"` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `"image"` - - `class BetaComputerTool: …` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `class BetaComputerUsePreviewTool: …` + - `"low"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"medium"` - - `class BetaWebSearchTool: …` + - `"high"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `user_location: Optional[UserLocation]` - - `class Mcp: …` + The user's location. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: Literal["approximate"]` - - `class CodeInterpreter: …` + The type of location approximation. Always `approximate`. - A tool that runs Python code to help generate a response to a prompt. + - `"approximate"` - - `class ProgrammaticToolCalling: …` + - `city: Optional[str]` - - `class ImageGeneration: …` + Free text input for the city of the user, e.g. `San Francisco`. - A tool that generates images using the GPT image models. + - `country: Optional[str]` - - `class LocalShell: …` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A tool that allows the model to execute shell commands in a local environment. + - `region: Optional[str]` - - `class BetaFunctionShellTool: …` + Free text input for the region of the user, e.g. `California`. - A tool that allows the model to execute shell commands. + - `timezone: Optional[str]` - - `class BetaCustomTool: …` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `class BetaApplyPatchTool: …` - - `class BetaNamespaceTool: …` + Allows the assistant to create, delete, or update files using unified diffs. - Groups function/custom tools under a shared namespace. + - `type: Literal["apply_patch"]` - - `class BetaToolSearchTool: …` + The type of the tool. Always `apply_patch`. - Hosted or BYOT tool search configuration for deferred tools. + - `"apply_patch"` - - `class BetaWebSearchPreviewTool: …` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The tool invocation context(s). - - `class BetaApplyPatchTool: …` + - `"direct"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"programmatic"` - `type: Literal["tool_search_output"]` @@ -88432,6 +99563,143 @@ print(compacted_response) The canonical name of the agent that produced this item. + - `class BetaResponseReasoningItem: …` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: str` + + The unique identifier of the reasoning content. + + - `summary: List[Summary]` + + Reasoning summary content. + + - `text: str` + + A summary of the reasoning output from the model so far. + + - `type: Literal["summary_text"]` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `type: Literal["reasoning"]` + + The type of the object. Always `reasoning`. + + - `"reasoning"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `content: Optional[List[Content]]` + + Reasoning text content. + + - `text: str` + + The reasoning text from the model. + + - `type: Literal["reasoning_text"]` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: Optional[str]` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class Program: …` + + - `id: str` + + The unique ID of the program item. + + - `call_id: str` + + The stable call ID of the program item. + + - `code: str` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: str` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: Literal["program"]` + + The type of the item. Always `program`. + + - `"program"` + + - `agent: Optional[ProgramAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput: …` + + - `id: str` + + The unique ID of the program output item. + + - `call_id: str` + + The call ID of the program item. + + - `result: str` + + The result produced by the program item. + + - `status: Literal["completed", "incomplete"]` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["program_output"]` + + The type of the item. Always `program_output`. + + - `"program_output"` + + - `agent: Optional[ProgramOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + - `class BetaResponseCompactionItem: …` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). @@ -88504,6 +99772,79 @@ print(compacted_response) A tool call to run code. + - `id: str` + + The unique ID of the code interpreter tool call. + + - `code: Optional[str]` + + The code to run, or null if not available. + + - `container_id: str` + + The ID of the container used to run the code. + + - `outputs: Optional[List[Output]]` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `class OutputLogs: …` + + The logs output from the code interpreter. + + - `logs: str` + + The logs output from the code interpreter. + + - `type: Literal["logs"]` + + The type of the output. Always `logs`. + + - `"logs"` + + - `class OutputImage: …` + + The image output from the code interpreter. + + - `type: Literal["image"]` + + The type of the output. Always `image`. + + - `"image"` + + - `url: str` + + The URL of the image output from the code interpreter. + + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: Literal["code_interpreter_call"]` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + - `class LocalShellCall: …` A tool call to run a command on the local shell. @@ -88978,76 +100319,15 @@ print(compacted_response) - `type: Literal["program"]` - - `"program"` - - - `created_by: Optional[str]` - - The ID of the entity that created this tool call output. - - - `output: Optional[str]` - - Optional textual output returned by the apply patch tool. - - - `class McpCall: …` - - An invocation of a tool on an MCP server. - - - `id: str` - - The unique ID of the tool call. - - - `arguments: str` - - A JSON string of the arguments passed to the tool. - - - `name: str` - - The name of the tool that was run. - - - `server_label: str` - - The label of the MCP server running the tool. - - - `type: Literal["mcp_call"]` - - The type of the item. Always `mcp_call`. - - - `"mcp_call"` - - - `agent: Optional[McpCallAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `approval_request_id: Optional[str]` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: Optional[str]` - - The error from the tool call, if any. - - - `output: Optional[str]` - - The output from the tool call. - - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - - `"in_progress"` + - `"program"` - - `"completed"` + - `created_by: Optional[str]` - - `"incomplete"` + The ID of the entity that created this tool call output. - - `"calling"` + - `output: Optional[str]` - - `"failed"` + Optional textual output returned by the apply patch tool. - `class McpListTools: …` @@ -89167,987 +100447,880 @@ print(compacted_response) Optional reason for the decision. - - `class BetaResponseCustomToolCall: …` - - A call to a custom tool created by the model. - - - `class BetaResponseCustomToolCallOutputItem: …` + - `class McpCall: …` - The output of a custom tool call from your code, being sent back to the model. + An invocation of a tool on an MCP server. - `id: str` - The unique ID of the custom tool call output item. - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` + The unique ID of the tool call. - - `"completed"` + - `arguments: str` - - `"incomplete"` + A JSON string of the arguments passed to the tool. - - `created_by: Optional[str]` + - `name: str` - The identifier of the actor that created the item. + The name of the tool that was run. - - `parallel_tool_calls: bool` + - `server_label: str` - Whether to allow the model to run tool calls in parallel. + The label of the MCP server running the tool. - - `temperature: Optional[float]` + - `type: Literal["mcp_call"]` - 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. - We generally recommend altering this or `top_p` but not both. + The type of the item. Always `mcp_call`. - - `tool_choice: ToolChoice` + - `"mcp_call"` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `agent: Optional[McpCallAgent]` - - `Literal["none", "auto", "required"]` + The agent that produced this item. - - `"none"` + - `agent_name: str` - - `"auto"` + The canonical name of the agent that produced this item. - - `"required"` + - `approval_request_id: Optional[str]` - - `class BetaToolChoiceAllowed: …` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - Constrains the tools available to the model to a pre-defined set. + - `error: Optional[str]` - - `mode: Literal["auto", "required"]` + The error from the tool call, if any. - Constrains the tools available to the model to a pre-defined set. + - `output: Optional[str]` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The output from the tool call. - `required` requires the model to call one or more of the allowed tools. + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - `"auto"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"required"` + - `"in_progress"` - - `tools: List[Dict[str, object]]` + - `"completed"` - A list of tool definitions that the model should be allowed to call. + - `"incomplete"` - For the Responses API, the list of tool definitions might look like: + - `"calling"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `"failed"` - - `type: Literal["allowed_tools"]` + - `class BetaResponseCustomToolCallItem: …` - Allowed tool configuration type. Always `allowed_tools`. + A call to a custom tool created by the model. - - `"allowed_tools"` + - `id: str` - - `class BetaToolChoiceTypes: …` + The unique ID of the custom tool call item. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"in_progress"` - Allowed values are: + - `"completed"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"incomplete"` - - `"file_search"` + - `created_by: Optional[str]` - - `"web_search_preview"` + The identifier of the actor that created the item. - - `"computer"` + - `class BetaResponseCustomToolCallOutputItem: …` - - `"computer_use_preview"` + The output of a custom tool call from your code, being sent back to the model. - - `"computer_use"` + - `id: str` - - `"web_search_preview_2025_03_11"` + The unique ID of the custom tool call output item. - - `"image_generation"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"code_interpreter"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class BetaToolChoiceFunction: …` + - `"in_progress"` - Use this option to force the model to call a specific function. + - `"completed"` - - `name: str` + - `"incomplete"` - The name of the function to call. + - `created_by: Optional[str]` - - `type: Literal["function"]` + The identifier of the actor that created the item. - For function calling, the type is always `function`. +### Beta Response Local Environment - - `"function"` +- `class BetaResponseLocalEnvironment: …` - - `class BetaToolChoiceMcp: …` + Represents the use of a local environment to perform shell actions. - Use this option to force the model to call a specific tool on a remote MCP server. + - `type: Literal["local"]` - - `server_label: str` + The environment type. Always `local`. - The label of the MCP server to use. + - `"local"` - - `type: Literal["mcp"]` +### Beta Response Mcp Call Arguments Delta Event - For MCP tools, the type is always `mcp`. +- `class BetaResponseMcpCallArgumentsDeltaEvent: …` - - `"mcp"` + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - - `name: Optional[str]` + - `delta: str` - The name of the tool to call on the server. + A JSON string containing the partial update to the arguments for the MCP tool call. - - `class BetaToolChoiceCustom: …` + - `item_id: str` - Use this option to force the model to call a specific custom tool. + The unique identifier of the MCP tool call item being processed. - - `name: str` + - `output_index: int` - The name of the custom tool to call. + The index of the output item in the response's output array. - - `type: Literal["custom"]` + - `sequence_number: int` - For custom tool calling, the type is always `custom`. + The sequence number of this event. - - `"custom"` + - `type: Literal["response.mcp_call_arguments.delta"]` - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + The type of the event. Always 'response.mcp_call_arguments.delta'. - - `type: Literal["programmatic_tool_calling"]` + - `"response.mcp_call_arguments.delta"` - The tool to call. Always `programmatic_tool_calling`. + - `agent: Optional[Agent]` - - `"programmatic_tool_calling"` + The agent that owns this multi-agent streaming event. - - `class BetaToolChoiceApplyPatch: …` + - `agent_name: str` - Forces the model to call the apply_patch tool when executing a tool call. + The canonical name of the agent that produced this item. - - `type: Literal["apply_patch"]` +### Beta Response Mcp Call Arguments Done Event - The tool to call. Always `apply_patch`. +- `class BetaResponseMcpCallArgumentsDoneEvent: …` - - `"apply_patch"` + Emitted when the arguments for an MCP tool call are finalized. - - `class BetaToolChoiceShell: …` + - `arguments: str` - Forces the model to call the shell tool when a tool call is required. + A JSON string containing the finalized arguments for the MCP tool call. - - `type: Literal["shell"]` + - `item_id: str` - The tool to call. Always `shell`. + The unique identifier of the MCP tool call item being processed. - - `"shell"` + - `output_index: int` - - `tools: List[BetaTool]` + The index of the output item in the response's output array. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `sequence_number: int` - We support the following categories of tools: + The sequence number of this event. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `type: Literal["response.mcp_call_arguments.done"]` - - `class BetaFunctionTool: …` + The type of the event. Always 'response.mcp_call_arguments.done'. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `"response.mcp_call_arguments.done"` - - `class BetaFileSearchTool: …` + - `agent: Optional[Agent]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The agent that owns this multi-agent streaming event. - - `class BetaComputerTool: …` + - `agent_name: str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The canonical name of the agent that produced this item. - - `class BetaComputerUsePreviewTool: …` +### Beta Response Mcp Call Completed Event - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +- `class BetaResponseMcpCallCompletedEvent: …` - - `class BetaWebSearchTool: …` + Emitted when an MCP tool call has completed successfully. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `item_id: str` - - `class Mcp: …` + The ID of the MCP tool call item that completed. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `output_index: int` - - `class CodeInterpreter: …` + The index of the output item that completed. - A tool that runs Python code to help generate a response to a prompt. + - `sequence_number: int` - - `class ProgrammaticToolCalling: …` + The sequence number of this event. - - `class ImageGeneration: …` + - `type: Literal["response.mcp_call.completed"]` - A tool that generates images using the GPT image models. + The type of the event. Always 'response.mcp_call.completed'. - - `class LocalShell: …` + - `"response.mcp_call.completed"` - A tool that allows the model to execute shell commands in a local environment. + - `agent: Optional[Agent]` - - `class BetaFunctionShellTool: …` + The agent that owns this multi-agent streaming event. - A tool that allows the model to execute shell commands. + - `agent_name: str` - - `class BetaCustomTool: …` + The canonical name of the agent that produced this item. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) +### Beta Response Mcp Call Failed Event - - `class BetaNamespaceTool: …` +- `class BetaResponseMcpCallFailedEvent: …` - Groups function/custom tools under a shared namespace. + Emitted when an MCP tool call has failed. - - `class BetaToolSearchTool: …` + - `item_id: str` - Hosted or BYOT tool search configuration for deferred tools. + The ID of the MCP tool call item that failed. - - `class BetaWebSearchPreviewTool: …` + - `output_index: int` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The index of the output item that failed. - - `class BetaApplyPatchTool: …` + - `sequence_number: int` - Allows the assistant to create, delete, or update files using unified diffs. + The sequence number of this event. - - `top_p: Optional[float]` + - `type: Literal["response.mcp_call.failed"]` - 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. + The type of the event. Always 'response.mcp_call.failed'. - We generally recommend altering this or `temperature` but not both. + - `"response.mcp_call.failed"` - - `background: Optional[bool]` + - `agent: Optional[Agent]` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The agent that owns this multi-agent streaming event. - - `completed_at: Optional[float]` + - `agent_name: str` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The canonical name of the agent that produced this item. - - `conversation: Optional[Conversation]` +### Beta Response Mcp Call In Progress Event - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. +- `class BetaResponseMcpCallInProgressEvent: …` - - `id: str` + Emitted when an MCP tool call is in progress. - The unique ID of the conversation that this response was associated with. + - `item_id: str` - - `max_output_tokens: Optional[int]` + The unique identifier of the MCP tool call item being processed. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `output_index: int` - - `max_tool_calls: Optional[int]` + The index of the output item in the response's output array. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `sequence_number: int` - - `moderation: Optional[Moderation]` + The sequence number of this event. - Moderation results for the response input and output, if moderated completions were requested. + - `type: Literal["response.mcp_call.in_progress"]` - - `input: ModerationInput` + The type of the event. Always 'response.mcp_call.in_progress'. - Moderation for the response input. + - `"response.mcp_call.in_progress"` - - `class ModerationInputModerationResult: …` + - `agent: Optional[Agent]` - A moderation result produced for the response input or output. + The agent that owns this multi-agent streaming event. - - `categories: Dict[str, bool]` + - `agent_name: str` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The canonical name of the agent that produced this item. - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` +### Beta Response Mcp List Tools Completed Event - Which modalities of input are reflected by the score for each category. +- `class BetaResponseMcpListToolsCompletedEvent: …` - - `"text"` + Emitted when the list of available MCP tools has been successfully retrieved. - - `"image"` + - `item_id: str` - - `category_scores: Dict[str, float]` + The ID of the MCP tool call item that produced this output. - A dictionary of moderation categories to scores. + - `output_index: int` - - `flagged: bool` + The index of the output item that was processed. - A boolean indicating whether the content was flagged by any category. + - `sequence_number: int` - - `model: str` + The sequence number of this event. - The moderation model that produced this result. + - `type: Literal["response.mcp_list_tools.completed"]` - - `type: Literal["moderation_result"]` + The type of the event. Always 'response.mcp_list_tools.completed'. - The object type, which was always `moderation_result` for successful moderation results. + - `"response.mcp_list_tools.completed"` - - `"moderation_result"` + - `agent: Optional[Agent]` - - `class ModerationInputError: …` + The agent that owns this multi-agent streaming event. - An error produced while attempting moderation for the response input or output. + - `agent_name: str` - - `code: str` + The canonical name of the agent that produced this item. - The error code. +### Beta Response Mcp List Tools Failed Event - - `message: str` +- `class BetaResponseMcpListToolsFailedEvent: …` - The error message. + Emitted when the attempt to list available MCP tools has failed. - - `type: Literal["error"]` + - `item_id: str` - The object type, which was always `error` for moderation failures. + The ID of the MCP tool call item that failed. - - `"error"` + - `output_index: int` - - `output: ModerationOutput` + The index of the output item that failed. - Moderation for the response output. + - `sequence_number: int` - - `class ModerationOutputModerationResult: …` + The sequence number of this event. - A moderation result produced for the response input or output. + - `type: Literal["response.mcp_list_tools.failed"]` - - `categories: Dict[str, bool]` + The type of the event. Always 'response.mcp_list_tools.failed'. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"response.mcp_list_tools.failed"` - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `agent: Optional[Agent]` - Which modalities of input are reflected by the score for each category. + The agent that owns this multi-agent streaming event. - - `"text"` + - `agent_name: str` - - `"image"` + The canonical name of the agent that produced this item. - - `category_scores: Dict[str, float]` +### Beta Response Mcp List Tools In Progress Event - A dictionary of moderation categories to scores. +- `class BetaResponseMcpListToolsInProgressEvent: …` - - `flagged: bool` + Emitted when the system is in the process of retrieving the list of available MCP tools. - A boolean indicating whether the content was flagged by any category. + - `item_id: str` - - `model: str` + The ID of the MCP tool call item that is being processed. - The moderation model that produced this result. + - `output_index: int` - - `type: Literal["moderation_result"]` + The index of the output item that is being processed. - The object type, which was always `moderation_result` for successful moderation results. + - `sequence_number: int` - - `"moderation_result"` + The sequence number of this event. - - `class ModerationOutputError: …` + - `type: Literal["response.mcp_list_tools.in_progress"]` - An error produced while attempting moderation for the response input or output. + The type of the event. Always 'response.mcp_list_tools.in_progress'. - - `code: str` + - `"response.mcp_list_tools.in_progress"` - The error code. + - `agent: Optional[Agent]` - - `message: str` + The agent that owns this multi-agent streaming event. - The error message. + - `agent_name: str` - - `type: Literal["error"]` + The canonical name of the agent that produced this item. - The object type, which was always `error` for moderation failures. +### Beta Response Output Audio - - `"error"` +- `class BetaResponseOutputAudio: …` - - `previous_response_id: Optional[str]` + An audio output from the model. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `data: str` - - `prompt: Optional[BetaResponsePrompt]` + Base64-encoded audio data from the model. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `transcript: str` - - `id: str` + The transcript of the audio data from the model. - The unique identifier of the prompt template to use. + - `type: Literal["output_audio"]` - - `variables: Optional[Dict[str, Variables]]` + The type of the output audio. Always `output_audio`. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `"output_audio"` - - `str` +### Beta Response Output Item - - `class BetaResponseInputText: …` +- `BetaResponseOutputItem` - A text input to the model. + An output message from the model. - - `class BetaResponseInputImage: …` + - `class BetaResponseOutputMessage: …` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An output message from the model. - - `class BetaResponseInputFile: …` + - `id: str` - A file input to the model. + The unique ID of the output message. - - `version: Optional[str]` + - `content: List[Content]` - Optional version of the prompt template. + The content of the output message. - - `prompt_cache_key: Optional[str]` + - `class BetaResponseOutputText: …` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + A text output from the model. - - `prompt_cache_options: Optional[PromptCacheOptions]` + - `annotations: List[Annotation]` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The annotations of the text output. - - `mode: Literal["implicit", "explicit"]` + - `class AnnotationFileCitation: …` - Whether implicit prompt-cache breakpoints were enabled. + A citation to a file. - - `"implicit"` + - `file_id: str` - - `"explicit"` + The ID of the file. - - `ttl: Literal["30m"]` + - `filename: str` - The minimum lifetime applied to each cache breakpoint. + The filename of the file cited. - - `"30m"` + - `index: int` - - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + The index of the file in the list of files. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `type: Literal["file_citation"]` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + The type of the file citation. Always `file_citation`. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `"file_citation"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `class AnnotationURLCitation: …` - - `"in_memory"` + A citation for a web resource used to generate a model response. - - `"24h"` + - `end_index: int` - - `reasoning: Optional[Reasoning]` + The index of the last character of the URL citation in the message. - **gpt-5 and o-series models only** + - `start_index: int` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The index of the first character of the URL citation in the message. - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + - `title: str` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + The title of the web resource. - - `"auto"` + - `type: Literal["url_citation"]` - - `"current_turn"` + The type of the URL citation. Always `url_citation`. - - `"all_turns"` + - `"url_citation"` - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + - `url: str` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The URL of the web resource. - - `"none"` + - `class AnnotationContainerFileCitation: …` - - `"minimal"` + A citation for a container file used to generate a model response. - - `"low"` + - `container_id: str` - - `"medium"` + The ID of the container file. - - `"high"` + - `end_index: int` - - `"xhigh"` + The index of the last character of the container file citation in the message. - - `"max"` + - `file_id: str` - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + The ID of the file. - **Deprecated:** use `summary` instead. + - `filename: str` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The filename of the container file cited. - - `"auto"` + - `start_index: int` - - `"concise"` + The index of the first character of the container file citation in the message. - - `"detailed"` + - `type: Literal["container_file_citation"]` - - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + The type of the container file citation. Always `container_file_citation`. - Controls the reasoning execution mode for the request. + - `"container_file_citation"` - When returned on a response, this is the effective execution mode. + - `class AnnotationFilePath: …` - - `str` + A path to a file. - - `Literal["standard", "pro"]` + - `file_id: str` - Controls the reasoning execution mode for the request. + The ID of the file. - When returned on a response, this is the effective execution mode. + - `index: int` - - `"standard"` + The index of the file in the list of files. - - `"pro"` + - `type: Literal["file_path"]` - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + The type of the file path. Always `file_path`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"file_path"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `text: str` - - `"auto"` + The text output from the model. - - `"concise"` + - `type: Literal["output_text"]` - - `"detailed"` + The type of the output text. Always `output_text`. - - `safety_identifier: Optional[str]` + - `"output_text"` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `logprobs: Optional[List[Logprob]]` - - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + - `token: str` - Specifies the processing type used for serving the request. + - `bytes: List[int]` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `logprob: float` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `top_logprobs: List[LogprobTopLogprob]` - - `"auto"` + - `token: str` - - `"default"` + - `bytes: List[int]` - - `"flex"` + - `logprob: float` - - `"scale"` + - `class BetaResponseOutputRefusal: …` - - `"priority"` + A refusal from the model. - - `status: Optional[BetaResponseStatus]` + - `refusal: str` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The refusal explanation from the model. - - `"completed"` + - `type: Literal["refusal"]` - - `"failed"` + The type of the refusal. Always `refusal`. - - `"in_progress"` + - `"refusal"` - - `"cancelled"` + - `role: Literal["assistant"]` - - `"queued"` + The role of the output message. Always `assistant`. - - `"incomplete"` + - `"assistant"` - - `text: Optional[BetaResponseTextConfig]` + - `status: Literal["in_progress", "completed", "incomplete"]` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `"in_progress"` - - `format: Optional[BetaResponseFormatTextConfig]` + - `"completed"` - An object specifying the format that the model must output. + - `"incomplete"` - Configuring `{ "type": "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). + - `type: Literal["message"]` - The default format is `{ "type": "text" }` with no additional options. + The type of the output message. Always `message`. - **Not recommended for gpt-4o and newer models:** + - `"message"` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `agent: Optional[Agent]` - - `class Text: …` + The agent that produced this item. - Default response format. Used to generate text responses. + - `agent_name: str` - - `type: Literal["text"]` + The canonical name of the agent that produced this item. - The type of response format being defined. Always `text`. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `"text"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `class BetaResponseFormatTextJSONSchemaConfig: …` + - `"commentary"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"final_answer"` - - `name: str` + - `class BetaResponseFileSearchToolCall: …` - 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. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `schema: Dict[str, object]` + - `id: str` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The unique ID of the file search tool call. - - `type: Literal["json_schema"]` + - `queries: List[str]` - The type of response format being defined. Always `json_schema`. + The queries used to search for files. - - `"json_schema"` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - - `description: Optional[str]` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"in_progress"` - - `strict: Optional[bool]` + - `"searching"` - 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). + - `"completed"` - - `class JSONObject: …` + - `"incomplete"` - 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. + - `"failed"` - - `type: Literal["json_object"]` + - `type: Literal["file_search_call"]` - The type of response format being defined. Always `json_object`. + The type of the file search tool call. Always `file_search_call`. - - `"json_object"` + - `"file_search_call"` - - `verbosity: Optional[Literal["low", "medium", "high"]]` + - `agent: Optional[Agent]` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + The agent that produced this item. - - `"low"` + - `agent_name: str` - - `"medium"` + The canonical name of the agent that produced this item. - - `"high"` + - `results: Optional[List[Result]]` - - `top_logprobs: Optional[int]` + The results of the file search tool call. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - - `truncation: Optional[Literal["auto", "disabled"]]` + 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, booleans, or numbers. - The truncation strategy to use for the model response. + - `str` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `float` - - `"auto"` + - `bool` - - `"disabled"` + - `file_id: Optional[str]` - - `usage: Optional[BetaResponseUsage]` + The unique ID of the file. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `filename: Optional[str]` - - `input_tokens: int` + The name of the file. - The number of input tokens. + - `score: Optional[float]` - - `input_tokens_details: InputTokensDetails` + The relevance score of the file - a value between 0 and 1. - A detailed breakdown of the input tokens. + - `text: Optional[str]` - - `cache_write_tokens: int` + The text that was retrieved from the file. - The number of input tokens that were written to the cache. + - `class BetaResponseFunctionToolCall: …` - - `cached_tokens: int` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `arguments: str` - - `output_tokens: int` + A JSON string of the arguments to pass to the function. - The number of output tokens. + - `call_id: str` - - `output_tokens_details: OutputTokensDetails` + The unique ID of the function tool call generated by the model. - A detailed breakdown of the output tokens. + - `name: str` - - `reasoning_tokens: int` + The name of the function to run. - The number of reasoning tokens. + - `type: Literal["function_call"]` - - `total_tokens: int` + The type of the function tool call. Always `function_call`. - The total number of tokens used. + - `"function_call"` - - `user: Optional[str]` + - `id: Optional[str]` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The unique ID of the function tool call. - - `sequence_number: int` + - `agent: Optional[Agent]` - The sequence number of this event. + The agent that produced this item. - - `type: Literal["response.in_progress"]` + - `agent_name: str` - The type of the event. Always `response.in_progress`. + The canonical name of the agent that produced this item. - - `"response.in_progress"` + - `caller: Optional[Caller]` - - `agent: Optional[Agent]` + The execution context that produced this tool call. - The agent that owns this multi-agent streaming event. + - `class CallerDirect: …` - - `agent_name: str` + - `type: Literal["direct"]` - The canonical name of the agent that produced this item. + - `"direct"` -### Beta Response Includable + - `class CallerProgram: …` -- `Literal["file_search_call.results", "web_search_call.results", "web_search_call.action.sources", 5 more]` + - `caller_id: str` - Specify additional output data to include in the model response. Currently supported values are: + The call ID of the program item that produced this tool call. - - `web_search_call.results`: Include the search results of the web search tool call. - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + - `type: Literal["program"]` - - `"file_search_call.results"` + - `"program"` - - `"web_search_call.results"` + - `namespace: Optional[str]` - - `"web_search_call.action.sources"` + The namespace of the function to run. - - `"message.input_image.image_url"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"computer_call_output.output.image_url"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"code_interpreter_call.outputs"` + - `"in_progress"` - - `"reasoning.encrypted_content"` + - `"completed"` - - `"message.output_text.logprobs"` + - `"incomplete"` -### Beta Response Incomplete Event + - `class BetaResponseFunctionToolCallOutputItem: …` -- `class BetaResponseIncompleteEvent: …` + - `id: str` - An event that is emitted when a response finishes as incomplete. + The unique ID of the function call tool output. - - `response: BetaResponse` + - `call_id: str` - The response that was incomplete. + The unique ID of the function tool call generated by the model. - - `id: str` + - `output: Union[str, List[OutputOutputContentList]]` - Unique identifier for this Response. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `created_at: float` + - `str` - Unix timestamp (in seconds) of when this Response was created. + A string of the output of the function call. - - `error: Optional[BetaResponseError]` + - `List[OutputOutputContentList]` - An error object returned when the model fails to generate a Response. + Text, image, or file output of the function call. - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + - `class BetaResponseInputText: …` - The error code for the response. + A text input to the model. - - `"server_error"` + - `text: str` - - `"rate_limit_exceeded"` + The text input to the model. - - `"invalid_prompt"` + - `type: Literal["input_text"]` - - `"bio_policy"` + The type of the input item. Always `input_text`. - - `"vector_store_timeout"` + - `"input_text"` - - `"invalid_image"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"invalid_image_format"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"invalid_base64_image"` + - `mode: Literal["explicit"]` - - `"invalid_image_url"` + The breakpoint mode. Always `explicit`. - - `"image_too_large"` + - `"explicit"` - - `"image_too_small"` + - `class BetaResponseInputImage: …` - - `"image_parse_error"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"image_content_policy_violation"` + - `detail: Literal["low", "high", "auto", "original"]` - - `"invalid_image_mode"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"image_file_too_large"` + - `"low"` - - `"unsupported_image_media_type"` + - `"high"` - - `"empty_image_file"` + - `"auto"` - - `"failed_to_download_image"` + - `"original"` - - `"image_file_not_found"` + - `type: Literal["input_image"]` - - `message: str` + The type of the input item. Always `input_image`. - A human-readable description of the error. + - `"input_image"` - - `incomplete_details: Optional[IncompleteDetails]` + - `file_id: Optional[str]` - Details about why the response is incomplete. + The ID of the file to be sent to the model. - - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` + - `image_url: Optional[str]` - The reason why the response is incomplete. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"max_output_tokens"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"content_filter"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `instructions: Union[str, List[BetaResponseInputItem], null]` + - `mode: Literal["explicit"]` - A system (or developer) message inserted into the model's context. + The breakpoint mode. Always `explicit`. - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `"explicit"` - - `str` + - `class BetaResponseInputFile: …` - A text input to the model, equivalent to a text input with the - `developer` role. + A file input to the model. - - `List[BetaResponseInputItem]` + - `type: Literal["input_file"]` - A list of one or many input items to the model, containing - different content types. + The type of the input item. Always `input_file`. - - `class BetaEasyInputMessage: …` + - `"input_file"` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `content: Union[str, BetaResponseInputMessageContentList]` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `"auto"` - - `str` + - `"low"` - A text input to the model. + - `"high"` - - `List[BetaResponseInputContent]` + - `file_data: Optional[str]` - - `class BetaResponseInputText: …` + The content of the file to be sent to the model. - A text input to the model. + - `file_id: Optional[str]` - - `text: str` + The ID of the file to be sent to the model. - The text input to the model. + - `file_url: Optional[str]` - - `type: Literal["input_text"]` + The URL of the file to be sent to the model. - The type of the input item. Always `input_text`. + - `filename: Optional[str]` - - `"input_text"` + The name of the file to be sent to the model. - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` @@ -90159,292 +101332,280 @@ print(compacted_response) - `"explicit"` - - `class BetaResponseInputImage: …` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: Literal["low", "high", "auto", "original"]` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"low"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"high"` + - `"in_progress"` - - `"auto"` + - `"completed"` - - `"original"` + - `"incomplete"` - - `type: Literal["input_image"]` + - `type: Literal["function_call_output"]` - The type of the input item. Always `input_image`. + The type of the function tool call output. Always `function_call_output`. - - `"input_image"` + - `"function_call_output"` - - `file_id: Optional[str]` + - `agent: Optional[Agent]` - The ID of the file to be sent to the model. + The agent that produced this item. - - `image_url: Optional[str]` + - `agent_name: str` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The canonical name of the agent that produced this item. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `caller: Optional[Caller]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The execution context that produced this tool call. - - `mode: Literal["explicit"]` + - `class CallerDirect: …` - The breakpoint mode. Always `explicit`. + - `type: Literal["direct"]` - - `"explicit"` + The caller type. Always `direct`. - - `class BetaResponseInputFile: …` + - `"direct"` - A file input to the model. + - `class CallerProgram: …` - - `type: Literal["input_file"]` + - `caller_id: str` - The type of the input item. Always `input_file`. + The call ID of the program item that produced this tool call. - - `"input_file"` + - `type: Literal["program"]` - - `detail: Optional[Literal["auto", "low", "high"]]` + The caller type. Always `program`. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"program"` - - `"auto"` + - `created_by: Optional[str]` - - `"low"` + The identifier of the actor that created the item. - - `"high"` + - `class AgentMessage: …` - - `file_data: Optional[str]` + - `id: str` - The content of the file to be sent to the model. + The unique ID of the agent message. - - `file_id: Optional[str]` + - `author: str` - The ID of the file to be sent to the model. + The sending agent identity. - - `file_url: Optional[str]` + - `content: List[AgentMessageContent]` - The URL of the file to be sent to the model. + Encrypted content sent between agents. - - `filename: Optional[str]` + - `class BetaResponseInputText: …` - The name of the file to be sent to the model. + A text input to the model. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `class BetaResponseOutputText: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A text output from the model. - - `mode: Literal["explicit"]` + - `class AgentMessageContentText: …` - The breakpoint mode. Always `explicit`. + A text content. - - `"explicit"` + - `text: str` - - `role: Literal["user", "assistant", "system", "developer"]` + - `type: Literal["text"]` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `"text"` - - `"user"` + - `class AgentMessageContentSummaryText: …` - - `"assistant"` + A summary text from the model. - - `"system"` + - `text: str` - - `"developer"` + A summary of the reasoning output from the model so far. - - `phase: Optional[Literal["commentary"]]` + - `type: Literal["summary_text"]` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The type of the object. Always `summary_text`. - - `"commentary"` + - `"summary_text"` - - `type: Optional[Literal["message"]]` + - `class AgentMessageContentReasoningText: …` - The type of the message input. Always `message`. + Reasoning text from the model. - - `"message"` + - `text: str` - - `class Message: …` + The reasoning text from the model. - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + - `type: Literal["reasoning_text"]` - - `content: BetaResponseInputMessageContentList` + The type of the reasoning text. Always `reasoning_text`. - A list of one or many input items to the model, containing different content - types. + - `"reasoning_text"` - - `class BetaResponseInputText: …` + - `class BetaResponseOutputRefusal: …` - A text input to the model. + A refusal from the model. - `class BetaResponseInputImage: …` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class BetaResponseInputFile: …` + - `class AgentMessageContentComputerScreenshot: …` - A file input to the model. + A screenshot of a computer. - - `role: Literal["user", "system", "developer"]` + - `detail: Literal["low", "high", "auto", "original"]` - The role of the message input. One of `user`, `system`, or `developer`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"user"` + - `"low"` - - `"system"` + - `"high"` - - `"developer"` + - `"auto"` - - `agent: Optional[MessageAgent]` + - `"original"` - The agent that produced this item. + - `file_id: Optional[str]` - - `agent_name: str` + The identifier of an uploaded file that contains the screenshot. - The canonical name of the agent that produced this item. + - `image_url: Optional[str]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The URL of the screenshot image. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: Literal["computer_screenshot"]` - - `"in_progress"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `"completed"` + - `"computer_screenshot"` - - `"incomplete"` + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - - `type: Optional[Literal["message"]]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The type of the message input. Always set to `message`. + - `mode: Literal["explicit"]` - - `"message"` + The breakpoint mode. Always `explicit`. - - `class BetaResponseOutputMessage: …` + - `"explicit"` - An output message from the model. + - `class BetaResponseInputFile: …` - - `id: str` + A file input to the model. - The unique ID of the output message. + - `class AgentMessageContentEncryptedContent: …` - - `content: List[Content]` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The content of the output message. + - `encrypted_content: str` - - `class BetaResponseOutputText: …` + Opaque encrypted content. - A text output from the model. + - `type: Literal["encrypted_content"]` - - `annotations: List[Annotation]` + The type of the input item. Always `encrypted_content`. - The annotations of the text output. + - `"encrypted_content"` - - `class AnnotationFileCitation: …` + - `recipient: str` - A citation to a file. + The destination agent identity. - - `file_id: str` + - `type: Literal["agent_message"]` - The ID of the file. + The type of the item. Always `agent_message`. - - `filename: str` + - `"agent_message"` - The filename of the file cited. + - `agent: Optional[AgentMessageAgent]` - - `index: int` + The agent that produced this item. - The index of the file in the list of files. + - `agent_name: str` - - `type: Literal["file_citation"]` + The canonical name of the agent that produced this item. - The type of the file citation. Always `file_citation`. + - `class MultiAgentCall: …` - - `"file_citation"` + - `id: str` - - `class AnnotationURLCitation: …` + The unique ID of the multi-agent call item. - A citation for a web resource used to generate a model response. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `end_index: int` + The multi-agent action to execute. - The index of the last character of the URL citation in the message. + - `"spawn_agent"` - - `start_index: int` + - `"interrupt_agent"` - The index of the first character of the URL citation in the message. + - `"list_agents"` - - `title: str` + - `"send_message"` - The title of the web resource. + - `"followup_task"` - - `type: Literal["url_citation"]` + - `"wait_agent"` - The type of the URL citation. Always `url_citation`. + - `arguments: str` - - `"url_citation"` + The JSON string of arguments generated for the action. - - `url: str` + - `call_id: str` - The URL of the web resource. + The unique ID linking this call to its output. - - `class AnnotationContainerFileCitation: …` + - `type: Literal["multi_agent_call"]` - A citation for a container file used to generate a model response. + The type of the multi-agent call. Always `multi_agent_call`. - - `container_id: str` + - `"multi_agent_call"` - The ID of the container file. + - `agent: Optional[MultiAgentCallAgent]` - - `end_index: int` + The agent that produced this item. - The index of the last character of the container file citation in the message. + - `agent_name: str` - - `file_id: str` + The canonical name of the agent that produced this item. - The ID of the file. + - `class MultiAgentCallOutput: …` - - `filename: str` + - `id: str` - The filename of the container file cited. + The unique ID of the multi-agent call output item. - - `start_index: int` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - The index of the first character of the container file citation in the message. + The multi-agent action that produced this result. - - `type: Literal["container_file_citation"]` + - `"spawn_agent"` - The type of the container file citation. Always `container_file_citation`. + - `"interrupt_agent"` - - `"container_file_citation"` + - `"list_agents"` - - `class AnnotationFilePath: …` + - `"send_message"` - A path to a file. + - `"followup_task"` - - `file_id: str` + - `"wait_agent"` - The ID of the file. + - `call_id: str` - - `index: int` + The unique ID of the multi-agent call. - The index of the file in the list of files. + - `output: List[BetaResponseOutputText]` - - `type: Literal["file_path"]` + Text output returned by the multi-agent action. - The type of the file path. Always `file_path`. + - `annotations: List[Annotation]` - - `"file_path"` + The annotations of the text output. - `text: str` @@ -90454,94 +101615,103 @@ print(compacted_response) The type of the output text. Always `output_text`. - - `"output_text"` - - `logprobs: Optional[List[Logprob]]` - - `token: str` + - `type: Literal["multi_agent_call_output"]` - - `bytes: List[int]` + The type of the multi-agent result. Always `multi_agent_call_output`. - - `logprob: float` + - `"multi_agent_call_output"` - - `top_logprobs: List[LogprobTopLogprob]` + - `agent: Optional[MultiAgentCallOutputAgent]` - - `token: str` + The agent that produced this item. - - `bytes: List[int]` + - `agent_name: str` - - `logprob: float` + The canonical name of the agent that produced this item. - - `class BetaResponseOutputRefusal: …` + - `class BetaResponseFunctionWebSearch: …` - A refusal from the model. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `refusal: str` + - `id: str` - The refusal explanation from the model. + The unique ID of the web search tool call. - - `type: Literal["refusal"]` + - `action: Action` - The type of the refusal. Always `refusal`. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `"refusal"` + - `class ActionSearch: …` - - `role: Literal["assistant"]` + Action type "search" - Performs a web search query. - The role of the output message. Always `assistant`. + - `type: Literal["search"]` - - `"assistant"` + The action type. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"search"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `queries: Optional[List[str]]` - - `"in_progress"` + The search queries. - - `"completed"` + - `query: Optional[str]` - - `"incomplete"` + The search query. - - `type: Literal["message"]` + - `sources: Optional[List[ActionSearchSource]]` - The type of the output message. Always `message`. + The sources used in the search. - - `"message"` + - `type: Literal["url"]` - - `agent: Optional[Agent]` + The type of source. Always `url`. - The agent that produced this item. + - `"url"` - - `agent_name: str` + - `url: str` - The canonical name of the agent that produced this item. + The URL of the source. - - `phase: Optional[Literal["commentary"]]` + - `class ActionOpenPage: …` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + Action type "open_page" - Opens a specific URL from search results. - - `"commentary"` + - `type: Literal["open_page"]` - - `class BetaResponseFileSearchToolCall: …` + The action type. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"open_page"` - - `id: str` + - `url: Optional[str]` - The unique ID of the file search tool call. + The URL opened by the model. - - `queries: List[str]` + - `class ActionFindInPage: …` - The queries used to search for files. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `pattern: str` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The pattern or text to search for within the page. + + - `type: Literal["find_in_page"]` + + The action type. + + - `"find_in_page"` + + - `url: str` + + The URL of the page searched for the pattern. + + - `status: Literal["in_progress", "searching", "completed", "failed"]` + + The status of the web search tool call. - `"in_progress"` @@ -90549,15 +101719,13 @@ print(compacted_response) - `"completed"` - - `"incomplete"` - - `"failed"` - - `type: Literal["file_search_call"]` + - `type: Literal["web_search_call"]` - The type of the file search tool call. Always `file_search_call`. + The type of the web search tool call. Always `web_search_call`. - - `"file_search_call"` + - `"web_search_call"` - `agent: Optional[Agent]` @@ -90567,40 +101735,6 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `results: Optional[List[Result]]` - - The results of the file search tool call. - - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - - 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, booleans, or numbers. - - - `str` - - - `float` - - - `bool` - - - `file_id: Optional[str]` - - The unique ID of the file. - - - `filename: Optional[str]` - - The name of the file. - - - `score: Optional[float]` - - The relevance score of the file - a value between 0 and 1. - - - `text: Optional[str]` - - The text that was retrieved from the file. - - `class BetaResponseComputerToolCall: …` A tool call to a computer use tool. See the @@ -90891,9 +102025,11 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ComputerCallOutput: …` + - `class BetaResponseComputerToolCallOutputItem: …` - The output of a computer tool call. + - `id: str` + + The unique ID of the computer call tool output. - `call_id: str` @@ -90918,19 +102054,29 @@ print(compacted_response) The URL of the screenshot image. + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + - `type: Literal["computer_call_output"]` The type of the computer tool call output. Always `computer_call_output`. - `"computer_call_output"` - - `id: Optional[str]` - - The ID of the computer tool call output. - - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - The safety checks reported by the API that have been acknowledged by the developer. + The safety checks reported by the API that have been acknowledged by the + developer. - `id: str` @@ -90944,7 +102090,7 @@ print(compacted_response) Details about the pending safety check. - - `agent: Optional[ComputerCallOutputAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -90952,146 +102098,40 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - - `"in_progress"` - - - `"completed"` + - `created_by: Optional[str]` - - `"incomplete"` + The identifier of the actor that created the item. - - `class BetaResponseFunctionWebSearch: …` + - `class BetaResponseReasoningItem: …` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: str` - The unique ID of the web search tool call. - - - `action: Action` - - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). - - - `class ActionSearch: …` - - Action type "search" - Performs a web search query. - - - `type: Literal["search"]` - - The action type. - - - `"search"` - - - `queries: Optional[List[str]]` - - The search queries. - - - `query: Optional[str]` - - The search query. - - - `sources: Optional[List[ActionSearchSource]]` - - The sources used in the search. - - - `type: Literal["url"]` - - The type of source. Always `url`. - - - `"url"` - - - `url: str` - - The URL of the source. - - - `class ActionOpenPage: …` - - Action type "open_page" - Opens a specific URL from search results. - - - `type: Literal["open_page"]` - - The action type. - - - `"open_page"` - - - `url: Optional[str]` - - The URL opened by the model. - - - `class ActionFindInPage: …` - - Action type "find_in_page": Searches for a pattern within a loaded page. - - - `pattern: str` - - The pattern or text to search for within the page. - - - `type: Literal["find_in_page"]` - - The action type. - - - `"find_in_page"` - - - `url: str` - - The URL of the page searched for the pattern. - - - `status: Literal["in_progress", "searching", "completed", "failed"]` - - The status of the web search tool call. - - - `"in_progress"` - - - `"searching"` - - - `"completed"` - - - `"failed"` - - - `type: Literal["web_search_call"]` - - The type of the web search tool call. Always `web_search_call`. - - - `"web_search_call"` - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `class BetaResponseFunctionToolCall: …` - - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - - `arguments: str` + The unique identifier of the reasoning content. - A JSON string of the arguments to pass to the function. + - `summary: List[Summary]` - - `call_id: str` + Reasoning summary content. - The unique ID of the function tool call generated by the model. + - `text: str` - - `name: str` + A summary of the reasoning output from the model so far. - The name of the function to run. + - `type: Literal["summary_text"]` - - `type: Literal["function_call"]` + The type of the object. Always `summary_text`. - The type of the function tool call. Always `function_call`. + - `"summary_text"` - - `"function_call"` + - `type: Literal["reasoning"]` - - `id: Optional[str]` + The type of the object. Always `reasoning`. - The unique ID of the function tool call. + - `"reasoning"` - `agent: Optional[Agent]` @@ -91101,29 +102141,24 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` - - - `type: Literal["direct"]` + - `content: Optional[List[Content]]` - - `"direct"` + Reasoning text content. - - `class CallerProgram: …` + - `text: str` - - `caller_id: str` + The reasoning text from the model. - The call ID of the program item that produced this tool call. + - `type: Literal["reasoning_text"]` - - `type: Literal["program"]` + The type of the reasoning text. Always `reasoning_text`. - - `"program"` + - `"reasoning_text"` - - `namespace: Optional[str]` + - `encrypted_content: Optional[str]` - The namespace of the function to run. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` @@ -91136,235 +102171,31 @@ print(compacted_response) - `"incomplete"` - - `class FunctionCallOutput: …` - - The output of a function tool call. - - - `call_id: str` - - The unique ID of the function tool call generated by the model. - - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - - Text, image, or file output of the function tool call. - - - `str` - - A JSON string of the output of the function tool call. - - - `List[BetaResponseFunctionCallOutputItem]` - - - `class BetaResponseInputTextContent: …` - - A text input to the model. - - - `text: str` - - The text input to the model. - - - `type: Literal["input_text"]` - - The type of the input item. Always `input_text`. - - - `"input_text"` - - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: Literal["explicit"]` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `class BetaResponseInputImageContent: …` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `type: Literal["input_image"]` - - The type of the input item. Always `input_image`. - - - `"input_image"` - - - `detail: Optional[Literal["low", "high", "auto", "original"]]` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `file_id: Optional[str]` - - The ID of the file to be sent to the model. - - - `image_url: Optional[str]` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: Literal["explicit"]` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `class BetaResponseInputFileContent: …` - - A file input to the model. - - - `type: Literal["input_file"]` - - The type of the input item. Always `input_file`. - - - `"input_file"` - - - `detail: Optional[Literal["auto", "low", "high"]]` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: Optional[str]` - - The base64-encoded data of the file to be sent to the model. - - - `file_id: Optional[str]` - - The ID of the file to be sent to the model. - - - `file_url: Optional[str]` - - The URL of the file to be sent to the model. - - - `filename: Optional[str]` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: Literal["explicit"]` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `type: Literal["function_call_output"]` - - The type of the function tool call output. Always `function_call_output`. - - - `"function_call_output"` - - - `id: Optional[str]` - - The unique ID of the function tool call output. Populated when this item is returned via API. - - - `agent: Optional[FunctionCallOutputAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `caller: Optional[FunctionCallOutputCaller]` + - `class Program: …` - The execution context that produced this tool call. + - `id: str` - - `class FunctionCallOutputCallerDirect: …` + The unique ID of the program item. - - `type: Literal["direct"]` + - `call_id: str` - The caller type. Always `direct`. + The stable call ID of the program item. - - `"direct"` + - `code: str` - - `class FunctionCallOutputCallerProgram: …` + The JavaScript source executed by programmatic tool calling. - - `caller_id: str` + - `fingerprint: str` - The call ID of the program item that produced this tool call. + Opaque program replay fingerprint that must be round-tripped. - `type: Literal["program"]` - The caller type. Always `program`. + The type of the item. Always `program`. - `"program"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `class AgentMessage: …` - - A message routed between agents. - - - `author: str` - - The sending agent identity. - - - `content: List[AgentMessageContent]` - - Plaintext, image, or encrypted content sent between agents. - - - `class BetaResponseInputTextContent: …` - - A text input to the model. - - - `class BetaResponseInputImageContent: …` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `class AgentMessageContentEncryptedContent: …` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `encrypted_content: str` - - Opaque encrypted content. - - - `type: Literal["encrypted_content"]` - - The type of the input item. Always `encrypted_content`. - - - `"encrypted_content"` - - - `recipient: str` - - The destination agent identity. - - - `type: Literal["agent_message"]` - - The item type. Always `agent_message`. - - - `"agent_message"` - - - `id: Optional[str]` - - The unique ID of this agent message item. - - - `agent: Optional[AgentMessageAgent]` + - `agent: Optional[ProgramAgent]` The agent that produced this item. @@ -91372,43 +102203,35 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class MultiAgentCall: …` - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - The multi-agent action that was executed. - - - `"spawn_agent"` - - - `"interrupt_agent"` + - `class ProgramOutput: …` - - `"list_agents"` + - `id: str` - - `"send_message"` + The unique ID of the program output item. - - `"followup_task"` + - `call_id: str` - - `"wait_agent"` + The call ID of the program item. - - `arguments: str` + - `result: str` - The action arguments as a JSON string. + The result produced by the program item. - - `call_id: str` + - `status: Literal["completed", "incomplete"]` - The unique ID linking this call to its output. + The terminal status of the program output item. - - `type: Literal["multi_agent_call"]` + - `"completed"` - The item type. Always `multi_agent_call`. + - `"incomplete"` - - `"multi_agent_call"` + - `type: Literal["program_output"]` - - `id: Optional[str]` + The type of the item. Always `program_output`. - The unique ID of this multi-agent call. + - `"program_output"` - - `agent: Optional[MultiAgentCallAgent]` + - `agent: Optional[ProgramOutputAgent]` The agent that produced this item. @@ -91416,129 +102239,45 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput: …` - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `call_id: str` - - The unique ID of the multi-agent call. - - - `output: List[MultiAgentCallOutputOutput]` - - Text output returned by the multi-agent action. - - - `text: str` - - The text content. - - - `type: Literal["output_text"]` - - The content type. Always `output_text`. - - - `"output_text"` - - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - - Citations associated with the text content. - - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - - - `file_id: str` - - The ID of the file. - - - `filename: str` - - The filename of the file cited. - - - `index: int` - - The index of the file in the list of files. - - - `type: Literal["file_citation"]` - - The citation type. Always `file_citation`. - - - `"file_citation"` - - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` - - - `end_index: int` - - The index of the last character of the citation in the message. - - - `start_index: int` - - The index of the first character of the citation in the message. - - - `title: str` - - The title of the cited resource. - - - `type: Literal["url_citation"]` - - The citation type. Always `url_citation`. - - - `"url_citation"` - - - `url: str` - - The URL of the cited resource. - - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `class BetaResponseToolSearchCall: …` - - `container_id: str` + - `id: str` - The ID of the container. + The unique ID of the tool search call item. - - `end_index: int` + - `arguments: object` - The index of the last character of the citation in the message. + Arguments used for the tool search call. - - `file_id: str` + - `call_id: Optional[str]` - The ID of the container file. + The unique ID of the tool search call generated by the model. - - `filename: str` + - `execution: Literal["server", "client"]` - The filename of the container file cited. + Whether tool search was executed by the server or by the client. - - `start_index: int` + - `"server"` - The index of the first character of the citation in the message. + - `"client"` - - `type: Literal["container_file_citation"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The citation type. Always `container_file_citation`. + The status of the tool search call item that was recorded. - - `"container_file_citation"` + - `"in_progress"` - - `type: Literal["multi_agent_call_output"]` + - `"completed"` - The item type. Always `multi_agent_call_output`. + - `"incomplete"` - - `"multi_agent_call_output"` + - `type: Literal["tool_search_call"]` - - `id: Optional[str]` + The type of the item. Always `tool_search_call`. - The unique ID of this multi-agent call output. + - `"tool_search_call"` - - `agent: Optional[MultiAgentCallOutputAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -91546,35 +102285,21 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ToolSearchCall: …` - - - `arguments: object` - - The arguments supplied to the tool search call. - - - `type: Literal["tool_search_call"]` - - The item type. Always `tool_search_call`. - - - `"tool_search_call"` - - - `id: Optional[str]` - - The unique ID of this tool search call. + - `created_by: Optional[str]` - - `agent: Optional[ToolSearchCallAgent]` + The identifier of the actor that created the item. - The agent that produced this item. + - `class BetaResponseToolSearchOutputItem: …` - - `agent_name: str` + - `id: str` - The canonical name of the agent that produced this item. + The unique ID of the tool search output item. - `call_id: Optional[str]` The unique ID of the tool search call generated by the model. - - `execution: Optional[Literal["server", "client"]]` + - `execution: Literal["server", "client"]` Whether tool search was executed by the server or by the client. @@ -91582,21 +102307,19 @@ print(compacted_response) - `"client"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the tool search call. + The status of the tool search output item that was recorded. - `"in_progress"` - `"completed"` - - `"incomplete"` - - - `class BetaResponseToolSearchOutputItemParam: …` + - `"incomplete"` - `tools: List[BetaTool]` - The loaded tool definitions returned by the tool search output. + The loaded tool definitions returned by tool search. - `class BetaFunctionTool: …` @@ -91695,7 +102418,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -91705,7 +102428,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `class FiltersCompoundFilter: …` @@ -91752,7 +102479,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -91762,7 +102489,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `object` @@ -92686,14 +103417,10 @@ print(compacted_response) - `type: Literal["tool_search_output"]` - The item type. Always `tool_search_output`. + The type of the item. Always `tool_search_output`. - `"tool_search_output"` - - `id: Optional[str]` - - The unique ID of this tool search output. - - `agent: Optional[Agent]` The agent that produced this item. @@ -92702,39 +103429,39 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `call_id: Optional[str]` - - The unique ID of the tool search call generated by the model. + - `created_by: Optional[str]` - - `execution: Optional[Literal["server", "client"]]` + The identifier of the actor that created the item. - Whether tool search was executed by the server or by the client. + - `class AdditionalTools: …` - - `"server"` + - `id: str` - - `"client"` + The unique ID of the additional tools item. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `role: Literal["unknown", "user", "assistant", 5 more]` - The status of the tool search output. + The role that provided the additional tools. - - `"in_progress"` + - `"unknown"` - - `"completed"` + - `"user"` - - `"incomplete"` + - `"assistant"` - - `class AdditionalTools: …` + - `"system"` - - `role: Literal["developer"]` + - `"critic"` - The role that provided the additional tools. Only `developer` is supported. + - `"discriminator"` - `"developer"` + - `"tool"` + - `tools: List[BetaTool]` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `class BetaFunctionTool: …` @@ -92802,14 +103529,10 @@ print(compacted_response) - `type: Literal["additional_tools"]` - The item type. Always `additional_tools`. + The type of the item. Always `additional_tools`. - `"additional_tools"` - - `id: Optional[str]` - - The unique ID of this additional tools item. - - `agent: Optional[AdditionalToolsAgent]` The agent that produced this item. @@ -92818,82 +103541,17 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseReasoningItem: …` + - `class BetaResponseCompactionItem: …` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `id: str` - The unique identifier of the reasoning content. - - - `summary: List[Summary]` - - Reasoning summary content. - - - `text: str` - - A summary of the reasoning output from the model so far. - - - `type: Literal["summary_text"]` - - The type of the object. Always `summary_text`. - - - `"summary_text"` - - - `type: Literal["reasoning"]` - - The type of the object. Always `reasoning`. - - - `"reasoning"` - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `content: Optional[List[Content]]` - - Reasoning text content. - - - `text: str` - - The reasoning text from the model. - - - `type: Literal["reasoning_text"]` - - The type of the reasoning text. Always `reasoning_text`. - - - `"reasoning_text"` - - - `encrypted_content: Optional[str]` - - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `class BetaResponseCompactionItemParam: …` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The unique ID of the compaction item. - `encrypted_content: str` - The encrypted content of the compaction summary. + The encrypted content that was produced by compaction. - `type: Literal["compaction"]` @@ -92901,125 +103559,6 @@ print(compacted_response) - `"compaction"` - - `id: Optional[str]` - - The ID of the compaction item. - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `class ImageGenerationCall: …` - - An image generation request made by the model. - - - `id: str` - - The unique ID of the image generation call. - - - `result: Optional[str]` - - The generated image encoded in base64. - - - `status: Literal["in_progress", "completed", "generating", "failed"]` - - The status of the image generation call. - - - `"in_progress"` - - - `"completed"` - - - `"generating"` - - - `"failed"` - - - `type: Literal["image_generation_call"]` - - The type of the image generation call. Always `image_generation_call`. - - - `"image_generation_call"` - - - `agent: Optional[ImageGenerationCallAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `class BetaResponseCodeInterpreterToolCall: …` - - A tool call to run code. - - - `id: str` - - The unique ID of the code interpreter tool call. - - - `code: Optional[str]` - - The code to run, or null if not available. - - - `container_id: str` - - The ID of the container used to run the code. - - - `outputs: Optional[List[Output]]` - - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. - - - `class OutputLogs: …` - - The logs output from the code interpreter. - - - `logs: str` - - The logs output from the code interpreter. - - - `type: Literal["logs"]` - - The type of the output. Always `logs`. - - - `"logs"` - - - `class OutputImage: …` - - The image output from the code interpreter. - - - `type: Literal["image"]` - - The type of the output. Always `image`. - - - `"image"` - - - `url: str` - - The URL of the image output from the code interpreter. - - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"interpreting"` - - - `"failed"` - - - `type: Literal["code_interpreter_call"]` - - The type of the code interpreter tool call. Always `code_interpreter_call`. - - - `"code_interpreter_call"` - - `agent: Optional[Agent]` The agent that produced this item. @@ -93028,809 +103567,41 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCall: …` - - A tool call to run a command on the local shell. - - - `id: str` - - The unique ID of the local shell call. - - - `action: LocalShellCallAction` - - Execute a shell command on the server. - - - `command: List[str]` - - The command to run. - - - `env: Dict[str, str]` - - Environment variables to set for the command. - - - `type: Literal["exec"]` - - The type of the local shell action. Always `exec`. - - - `"exec"` - - - `timeout_ms: Optional[int]` - - Optional timeout in milliseconds for the command. - - - `user: Optional[str]` - - Optional user to run the command as. - - - `working_directory: Optional[str]` - - Optional working directory to run the command in. - - - `call_id: str` - - The unique ID of the local shell tool call generated by the model. - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the local shell call. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `type: Literal["local_shell_call"]` - - The type of the local shell call. Always `local_shell_call`. - - - `"local_shell_call"` - - - `agent: Optional[LocalShellCallAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `class LocalShellCallOutput: …` - - The output of a local shell tool call. - - - `id: str` - - The unique ID of the local shell tool call generated by the model. - - - `output: str` - - A JSON string of the output of the local shell tool call. - - - `type: Literal["local_shell_call_output"]` - - The type of the local shell tool call output. Always `local_shell_call_output`. - - - `"local_shell_call_output"` - - - `agent: Optional[LocalShellCallOutputAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `class ShellCall: …` - - A tool representing a request to execute one or more shell commands. - - - `action: ShellCallAction` - - The shell commands and limits that describe how to run the tool call. - - - `commands: List[str]` - - Ordered shell commands for the execution environment to run. - - - `max_output_length: Optional[int]` - - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - - `timeout_ms: Optional[int]` - - Maximum wall-clock time in milliseconds to allow the shell commands to run. - - - `call_id: str` - - The unique ID of the shell tool call generated by the model. - - - `type: Literal["shell_call"]` - - The type of the item. Always `shell_call`. - - - `"shell_call"` - - - `id: Optional[str]` - - The unique ID of the shell tool call. Populated when this item is returned via API. - - - `agent: Optional[ShellCallAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `caller: Optional[ShellCallCaller]` - - The execution context that produced this tool call. - - - `class ShellCallCallerDirect: …` - - - `type: Literal["direct"]` - - The caller type. Always `direct`. - - - `"direct"` - - - `class ShellCallCallerProgram: …` - - - `caller_id: str` - - The call ID of the program item that produced this tool call. - - - `type: Literal["program"]` - - The caller type. Always `program`. - - - `"program"` - - - `environment: Optional[ShellCallEnvironment]` - - The environment to execute the shell commands in. - - - `class BetaLocalEnvironment: …` - - - `class BetaContainerReference: …` - - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `class ShellCallOutput: …` - - The streamed output items emitted by a shell tool call. - - - `call_id: str` - - The unique ID of the shell tool call generated by the model. - - - `output: List[BetaResponseFunctionShellCallOutputContent]` - - Captured chunks of stdout and stderr output, along with their associated outcomes. - - - `outcome: Outcome` - - The exit or timeout outcome associated with this shell call. - - - `class OutcomeTimeout: …` - - Indicates that the shell call exceeded its configured time limit. - - - `type: Literal["timeout"]` - - The outcome type. Always `timeout`. - - - `"timeout"` - - - `class OutcomeExit: …` - - Indicates that the shell commands finished and returned an exit code. - - - `exit_code: int` - - The exit code returned by the shell process. - - - `type: Literal["exit"]` - - The outcome type. Always `exit`. - - - `"exit"` - - - `stderr: str` - - Captured stderr output for the shell call. - - - `stdout: str` - - Captured stdout output for the shell call. - - - `type: Literal["shell_call_output"]` - - The type of the item. Always `shell_call_output`. - - - `"shell_call_output"` - - - `id: Optional[str]` - - The unique ID of the shell tool call output. Populated when this item is returned via API. - - - `agent: Optional[ShellCallOutputAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `caller: Optional[ShellCallOutputCaller]` - - The execution context that produced this tool call. - - - `class ShellCallOutputCallerDirect: …` - - - `type: Literal["direct"]` - - The caller type. Always `direct`. - - - `"direct"` - - - `class ShellCallOutputCallerProgram: …` - - - `caller_id: str` - - The call ID of the program item that produced this tool call. - - - `type: Literal["program"]` - - The caller type. Always `program`. - - - `"program"` - - - `max_output_length: Optional[int]` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the shell call output. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `class ApplyPatchCall: …` - - A tool call representing a request to create, delete, or update files using diff patches. - - - `call_id: str` - - The unique ID of the apply patch tool call generated by the model. - - - `operation: ApplyPatchCallOperation` - - The specific create, delete, or update instruction for the apply_patch tool call. - - - `class ApplyPatchCallOperationCreateFile: …` - - Instruction for creating a new file via the apply_patch tool. - - - `diff: str` - - Unified diff content to apply when creating the file. - - - `path: str` - - Path of the file to create relative to the workspace root. - - - `type: Literal["create_file"]` - - The operation type. Always `create_file`. - - - `"create_file"` - - - `class ApplyPatchCallOperationDeleteFile: …` - - Instruction for deleting an existing file via the apply_patch tool. - - - `path: str` - - Path of the file to delete relative to the workspace root. - - - `type: Literal["delete_file"]` - - The operation type. Always `delete_file`. - - - `"delete_file"` - - - `class ApplyPatchCallOperationUpdateFile: …` - - Instruction for updating an existing file via the apply_patch tool. - - - `diff: str` - - Unified diff content to apply to the existing file. - - - `path: str` - - Path of the file to update relative to the workspace root. - - - `type: Literal["update_file"]` - - The operation type. Always `update_file`. - - - `"update_file"` - - - `status: Literal["in_progress", "completed"]` - - The status of the apply patch tool call. One of `in_progress` or `completed`. - - - `"in_progress"` - - - `"completed"` - - - `type: Literal["apply_patch_call"]` - - The type of the item. Always `apply_patch_call`. - - - `"apply_patch_call"` - - - `id: Optional[str]` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `agent: Optional[ApplyPatchCallAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `caller: Optional[ApplyPatchCallCaller]` - - The execution context that produced this tool call. - - - `class ApplyPatchCallCallerDirect: …` - - - `type: Literal["direct"]` - - The caller type. Always `direct`. - - - `"direct"` - - - `class ApplyPatchCallCallerProgram: …` - - - `caller_id: str` - - The call ID of the program item that produced this tool call. - - - `type: Literal["program"]` - - The caller type. Always `program`. - - - `"program"` - - - `class ApplyPatchCallOutput: …` - - The streamed output emitted by an apply patch tool call. - - - `call_id: str` - - The unique ID of the apply patch tool call generated by the model. - - - `status: Literal["completed", "failed"]` - - The status of the apply patch tool call output. One of `completed` or `failed`. - - - `"completed"` - - - `"failed"` - - - `type: Literal["apply_patch_call_output"]` - - The type of the item. Always `apply_patch_call_output`. - - - `"apply_patch_call_output"` - - - `id: Optional[str]` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - - `agent: Optional[ApplyPatchCallOutputAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `caller: Optional[ApplyPatchCallOutputCaller]` - - The execution context that produced this tool call. - - - `class ApplyPatchCallOutputCallerDirect: …` - - - `type: Literal["direct"]` - - The caller type. Always `direct`. - - - `"direct"` - - - `class ApplyPatchCallOutputCallerProgram: …` - - - `caller_id: str` - - The call ID of the program item that produced this tool call. - - - `type: Literal["program"]` - - The caller type. Always `program`. - - - `"program"` - - - `output: Optional[str]` - - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - - `class McpListTools: …` - - A list of tools available on an MCP server. - - - `id: str` - - The unique ID of the list. - - - `server_label: str` - - The label of the MCP server. - - - `tools: List[McpListToolsTool]` - - The tools available on the server. - - - `input_schema: object` - - The JSON schema describing the tool's input. - - - `name: str` - - The name of the tool. - - - `annotations: Optional[object]` - - Additional annotations about the tool. - - - `description: Optional[str]` - - The description of the tool. - - - `type: Literal["mcp_list_tools"]` - - The type of the item. Always `mcp_list_tools`. - - - `"mcp_list_tools"` - - - `agent: Optional[McpListToolsAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `error: Optional[str]` - - Error message if the server could not list tools. - - - `class McpApprovalRequest: …` - - A request for human approval of a tool invocation. - - - `id: str` - - The unique ID of the approval request. - - - `arguments: str` - - A JSON string of arguments for the tool. - - - `name: str` - - The name of the tool to run. - - - `server_label: str` - - The label of the MCP server making the request. - - - `type: Literal["mcp_approval_request"]` - - The type of the item. Always `mcp_approval_request`. - - - `"mcp_approval_request"` - - - `agent: Optional[McpApprovalRequestAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `class McpApprovalResponse: …` - - A response to an MCP approval request. - - - `approval_request_id: str` - - The ID of the approval request being answered. - - - `approve: bool` - - Whether the request was approved. - - - `type: Literal["mcp_approval_response"]` - - The type of the item. Always `mcp_approval_response`. - - - `"mcp_approval_response"` - - - `id: Optional[str]` - - The unique ID of the approval response - - - `agent: Optional[McpApprovalResponseAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `reason: Optional[str]` + - `created_by: Optional[str]` - Optional reason for the decision. + The identifier of the actor that created the item. - - `class McpCall: …` + - `class ImageGenerationCall: …` - An invocation of a tool on an MCP server. + An image generation request made by the model. - `id: str` - The unique ID of the tool call. - - - `arguments: str` - - A JSON string of the arguments passed to the tool. - - - `name: str` - - The name of the tool that was run. - - - `server_label: str` - - The label of the MCP server running the tool. - - - `type: Literal["mcp_call"]` - - The type of the item. Always `mcp_call`. - - - `"mcp_call"` - - - `agent: Optional[McpCallAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `approval_request_id: Optional[str]` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: Optional[str]` - - The error from the tool call, if any. - - - `output: Optional[str]` - - The output from the tool call. - - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"calling"` - - - `"failed"` - - - `class BetaResponseCustomToolCallOutput: …` - - The output of a custom tool call from your code, being sent back to the model. - - - `call_id: str` - - The call ID, used to map this custom tool call output to a custom tool call. - - - `output: Union[str, List[OutputOutputContentList]]` - - The output from the custom tool call generated by your code. - Can be a string or an list of output content. - - - `str` - - A string of the output of the custom tool call. - - - `List[OutputOutputContentList]` - - Text, image, or file output of the custom tool call. - - - `class BetaResponseInputText: …` - - A text input to the model. - - - `class BetaResponseInputImage: …` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class BetaResponseInputFile: …` - - A file input to the model. - - - `type: Literal["custom_tool_call_output"]` - - The type of the custom tool call output. Always `custom_tool_call_output`. - - - `"custom_tool_call_output"` - - - `id: Optional[str]` - - The unique ID of the custom tool call output in the OpenAI platform. - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` - - - `type: Literal["direct"]` - - The caller type. Always `direct`. - - - `"direct"` - - - `class CallerProgram: …` - - - `caller_id: str` - - The call ID of the program item that produced this tool call. - - - `type: Literal["program"]` - - The caller type. Always `program`. - - - `"program"` - - - `class BetaResponseCustomToolCall: …` - - A call to a custom tool created by the model. - - - `call_id: str` - - An identifier used to map this custom tool call to a tool call output. - - - `input: str` - - The input for the custom tool call generated by the model. - - - `name: str` - - The name of the custom tool being called. - - - `type: Literal["custom_tool_call"]` - - The type of the custom tool call. Always `custom_tool_call`. - - - `"custom_tool_call"` - - - `id: Optional[str]` - - The unique ID of the custom tool call in the OpenAI platform. - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` - - - `type: Literal["direct"]` - - - `"direct"` - - - `class CallerProgram: …` - - - `caller_id: str` - - The call ID of the program item that produced this tool call. - - - `type: Literal["program"]` - - - `"program"` - - - `namespace: Optional[str]` - - The namespace of the custom tool being called. - - - `class CompactionTrigger: …` - - Compacts the current context. Must be the final input item. + The unique ID of the image generation call. - - `type: Literal["compaction_trigger"]` + - `result: Optional[str]` - The type of the item. Always `compaction_trigger`. + The generated image encoded in base64. - - `"compaction_trigger"` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - - `agent: Optional[CompactionTriggerAgent]` + The status of the image generation call. - The agent that produced this item. + - `"in_progress"` - - `agent_name: str` + - `"completed"` - The canonical name of the agent that produced this item. + - `"generating"` - - `class ItemReference: …` + - `"failed"` - An internal identifier for an item to reference. + - `type: Literal["image_generation_call"]` - - `id: str` + The type of the image generation call. Always `image_generation_call`. - The ID of the item to reference. + - `"image_generation_call"` - - `agent: Optional[ItemReferenceAgent]` + - `agent: Optional[ImageGenerationCallAgent]` The agent that produced this item. @@ -93838,73 +103609,76 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `type: Optional[Literal["item_reference"]]` - - The type of item to reference. Always `item_reference`. - - - `"item_reference"` + - `class BetaResponseCodeInterpreterToolCall: …` - - `class Program: …` + A tool call to run code. - `id: str` - The unique ID of this program item. + The unique ID of the code interpreter tool call. - - `call_id: str` + - `code: Optional[str]` - The stable call ID of the program item. + The code to run, or null if not available. - - `code: str` + - `container_id: str` - The JavaScript source executed by programmatic tool calling. + The ID of the container used to run the code. - - `fingerprint: str` + - `outputs: Optional[List[Output]]` - Opaque program replay fingerprint that must be round-tripped. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `type: Literal["program"]` + - `class OutputLogs: …` - The item type. Always `program`. + The logs output from the code interpreter. - - `"program"` + - `logs: str` - - `agent: Optional[ProgramAgent]` + The logs output from the code interpreter. - The agent that produced this item. + - `type: Literal["logs"]` - - `agent_name: str` + The type of the output. Always `logs`. - The canonical name of the agent that produced this item. + - `"logs"` - - `class ProgramOutput: …` + - `class OutputImage: …` - - `id: str` + The image output from the code interpreter. - The unique ID of this program output item. + - `type: Literal["image"]` - - `call_id: str` + The type of the output. Always `image`. - The call ID of the program item. + - `"image"` - - `result: str` + - `url: str` - The result produced by the program item. + The URL of the image output from the code interpreter. - - `status: Literal["completed", "incomplete"]` + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - The terminal status of the program output. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` - `"completed"` - `"incomplete"` - - `type: Literal["program_output"]` + - `"interpreting"` - The item type. Always `program_output`. + - `"failed"` - - `"program_output"` + - `type: Literal["code_interpreter_call"]` - - `agent: Optional[ProgramOutputAgent]` + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `agent: Optional[Agent]` The agent that produced this item. @@ -93912,291 +103686,271 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `metadata: Optional[Dict[str, str]]` - - 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. + - `class LocalShellCall: …` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A tool call to run a command on the local shell. - - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` + - `id: str` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + The unique ID of the local shell call. - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` + - `action: LocalShellCallAction` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + Execute a shell command on the server. - - `"gpt-5.6-sol"` + - `command: List[str]` - - `"gpt-5.6-terra"` + The command to run. - - `"gpt-5.6-luna"` + - `env: Dict[str, str]` - - `"gpt-5.4"` + Environment variables to set for the command. - - `"gpt-5.4-mini"` + - `type: Literal["exec"]` - - `"gpt-5.4-nano"` + The type of the local shell action. Always `exec`. - - `"gpt-5.4-mini-2026-03-17"` + - `"exec"` - - `"gpt-5.4-nano-2026-03-17"` + - `timeout_ms: Optional[int]` - - `"gpt-5.3-chat-latest"` + Optional timeout in milliseconds for the command. - - `"gpt-5.2"` + - `user: Optional[str]` - - `"gpt-5.2-2025-12-11"` + Optional user to run the command as. - - `"gpt-5.2-chat-latest"` + - `working_directory: Optional[str]` - - `"gpt-5.2-pro"` + Optional working directory to run the command in. - - `"gpt-5.2-pro-2025-12-11"` + - `call_id: str` - - `"gpt-5.1"` + The unique ID of the local shell tool call generated by the model. - - `"gpt-5.1-2025-11-13"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"gpt-5.1-codex"` + The status of the local shell call. - - `"gpt-5.1-mini"` + - `"in_progress"` - - `"gpt-5.1-chat-latest"` + - `"completed"` - - `"gpt-5"` + - `"incomplete"` - - `"gpt-5-mini"` + - `type: Literal["local_shell_call"]` - - `"gpt-5-nano"` + The type of the local shell call. Always `local_shell_call`. - - `"gpt-5-2025-08-07"` + - `"local_shell_call"` - - `"gpt-5-mini-2025-08-07"` + - `agent: Optional[LocalShellCallAgent]` - - `"gpt-5-nano-2025-08-07"` + The agent that produced this item. - - `"gpt-5-chat-latest"` + - `agent_name: str` - - `"gpt-4.1"` + The canonical name of the agent that produced this item. - - `"gpt-4.1-mini"` + - `class LocalShellCallOutput: …` - - `"gpt-4.1-nano"` + The output of a local shell tool call. - - `"gpt-4.1-2025-04-14"` + - `id: str` - - `"gpt-4.1-mini-2025-04-14"` + The unique ID of the local shell tool call generated by the model. - - `"gpt-4.1-nano-2025-04-14"` + - `output: str` - - `"o4-mini"` + A JSON string of the output of the local shell tool call. - - `"o4-mini-2025-04-16"` + - `type: Literal["local_shell_call_output"]` - - `"o3"` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"o3-2025-04-16"` + - `"local_shell_call_output"` - - `"o3-mini"` + - `agent: Optional[LocalShellCallOutputAgent]` - - `"o3-mini-2025-01-31"` + The agent that produced this item. - - `"o1"` + - `agent_name: str` - - `"o1-2024-12-17"` + The canonical name of the agent that produced this item. - - `"o1-preview"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"o1-preview-2024-09-12"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"o1-mini"` + - `"in_progress"` - - `"o1-mini-2024-09-12"` + - `"completed"` - - `"gpt-4o"` + - `"incomplete"` - - `"gpt-4o-2024-11-20"` + - `class BetaResponseFunctionShellToolCall: …` - - `"gpt-4o-2024-08-06"` + A tool call that executes one or more shell commands in a managed environment. - - `"gpt-4o-2024-05-13"` + - `id: str` - - `"gpt-4o-audio-preview"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"gpt-4o-audio-preview-2024-10-01"` + - `action: Action` - - `"gpt-4o-audio-preview-2024-12-17"` + The shell commands and limits that describe how to run the tool call. - - `"gpt-4o-audio-preview-2025-06-03"` + - `commands: List[str]` - - `"gpt-4o-mini-audio-preview"` + - `max_output_length: Optional[int]` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + Optional maximum number of characters to return from each command. - - `"gpt-4o-search-preview"` + - `timeout_ms: Optional[int]` - - `"gpt-4o-mini-search-preview"` + Optional timeout in milliseconds for the commands. - - `"gpt-4o-search-preview-2025-03-11"` + - `call_id: str` - - `"gpt-4o-mini-search-preview-2025-03-11"` + The unique ID of the shell tool call generated by the model. - - `"chatgpt-4o-latest"` + - `environment: Optional[Environment]` - - `"codex-mini-latest"` + Represents the use of a local environment to perform shell actions. - - `"gpt-4o-mini"` + - `class BetaResponseLocalEnvironment: …` - - `"gpt-4o-mini-2024-07-18"` + Represents the use of a local environment to perform shell actions. - - `"gpt-4-turbo"` + - `type: Literal["local"]` - - `"gpt-4-turbo-2024-04-09"` + The environment type. Always `local`. - - `"gpt-4-0125-preview"` + - `"local"` - - `"gpt-4-turbo-preview"` + - `class BetaResponseContainerReference: …` - - `"gpt-4-1106-preview"` + Represents a container created with /v1/containers. - - `"gpt-4-vision-preview"` + - `container_id: str` - - `"gpt-4"` + - `type: Literal["container_reference"]` - - `"gpt-4-0314"` + The environment type. Always `container_reference`. - - `"gpt-4-0613"` + - `"container_reference"` - - `"gpt-4-32k"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"gpt-4-32k-0314"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `"gpt-4-32k-0613"` + - `"in_progress"` - - `"gpt-3.5-turbo"` + - `"completed"` - - `"gpt-3.5-turbo-16k"` + - `"incomplete"` - - `"gpt-3.5-turbo-0301"` + - `type: Literal["shell_call"]` - - `"gpt-3.5-turbo-0613"` + The type of the item. Always `shell_call`. - - `"gpt-3.5-turbo-1106"` + - `"shell_call"` - - `"gpt-3.5-turbo-0125"` + - `agent: Optional[Agent]` - - `"gpt-3.5-turbo-16k-0613"` + The agent that produced this item. - - `"o1-pro"` + - `agent_name: str` - - `"o1-pro-2025-03-19"` + The canonical name of the agent that produced this item. - - `"o3-pro"` + - `caller: Optional[Caller]` - - `"o3-pro-2025-06-10"` + The execution context that produced this tool call. - - `"o3-deep-research"` + - `class CallerDirect: …` - - `"o3-deep-research-2025-06-26"` + - `type: Literal["direct"]` - - `"o4-mini-deep-research"` + - `"direct"` - - `"o4-mini-deep-research-2025-06-26"` + - `class CallerProgram: …` - - `"computer-use-preview"` + - `caller_id: str` - - `"computer-use-preview-2025-03-11"` + The call ID of the program item that produced this tool call. - - `"gpt-5-codex"` + - `type: Literal["program"]` - - `"gpt-5-pro"` + - `"program"` - - `"gpt-5-pro-2025-10-06"` + - `created_by: Optional[str]` - - `"gpt-5.1-codex-max"` + The ID of the entity that created this tool call. - - `str` + - `class BetaResponseFunctionShellToolCallOutput: …` - - `object: Literal["response"]` + The output of a shell tool call that was emitted. - The object type of this resource - always set to `response`. + - `id: str` - - `"response"` + The unique ID of the shell call output. Populated when this item is returned via API. - - `output: List[BetaResponseOutputItem]` + - `call_id: str` - An array of content items generated by the model. + The unique ID of the shell tool call generated by the model. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `max_output_length: Optional[int]` - - `class BetaResponseOutputMessage: …` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - An output message from the model. + - `output: List[Output]` - - `class BetaResponseFileSearchToolCall: …` + An array of shell call output contents - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `outcome: OutputOutcome` - - `class BetaResponseFunctionToolCall: …` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `class OutputOutcomeTimeout: …` - - `class BetaResponseFunctionToolCallOutputItem: …` + Indicates that the shell call exceeded its configured time limit. - - `id: str` + - `type: Literal["timeout"]` - The unique ID of the function call tool output. + The outcome type. Always `timeout`. - - `call_id: str` + - `"timeout"` - The unique ID of the function tool call generated by the model. + - `class OutputOutcomeExit: …` - - `output: Union[str, List[OutputOutputContentList]]` + Indicates that the shell commands finished and returned an exit code. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `exit_code: int` - - `str` + Exit code from the shell process. - A string of the output of the function call. + - `type: Literal["exit"]` - - `List[OutputOutputContentList]` + The outcome type. Always `exit`. - Text, image, or file output of the function call. + - `"exit"` - - `class BetaResponseInputText: …` + - `stderr: str` - A text input to the model. + The standard error output that was captured. - - `class BetaResponseInputImage: …` + - `stdout: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The standard output that was captured. - - `class BetaResponseInputFile: …` + - `created_by: Optional[str]` - A file input to the model. + The identifier of the actor that created the item. - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -94204,11 +103958,11 @@ print(compacted_response) - `"incomplete"` - - `type: Literal["function_call_output"]` + - `type: Literal["shell_call_output"]` - The type of the function tool call output. Always `function_call_output`. + The type of the shell call output. Always `shell_call_output`. - - `"function_call_output"` + - `"shell_call_output"` - `agent: Optional[Agent]` @@ -94226,8 +103980,6 @@ print(compacted_response) - `type: Literal["direct"]` - The caller type. Always `direct`. - - `"direct"` - `class CallerProgram: …` @@ -94238,151 +103990,151 @@ print(compacted_response) - `type: Literal["program"]` - The caller type. Always `program`. - - `"program"` - `created_by: Optional[str]` The identifier of the actor that created the item. - - `class AgentMessage: …` + - `class BetaResponseApplyPatchToolCall: …` + + A tool call that applies file diffs by creating, deleting, or updating files. - `id: str` - The unique ID of the agent message. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `author: str` + - `call_id: str` - The sending agent identity. + The unique ID of the apply patch tool call generated by the model. - - `content: List[AgentMessageContent]` + - `operation: Operation` - Encrypted content sent between agents. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `class BetaResponseInputText: …` + - `class OperationCreateFile: …` - A text input to the model. + Instruction describing how to create a file via the apply_patch tool. - - `class BetaResponseOutputText: …` + - `diff: str` - A text output from the model. + Diff to apply. - - `class AgentMessageContentText: …` + - `path: str` - A text content. + Path of the file to create. - - `text: str` + - `type: Literal["create_file"]` - - `type: Literal["text"]` + Create a new file with the provided diff. - - `"text"` + - `"create_file"` - - `class AgentMessageContentSummaryText: …` + - `class OperationDeleteFile: …` - A summary text from the model. + Instruction describing how to delete a file via the apply_patch tool. - - `text: str` + - `path: str` - A summary of the reasoning output from the model so far. + Path of the file to delete. - - `type: Literal["summary_text"]` + - `type: Literal["delete_file"]` - The type of the object. Always `summary_text`. + Delete the specified file. - - `"summary_text"` + - `"delete_file"` - - `class AgentMessageContentReasoningText: …` + - `class OperationUpdateFile: …` - Reasoning text from the model. + Instruction describing how to update a file via the apply_patch tool. - - `text: str` + - `diff: str` - The reasoning text from the model. + Diff to apply. - - `type: Literal["reasoning_text"]` + - `path: str` - The type of the reasoning text. Always `reasoning_text`. + Path of the file to update. - - `"reasoning_text"` + - `type: Literal["update_file"]` - - `class BetaResponseOutputRefusal: …` + Update an existing file with the provided diff. - A refusal from the model. + - `"update_file"` - - `class BetaResponseInputImage: …` + - `status: Literal["in_progress", "completed"]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `class AgentMessageContentComputerScreenshot: …` + - `"in_progress"` - A screenshot of a computer. + - `"completed"` - - `detail: Literal["low", "high", "auto", "original"]` + - `type: Literal["apply_patch_call"]` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The type of the item. Always `apply_patch_call`. - - `"low"` + - `"apply_patch_call"` - - `"high"` + - `agent: Optional[Agent]` - - `"auto"` + The agent that produced this item. - - `"original"` + - `agent_name: str` - - `file_id: Optional[str]` + The canonical name of the agent that produced this item. - The identifier of an uploaded file that contains the screenshot. + - `caller: Optional[Caller]` - - `image_url: Optional[str]` + The execution context that produced this tool call. - The URL of the screenshot image. + - `class CallerDirect: …` - - `type: Literal["computer_screenshot"]` + - `type: Literal["direct"]` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"direct"` - - `"computer_screenshot"` + - `class CallerProgram: …` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `caller_id: str` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The call ID of the program item that produced this tool call. - - `mode: Literal["explicit"]` + - `type: Literal["program"]` - The breakpoint mode. Always `explicit`. + - `"program"` - - `"explicit"` + - `created_by: Optional[str]` - - `class BetaResponseInputFile: …` + The ID of the entity that created this tool call. - A file input to the model. + - `class BetaResponseApplyPatchToolCallOutput: …` - - `class AgentMessageContentEncryptedContent: …` + The output emitted by an apply patch tool call. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `id: str` - - `encrypted_content: str` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - Opaque encrypted content. + - `call_id: str` - - `type: Literal["encrypted_content"]` + The unique ID of the apply patch tool call generated by the model. - The type of the input item. Always `encrypted_content`. + - `status: Literal["completed", "failed"]` - - `"encrypted_content"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `recipient: str` + - `"completed"` - The destination agent identity. + - `"failed"` - - `type: Literal["agent_message"]` + - `type: Literal["apply_patch_call_output"]` - The type of the item. Always `agent_message`. + The type of the item. Always `apply_patch_call_output`. - - `"agent_message"` + - `"apply_patch_call_output"` - - `agent: Optional[AgentMessageAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -94390,169 +104142,134 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class MultiAgentCall: …` - - - `id: str` - - The unique ID of the multi-agent call item. - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - The multi-agent action to execute. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` + - `caller: Optional[Caller]` - - `"send_message"` + The execution context that produced this tool call. - - `"followup_task"` + - `class CallerDirect: …` - - `"wait_agent"` + - `type: Literal["direct"]` - - `arguments: str` + - `"direct"` - The JSON string of arguments generated for the action. + - `class CallerProgram: …` - - `call_id: str` + - `caller_id: str` - The unique ID linking this call to its output. + The call ID of the program item that produced this tool call. - - `type: Literal["multi_agent_call"]` + - `type: Literal["program"]` - The type of the multi-agent call. Always `multi_agent_call`. + - `"program"` - - `"multi_agent_call"` + - `created_by: Optional[str]` - - `agent: Optional[MultiAgentCallAgent]` + The ID of the entity that created this tool call output. - The agent that produced this item. + - `output: Optional[str]` - - `agent_name: str` + Optional textual output returned by the apply patch tool. - The canonical name of the agent that produced this item. + - `class McpCall: …` - - `class MultiAgentCallOutput: …` + An invocation of a tool on an MCP server. - `id: str` - The unique ID of the multi-agent call output item. - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - The multi-agent action that produced this result. - - - `"spawn_agent"` + The unique ID of the tool call. - - `"interrupt_agent"` + - `arguments: str` - - `"list_agents"` + A JSON string of the arguments passed to the tool. - - `"send_message"` + - `name: str` - - `"followup_task"` + The name of the tool that was run. - - `"wait_agent"` + - `server_label: str` - - `call_id: str` + The label of the MCP server running the tool. - The unique ID of the multi-agent call. + - `type: Literal["mcp_call"]` - - `output: List[BetaResponseOutputText]` + The type of the item. Always `mcp_call`. - Text output returned by the multi-agent action. + - `"mcp_call"` - - `annotations: List[Annotation]` + - `agent: Optional[McpCallAgent]` - The annotations of the text output. + The agent that produced this item. - - `text: str` + - `agent_name: str` - The text output from the model. + The canonical name of the agent that produced this item. - - `type: Literal["output_text"]` + - `approval_request_id: Optional[str]` - The type of the output text. Always `output_text`. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `logprobs: Optional[List[Logprob]]` + - `error: Optional[str]` - - `type: Literal["multi_agent_call_output"]` + The error from the tool call, if any. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `output: Optional[str]` - - `"multi_agent_call_output"` + The output from the tool call. - - `agent: Optional[MultiAgentCallOutputAgent]` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - The agent that produced this item. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `agent_name: str` + - `"in_progress"` - The canonical name of the agent that produced this item. + - `"completed"` - - `class BetaResponseFunctionWebSearch: …` + - `"incomplete"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `"calling"` - - `class BetaResponseComputerToolCall: …` + - `"failed"` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `class McpListTools: …` - - `class BetaResponseComputerToolCallOutputItem: …` + A list of tools available on an MCP server. - `id: str` - The unique ID of the computer call tool output. - - - `call_id: str` - - The ID of the computer tool call that produced the output. - - - `output: BetaResponseComputerToolCallOutputScreenshot` - - A computer screenshot image used with the computer use tool. - - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The unique ID of the list. - - `"completed"` + - `server_label: str` - - `"incomplete"` + The label of the MCP server. - - `"failed"` + - `tools: List[McpListToolsTool]` - - `"in_progress"` + The tools available on the server. - - `type: Literal["computer_call_output"]` + - `input_schema: object` - The type of the computer tool call output. Always `computer_call_output`. + The JSON schema describing the tool's input. - - `"computer_call_output"` + - `name: str` - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + The name of the tool. - The safety checks reported by the API that have been acknowledged by the - developer. + - `annotations: Optional[object]` - - `id: str` + Additional annotations about the tool. - The ID of the pending safety check. + - `description: Optional[str]` - - `code: Optional[str]` + The description of the tool. - The type of the pending safety check. + - `type: Literal["mcp_list_tools"]` - - `message: Optional[str]` + The type of the item. Always `mcp_list_tools`. - Details about the pending safety check. + - `"mcp_list_tools"` - - `agent: Optional[Agent]` + - `agent: Optional[McpListToolsAgent]` The agent that produced this item. @@ -94560,42 +104277,37 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. + - `error: Optional[str]` - - `class BetaResponseReasoningItem: …` + Error message if the server could not list tools. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class McpApprovalRequest: …` - - `class Program: …` + A request for human approval of a tool invocation. - `id: str` - The unique ID of the program item. + The unique ID of the approval request. - - `call_id: str` + - `arguments: str` - The stable call ID of the program item. + A JSON string of arguments for the tool. - - `code: str` + - `name: str` - The JavaScript source executed by programmatic tool calling. + The name of the tool to run. - - `fingerprint: str` + - `server_label: str` - Opaque program replay fingerprint that must be round-tripped. + The label of the MCP server making the request. - - `type: Literal["program"]` + - `type: Literal["mcp_approval_request"]` - The type of the item. Always `program`. + The type of the item. Always `mcp_approval_request`. - - `"program"` + - `"mcp_approval_request"` - - `agent: Optional[ProgramAgent]` + - `agent: Optional[McpApprovalRequestAgent]` The agent that produced this item. @@ -94603,35 +104315,29 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ProgramOutput: …` - - - `id: str` - - The unique ID of the program output item. - - - `call_id: str` + - `class McpApprovalResponse: …` - The call ID of the program item. + A response to an MCP approval request. - - `result: str` + - `id: str` - The result produced by the program item. + The unique ID of the approval response - - `status: Literal["completed", "incomplete"]` + - `approval_request_id: str` - The terminal status of the program output item. + The ID of the approval request being answered. - - `"completed"` + - `approve: bool` - - `"incomplete"` + Whether the request was approved. - - `type: Literal["program_output"]` + - `type: Literal["mcp_approval_response"]` - The type of the item. Always `program_output`. + The type of the item. Always `mcp_approval_response`. - - `"program_output"` + - `"mcp_approval_response"` - - `agent: Optional[ProgramOutputAgent]` + - `agent: Optional[McpApprovalResponseAgent]` The agent that produced this item. @@ -94639,43 +104345,35 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall: …` - - - `id: str` - - The unique ID of the tool search call item. - - - `arguments: object` - - Arguments used for the tool search call. + - `reason: Optional[str]` - - `call_id: Optional[str]` + Optional reason for the decision. - The unique ID of the tool search call generated by the model. + - `class BetaResponseCustomToolCall: …` - - `execution: Literal["server", "client"]` + A call to a custom tool created by the model. - Whether tool search was executed by the server or by the client. + - `call_id: str` - - `"server"` + An identifier used to map this custom tool call to a tool call output. - - `"client"` + - `input: str` - - `status: Literal["in_progress", "completed", "incomplete"]` + The input for the custom tool call generated by the model. - The status of the tool search call item that was recorded. + - `name: str` - - `"in_progress"` + The name of the custom tool being called. - - `"completed"` + - `type: Literal["custom_tool_call"]` - - `"incomplete"` + The type of the custom tool call. Always `custom_tool_call`. - - `type: Literal["tool_search_call"]` + - `"custom_tool_call"` - The type of the item. Always `tool_search_call`. + - `id: Optional[str]` - - `"tool_search_call"` + The unique ID of the custom tool call in the OpenAI platform. - `agent: Optional[Agent]` @@ -94685,249 +104383,241 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `class BetaResponseToolSearchOutputItem: …` - - - `id: str` + - `caller: Optional[Caller]` - The unique ID of the tool search output item. + The execution context that produced this tool call. - - `call_id: Optional[str]` + - `class CallerDirect: …` - The unique ID of the tool search call generated by the model. + - `type: Literal["direct"]` - - `execution: Literal["server", "client"]` + - `"direct"` - Whether tool search was executed by the server or by the client. + - `class CallerProgram: …` - - `"server"` + - `caller_id: str` - - `"client"` + The call ID of the program item that produced this tool call. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `type: Literal["program"]` - The status of the tool search output item that was recorded. + - `"program"` - - `"in_progress"` + - `namespace: Optional[str]` - - `"completed"` + The namespace of the custom tool being called. - - `"incomplete"` + - `class BetaResponseCustomToolCallOutputItem: …` - - `tools: List[BetaTool]` + The output of a custom tool call from your code, being sent back to the model. - The loaded tool definitions returned by tool search. + - `id: str` - - `class BetaFunctionTool: …` + The unique ID of the custom tool call output item. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `status: Literal["in_progress", "completed", "incomplete"]` - - `class BetaFileSearchTool: …` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `"in_progress"` - - `class BetaComputerTool: …` + - `"completed"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"incomplete"` - - `class BetaComputerUsePreviewTool: …` + - `created_by: Optional[str]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The identifier of the actor that created the item. - - `class BetaWebSearchTool: …` +### Beta Response Output Item Added Event - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). +- `class BetaResponseOutputItemAddedEvent: …` - - `class Mcp: …` + Emitted when a new output item is added. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `item: BetaResponseOutputItem` - - `class CodeInterpreter: …` + The output item that was added. - A tool that runs Python code to help generate a response to a prompt. + - `class BetaResponseOutputMessage: …` - - `class ProgrammaticToolCalling: …` + An output message from the model. - - `class ImageGeneration: …` + - `id: str` - A tool that generates images using the GPT image models. + The unique ID of the output message. - - `class LocalShell: …` + - `content: List[Content]` - A tool that allows the model to execute shell commands in a local environment. + The content of the output message. - - `class BetaFunctionShellTool: …` + - `class BetaResponseOutputText: …` - A tool that allows the model to execute shell commands. + A text output from the model. - - `class BetaCustomTool: …` + - `annotations: List[Annotation]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The annotations of the text output. - - `class BetaNamespaceTool: …` + - `class AnnotationFileCitation: …` - Groups function/custom tools under a shared namespace. + A citation to a file. - - `class BetaToolSearchTool: …` + - `file_id: str` - Hosted or BYOT tool search configuration for deferred tools. + The ID of the file. - - `class BetaWebSearchPreviewTool: …` + - `filename: str` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The filename of the file cited. - - `class BetaApplyPatchTool: …` + - `index: int` - Allows the assistant to create, delete, or update files using unified diffs. + The index of the file in the list of files. - - `type: Literal["tool_search_output"]` + - `type: Literal["file_citation"]` - The type of the item. Always `tool_search_output`. + The type of the file citation. Always `file_citation`. - - `"tool_search_output"` + - `"file_citation"` - - `agent: Optional[Agent]` + - `class AnnotationURLCitation: …` - The agent that produced this item. + A citation for a web resource used to generate a model response. - - `agent_name: str` + - `end_index: int` - The canonical name of the agent that produced this item. + The index of the last character of the URL citation in the message. - - `created_by: Optional[str]` + - `start_index: int` - The identifier of the actor that created the item. + The index of the first character of the URL citation in the message. - - `class AdditionalTools: …` + - `title: str` - - `id: str` + The title of the web resource. - The unique ID of the additional tools item. + - `type: Literal["url_citation"]` - - `role: Literal["unknown", "user", "assistant", 5 more]` + The type of the URL citation. Always `url_citation`. - The role that provided the additional tools. + - `"url_citation"` - - `"unknown"` + - `url: str` - - `"user"` + The URL of the web resource. - - `"assistant"` + - `class AnnotationContainerFileCitation: …` - - `"system"` + A citation for a container file used to generate a model response. - - `"critic"` + - `container_id: str` - - `"discriminator"` + The ID of the container file. - - `"developer"` + - `end_index: int` - - `"tool"` + The index of the last character of the container file citation in the message. - - `tools: List[BetaTool]` + - `file_id: str` - The additional tool definitions made available at this item. + The ID of the file. - - `class BetaFunctionTool: …` + - `filename: str` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The filename of the container file cited. - - `class BetaFileSearchTool: …` + - `start_index: int` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The index of the first character of the container file citation in the message. - - `class BetaComputerTool: …` + - `type: Literal["container_file_citation"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the container file citation. Always `container_file_citation`. - - `class BetaComputerUsePreviewTool: …` + - `"container_file_citation"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class AnnotationFilePath: …` - - `class BetaWebSearchTool: …` + A path to a file. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `file_id: str` - - `class Mcp: …` + The ID of the file. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `index: int` - - `class CodeInterpreter: …` + The index of the file in the list of files. - A tool that runs Python code to help generate a response to a prompt. + - `type: Literal["file_path"]` - - `class ProgrammaticToolCalling: …` + The type of the file path. Always `file_path`. - - `class ImageGeneration: …` + - `"file_path"` - A tool that generates images using the GPT image models. + - `text: str` - - `class LocalShell: …` + The text output from the model. - A tool that allows the model to execute shell commands in a local environment. + - `type: Literal["output_text"]` - - `class BetaFunctionShellTool: …` + The type of the output text. Always `output_text`. - A tool that allows the model to execute shell commands. + - `"output_text"` - - `class BetaCustomTool: …` + - `logprobs: Optional[List[Logprob]]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `token: str` - - `class BetaNamespaceTool: …` + - `bytes: List[int]` - Groups function/custom tools under a shared namespace. + - `logprob: float` - - `class BetaToolSearchTool: …` + - `top_logprobs: List[LogprobTopLogprob]` - Hosted or BYOT tool search configuration for deferred tools. + - `token: str` - - `class BetaWebSearchPreviewTool: …` + - `bytes: List[int]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `logprob: float` - - `class BetaApplyPatchTool: …` + - `class BetaResponseOutputRefusal: …` - Allows the assistant to create, delete, or update files using unified diffs. + A refusal from the model. - - `type: Literal["additional_tools"]` + - `refusal: str` - The type of the item. Always `additional_tools`. + The refusal explanation from the model. - - `"additional_tools"` + - `type: Literal["refusal"]` - - `agent: Optional[AdditionalToolsAgent]` + The type of the refusal. Always `refusal`. - The agent that produced this item. + - `"refusal"` - - `agent_name: str` + - `role: Literal["assistant"]` - The canonical name of the agent that produced this item. + The role of the output message. Always `assistant`. - - `class BetaResponseCompactionItem: …` + - `"assistant"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `status: Literal["in_progress", "completed", "incomplete"]` - - `id: str` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The unique ID of the compaction item. + - `"in_progress"` - - `encrypted_content: str` + - `"completed"` - The encrypted content that was produced by compaction. + - `"incomplete"` - - `type: Literal["compaction"]` + - `type: Literal["message"]` - The type of the item. Always `compaction`. + The type of the output message. Always `message`. - - `"compaction"` + - `"message"` - `agent: Optional[Agent]` @@ -94937,41 +104627,51 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` + - `phase: Optional[Literal["commentary", "final_answer"]]` - The identifier of the actor that created the item. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `class ImageGenerationCall: …` + - `"commentary"` - An image generation request made by the model. + - `"final_answer"` + + - `class BetaResponseFileSearchToolCall: …` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: str` - The unique ID of the image generation call. + The unique ID of the file search tool call. - - `result: Optional[str]` + - `queries: List[str]` - The generated image encoded in base64. + The queries used to search for files. - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - The status of the image generation call. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `"in_progress"` + - `"searching"` + - `"completed"` - - `"generating"` + - `"incomplete"` - `"failed"` - - `type: Literal["image_generation_call"]` + - `type: Literal["file_search_call"]` - The type of the image generation call. Always `image_generation_call`. + The type of the file search tool call. Always `file_search_call`. - - `"image_generation_call"` + - `"file_search_call"` - - `agent: Optional[ImageGenerationCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -94979,69 +104679,68 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall: …` - - A tool call to run code. - - - `class LocalShellCall: …` + - `results: Optional[List[Result]]` - A tool call to run a command on the local shell. + The results of the file search tool call. - - `id: str` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - The unique ID of the local shell call. + 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, booleans, or numbers. - - `action: LocalShellCallAction` + - `str` - Execute a shell command on the server. + - `float` - - `command: List[str]` + - `bool` - The command to run. + - `file_id: Optional[str]` - - `env: Dict[str, str]` + The unique ID of the file. - Environment variables to set for the command. + - `filename: Optional[str]` - - `type: Literal["exec"]` + The name of the file. - The type of the local shell action. Always `exec`. + - `score: Optional[float]` - - `"exec"` + The relevance score of the file - a value between 0 and 1. - - `timeout_ms: Optional[int]` + - `text: Optional[str]` - Optional timeout in milliseconds for the command. + The text that was retrieved from the file. - - `user: Optional[str]` + - `class BetaResponseFunctionToolCall: …` - Optional user to run the command as. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `working_directory: Optional[str]` + - `arguments: str` - Optional working directory to run the command in. + A JSON string of the arguments to pass to the function. - `call_id: str` - The unique ID of the local shell tool call generated by the model. - - - `status: Literal["in_progress", "completed", "incomplete"]` + The unique ID of the function tool call generated by the model. - The status of the local shell call. + - `name: str` - - `"in_progress"` + The name of the function to run. - - `"completed"` + - `type: Literal["function_call"]` - - `"incomplete"` + The type of the function tool call. Always `function_call`. - - `type: Literal["local_shell_call"]` + - `"function_call"` - The type of the local shell call. Always `local_shell_call`. + - `id: Optional[str]` - - `"local_shell_call"` + The unique ID of the function tool call. - - `agent: Optional[LocalShellCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -95049,35 +104748,34 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCallOutput: …` - - The output of a local shell tool call. + - `caller: Optional[Caller]` - - `id: str` + The execution context that produced this tool call. - The unique ID of the local shell tool call generated by the model. + - `class CallerDirect: …` - - `output: str` + - `type: Literal["direct"]` - A JSON string of the output of the local shell tool call. + - `"direct"` - - `type: Literal["local_shell_call_output"]` + - `class CallerProgram: …` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `caller_id: str` - - `"local_shell_call_output"` + The call ID of the program item that produced this tool call. - - `agent: Optional[LocalShellCallOutputAgent]` + - `type: Literal["program"]` - The agent that produced this item. + - `"program"` - - `agent_name: str` + - `namespace: Optional[str]` - The canonical name of the agent that produced this item. + The namespace of the function to run. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -95085,169 +104783,143 @@ print(compacted_response) - `"incomplete"` - - `class BetaResponseFunctionShellToolCall: …` - - A tool call that executes one or more shell commands in a managed environment. + - `class BetaResponseFunctionToolCallOutputItem: …` - `id: str` - The unique ID of the shell tool call. Populated when this item is returned via API. - - - `action: Action` - - The shell commands and limits that describe how to run the tool call. - - - `commands: List[str]` - - - `max_output_length: Optional[int]` - - Optional maximum number of characters to return from each command. - - - `timeout_ms: Optional[int]` - - Optional timeout in milliseconds for the commands. + The unique ID of the function call tool output. - `call_id: str` - The unique ID of the shell tool call generated by the model. - - - `environment: Optional[Environment]` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment: …` - - Represents the use of a local environment to perform shell actions. - - - `type: Literal["local"]` - - The environment type. Always `local`. + The unique ID of the function tool call generated by the model. - - `"local"` + - `output: Union[str, List[OutputOutputContentList]]` - - `class BetaResponseContainerReference: …` + The output from the function call generated by your code. + Can be a string or an list of output content. - Represents a container created with /v1/containers. + - `str` - - `container_id: str` + A string of the output of the function call. - - `type: Literal["container_reference"]` + - `List[OutputOutputContentList]` - The environment type. Always `container_reference`. + Text, image, or file output of the function call. - - `"container_reference"` + - `class BetaResponseInputText: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + A text input to the model. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `text: str` - - `"in_progress"` + The text input to the model. - - `"completed"` + - `type: Literal["input_text"]` - - `"incomplete"` + The type of the input item. Always `input_text`. - - `type: Literal["shell_call"]` + - `"input_text"` - The type of the item. Always `shell_call`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"shell_call"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `agent: Optional[Agent]` + - `mode: Literal["explicit"]` - The agent that produced this item. + The breakpoint mode. Always `explicit`. - - `agent_name: str` + - `"explicit"` - The canonical name of the agent that produced this item. + - `class BetaResponseInputImage: …` - - `caller: Optional[Caller]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The execution context that produced this tool call. + - `detail: Literal["low", "high", "auto", "original"]` - - `class CallerDirect: …` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: Literal["direct"]` + - `"low"` - - `"direct"` + - `"high"` - - `class CallerProgram: …` + - `"auto"` - - `caller_id: str` + - `"original"` - The call ID of the program item that produced this tool call. + - `type: Literal["input_image"]` - - `type: Literal["program"]` + The type of the input item. Always `input_image`. - - `"program"` + - `"input_image"` - - `created_by: Optional[str]` + - `file_id: Optional[str]` - The ID of the entity that created this tool call. + The ID of the file to be sent to the model. - - `class BetaResponseFunctionShellToolCallOutput: …` + - `image_url: Optional[str]` - The output of a shell tool call that was emitted. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `id: str` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The unique ID of the shell call output. Populated when this item is returned via API. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `call_id: str` + - `mode: Literal["explicit"]` - The unique ID of the shell tool call generated by the model. + The breakpoint mode. Always `explicit`. - - `max_output_length: Optional[int]` + - `"explicit"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `class BetaResponseInputFile: …` - - `output: List[Output]` + A file input to the model. - An array of shell call output contents + - `type: Literal["input_file"]` - - `outcome: OutputOutcome` + The type of the input item. Always `input_file`. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `"input_file"` - - `class OutputOutcomeTimeout: …` + - `detail: Optional[Literal["auto", "low", "high"]]` - Indicates that the shell call exceeded its configured time limit. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `type: Literal["timeout"]` + - `"auto"` - The outcome type. Always `timeout`. + - `"low"` - - `"timeout"` + - `"high"` - - `class OutputOutcomeExit: …` + - `file_data: Optional[str]` - Indicates that the shell commands finished and returned an exit code. + The content of the file to be sent to the model. - - `exit_code: int` + - `file_id: Optional[str]` - Exit code from the shell process. + The ID of the file to be sent to the model. - - `type: Literal["exit"]` + - `file_url: Optional[str]` - The outcome type. Always `exit`. + The URL of the file to be sent to the model. - - `"exit"` + - `filename: Optional[str]` - - `stderr: str` + The name of the file to be sent to the model. - The standard error output that was captured. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `stdout: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The standard output that was captured. + - `mode: Literal["explicit"]` - - `created_by: Optional[str]` + The breakpoint mode. Always `explicit`. - The identifier of the actor that created the item. + - `"explicit"` - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -95255,11 +104927,11 @@ print(compacted_response) - `"incomplete"` - - `type: Literal["shell_call_output"]` + - `type: Literal["function_call_output"]` - The type of the shell call output. Always `shell_call_output`. + The type of the function tool call output. Always `function_call_output`. - - `"shell_call_output"` + - `"function_call_output"` - `agent: Optional[Agent]` @@ -95277,6 +104949,8 @@ print(compacted_response) - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - `class CallerProgram: …` @@ -95287,151 +104961,151 @@ print(compacted_response) - `type: Literal["program"]` + The caller type. Always `program`. + - `"program"` - `created_by: Optional[str]` The identifier of the actor that created the item. - - `class BetaResponseApplyPatchToolCall: …` - - A tool call that applies file diffs by creating, deleting, or updating files. + - `class AgentMessage: …` - `id: str` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of the agent message. - - `call_id: str` + - `author: str` - The unique ID of the apply patch tool call generated by the model. + The sending agent identity. - - `operation: Operation` + - `content: List[AgentMessageContent]` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + Encrypted content sent between agents. - - `class OperationCreateFile: …` + - `class BetaResponseInputText: …` - Instruction describing how to create a file via the apply_patch tool. + A text input to the model. - - `diff: str` + - `class BetaResponseOutputText: …` - Diff to apply. + A text output from the model. - - `path: str` + - `class AgentMessageContentText: …` - Path of the file to create. + A text content. - - `type: Literal["create_file"]` + - `text: str` - Create a new file with the provided diff. + - `type: Literal["text"]` - - `"create_file"` + - `"text"` - - `class OperationDeleteFile: …` + - `class AgentMessageContentSummaryText: …` - Instruction describing how to delete a file via the apply_patch tool. + A summary text from the model. - - `path: str` + - `text: str` - Path of the file to delete. + A summary of the reasoning output from the model so far. - - `type: Literal["delete_file"]` + - `type: Literal["summary_text"]` - Delete the specified file. + The type of the object. Always `summary_text`. - - `"delete_file"` + - `"summary_text"` - - `class OperationUpdateFile: …` + - `class AgentMessageContentReasoningText: …` - Instruction describing how to update a file via the apply_patch tool. + Reasoning text from the model. - - `diff: str` + - `text: str` - Diff to apply. + The reasoning text from the model. - - `path: str` + - `type: Literal["reasoning_text"]` - Path of the file to update. + The type of the reasoning text. Always `reasoning_text`. - - `type: Literal["update_file"]` + - `"reasoning_text"` - Update an existing file with the provided diff. + - `class BetaResponseOutputRefusal: …` - - `"update_file"` + A refusal from the model. - - `status: Literal["in_progress", "completed"]` + - `class BetaResponseInputImage: …` - The status of the apply patch tool call. One of `in_progress` or `completed`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"in_progress"` + - `class AgentMessageContentComputerScreenshot: …` - - `"completed"` + A screenshot of a computer. - - `type: Literal["apply_patch_call"]` + - `detail: Literal["low", "high", "auto", "original"]` - The type of the item. Always `apply_patch_call`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"apply_patch_call"` + - `"low"` - - `agent: Optional[Agent]` + - `"high"` - The agent that produced this item. + - `"auto"` - - `agent_name: str` + - `"original"` - The canonical name of the agent that produced this item. + - `file_id: Optional[str]` - - `caller: Optional[Caller]` + The identifier of an uploaded file that contains the screenshot. - The execution context that produced this tool call. + - `image_url: Optional[str]` - - `class CallerDirect: …` + The URL of the screenshot image. - - `type: Literal["direct"]` + - `type: Literal["computer_screenshot"]` - - `"direct"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `class CallerProgram: …` + - `"computer_screenshot"` - - `caller_id: str` + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - The call ID of the program item that produced this tool call. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `type: Literal["program"]` + - `mode: Literal["explicit"]` - - `"program"` + The breakpoint mode. Always `explicit`. - - `created_by: Optional[str]` + - `"explicit"` - The ID of the entity that created this tool call. + - `class BetaResponseInputFile: …` - - `class BetaResponseApplyPatchToolCallOutput: …` + A file input to the model. - The output emitted by an apply patch tool call. + - `class AgentMessageContentEncryptedContent: …` - - `id: str` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `encrypted_content: str` - - `call_id: str` + Opaque encrypted content. - The unique ID of the apply patch tool call generated by the model. + - `type: Literal["encrypted_content"]` - - `status: Literal["completed", "failed"]` + The type of the input item. Always `encrypted_content`. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"encrypted_content"` - - `"completed"` + - `recipient: str` - - `"failed"` + The destination agent identity. - - `type: Literal["apply_patch_call_output"]` + - `type: Literal["agent_message"]` - The type of the item. Always `apply_patch_call_output`. + The type of the item. Always `agent_message`. - - `"apply_patch_call_output"` + - `"agent_message"` - - `agent: Optional[Agent]` + - `agent: Optional[AgentMessageAgent]` The agent that produced this item. @@ -95439,202 +105113,205 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `class MultiAgentCall: …` - The execution context that produced this tool call. + - `id: str` - - `class CallerDirect: …` + The unique ID of the multi-agent call item. - - `type: Literal["direct"]` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"direct"` + The multi-agent action to execute. - - `class CallerProgram: …` + - `"spawn_agent"` - - `caller_id: str` + - `"interrupt_agent"` - The call ID of the program item that produced this tool call. + - `"list_agents"` - - `type: Literal["program"]` + - `"send_message"` - - `"program"` + - `"followup_task"` - - `created_by: Optional[str]` + - `"wait_agent"` - The ID of the entity that created this tool call output. + - `arguments: str` - - `output: Optional[str]` + The JSON string of arguments generated for the action. - Optional textual output returned by the apply patch tool. + - `call_id: str` - - `class McpCall: …` + The unique ID linking this call to its output. - An invocation of a tool on an MCP server. + - `type: Literal["multi_agent_call"]` - - `id: str` + The type of the multi-agent call. Always `multi_agent_call`. - The unique ID of the tool call. + - `"multi_agent_call"` - - `arguments: str` + - `agent: Optional[MultiAgentCallAgent]` - A JSON string of the arguments passed to the tool. + The agent that produced this item. - - `name: str` + - `agent_name: str` - The name of the tool that was run. + The canonical name of the agent that produced this item. - - `server_label: str` + - `class MultiAgentCallOutput: …` - The label of the MCP server running the tool. + - `id: str` - - `type: Literal["mcp_call"]` + The unique ID of the multi-agent call output item. - The type of the item. Always `mcp_call`. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"mcp_call"` + The multi-agent action that produced this result. - - `agent: Optional[McpCallAgent]` + - `"spawn_agent"` - The agent that produced this item. + - `"interrupt_agent"` - - `agent_name: str` + - `"list_agents"` - The canonical name of the agent that produced this item. + - `"send_message"` - - `approval_request_id: Optional[str]` + - `"followup_task"` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `"wait_agent"` - - `error: Optional[str]` + - `call_id: str` - The error from the tool call, if any. + The unique ID of the multi-agent call. - - `output: Optional[str]` + - `output: List[BetaResponseOutputText]` - The output from the tool call. + Text output returned by the multi-agent action. - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `annotations: List[Annotation]` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The annotations of the text output. - - `"in_progress"` + - `text: str` - - `"completed"` + The text output from the model. - - `"incomplete"` + - `type: Literal["output_text"]` - - `"calling"` + The type of the output text. Always `output_text`. - - `"failed"` + - `logprobs: Optional[List[Logprob]]` - - `class McpListTools: …` + - `type: Literal["multi_agent_call_output"]` - A list of tools available on an MCP server. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `id: str` + - `"multi_agent_call_output"` - The unique ID of the list. + - `agent: Optional[MultiAgentCallOutputAgent]` - - `server_label: str` + The agent that produced this item. - The label of the MCP server. + - `agent_name: str` - - `tools: List[McpListToolsTool]` + The canonical name of the agent that produced this item. - The tools available on the server. + - `class BetaResponseFunctionWebSearch: …` - - `input_schema: object` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The JSON schema describing the tool's input. + - `id: str` - - `name: str` + The unique ID of the web search tool call. - The name of the tool. + - `action: Action` - - `annotations: Optional[object]` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - Additional annotations about the tool. + - `class ActionSearch: …` - - `description: Optional[str]` + Action type "search" - Performs a web search query. - The description of the tool. + - `type: Literal["search"]` - - `type: Literal["mcp_list_tools"]` + The action type. - The type of the item. Always `mcp_list_tools`. + - `"search"` - - `"mcp_list_tools"` + - `queries: Optional[List[str]]` - - `agent: Optional[McpListToolsAgent]` + The search queries. - The agent that produced this item. + - `query: Optional[str]` - - `agent_name: str` + The search query. - The canonical name of the agent that produced this item. + - `sources: Optional[List[ActionSearchSource]]` - - `error: Optional[str]` + The sources used in the search. - Error message if the server could not list tools. + - `type: Literal["url"]` - - `class McpApprovalRequest: …` + The type of source. Always `url`. - A request for human approval of a tool invocation. + - `"url"` - - `id: str` + - `url: str` - The unique ID of the approval request. + The URL of the source. - - `arguments: str` + - `class ActionOpenPage: …` - A JSON string of arguments for the tool. + Action type "open_page" - Opens a specific URL from search results. - - `name: str` + - `type: Literal["open_page"]` - The name of the tool to run. + The action type. - - `server_label: str` + - `"open_page"` - The label of the MCP server making the request. + - `url: Optional[str]` - - `type: Literal["mcp_approval_request"]` + The URL opened by the model. - The type of the item. Always `mcp_approval_request`. + - `class ActionFindInPage: …` - - `"mcp_approval_request"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `agent: Optional[McpApprovalRequestAgent]` + - `pattern: str` - The agent that produced this item. + The pattern or text to search for within the page. - - `agent_name: str` + - `type: Literal["find_in_page"]` - The canonical name of the agent that produced this item. + The action type. - - `class McpApprovalResponse: …` + - `"find_in_page"` - A response to an MCP approval request. + - `url: str` - - `id: str` + The URL of the page searched for the pattern. - The unique ID of the approval response + - `status: Literal["in_progress", "searching", "completed", "failed"]` - - `approval_request_id: str` + The status of the web search tool call. - The ID of the approval request being answered. + - `"in_progress"` - - `approve: bool` + - `"searching"` - Whether the request was approved. + - `"completed"` - - `type: Literal["mcp_approval_response"]` + - `"failed"` - The type of the item. Always `mcp_approval_response`. + - `type: Literal["web_search_call"]` - - `"mcp_approval_response"` + The type of the web search tool call. Always `web_search_call`. - - `agent: Optional[McpApprovalResponseAgent]` + - `"web_search_call"` + + - `agent: Optional[Agent]` The agent that produced this item. @@ -95642,21 +105319,34 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `reason: Optional[str]` + - `class BetaResponseComputerToolCall: …` - Optional reason for the decision. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `class BetaResponseCustomToolCall: …` + - `id: str` - A call to a custom tool created by the model. + The unique ID of the computer call. - - `class BetaResponseCustomToolCallOutputItem: …` + - `call_id: str` - The output of a custom tool call from your code, being sent back to the model. + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: List[PendingSafetyCheck]` + + The pending safety checks for the computer call. - `id: str` - The unique ID of the custom tool call output item. + The ID of the pending safety check. + + - `code: Optional[str]` + + The type of the pending safety check. + + - `message: Optional[str]` + + Details about the pending safety check. - `status: Literal["in_progress", "completed", "incomplete"]` @@ -95669,1639 +105359,1653 @@ print(compacted_response) - `"incomplete"` - - `created_by: Optional[str]` + - `type: Literal["computer_call"]` - The identifier of the actor that created the item. + The type of the computer call. Always `computer_call`. - - `parallel_tool_calls: bool` + - `"computer_call"` - Whether to allow the model to run tool calls in parallel. + - `action: Optional[BetaComputerAction]` - - `temperature: Optional[float]` + A click action. - 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. - We generally recommend altering this or `top_p` but not both. + - `class Click: …` - - `tool_choice: ToolChoice` + A click action. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `button: Literal["left", "right", "wheel", 2 more]` - - `Literal["none", "auto", "required"]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"none"` + - `"left"` - - `"auto"` + - `"right"` - - `"required"` + - `"wheel"` - - `class BetaToolChoiceAllowed: …` + - `"back"` - Constrains the tools available to the model to a pre-defined set. + - `"forward"` - - `mode: Literal["auto", "required"]` + - `type: Literal["click"]` - Constrains the tools available to the model to a pre-defined set. + Specifies the event type. For a click action, this property is always `click`. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `"click"` - `required` requires the model to call one or more of the allowed tools. + - `x: int` - - `"auto"` + The x-coordinate where the click occurred. - - `"required"` + - `y: int` - - `tools: List[Dict[str, object]]` + The y-coordinate where the click occurred. - A list of tool definitions that the model should be allowed to call. + - `keys: Optional[List[str]]` - For the Responses API, the list of tool definitions might look like: + The keys being held while clicking. - ```json + - `class DoubleClick: …` + + A double click action. + + - `keys: Optional[List[str]]` + + The keys being held while double-clicking. + + - `type: Literal["double_click"]` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: int` + + The x-coordinate where the double click occurred. + + - `y: int` + + The y-coordinate where the double click occurred. + + - `class Drag: …` + + A drag action. + + - `path: List[DragPath]` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } + { x: 100, y: 200 }, + { x: 200, y: 300 } ] ``` - - `type: Literal["allowed_tools"]` + - `x: int` - Allowed tool configuration type. Always `allowed_tools`. + The x-coordinate. - - `"allowed_tools"` + - `y: int` - - `class BetaToolChoiceTypes: …` + The y-coordinate. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `type: Literal["drag"]` - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + Specifies the event type. For a drag action, this property is always set to `drag`. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"drag"` - Allowed values are: + - `keys: Optional[List[str]]` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The keys being held while dragging the mouse. - - `"file_search"` + - `class Keypress: …` - - `"web_search_preview"` + A collection of keypresses the model would like to perform. - - `"computer"` + - `keys: List[str]` - - `"computer_use_preview"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"computer_use"` + - `type: Literal["keypress"]` - - `"web_search_preview_2025_03_11"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `"image_generation"` + - `"keypress"` - - `"code_interpreter"` + - `class Move: …` - - `class BetaToolChoiceFunction: …` + A mouse move action. - Use this option to force the model to call a specific function. + - `type: Literal["move"]` - - `name: str` + Specifies the event type. For a move action, this property is always set to `move`. - The name of the function to call. + - `"move"` - - `type: Literal["function"]` + - `x: int` - For function calling, the type is always `function`. + The x-coordinate to move to. - - `"function"` + - `y: int` - - `class BetaToolChoiceMcp: …` + The y-coordinate to move to. - Use this option to force the model to call a specific tool on a remote MCP server. + - `keys: Optional[List[str]]` - - `server_label: str` + The keys being held while moving the mouse. - The label of the MCP server to use. + - `class Screenshot: …` - - `type: Literal["mcp"]` + A screenshot action. - For MCP tools, the type is always `mcp`. + - `type: Literal["screenshot"]` - - `"mcp"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `name: Optional[str]` + - `"screenshot"` - The name of the tool to call on the server. + - `class Scroll: …` - - `class BetaToolChoiceCustom: …` + A scroll action. - Use this option to force the model to call a specific custom tool. + - `scroll_x: int` - - `name: str` + The horizontal scroll distance. - The name of the custom tool to call. + - `scroll_y: int` - - `type: Literal["custom"]` + The vertical scroll distance. - For custom tool calling, the type is always `custom`. + - `type: Literal["scroll"]` - - `"custom"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + - `"scroll"` - - `type: Literal["programmatic_tool_calling"]` + - `x: int` - The tool to call. Always `programmatic_tool_calling`. + The x-coordinate where the scroll occurred. - - `"programmatic_tool_calling"` + - `y: int` - - `class BetaToolChoiceApplyPatch: …` + The y-coordinate where the scroll occurred. - Forces the model to call the apply_patch tool when executing a tool call. + - `keys: Optional[List[str]]` - - `type: Literal["apply_patch"]` + The keys being held while scrolling. - The tool to call. Always `apply_patch`. + - `class Type: …` - - `"apply_patch"` + An action to type in text. - - `class BetaToolChoiceShell: …` + - `text: str` - Forces the model to call the shell tool when a tool call is required. + The text to type. - - `type: Literal["shell"]` + - `type: Literal["type"]` - The tool to call. Always `shell`. + Specifies the event type. For a type action, this property is always set to `type`. - - `"shell"` + - `"type"` - - `tools: List[BetaTool]` + - `class Wait: …` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + A wait action. - We support the following categories of tools: + - `type: Literal["wait"]` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `class BetaFunctionTool: …` + - `"wait"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `actions: Optional[BetaComputerActionList]` - - `class BetaFileSearchTool: …` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `class Click: …` - - `class BetaComputerTool: …` + A click action. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class DoubleClick: …` - - `class BetaComputerUsePreviewTool: …` + A double click action. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class Drag: …` - - `class BetaWebSearchTool: …` + A drag action. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class Keypress: …` - - `class Mcp: …` + A collection of keypresses the model would like to perform. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `class Move: …` - - `class CodeInterpreter: …` + A mouse move action. - A tool that runs Python code to help generate a response to a prompt. + - `class Screenshot: …` - - `class ProgrammaticToolCalling: …` + A screenshot action. - - `class ImageGeneration: …` + - `class Scroll: …` - A tool that generates images using the GPT image models. + A scroll action. - - `class LocalShell: …` + - `class Type: …` - A tool that allows the model to execute shell commands in a local environment. + An action to type in text. - - `class BetaFunctionShellTool: …` + - `class Wait: …` - A tool that allows the model to execute shell commands. + A wait action. - - `class BetaCustomTool: …` + - `agent: Optional[Agent]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The agent that produced this item. - - `class BetaNamespaceTool: …` + - `agent_name: str` - Groups function/custom tools under a shared namespace. + The canonical name of the agent that produced this item. - - `class BetaToolSearchTool: …` + - `class BetaResponseComputerToolCallOutputItem: …` - Hosted or BYOT tool search configuration for deferred tools. + - `id: str` - - `class BetaWebSearchPreviewTool: …` + The unique ID of the computer call tool output. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `call_id: str` - - `class BetaApplyPatchTool: …` + The ID of the computer tool call that produced the output. - Allows the assistant to create, delete, or update files using unified diffs. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `top_p: Optional[float]` + A computer screenshot image used with the computer use tool. - 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. + - `type: Literal["computer_screenshot"]` - We generally recommend altering this or `temperature` but not both. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `background: Optional[bool]` + - `"computer_screenshot"` + + - `file_id: Optional[str]` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: Optional[str]` + + The URL of the screenshot image. + + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: Literal["computer_call_output"]` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: str` + + The ID of the pending safety check. + + - `code: Optional[str]` + + The type of the pending safety check. + + - `message: Optional[str]` + + Details about the pending safety check. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `agent: Optional[Agent]` - - `completed_at: Optional[float]` + The agent that produced this item. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `agent_name: str` - - `conversation: Optional[Conversation]` + The canonical name of the agent that produced this item. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `created_by: Optional[str]` - - `id: str` + The identifier of the actor that created the item. - The unique ID of the conversation that this response was associated with. + - `class BetaResponseReasoningItem: …` - - `max_output_tokens: Optional[int]` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `id: str` - - `max_tool_calls: Optional[int]` + The unique identifier of the reasoning content. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `summary: List[Summary]` - - `moderation: Optional[Moderation]` + Reasoning summary content. - Moderation results for the response input and output, if moderated completions were requested. + - `text: str` - - `input: ModerationInput` + A summary of the reasoning output from the model so far. - Moderation for the response input. + - `type: Literal["summary_text"]` - - `class ModerationInputModerationResult: …` + The type of the object. Always `summary_text`. - A moderation result produced for the response input or output. + - `"summary_text"` - - `categories: Dict[str, bool]` + - `type: Literal["reasoning"]` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The type of the object. Always `reasoning`. - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `"reasoning"` - Which modalities of input are reflected by the score for each category. + - `agent: Optional[Agent]` - - `"text"` + The agent that produced this item. - - `"image"` + - `agent_name: str` - - `category_scores: Dict[str, float]` + The canonical name of the agent that produced this item. - A dictionary of moderation categories to scores. + - `content: Optional[List[Content]]` - - `flagged: bool` + Reasoning text content. - A boolean indicating whether the content was flagged by any category. + - `text: str` - - `model: str` + The reasoning text from the model. - The moderation model that produced this result. + - `type: Literal["reasoning_text"]` - - `type: Literal["moderation_result"]` + The type of the reasoning text. Always `reasoning_text`. - The object type, which was always `moderation_result` for successful moderation results. + - `"reasoning_text"` - - `"moderation_result"` + - `encrypted_content: Optional[str]` - - `class ModerationInputError: …` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - An error produced while attempting moderation for the response input or output. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `code: str` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The error code. + - `"in_progress"` - - `message: str` + - `"completed"` - The error message. + - `"incomplete"` - - `type: Literal["error"]` + - `class Program: …` - The object type, which was always `error` for moderation failures. + - `id: str` - - `"error"` + The unique ID of the program item. - - `output: ModerationOutput` + - `call_id: str` - Moderation for the response output. + The stable call ID of the program item. - - `class ModerationOutputModerationResult: …` + - `code: str` - A moderation result produced for the response input or output. + The JavaScript source executed by programmatic tool calling. - - `categories: Dict[str, bool]` + - `fingerprint: str` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + Opaque program replay fingerprint that must be round-tripped. - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `type: Literal["program"]` - Which modalities of input are reflected by the score for each category. + The type of the item. Always `program`. - - `"text"` + - `"program"` - - `"image"` + - `agent: Optional[ProgramAgent]` - - `category_scores: Dict[str, float]` + The agent that produced this item. - A dictionary of moderation categories to scores. + - `agent_name: str` - - `flagged: bool` + The canonical name of the agent that produced this item. - A boolean indicating whether the content was flagged by any category. + - `class ProgramOutput: …` - - `model: str` + - `id: str` - The moderation model that produced this result. + The unique ID of the program output item. - - `type: Literal["moderation_result"]` + - `call_id: str` - The object type, which was always `moderation_result` for successful moderation results. + The call ID of the program item. - - `"moderation_result"` + - `result: str` - - `class ModerationOutputError: …` + The result produced by the program item. - An error produced while attempting moderation for the response input or output. + - `status: Literal["completed", "incomplete"]` - - `code: str` + The terminal status of the program output item. - The error code. + - `"completed"` - - `message: str` + - `"incomplete"` - The error message. + - `type: Literal["program_output"]` - - `type: Literal["error"]` + The type of the item. Always `program_output`. - The object type, which was always `error` for moderation failures. + - `"program_output"` - - `"error"` + - `agent: Optional[ProgramOutputAgent]` - - `previous_response_id: Optional[str]` + The agent that produced this item. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `agent_name: str` - - `prompt: Optional[BetaResponsePrompt]` + The canonical name of the agent that produced this item. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `class BetaResponseToolSearchCall: …` - `id: str` - The unique identifier of the prompt template to use. + The unique ID of the tool search call item. - - `variables: Optional[Dict[str, Variables]]` + - `arguments: object` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + Arguments used for the tool search call. - - `str` + - `call_id: Optional[str]` - - `class BetaResponseInputText: …` + The unique ID of the tool search call generated by the model. - A text input to the model. + - `execution: Literal["server", "client"]` - - `class BetaResponseInputImage: …` + Whether tool search was executed by the server or by the client. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"server"` - - `class BetaResponseInputFile: …` + - `"client"` - A file input to the model. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `version: Optional[str]` + The status of the tool search call item that was recorded. - Optional version of the prompt template. + - `"in_progress"` - - `prompt_cache_key: Optional[str]` + - `"completed"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `"incomplete"` - - `prompt_cache_options: Optional[PromptCacheOptions]` + - `type: Literal["tool_search_call"]` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The type of the item. Always `tool_search_call`. - - `mode: Literal["implicit", "explicit"]` + - `"tool_search_call"` - Whether implicit prompt-cache breakpoints were enabled. + - `agent: Optional[Agent]` - - `"implicit"` + The agent that produced this item. - - `"explicit"` + - `agent_name: str` - - `ttl: Literal["30m"]` + The canonical name of the agent that produced this item. - The minimum lifetime applied to each cache breakpoint. + - `created_by: Optional[str]` - - `"30m"` + The identifier of the actor that created the item. - - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + - `class BetaResponseToolSearchOutputItem: …` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `id: str` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + The unique ID of the tool search output item. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `call_id: Optional[str]` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + The unique ID of the tool search call generated by the model. - - `"in_memory"` + - `execution: Literal["server", "client"]` - - `"24h"` + Whether tool search was executed by the server or by the client. - - `reasoning: Optional[Reasoning]` + - `"server"` - **gpt-5 and o-series models only** + - `"client"` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `status: Literal["in_progress", "completed", "incomplete"]` - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + The status of the tool search output item that was recorded. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `"in_progress"` - - `"auto"` + - `"completed"` - - `"current_turn"` + - `"incomplete"` - - `"all_turns"` + - `tools: List[BetaTool]` - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + The loaded tool definitions returned by tool search. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `class BetaFunctionTool: …` - - `"none"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"minimal"` + - `name: str` - - `"low"` + The name of the function to call. - - `"medium"` + - `parameters: Optional[Dict[str, object]]` - - `"high"` + A JSON schema object describing the parameters of the function. - - `"xhigh"` + - `strict: Optional[bool]` - - `"max"` + Whether strict parameter validation is enforced for this function tool. - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + - `type: Literal["function"]` - **Deprecated:** use `summary` instead. + The type of the function tool. Always `function`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"function"` - - `"auto"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"concise"` + The tool invocation context(s). - - `"detailed"` + - `"direct"` - - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + - `"programmatic"` - Controls the reasoning execution mode for the request. + - `defer_loading: Optional[bool]` - When returned on a response, this is the effective execution mode. + Whether this function is deferred and loaded via tool search. - - `str` + - `description: Optional[str]` - - `Literal["standard", "pro"]` + A description of the function. Used by the model to determine whether or not to call the function. - Controls the reasoning execution mode for the request. + - `output_schema: Optional[Dict[str, object]]` - When returned on a response, this is the effective execution mode. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"standard"` + - `class BetaFileSearchTool: …` - - `"pro"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + - `type: Literal["file_search"]` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The type of the file search tool. Always `file_search`. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `"file_search"` - - `"auto"` + - `vector_store_ids: List[str]` - - `"concise"` + The IDs of the vector stores to search. - - `"detailed"` + - `filters: Optional[Filters]` - - `safety_identifier: Optional[str]` + A filter to apply. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `class FiltersComparisonFilter: …` - - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Specifies the processing type used for serving the request. + - `key: str` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The key to compare against the value. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `"auto"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"default"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `"flex"` + - `"eq"` - - `"scale"` + - `"ne"` - - `"priority"` + - `"gt"` - - `status: Optional[BetaResponseStatus]` + - `"gte"` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `"lt"` - - `"completed"` + - `"lte"` - - `"failed"` + - `"in"` - - `"in_progress"` + - `"nin"` - - `"cancelled"` + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `"queued"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"incomplete"` + - `str` - - `text: Optional[BetaResponseTextConfig]` + - `float` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `bool` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `List[Union[str, float]]` - - `format: Optional[BetaResponseFormatTextConfig]` + - `str` - An object specifying the format that the model must output. + - `float` - Configuring `{ "type": "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). + - `class FiltersCompoundFilter: …` - The default format is `{ "type": "text" }` with no additional options. + Combine multiple filters using `and` or `or`. - **Not recommended for gpt-4o and newer models:** + - `filters: List[FiltersCompoundFilterFilter]` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `class Text: …` + - `class FiltersCompoundFilterFilterComparisonFilter: …` - Default response format. Used to generate text responses. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: Literal["text"]` + - `key: str` - The type of response format being defined. Always `text`. + The key to compare against the value. - - `"text"` + - `type: Literal["eq", "ne", "gt", 5 more]` - - `class BetaResponseFormatTextJSONSchemaConfig: …` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `name: str` + - `"eq"` - 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. + - `"ne"` - - `schema: Dict[str, object]` + - `"gt"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"gte"` - - `type: Literal["json_schema"]` + - `"lt"` - The type of response format being defined. Always `json_schema`. + - `"lte"` - - `"json_schema"` + - `"in"` - - `description: Optional[str]` + - `"nin"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `strict: Optional[bool]` + The value to compare against the attribute key; supports string, number, or boolean types. - 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). + - `str` - - `class JSONObject: …` + - `float` - 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. + - `bool` - - `type: Literal["json_object"]` + - `List[Union[str, float]]` - The type of response format being defined. Always `json_object`. + - `str` - - `"json_object"` + - `float` - - `verbosity: Optional[Literal["low", "medium", "high"]]` + - `object` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `type: Literal["and", "or"]` - - `"low"` + Type of operation: `and` or `or`. - - `"medium"` + - `"and"` - - `"high"` + - `"or"` - - `top_logprobs: Optional[int]` + - `max_num_results: Optional[int]` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `truncation: Optional[Literal["auto", "disabled"]]` + - `ranking_options: Optional[RankingOptions]` - The truncation strategy to use for the model response. + Ranking options for search. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - `"auto"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"disabled"` + - `embedding_weight: float` - - `usage: Optional[BetaResponseUsage]` + The weight of the embedding in the reciprocal ranking fusion. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `text_weight: float` - - `input_tokens: int` + The weight of the text in the reciprocal ranking fusion. - The number of input tokens. + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - - `input_tokens_details: InputTokensDetails` + The ranker to use for the file search. - A detailed breakdown of the input tokens. + - `"auto"` - - `cache_write_tokens: int` + - `"default-2024-11-15"` - The number of input tokens that were written to the cache. + - `score_threshold: Optional[float]` - - `cached_tokens: int` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `class BetaComputerTool: …` - - `output_tokens: int` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The number of output tokens. + - `type: Literal["computer"]` - - `output_tokens_details: OutputTokensDetails` + The type of the computer tool. Always `computer`. - A detailed breakdown of the output tokens. + - `"computer"` - - `reasoning_tokens: int` + - `class BetaComputerUsePreviewTool: …` - The number of reasoning tokens. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `total_tokens: int` + - `display_height: int` - The total number of tokens used. + The height of the computer display. - - `user: Optional[str]` + - `display_width: int` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The width of the computer display. - - `sequence_number: int` + - `environment: Literal["windows", "mac", "linux", 2 more]` - The sequence number of this event. + The type of computer environment to control. - - `type: Literal["response.incomplete"]` + - `"windows"` - The type of the event. Always `response.incomplete`. + - `"mac"` - - `"response.incomplete"` + - `"linux"` - - `agent: Optional[Agent]` + - `"ubuntu"` - The agent that owns this multi-agent streaming event. + - `"browser"` - - `agent_name: str` + - `type: Literal["computer_use_preview"]` - The canonical name of the agent that produced this item. + The type of the computer use tool. Always `computer_use_preview`. -### Beta Response Input + - `"computer_use_preview"` -- `List[BetaResponseInputItem]` + - `class BetaWebSearchTool: …` - A list of one or many input items to the model, containing - different content types. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class BetaEasyInputMessage: …` + - `type: Literal["web_search", "web_search_2025_08_26"]` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `content: Union[str, BetaResponseInputMessageContentList]` + - `"web_search"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `"web_search_2025_08_26"` - - `str` + - `filters: Optional[Filters]` - A text input to the model. + Filters for the search. - - `List[BetaResponseInputContent]` + - `allowed_domains: Optional[List[str]]` - - `class BetaResponseInputText: …` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - A text input to the model. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `text: str` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The text input to the model. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `type: Literal["input_text"]` + - `"low"` - The type of the input item. Always `input_text`. + - `"medium"` - - `"input_text"` + - `"high"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `user_location: Optional[UserLocation]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The approximate location of the user. - - `mode: Literal["explicit"]` + - `city: Optional[str]` - The breakpoint mode. Always `explicit`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"explicit"` + - `country: Optional[str]` - - `class BetaResponseInputImage: …` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `region: Optional[str]` - - `detail: Literal["low", "high", "auto", "original"]` + Free text input for the region of the user, e.g. `California`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `timezone: Optional[str]` - - `"low"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"high"` + - `type: Optional[Literal["approximate"]]` - - `"auto"` + The type of location approximation. Always `approximate`. - - `"original"` + - `"approximate"` - - `type: Literal["input_image"]` + - `class Mcp: …` - The type of the input item. Always `input_image`. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"input_image"` + - `server_label: str` - - `file_id: Optional[str]` + A label for this MCP server, used to identify it in tool calls. - The ID of the file to be sent to the model. + - `type: Literal["mcp"]` - - `image_url: Optional[str]` + The type of the MCP tool. Always `mcp`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"mcp"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The tool invocation context(s). - - `mode: Literal["explicit"]` + - `"direct"` - The breakpoint mode. Always `explicit`. + - `"programmatic"` - - `"explicit"` + - `allowed_tools: Optional[McpAllowedTools]` - - `class BetaResponseInputFile: …` + List of allowed tool names or a filter object. - A file input to the model. + - `List[str]` - - `type: Literal["input_file"]` + A string array of allowed tool names - The type of the input item. Always `input_file`. + - `class McpAllowedToolsMcpToolFilter: …` - - `"input_file"` + A filter object to specify which tools are allowed. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `read_only: Optional[bool]` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"auto"` + - `tool_names: Optional[List[str]]` - - `"low"` + List of allowed tool names. - - `"high"` + - `authorization: Optional[str]` - - `file_data: Optional[str]` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The content of the file to be sent to the model. + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `file_id: Optional[str]` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - The ID of the file to be sent to the model. + Currently supported `connector_id` values are: - - `file_url: Optional[str]` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The URL of the file to be sent to the model. + - `"connector_dropbox"` - - `filename: Optional[str]` + - `"connector_gmail"` - The name of the file to be sent to the model. + - `"connector_googlecalendar"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"connector_googledrive"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"connector_microsoftteams"` - - `mode: Literal["explicit"]` + - `"connector_outlookcalendar"` - The breakpoint mode. Always `explicit`. + - `"connector_outlookemail"` - - `"explicit"` + - `"connector_sharepoint"` - - `role: Literal["user", "assistant", "system", "developer"]` + - `defer_loading: Optional[bool]` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + Whether this MCP tool is deferred and discovered via tool search. - - `"user"` + - `headers: Optional[Dict[str, str]]` - - `"assistant"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"system"` + - `require_approval: Optional[McpRequireApproval]` - - `"developer"` + Specify which of the MCP server's tools require approval. - - `phase: Optional[Literal["commentary"]]` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"commentary"` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `type: Optional[Literal["message"]]` + A filter object to specify which tools are allowed. - The type of the message input. Always `message`. + - `read_only: Optional[bool]` - - `"message"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `class Message: …` + - `tool_names: Optional[List[str]]` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + List of allowed tool names. - - `content: BetaResponseInputMessageContentList` + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - A list of one or many input items to the model, containing different content - types. + A filter object to specify which tools are allowed. - - `class BetaResponseInputText: …` + - `read_only: Optional[bool]` - A text input to the model. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `class BetaResponseInputImage: …` + - `tool_names: Optional[List[str]]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + List of allowed tool names. - - `class BetaResponseInputFile: …` + - `Literal["always", "never"]` - A file input to the model. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `role: Literal["user", "system", "developer"]` + - `"always"` - The role of the message input. One of `user`, `system`, or `developer`. + - `"never"` - - `"user"` + - `server_description: Optional[str]` - - `"system"` + Optional description of the MCP server, used to provide more context. - - `"developer"` + - `server_url: Optional[str]` - - `agent: Optional[MessageAgent]` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The agent that produced this item. + - `tunnel_id: Optional[str]` - - `agent_name: str` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The canonical name of the agent that produced this item. + - `class CodeInterpreter: …` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + A tool that runs Python code to help generate a response to a prompt. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `container: CodeInterpreterContainer` - - `"in_progress"` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `"completed"` + - `str` - - `"incomplete"` + The container ID. - - `type: Optional[Literal["message"]]` + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - The type of the message input. Always set to `message`. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"message"` + - `type: Literal["auto"]` - - `class BetaResponseOutputMessage: …` + Always `auto`. - An output message from the model. + - `"auto"` - - `id: str` + - `file_ids: Optional[List[str]]` - The unique ID of the output message. + An optional list of uploaded files to make available to your code. - - `content: List[Content]` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The content of the output message. + The memory limit for the code interpreter container. - - `class BetaResponseOutputText: …` + - `"1g"` - A text output from the model. + - `"4g"` - - `annotations: List[Annotation]` + - `"16g"` - The annotations of the text output. + - `"64g"` - - `class AnnotationFileCitation: …` + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - A citation to a file. + Network access policy for the container. - - `file_id: str` + - `class BetaContainerNetworkPolicyDisabled: …` - The ID of the file. + - `type: Literal["disabled"]` - - `filename: str` + Disable outbound network access. Always `disabled`. - The filename of the file cited. + - `"disabled"` - - `index: int` + - `class BetaContainerNetworkPolicyAllowlist: …` - The index of the file in the list of files. + - `allowed_domains: List[str]` - - `type: Literal["file_citation"]` + A list of allowed domains when type is `allowlist`. - The type of the file citation. Always `file_citation`. + - `type: Literal["allowlist"]` - - `"file_citation"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `class AnnotationURLCitation: …` + - `"allowlist"` - A citation for a web resource used to generate a model response. + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `end_index: int` + Optional domain-scoped secrets for allowlisted domains. - The index of the last character of the URL citation in the message. + - `domain: str` - - `start_index: int` + The domain associated with the secret. - The index of the first character of the URL citation in the message. + - `name: str` - - `title: str` + The name of the secret to inject for the domain. - The title of the web resource. + - `value: str` - - `type: Literal["url_citation"]` + The secret value to inject for the domain. - The type of the URL citation. Always `url_citation`. + - `type: Literal["code_interpreter"]` - - `"url_citation"` + The type of the code interpreter tool. Always `code_interpreter`. - - `url: str` + - `"code_interpreter"` - The URL of the web resource. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `class AnnotationContainerFileCitation: …` + The tool invocation context(s). - A citation for a container file used to generate a model response. + - `"direct"` - - `container_id: str` + - `"programmatic"` - The ID of the container file. + - `class ProgrammaticToolCalling: …` - - `end_index: int` + - `type: Literal["programmatic_tool_calling"]` - The index of the last character of the container file citation in the message. + The type of the tool. Always `programmatic_tool_calling`. - - `file_id: str` + - `"programmatic_tool_calling"` - The ID of the file. + - `class ImageGeneration: …` - - `filename: str` + A tool that generates images using the GPT image models. - The filename of the container file cited. + - `type: Literal["image_generation"]` - - `start_index: int` + The type of the image generation tool. Always `image_generation`. - The index of the first character of the container file citation in the message. + - `"image_generation"` - - `type: Literal["container_file_citation"]` + - `action: Optional[Literal["generate", "edit", "auto"]]` - The type of the container file citation. Always `container_file_citation`. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"container_file_citation"` + - `"generate"` - - `class AnnotationFilePath: …` + - `"edit"` - A path to a file. + - `"auto"` - - `file_id: str` + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - The ID of the file. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `index: int` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - The index of the file in the list of files. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `type: Literal["file_path"]` + - `"transparent"` - The type of the file path. Always `file_path`. + - `"opaque"` - - `"file_path"` + - `"auto"` - - `text: str` + - `input_fidelity: Optional[Literal["high", "low"]]` - The text output from the model. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `type: Literal["output_text"]` + - `"high"` - The type of the output text. Always `output_text`. + - `"low"` - - `"output_text"` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - - `logprobs: Optional[List[Logprob]]` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `token: str` + - `file_id: Optional[str]` - - `bytes: List[int]` + File ID for the mask image. - - `logprob: float` + - `image_url: Optional[str]` - - `top_logprobs: List[LogprobTopLogprob]` + Base64-encoded mask image. - - `token: str` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - - `bytes: List[int]` + The image generation model to use. Default: `gpt-image-1`. - - `logprob: float` + - `str` - - `class BetaResponseOutputRefusal: …` + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - A refusal from the model. + The image generation model to use. Default: `gpt-image-1`. - - `refusal: str` + - `"gpt-image-1"` - The refusal explanation from the model. + - `"gpt-image-1-mini"` - - `type: Literal["refusal"]` + - `"gpt-image-2"` - The type of the refusal. Always `refusal`. + - `"gpt-image-2-2026-04-21"` - - `"refusal"` + - `"gpt-image-1.5"` - - `role: Literal["assistant"]` + - `"chatgpt-image-latest"` - The role of the output message. Always `assistant`. + - `moderation: Optional[Literal["auto", "low"]]` - - `"assistant"` + Moderation level for the generated image. Default: `auto`. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"auto"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"low"` - - `"in_progress"` + - `output_compression: Optional[int]` - - `"completed"` + Compression level for the output image. Default: 100. - - `"incomplete"` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `type: Literal["message"]` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The type of the output message. Always `message`. + - `"png"` - - `"message"` + - `"webp"` - - `agent: Optional[Agent]` + - `"jpeg"` - The agent that produced this item. + - `partial_images: Optional[int]` - - `agent_name: str` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The canonical name of the agent that produced this item. + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - - `phase: Optional[Literal["commentary"]]` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `"low"` - - `"commentary"` + - `"medium"` - - `class BetaResponseFileSearchToolCall: …` + - `"high"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"auto"` - - `id: str` + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - The unique ID of the file search tool call. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `queries: List[str]` + - `str` - The queries used to search for files. + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `status: Literal["in_progress", "searching", "completed", 2 more]` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"1024x1024"` - - `"in_progress"` + - `"1024x1536"` - - `"searching"` + - `"1536x1024"` - - `"completed"` + - `"auto"` - - `"incomplete"` + - `class LocalShell: …` - - `"failed"` + A tool that allows the model to execute shell commands in a local environment. - - `type: Literal["file_search_call"]` + - `type: Literal["local_shell"]` - The type of the file search tool call. Always `file_search_call`. + The type of the local shell tool. Always `local_shell`. - - `"file_search_call"` + - `"local_shell"` - - `agent: Optional[Agent]` + - `class BetaFunctionShellTool: …` - The agent that produced this item. + A tool that allows the model to execute shell commands. - - `agent_name: str` + - `type: Literal["shell"]` - The canonical name of the agent that produced this item. + The type of the shell tool. Always `shell`. - - `results: Optional[List[Result]]` + - `"shell"` - The results of the file search tool call. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + The tool invocation context(s). - 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, booleans, or numbers. + - `"direct"` - - `str` + - `"programmatic"` - - `float` + - `environment: Optional[Environment]` - - `bool` + - `class BetaContainerAuto: …` - - `file_id: Optional[str]` + - `type: Literal["container_auto"]` - The unique ID of the file. + Automatically creates a container for this request - - `filename: Optional[str]` + - `"container_auto"` - The name of the file. + - `file_ids: Optional[List[str]]` - - `score: Optional[float]` + An optional list of uploaded files to make available to your code. - The relevance score of the file - a value between 0 and 1. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `text: Optional[str]` + The memory limit for the container. - The text that was retrieved from the file. + - `"1g"` - - `class BetaResponseComputerToolCall: …` + - `"4g"` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `"16g"` - - `id: str` + - `"64g"` - The unique ID of the computer call. + - `network_policy: Optional[NetworkPolicy]` - - `call_id: str` + Network access policy for the container. - An identifier used when responding to the tool call with output. + - `class BetaContainerNetworkPolicyDisabled: …` - - `pending_safety_checks: List[PendingSafetyCheck]` + - `class BetaContainerNetworkPolicyAllowlist: …` - The pending safety checks for the computer call. + - `skills: Optional[List[Skill]]` - - `id: str` + An optional list of skills referenced by id or inline data. - The ID of the pending safety check. + - `class BetaSkillReference: …` - - `code: Optional[str]` + - `skill_id: str` - The type of the pending safety check. + The ID of the referenced skill. - - `message: Optional[str]` + - `type: Literal["skill_reference"]` - Details about the pending safety check. + References a skill created with the /v1/skills endpoint. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"skill_reference"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `version: Optional[str]` - - `"in_progress"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `"completed"` + - `class BetaInlineSkill: …` - - `"incomplete"` + - `description: str` - - `type: Literal["computer_call"]` + The description of the skill. - The type of the computer call. Always `computer_call`. + - `name: str` - - `"computer_call"` + The name of the skill. - - `action: Optional[BetaComputerAction]` + - `source: BetaInlineSkillSource` - A click action. + Inline skill payload - - `class Click: …` + - `data: str` - A click action. + Base64-encoded skill zip bundle. - - `button: Literal["left", "right", "wheel", 2 more]` + - `media_type: Literal["application/zip"]` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The media type of the inline skill payload. Must be `application/zip`. - - `"left"` + - `"application/zip"` - - `"right"` + - `type: Literal["base64"]` - - `"wheel"` + The type of the inline skill source. Must be `base64`. - - `"back"` + - `"base64"` - - `"forward"` + - `type: Literal["inline"]` - - `type: Literal["click"]` + Defines an inline skill for this request. - Specifies the event type. For a click action, this property is always `click`. + - `"inline"` - - `"click"` + - `class BetaLocalEnvironment: …` - - `x: int` + - `type: Literal["local"]` - The x-coordinate where the click occurred. + Use a local computer environment. - - `y: int` + - `"local"` - The y-coordinate where the click occurred. + - `skills: Optional[List[BetaLocalSkill]]` - - `keys: Optional[List[str]]` + An optional list of skills. - The keys being held while clicking. + - `description: str` - - `class DoubleClick: …` + The description of the skill. - A double click action. + - `name: str` - - `keys: Optional[List[str]]` + The name of the skill. - The keys being held while double-clicking. + - `path: str` - - `type: Literal["double_click"]` + The path to the directory containing the skill. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `class BetaContainerReference: …` - - `"double_click"` + - `container_id: str` - - `x: int` + The ID of the referenced container. - The x-coordinate where the double click occurred. + - `type: Literal["container_reference"]` - - `y: int` + References a container created with the /v1/containers endpoint - The y-coordinate where the double click occurred. + - `"container_reference"` - - `class Drag: …` + - `class BetaCustomTool: …` - A drag action. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `path: List[DragPath]` + - `name: str` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The name of the custom tool, used to identify it in tool calls. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `type: Literal["custom"]` - - `x: int` + The type of the custom tool. Always `custom`. - The x-coordinate. + - `"custom"` - - `y: int` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The y-coordinate. + The tool invocation context(s). - - `type: Literal["drag"]` + - `"direct"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `"programmatic"` - - `"drag"` + - `defer_loading: Optional[bool]` - - `keys: Optional[List[str]]` + Whether this tool should be deferred and discovered via tool search. - The keys being held while dragging the mouse. + - `description: Optional[str]` - - `class Keypress: …` + Optional description of the custom tool, used to provide more context. - A collection of keypresses the model would like to perform. + - `format: Optional[Format]` - - `keys: List[str]` + The input format for the custom tool. Default is unconstrained text. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `class FormatText: …` - - `type: Literal["keypress"]` + Unconstrained free-form text. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `type: Literal["text"]` - - `"keypress"` + Unconstrained text format. Always `text`. - - `class Move: …` + - `"text"` - A mouse move action. + - `class FormatGrammar: …` - - `type: Literal["move"]` + A grammar defined by the user. - Specifies the event type. For a move action, this property is always set to `move`. + - `definition: str` - - `"move"` + The grammar definition. - - `x: int` + - `syntax: Literal["lark", "regex"]` - The x-coordinate to move to. + The syntax of the grammar definition. One of `lark` or `regex`. - - `y: int` + - `"lark"` - The y-coordinate to move to. + - `"regex"` - - `keys: Optional[List[str]]` + - `type: Literal["grammar"]` - The keys being held while moving the mouse. + Grammar format. Always `grammar`. - - `class Screenshot: …` + - `"grammar"` - A screenshot action. + - `class BetaNamespaceTool: …` - - `type: Literal["screenshot"]` + Groups function/custom tools under a shared namespace. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `description: str` - - `"screenshot"` + A description of the namespace shown to the model. - - `class Scroll: …` + - `name: str` - A scroll action. + The namespace name used in tool calls (for example, `crm`). - - `scroll_x: int` + - `tools: List[Tool]` - The horizontal scroll distance. + The function/custom tools available inside this namespace. - - `scroll_y: int` + - `class ToolFunction: …` - The vertical scroll distance. + - `name: str` - - `type: Literal["scroll"]` + - `type: Literal["function"]` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"function"` - - `"scroll"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `x: int` + The tool invocation context(s). - The x-coordinate where the scroll occurred. + - `"direct"` - - `y: int` + - `"programmatic"` - The y-coordinate where the scroll occurred. + - `defer_loading: Optional[bool]` - - `keys: Optional[List[str]]` + Whether this function should be deferred and discovered via tool search. - The keys being held while scrolling. + - `description: Optional[str]` - - `class Type: …` + - `output_schema: Optional[Dict[str, object]]` - An action to type in text. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `text: str` + - `parameters: Optional[object]` - The text to type. + - `strict: Optional[bool]` - - `type: Literal["type"]` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - Specifies the event type. For a type action, this property is always set to `type`. + - `class BetaCustomTool: …` - - `"type"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `class Wait: …` + - `type: Literal["namespace"]` - A wait action. + The type of the tool. Always `namespace`. - - `type: Literal["wait"]` + - `"namespace"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `class BetaToolSearchTool: …` - - `"wait"` + Hosted or BYOT tool search configuration for deferred tools. - - `actions: Optional[BetaComputerActionList]` + - `type: Literal["tool_search"]` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The type of the tool. Always `tool_search`. - - `class Click: …` + - `"tool_search"` - A click action. + - `description: Optional[str]` - - `class DoubleClick: …` + Description shown to the model for a client-executed tool search tool. - A double click action. + - `execution: Optional[Literal["server", "client"]]` - - `class Drag: …` + Whether tool search is executed by the server or by the client. - A drag action. + - `"server"` - - `class Keypress: …` + - `"client"` - A collection of keypresses the model would like to perform. + - `parameters: Optional[object]` - - `class Move: …` + Parameter schema for a client-executed tool search tool. - A mouse move action. + - `class BetaWebSearchPreviewTool: …` - - `class Screenshot: …` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - A screenshot action. + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - - `class Scroll: …` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - A scroll action. + - `"web_search_preview"` - - `class Type: …` + - `"web_search_preview_2025_03_11"` - An action to type in text. + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `class Wait: …` + - `"text"` - A wait action. + - `"image"` - - `agent: Optional[Agent]` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The agent that produced this item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `agent_name: str` + - `"low"` - The canonical name of the agent that produced this item. + - `"medium"` - - `class ComputerCallOutput: …` + - `"high"` - The output of a computer tool call. + - `user_location: Optional[UserLocation]` - - `call_id: str` + The user's location. - The ID of the computer tool call that produced the output. + - `type: Literal["approximate"]` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The type of location approximation. Always `approximate`. - A computer screenshot image used with the computer use tool. + - `"approximate"` - - `type: Literal["computer_screenshot"]` + - `city: Optional[str]` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"computer_screenshot"` + - `country: Optional[str]` - - `file_id: Optional[str]` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The identifier of an uploaded file that contains the screenshot. + - `region: Optional[str]` - - `image_url: Optional[str]` + Free text input for the region of the user, e.g. `California`. - The URL of the screenshot image. + - `timezone: Optional[str]` - - `type: Literal["computer_call_output"]` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The type of the computer tool call output. Always `computer_call_output`. + - `class BetaApplyPatchTool: …` - - `"computer_call_output"` + Allows the assistant to create, delete, or update files using unified diffs. - - `id: Optional[str]` + - `type: Literal["apply_patch"]` - The ID of the computer tool call output. + The type of the tool. Always `apply_patch`. - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + - `"apply_patch"` - The safety checks reported by the API that have been acknowledged by the developer. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `id: str` + The tool invocation context(s). - The ID of the pending safety check. + - `"direct"` - - `code: Optional[str]` + - `"programmatic"` - The type of the pending safety check. + - `type: Literal["tool_search_output"]` - - `message: Optional[str]` + The type of the item. Always `tool_search_output`. - Details about the pending safety check. + - `"tool_search_output"` - - `agent: Optional[ComputerCallOutputAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -97309,113 +107013,111 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `created_by: Optional[str]` - - `"in_progress"` + The identifier of the actor that created the item. - - `"completed"` + - `class AdditionalTools: …` - - `"incomplete"` + - `id: str` - - `class BetaResponseFunctionWebSearch: …` + The unique ID of the additional tools item. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `role: Literal["unknown", "user", "assistant", 5 more]` - - `id: str` + The role that provided the additional tools. - The unique ID of the web search tool call. + - `"unknown"` - - `action: Action` + - `"user"` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `"assistant"` - - `class ActionSearch: …` + - `"system"` - Action type "search" - Performs a web search query. + - `"critic"` - - `type: Literal["search"]` + - `"discriminator"` - The action type. + - `"developer"` - - `"search"` + - `"tool"` - - `queries: Optional[List[str]]` + - `tools: List[BetaTool]` - The search queries. + The additional tool definitions made available at this item. - - `query: Optional[str]` + - `class BetaFunctionTool: …` - The search query. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `sources: Optional[List[ActionSearchSource]]` + - `class BetaFileSearchTool: …` - The sources used in the search. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: Literal["url"]` + - `class BetaComputerTool: …` - The type of source. Always `url`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"url"` + - `class BetaComputerUsePreviewTool: …` - - `url: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The URL of the source. + - `class BetaWebSearchTool: …` - - `class ActionOpenPage: …` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Action type "open_page" - Opens a specific URL from search results. + - `class Mcp: …` - - `type: Literal["open_page"]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The action type. + - `class CodeInterpreter: …` - - `"open_page"` + A tool that runs Python code to help generate a response to a prompt. - - `url: Optional[str]` + - `class ProgrammaticToolCalling: …` - The URL opened by the model. + - `class ImageGeneration: …` - - `class ActionFindInPage: …` + A tool that generates images using the GPT image models. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `class LocalShell: …` - - `pattern: str` + A tool that allows the model to execute shell commands in a local environment. - The pattern or text to search for within the page. + - `class BetaFunctionShellTool: …` - - `type: Literal["find_in_page"]` + A tool that allows the model to execute shell commands. - The action type. + - `class BetaCustomTool: …` - - `"find_in_page"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `url: str` + - `class BetaNamespaceTool: …` - The URL of the page searched for the pattern. + Groups function/custom tools under a shared namespace. - - `status: Literal["in_progress", "searching", "completed", "failed"]` + - `class BetaToolSearchTool: …` - The status of the web search tool call. + Hosted or BYOT tool search configuration for deferred tools. - - `"in_progress"` + - `class BetaWebSearchPreviewTool: …` - - `"searching"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"completed"` + - `class BetaApplyPatchTool: …` - - `"failed"` + Allows the assistant to create, delete, or update files using unified diffs. - - `type: Literal["web_search_call"]` + - `type: Literal["additional_tools"]` - The type of the web search tool call. Always `web_search_call`. + The type of the item. Always `additional_tools`. - - `"web_search_call"` + - `"additional_tools"` - - `agent: Optional[Agent]` + - `agent: Optional[AdditionalToolsAgent]` The agent that produced this item. @@ -97423,32 +107125,23 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall: …` - - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - - `arguments: str` - - A JSON string of the arguments to pass to the function. - - - `call_id: str` + - `class BetaResponseCompactionItem: …` - The unique ID of the function tool call generated by the model. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `name: str` + - `id: str` - The name of the function to run. + The unique ID of the compaction item. - - `type: Literal["function_call"]` + - `encrypted_content: str` - The type of the function tool call. Always `function_call`. + The encrypted content that was produced by compaction. - - `"function_call"` + - `type: Literal["compaction"]` - - `id: Optional[str]` + The type of the item. Always `compaction`. - The unique ID of the function tool call. + - `"compaction"` - `agent: Optional[Agent]` @@ -97458,180 +107151,184 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `created_by: Optional[str]` - The execution context that produced this tool call. + The identifier of the actor that created the item. - - `class CallerDirect: …` + - `class ImageGenerationCall: …` - - `type: Literal["direct"]` + An image generation request made by the model. - - `"direct"` + - `id: str` - - `class CallerProgram: …` + The unique ID of the image generation call. - - `caller_id: str` + - `result: Optional[str]` - The call ID of the program item that produced this tool call. + The generated image encoded in base64. - - `type: Literal["program"]` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - - `"program"` + The status of the image generation call. - - `namespace: Optional[str]` + - `"in_progress"` - The namespace of the function to run. + - `"completed"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"generating"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"failed"` - - `"in_progress"` + - `type: Literal["image_generation_call"]` - - `"completed"` + The type of the image generation call. Always `image_generation_call`. - - `"incomplete"` + - `"image_generation_call"` - - `class FunctionCallOutput: …` + - `agent: Optional[ImageGenerationCallAgent]` - The output of a function tool call. + The agent that produced this item. - - `call_id: str` + - `agent_name: str` - The unique ID of the function tool call generated by the model. + The canonical name of the agent that produced this item. - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + - `class BetaResponseCodeInterpreterToolCall: …` - Text, image, or file output of the function tool call. + A tool call to run code. - - `str` + - `id: str` - A JSON string of the output of the function tool call. + The unique ID of the code interpreter tool call. - - `List[BetaResponseFunctionCallOutputItem]` + - `code: Optional[str]` - - `class BetaResponseInputTextContent: …` + The code to run, or null if not available. - A text input to the model. + - `container_id: str` - - `text: str` + The ID of the container used to run the code. - The text input to the model. + - `outputs: Optional[List[Output]]` - - `type: Literal["input_text"]` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The type of the input item. Always `input_text`. + - `class OutputLogs: …` - - `"input_text"` + The logs output from the code interpreter. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `logs: str` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The logs output from the code interpreter. - - `mode: Literal["explicit"]` + - `type: Literal["logs"]` - The breakpoint mode. Always `explicit`. + The type of the output. Always `logs`. - - `"explicit"` + - `"logs"` - - `class BetaResponseInputImageContent: …` + - `class OutputImage: …` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The image output from the code interpreter. - - `type: Literal["input_image"]` + - `type: Literal["image"]` - The type of the input item. Always `input_image`. + The type of the output. Always `image`. - - `"input_image"` + - `"image"` - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + - `url: str` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The URL of the image output from the code interpreter. - - `"low"` + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - - `"high"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"auto"` + - `"in_progress"` - - `"original"` + - `"completed"` - - `file_id: Optional[str]` + - `"incomplete"` - The ID of the file to be sent to the model. + - `"interpreting"` - - `image_url: Optional[str]` + - `"failed"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: Literal["code_interpreter_call"]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The type of the code interpreter tool call. Always `code_interpreter_call`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"code_interpreter_call"` - - `mode: Literal["explicit"]` + - `agent: Optional[Agent]` - The breakpoint mode. Always `explicit`. + The agent that produced this item. - - `"explicit"` + - `agent_name: str` - - `class BetaResponseInputFileContent: …` + The canonical name of the agent that produced this item. - A file input to the model. + - `class LocalShellCall: …` - - `type: Literal["input_file"]` + A tool call to run a command on the local shell. - The type of the input item. Always `input_file`. + - `id: str` - - `"input_file"` + The unique ID of the local shell call. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `action: LocalShellCallAction` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + Execute a shell command on the server. - - `"auto"` + - `command: List[str]` - - `"low"` + The command to run. - - `"high"` + - `env: Dict[str, str]` - - `file_data: Optional[str]` + Environment variables to set for the command. - The base64-encoded data of the file to be sent to the model. + - `type: Literal["exec"]` - - `file_id: Optional[str]` + The type of the local shell action. Always `exec`. - The ID of the file to be sent to the model. + - `"exec"` - - `file_url: Optional[str]` + - `timeout_ms: Optional[int]` - The URL of the file to be sent to the model. + Optional timeout in milliseconds for the command. - - `filename: Optional[str]` + - `user: Optional[str]` - The name of the file to be sent to the model. + Optional user to run the command as. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `working_directory: Optional[str]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Optional working directory to run the command in. - - `mode: Literal["explicit"]` + - `call_id: str` - The breakpoint mode. Always `explicit`. + The unique ID of the local shell tool call generated by the model. - - `"explicit"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["function_call_output"]` + The status of the local shell call. - The type of the function tool call output. Always `function_call_output`. + - `"in_progress"` - - `"function_call_output"` + - `"completed"` - - `id: Optional[str]` + - `"incomplete"` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `type: Literal["local_shell_call"]` - - `agent: Optional[FunctionCallOutputAgent]` + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `agent: Optional[LocalShellCallAgent]` The agent that produced this item. @@ -97639,33 +107336,35 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[FunctionCallOutputCaller]` + - `class LocalShellCallOutput: …` - The execution context that produced this tool call. + The output of a local shell tool call. - - `class FunctionCallOutputCallerDirect: …` + - `id: str` - - `type: Literal["direct"]` + The unique ID of the local shell tool call generated by the model. - The caller type. Always `direct`. + - `output: str` - - `"direct"` + A JSON string of the output of the local shell tool call. - - `class FunctionCallOutputCallerProgram: …` + - `type: Literal["local_shell_call_output"]` - - `caller_id: str` + The type of the local shell tool call output. Always `local_shell_call_output`. - The call ID of the program item that produced this tool call. + - `"local_shell_call_output"` - - `type: Literal["program"]` + - `agent: Optional[LocalShellCallOutputAgent]` - The caller type. Always `program`. + The agent that produced this item. - - `"program"` + - `agent_name: str` + + The canonical name of the agent that produced this item. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -97673,1385 +107372,1346 @@ print(compacted_response) - `"incomplete"` - - `class AgentMessage: …` - - A message routed between agents. - - - `author: str` + - `class BetaResponseFunctionShellToolCall: …` - The sending agent identity. + A tool call that executes one or more shell commands in a managed environment. - - `content: List[AgentMessageContent]` + - `id: str` - Plaintext, image, or encrypted content sent between agents. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `class BetaResponseInputTextContent: …` + - `action: Action` - A text input to the model. + The shell commands and limits that describe how to run the tool call. - - `class BetaResponseInputImageContent: …` + - `commands: List[str]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `max_output_length: Optional[int]` - - `class AgentMessageContentEncryptedContent: …` + Optional maximum number of characters to return from each command. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `timeout_ms: Optional[int]` - - `encrypted_content: str` + Optional timeout in milliseconds for the commands. - Opaque encrypted content. + - `call_id: str` - - `type: Literal["encrypted_content"]` + The unique ID of the shell tool call generated by the model. - The type of the input item. Always `encrypted_content`. + - `environment: Optional[Environment]` - - `"encrypted_content"` + Represents the use of a local environment to perform shell actions. - - `recipient: str` + - `class BetaResponseLocalEnvironment: …` - The destination agent identity. + Represents the use of a local environment to perform shell actions. - - `type: Literal["agent_message"]` + - `type: Literal["local"]` - The item type. Always `agent_message`. + The environment type. Always `local`. - - `"agent_message"` + - `"local"` - - `id: Optional[str]` + - `class BetaResponseContainerReference: …` - The unique ID of this agent message item. + Represents a container created with /v1/containers. - - `agent: Optional[AgentMessageAgent]` + - `container_id: str` - The agent that produced this item. + - `type: Literal["container_reference"]` - - `agent_name: str` + The environment type. Always `container_reference`. - The canonical name of the agent that produced this item. + - `"container_reference"` - - `class MultiAgentCall: …` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The multi-agent action that was executed. + - `"in_progress"` - - `"spawn_agent"` + - `"completed"` - - `"interrupt_agent"` + - `"incomplete"` - - `"list_agents"` + - `type: Literal["shell_call"]` - - `"send_message"` + The type of the item. Always `shell_call`. - - `"followup_task"` + - `"shell_call"` - - `"wait_agent"` + - `agent: Optional[Agent]` - - `arguments: str` + The agent that produced this item. - The action arguments as a JSON string. + - `agent_name: str` - - `call_id: str` + The canonical name of the agent that produced this item. - The unique ID linking this call to its output. + - `caller: Optional[Caller]` - - `type: Literal["multi_agent_call"]` + The execution context that produced this tool call. - The item type. Always `multi_agent_call`. + - `class CallerDirect: …` - - `"multi_agent_call"` + - `type: Literal["direct"]` - - `id: Optional[str]` + - `"direct"` - The unique ID of this multi-agent call. + - `class CallerProgram: …` - - `agent: Optional[MultiAgentCallAgent]` + - `caller_id: str` - The agent that produced this item. + The call ID of the program item that produced this tool call. - - `agent_name: str` + - `type: Literal["program"]` - The canonical name of the agent that produced this item. + - `"program"` - - `class MultiAgentCallOutput: …` + - `created_by: Optional[str]` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The ID of the entity that created this tool call. - The multi-agent action that produced this result. + - `class BetaResponseFunctionShellToolCallOutput: …` - - `"spawn_agent"` + The output of a shell tool call that was emitted. - - `"interrupt_agent"` + - `id: str` - - `"list_agents"` + The unique ID of the shell call output. Populated when this item is returned via API. - - `"send_message"` + - `call_id: str` - - `"followup_task"` + The unique ID of the shell tool call generated by the model. - - `"wait_agent"` + - `max_output_length: Optional[int]` - - `call_id: str` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - The unique ID of the multi-agent call. + - `output: List[Output]` - - `output: List[MultiAgentCallOutputOutput]` + An array of shell call output contents - Text output returned by the multi-agent action. + - `outcome: OutputOutcome` - - `text: str` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The text content. + - `class OutputOutcomeTimeout: …` - - `type: Literal["output_text"]` + Indicates that the shell call exceeded its configured time limit. - The content type. Always `output_text`. + - `type: Literal["timeout"]` - - `"output_text"` + The outcome type. Always `timeout`. - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + - `"timeout"` - Citations associated with the text content. + - `class OutputOutcomeExit: …` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + Indicates that the shell commands finished and returned an exit code. - - `file_id: str` + - `exit_code: int` - The ID of the file. + Exit code from the shell process. - - `filename: str` + - `type: Literal["exit"]` - The filename of the file cited. + The outcome type. Always `exit`. - - `index: int` + - `"exit"` - The index of the file in the list of files. + - `stderr: str` - - `type: Literal["file_citation"]` + The standard error output that was captured. - The citation type. Always `file_citation`. + - `stdout: str` - - `"file_citation"` + The standard output that was captured. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + - `created_by: Optional[str]` - - `end_index: int` + The identifier of the actor that created the item. - The index of the last character of the citation in the message. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `start_index: int` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The index of the first character of the citation in the message. + - `"in_progress"` - - `title: str` + - `"completed"` - The title of the cited resource. + - `"incomplete"` - - `type: Literal["url_citation"]` + - `type: Literal["shell_call_output"]` - The citation type. Always `url_citation`. + The type of the shell call output. Always `shell_call_output`. - - `"url_citation"` + - `"shell_call_output"` - - `url: str` + - `agent: Optional[Agent]` - The URL of the cited resource. + The agent that produced this item. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `agent_name: str` - - `container_id: str` + The canonical name of the agent that produced this item. - The ID of the container. + - `caller: Optional[Caller]` - - `end_index: int` + The execution context that produced this tool call. - The index of the last character of the citation in the message. + - `class CallerDirect: …` - - `file_id: str` + - `type: Literal["direct"]` - The ID of the container file. + - `"direct"` - - `filename: str` + - `class CallerProgram: …` - The filename of the container file cited. + - `caller_id: str` - - `start_index: int` + The call ID of the program item that produced this tool call. - The index of the first character of the citation in the message. + - `type: Literal["program"]` - - `type: Literal["container_file_citation"]` + - `"program"` - The citation type. Always `container_file_citation`. + - `created_by: Optional[str]` - - `"container_file_citation"` + The identifier of the actor that created the item. - - `type: Literal["multi_agent_call_output"]` + - `class BetaResponseApplyPatchToolCall: …` - The item type. Always `multi_agent_call_output`. + A tool call that applies file diffs by creating, deleting, or updating files. - - `"multi_agent_call_output"` + - `id: str` - - `id: Optional[str]` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The unique ID of this multi-agent call output. + - `call_id: str` - - `agent: Optional[MultiAgentCallOutputAgent]` + The unique ID of the apply patch tool call generated by the model. - The agent that produced this item. + - `operation: Operation` - - `agent_name: str` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The canonical name of the agent that produced this item. + - `class OperationCreateFile: …` - - `class ToolSearchCall: …` + Instruction describing how to create a file via the apply_patch tool. - - `arguments: object` + - `diff: str` - The arguments supplied to the tool search call. + Diff to apply. - - `type: Literal["tool_search_call"]` + - `path: str` - The item type. Always `tool_search_call`. + Path of the file to create. - - `"tool_search_call"` + - `type: Literal["create_file"]` - - `id: Optional[str]` + Create a new file with the provided diff. - The unique ID of this tool search call. + - `"create_file"` - - `agent: Optional[ToolSearchCallAgent]` + - `class OperationDeleteFile: …` - The agent that produced this item. + Instruction describing how to delete a file via the apply_patch tool. - - `agent_name: str` + - `path: str` - The canonical name of the agent that produced this item. + Path of the file to delete. - - `call_id: Optional[str]` + - `type: Literal["delete_file"]` - The unique ID of the tool search call generated by the model. + Delete the specified file. - - `execution: Optional[Literal["server", "client"]]` + - `"delete_file"` - Whether tool search was executed by the server or by the client. + - `class OperationUpdateFile: …` - - `"server"` + Instruction describing how to update a file via the apply_patch tool. - - `"client"` + - `diff: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + Diff to apply. - The status of the tool search call. + - `path: str` - - `"in_progress"` + Path of the file to update. - - `"completed"` + - `type: Literal["update_file"]` - - `"incomplete"` + Update an existing file with the provided diff. - - `class BetaResponseToolSearchOutputItemParam: …` + - `"update_file"` - - `tools: List[BetaTool]` + - `status: Literal["in_progress", "completed"]` - The loaded tool definitions returned by the tool search output. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `class BetaFunctionTool: …` + - `"in_progress"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `"completed"` - - `name: str` + - `type: Literal["apply_patch_call"]` - The name of the function to call. + The type of the item. Always `apply_patch_call`. - - `parameters: Optional[Dict[str, object]]` + - `"apply_patch_call"` - A JSON schema object describing the parameters of the function. + - `agent: Optional[Agent]` - - `strict: Optional[bool]` + The agent that produced this item. - Whether strict parameter validation is enforced for this function tool. + - `agent_name: str` - - `type: Literal["function"]` + The canonical name of the agent that produced this item. - The type of the function tool. Always `function`. + - `caller: Optional[Caller]` - - `"function"` + The execution context that produced this tool call. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `class CallerDirect: …` - The tool invocation context(s). + - `type: Literal["direct"]` - `"direct"` - - `"programmatic"` + - `class CallerProgram: …` - - `defer_loading: Optional[bool]` + - `caller_id: str` - Whether this function is deferred and loaded via tool search. + The call ID of the program item that produced this tool call. - - `description: Optional[str]` + - `type: Literal["program"]` - A description of the function. Used by the model to determine whether or not to call the function. + - `"program"` - - `output_schema: Optional[Dict[str, object]]` + - `created_by: Optional[str]` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The ID of the entity that created this tool call. - - `class BetaFileSearchTool: …` + - `class BetaResponseApplyPatchToolCallOutput: …` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The output emitted by an apply patch tool call. - - `type: Literal["file_search"]` + - `id: str` - The type of the file search tool. Always `file_search`. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"file_search"` + - `call_id: str` - - `vector_store_ids: List[str]` + The unique ID of the apply patch tool call generated by the model. - The IDs of the vector stores to search. + - `status: Literal["completed", "failed"]` - - `filters: Optional[Filters]` + The status of the apply patch tool call output. One of `completed` or `failed`. - A filter to apply. + - `"completed"` - - `class FiltersComparisonFilter: …` + - `"failed"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: Literal["apply_patch_call_output"]` - - `key: str` + The type of the item. Always `apply_patch_call_output`. - The key to compare against the value. + - `"apply_patch_call_output"` - - `type: Literal["eq", "ne", "gt", 5 more]` + - `agent: Optional[Agent]` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The agent that produced this item. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `agent_name: str` - - `"eq"` + The canonical name of the agent that produced this item. - - `"ne"` + - `caller: Optional[Caller]` - - `"gt"` + The execution context that produced this tool call. - - `"gte"` + - `class CallerDirect: …` - - `"lt"` + - `type: Literal["direct"]` - - `"lte"` + - `"direct"` - - `"in"` + - `class CallerProgram: …` - - `"nin"` + - `caller_id: str` - - `value: Union[str, float, bool, List[object]]` + The call ID of the program item that produced this tool call. - The value to compare against the attribute key; supports string, number, or boolean types. + - `type: Literal["program"]` - - `str` + - `"program"` - - `float` + - `created_by: Optional[str]` - - `bool` + The ID of the entity that created this tool call output. - - `List[object]` + - `output: Optional[str]` - - `class FiltersCompoundFilter: …` + Optional textual output returned by the apply patch tool. - Combine multiple filters using `and` or `or`. + - `class McpCall: …` - - `filters: List[FiltersCompoundFilterFilter]` + An invocation of a tool on an MCP server. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `id: str` - - `class FiltersCompoundFilterFilterComparisonFilter: …` + The unique ID of the tool call. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `arguments: str` - - `key: str` + A JSON string of the arguments passed to the tool. - The key to compare against the value. + - `name: str` - - `type: Literal["eq", "ne", "gt", 5 more]` + The name of the tool that was run. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `server_label: str` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The label of the MCP server running the tool. - - `"eq"` + - `type: Literal["mcp_call"]` - - `"ne"` + The type of the item. Always `mcp_call`. - - `"gt"` + - `"mcp_call"` - - `"gte"` + - `agent: Optional[McpCallAgent]` - - `"lt"` + The agent that produced this item. - - `"lte"` + - `agent_name: str` - - `"in"` + The canonical name of the agent that produced this item. - - `"nin"` + - `approval_request_id: Optional[str]` - - `value: Union[str, float, bool, List[object]]` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The value to compare against the attribute key; supports string, number, or boolean types. + - `error: Optional[str]` - - `str` + The error from the tool call, if any. - - `float` + - `output: Optional[str]` - - `bool` + The output from the tool call. - - `List[object]` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - `object` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `type: Literal["and", "or"]` + - `"in_progress"` - Type of operation: `and` or `or`. + - `"completed"` - - `"and"` + - `"incomplete"` - - `"or"` + - `"calling"` - - `max_num_results: Optional[int]` + - `"failed"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `class McpListTools: …` - - `ranking_options: Optional[RankingOptions]` + A list of tools available on an MCP server. - Ranking options for search. + - `id: str` - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + The unique ID of the list. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `server_label: str` - - `embedding_weight: float` + The label of the MCP server. - The weight of the embedding in the reciprocal ranking fusion. + - `tools: List[McpListToolsTool]` - - `text_weight: float` + The tools available on the server. - The weight of the text in the reciprocal ranking fusion. + - `input_schema: object` - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + The JSON schema describing the tool's input. - The ranker to use for the file search. + - `name: str` - - `"auto"` + The name of the tool. - - `"default-2024-11-15"` + - `annotations: Optional[object]` - - `score_threshold: Optional[float]` + Additional annotations about the tool. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `description: Optional[str]` - - `class BetaComputerTool: …` + The description of the tool. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: Literal["mcp_list_tools"]` - - `type: Literal["computer"]` + The type of the item. Always `mcp_list_tools`. - The type of the computer tool. Always `computer`. + - `"mcp_list_tools"` - - `"computer"` + - `agent: Optional[McpListToolsAgent]` - - `class BetaComputerUsePreviewTool: …` + The agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent_name: str` - - `display_height: int` + The canonical name of the agent that produced this item. - The height of the computer display. + - `error: Optional[str]` - - `display_width: int` + Error message if the server could not list tools. - The width of the computer display. + - `class McpApprovalRequest: …` - - `environment: Literal["windows", "mac", "linux", 2 more]` + A request for human approval of a tool invocation. - The type of computer environment to control. + - `id: str` - - `"windows"` + The unique ID of the approval request. - - `"mac"` + - `arguments: str` - - `"linux"` + A JSON string of arguments for the tool. - - `"ubuntu"` + - `name: str` - - `"browser"` + The name of the tool to run. - - `type: Literal["computer_use_preview"]` + - `server_label: str` - The type of the computer use tool. Always `computer_use_preview`. + The label of the MCP server making the request. - - `"computer_use_preview"` + - `type: Literal["mcp_approval_request"]` - - `class BetaWebSearchTool: …` + The type of the item. Always `mcp_approval_request`. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"mcp_approval_request"` - - `type: Literal["web_search", "web_search_2025_08_26"]` + - `agent: Optional[McpApprovalRequestAgent]` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The agent that produced this item. - - `"web_search"` + - `agent_name: str` - - `"web_search_2025_08_26"` + The canonical name of the agent that produced this item. - - `filters: Optional[Filters]` + - `class McpApprovalResponse: …` - Filters for the search. + A response to an MCP approval request. - - `allowed_domains: Optional[List[str]]` + - `id: str` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The unique ID of the approval response - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `approval_request_id: str` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + The ID of the approval request being answered. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `approve: bool` - - `"low"` + Whether the request was approved. - - `"medium"` + - `type: Literal["mcp_approval_response"]` - - `"high"` + The type of the item. Always `mcp_approval_response`. - - `user_location: Optional[UserLocation]` + - `"mcp_approval_response"` - The approximate location of the user. + - `agent: Optional[McpApprovalResponseAgent]` - - `city: Optional[str]` + The agent that produced this item. - Free text input for the city of the user, e.g. `San Francisco`. + - `agent_name: str` - - `country: Optional[str]` + The canonical name of the agent that produced this item. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `reason: Optional[str]` - - `region: Optional[str]` + Optional reason for the decision. - Free text input for the region of the user, e.g. `California`. + - `class BetaResponseCustomToolCall: …` - - `timezone: Optional[str]` + A call to a custom tool created by the model. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `call_id: str` - - `type: Optional[Literal["approximate"]]` + An identifier used to map this custom tool call to a tool call output. - The type of location approximation. Always `approximate`. + - `input: str` - - `"approximate"` + The input for the custom tool call generated by the model. - - `class Mcp: …` + - `name: str` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The name of the custom tool being called. - - `server_label: str` + - `type: Literal["custom_tool_call"]` - A label for this MCP server, used to identify it in tool calls. + The type of the custom tool call. Always `custom_tool_call`. - - `type: Literal["mcp"]` + - `"custom_tool_call"` - The type of the MCP tool. Always `mcp`. + - `id: Optional[str]` - - `"mcp"` + The unique ID of the custom tool call in the OpenAI platform. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `agent: Optional[Agent]` - The tool invocation context(s). + The agent that produced this item. - - `"direct"` + - `agent_name: str` - - `"programmatic"` + The canonical name of the agent that produced this item. - - `allowed_tools: Optional[McpAllowedTools]` + - `caller: Optional[Caller]` - List of allowed tool names or a filter object. + The execution context that produced this tool call. - - `List[str]` + - `class CallerDirect: …` - A string array of allowed tool names + - `type: Literal["direct"]` - - `class McpAllowedToolsMcpToolFilter: …` + - `"direct"` - A filter object to specify which tools are allowed. + - `class CallerProgram: …` - - `read_only: Optional[bool]` + - `caller_id: str` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The call ID of the program item that produced this tool call. - - `tool_names: Optional[List[str]]` + - `type: Literal["program"]` - List of allowed tool names. + - `"program"` - - `authorization: Optional[str]` + - `namespace: Optional[str]` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The namespace of the custom tool being called. - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + - `class BetaResponseCustomToolCallOutputItem: …` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The output of a custom tool call from your code, being sent back to the model. - Currently supported `connector_id` values are: + - `id: str` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The unique ID of the custom tool call output item. - - `"connector_dropbox"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"connector_gmail"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"connector_googlecalendar"` + - `"in_progress"` - - `"connector_googledrive"` + - `"completed"` - - `"connector_microsoftteams"` + - `"incomplete"` - - `"connector_outlookcalendar"` + - `created_by: Optional[str]` - - `"connector_outlookemail"` + The identifier of the actor that created the item. - - `"connector_sharepoint"` + - `output_index: int` - - `defer_loading: Optional[bool]` + The index of the output item that was added. - Whether this MCP tool is deferred and discovered via tool search. + - `sequence_number: int` - - `headers: Optional[Dict[str, str]]` + The sequence number of this event. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `type: Literal["response.output_item.added"]` - - `require_approval: Optional[McpRequireApproval]` + The type of the event. Always `response.output_item.added`. - Specify which of the MCP server's tools require approval. + - `"response.output_item.added"` - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `agent: Optional[Agent]` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The agent that owns this multi-agent streaming event. - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `agent_name: str` - A filter object to specify which tools are allowed. + The canonical name of the agent that produced this item. - - `read_only: Optional[bool]` +### Beta Response Output Item Done Event - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. +- `class BetaResponseOutputItemDoneEvent: …` - - `tool_names: Optional[List[str]]` + Emitted when an output item is marked done. - List of allowed tool names. + - `item: BetaResponseOutputItem` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + The output item that was marked done. - A filter object to specify which tools are allowed. + - `class BetaResponseOutputMessage: …` - - `read_only: Optional[bool]` + An output message from the model. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `id: str` - - `tool_names: Optional[List[str]]` + The unique ID of the output message. - List of allowed tool names. + - `content: List[Content]` - - `Literal["always", "never"]` + The content of the output message. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `class BetaResponseOutputText: …` - - `"always"` + A text output from the model. - - `"never"` + - `annotations: List[Annotation]` - - `server_description: Optional[str]` + The annotations of the text output. - Optional description of the MCP server, used to provide more context. + - `class AnnotationFileCitation: …` - - `server_url: Optional[str]` + A citation to a file. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `file_id: str` - - `tunnel_id: Optional[str]` + The ID of the file. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `filename: str` - - `class CodeInterpreter: …` + The filename of the file cited. - A tool that runs Python code to help generate a response to a prompt. + - `index: int` - - `container: CodeInterpreterContainer` + The index of the file in the list of files. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `type: Literal["file_citation"]` - - `str` + The type of the file citation. Always `file_citation`. - The container ID. + - `"file_citation"` - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `class AnnotationURLCitation: …` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + A citation for a web resource used to generate a model response. - - `type: Literal["auto"]` + - `end_index: int` - Always `auto`. + The index of the last character of the URL citation in the message. - - `"auto"` + - `start_index: int` - - `file_ids: Optional[List[str]]` + The index of the first character of the URL citation in the message. - An optional list of uploaded files to make available to your code. + - `title: str` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + The title of the web resource. - The memory limit for the code interpreter container. + - `type: Literal["url_citation"]` - - `"1g"` + The type of the URL citation. Always `url_citation`. - - `"4g"` + - `"url_citation"` - - `"16g"` + - `url: str` - - `"64g"` + The URL of the web resource. - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `class AnnotationContainerFileCitation: …` - Network access policy for the container. + A citation for a container file used to generate a model response. - - `class BetaContainerNetworkPolicyDisabled: …` + - `container_id: str` - - `type: Literal["disabled"]` + The ID of the container file. - Disable outbound network access. Always `disabled`. + - `end_index: int` - - `"disabled"` + The index of the last character of the container file citation in the message. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `file_id: str` - - `allowed_domains: List[str]` + The ID of the file. - A list of allowed domains when type is `allowlist`. + - `filename: str` - - `type: Literal["allowlist"]` + The filename of the container file cited. - Allow outbound network access only to specified domains. Always `allowlist`. + - `start_index: int` - - `"allowlist"` + The index of the first character of the container file citation in the message. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `type: Literal["container_file_citation"]` - Optional domain-scoped secrets for allowlisted domains. + The type of the container file citation. Always `container_file_citation`. - - `domain: str` + - `"container_file_citation"` - The domain associated with the secret. + - `class AnnotationFilePath: …` - - `name: str` + A path to a file. - The name of the secret to inject for the domain. + - `file_id: str` - - `value: str` + The ID of the file. - The secret value to inject for the domain. + - `index: int` - - `type: Literal["code_interpreter"]` + The index of the file in the list of files. - The type of the code interpreter tool. Always `code_interpreter`. + - `type: Literal["file_path"]` - - `"code_interpreter"` + The type of the file path. Always `file_path`. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"file_path"` - The tool invocation context(s). + - `text: str` - - `"direct"` + The text output from the model. - - `"programmatic"` + - `type: Literal["output_text"]` - - `class ProgrammaticToolCalling: …` + The type of the output text. Always `output_text`. - - `type: Literal["programmatic_tool_calling"]` + - `"output_text"` - The type of the tool. Always `programmatic_tool_calling`. + - `logprobs: Optional[List[Logprob]]` - - `"programmatic_tool_calling"` + - `token: str` - - `class ImageGeneration: …` + - `bytes: List[int]` - A tool that generates images using the GPT image models. + - `logprob: float` - - `type: Literal["image_generation"]` + - `top_logprobs: List[LogprobTopLogprob]` - The type of the image generation tool. Always `image_generation`. + - `token: str` - - `"image_generation"` + - `bytes: List[int]` - - `action: Optional[Literal["generate", "edit", "auto"]]` + - `logprob: float` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `class BetaResponseOutputRefusal: …` - - `"generate"` + A refusal from the model. - - `"edit"` + - `refusal: str` - - `"auto"` + The refusal explanation from the model. - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + - `type: Literal["refusal"]` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The type of the refusal. Always `refusal`. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `"refusal"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `role: Literal["assistant"]` - - `"transparent"` + The role of the output message. Always `assistant`. - - `"opaque"` + - `"assistant"` - - `"auto"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `input_fidelity: Optional[Literal["high", "low"]]` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `"in_progress"` - - `"high"` + - `"completed"` - - `"low"` + - `"incomplete"` - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + - `type: Literal["message"]` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The type of the output message. Always `message`. - - `file_id: Optional[str]` + - `"message"` - File ID for the mask image. + - `agent: Optional[Agent]` - - `image_url: Optional[str]` + The agent that produced this item. - Base64-encoded mask image. + - `agent_name: str` - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + The canonical name of the agent that produced this item. - The image generation model to use. Default: `gpt-image-1`. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `str` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `"commentary"` - The image generation model to use. Default: `gpt-image-1`. + - `"final_answer"` - - `"gpt-image-1"` + - `class BetaResponseFileSearchToolCall: …` - - `"gpt-image-1-mini"` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `"gpt-image-2"` + - `id: str` - - `"gpt-image-2-2026-04-21"` + The unique ID of the file search tool call. - - `"gpt-image-1.5"` + - `queries: List[str]` - - `"chatgpt-image-latest"` + The queries used to search for files. - - `moderation: Optional[Literal["auto", "low"]]` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - Moderation level for the generated image. Default: `auto`. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"auto"` + - `"in_progress"` - - `"low"` + - `"searching"` - - `output_compression: Optional[int]` + - `"completed"` - Compression level for the output image. Default: 100. + - `"incomplete"` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + - `"failed"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `type: Literal["file_search_call"]` - - `"png"` + The type of the file search tool call. Always `file_search_call`. - - `"webp"` + - `"file_search_call"` - - `"jpeg"` + - `agent: Optional[Agent]` - - `partial_images: Optional[int]` + The agent that produced this item. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `agent_name: str` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + The canonical name of the agent that produced this item. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `results: Optional[List[Result]]` - - `"low"` + The results of the file search tool call. - - `"medium"` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - - `"high"` + 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, booleans, or numbers. - - `"auto"` + - `str` - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + - `float` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `bool` - - `str` + - `file_id: Optional[str]` - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + The unique ID of the file. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `filename: Optional[str]` - - `"1024x1024"` + The name of the file. - - `"1024x1536"` + - `score: Optional[float]` - - `"1536x1024"` + The relevance score of the file - a value between 0 and 1. - - `"auto"` + - `text: Optional[str]` - - `class LocalShell: …` + The text that was retrieved from the file. - A tool that allows the model to execute shell commands in a local environment. + - `class BetaResponseFunctionToolCall: …` - - `type: Literal["local_shell"]` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The type of the local shell tool. Always `local_shell`. + - `arguments: str` - - `"local_shell"` + A JSON string of the arguments to pass to the function. - - `class BetaFunctionShellTool: …` + - `call_id: str` - A tool that allows the model to execute shell commands. + The unique ID of the function tool call generated by the model. - - `type: Literal["shell"]` + - `name: str` - The type of the shell tool. Always `shell`. + The name of the function to run. - - `"shell"` + - `type: Literal["function_call"]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The type of the function tool call. Always `function_call`. - The tool invocation context(s). + - `"function_call"` - - `"direct"` + - `id: Optional[str]` - - `"programmatic"` + The unique ID of the function tool call. - - `environment: Optional[Environment]` + - `agent: Optional[Agent]` - - `class BetaContainerAuto: …` + The agent that produced this item. - - `type: Literal["container_auto"]` + - `agent_name: str` - Automatically creates a container for this request + The canonical name of the agent that produced this item. - - `"container_auto"` + - `caller: Optional[Caller]` - - `file_ids: Optional[List[str]]` + The execution context that produced this tool call. - An optional list of uploaded files to make available to your code. + - `class CallerDirect: …` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `type: Literal["direct"]` - The memory limit for the container. + - `"direct"` - - `"1g"` + - `class CallerProgram: …` - - `"4g"` + - `caller_id: str` - - `"16g"` + The call ID of the program item that produced this tool call. - - `"64g"` + - `type: Literal["program"]` - - `network_policy: Optional[NetworkPolicy]` + - `"program"` - Network access policy for the container. + - `namespace: Optional[str]` - - `class BetaContainerNetworkPolicyDisabled: …` + The namespace of the function to run. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `skills: Optional[List[Skill]]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - An optional list of skills referenced by id or inline data. + - `"in_progress"` - - `class BetaSkillReference: …` + - `"completed"` - - `skill_id: str` + - `"incomplete"` - The ID of the referenced skill. + - `class BetaResponseFunctionToolCallOutputItem: …` - - `type: Literal["skill_reference"]` + - `id: str` - References a skill created with the /v1/skills endpoint. + The unique ID of the function call tool output. - - `"skill_reference"` + - `call_id: str` - - `version: Optional[str]` + The unique ID of the function tool call generated by the model. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `output: Union[str, List[OutputOutputContentList]]` - - `class BetaInlineSkill: …` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `description: str` + - `str` - The description of the skill. + A string of the output of the function call. - - `name: str` + - `List[OutputOutputContentList]` - The name of the skill. + Text, image, or file output of the function call. - - `source: BetaInlineSkillSource` + - `class BetaResponseInputText: …` - Inline skill payload + A text input to the model. - - `data: str` + - `text: str` - Base64-encoded skill zip bundle. + The text input to the model. - - `media_type: Literal["application/zip"]` + - `type: Literal["input_text"]` - The media type of the inline skill payload. Must be `application/zip`. + The type of the input item. Always `input_text`. - - `"application/zip"` + - `"input_text"` - - `type: Literal["base64"]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The type of the inline skill source. Must be `base64`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"base64"` + - `mode: Literal["explicit"]` - - `type: Literal["inline"]` + The breakpoint mode. Always `explicit`. - Defines an inline skill for this request. + - `"explicit"` - - `"inline"` + - `class BetaResponseInputImage: …` - - `class BetaLocalEnvironment: …` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `type: Literal["local"]` + - `detail: Literal["low", "high", "auto", "original"]` - Use a local computer environment. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"local"` + - `"low"` - - `skills: Optional[List[BetaLocalSkill]]` + - `"high"` - An optional list of skills. + - `"auto"` - - `description: str` + - `"original"` - The description of the skill. + - `type: Literal["input_image"]` - - `name: str` + The type of the input item. Always `input_image`. - The name of the skill. + - `"input_image"` - - `path: str` + - `file_id: Optional[str]` - The path to the directory containing the skill. + The ID of the file to be sent to the model. - - `class BetaContainerReference: …` + - `image_url: Optional[str]` - - `container_id: str` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The ID of the referenced container. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `type: Literal["container_reference"]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - References a container created with the /v1/containers endpoint + - `mode: Literal["explicit"]` - - `"container_reference"` + The breakpoint mode. Always `explicit`. - - `class BetaCustomTool: …` + - `"explicit"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `class BetaResponseInputFile: …` - - `name: str` + A file input to the model. - The name of the custom tool, used to identify it in tool calls. + - `type: Literal["input_file"]` - - `type: Literal["custom"]` + The type of the input item. Always `input_file`. - The type of the custom tool. Always `custom`. + - `"input_file"` - - `"custom"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The tool invocation context(s). + - `"auto"` - - `"direct"` + - `"low"` - - `"programmatic"` + - `"high"` - - `defer_loading: Optional[bool]` + - `file_data: Optional[str]` - Whether this tool should be deferred and discovered via tool search. + The content of the file to be sent to the model. - - `description: Optional[str]` + - `file_id: Optional[str]` - Optional description of the custom tool, used to provide more context. + The ID of the file to be sent to the model. - - `format: Optional[Format]` + - `file_url: Optional[str]` - The input format for the custom tool. Default is unconstrained text. + The URL of the file to be sent to the model. - - `class FormatText: …` + - `filename: Optional[str]` - Unconstrained free-form text. + The name of the file to be sent to the model. - - `type: Literal["text"]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Unconstrained text format. Always `text`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"text"` + - `mode: Literal["explicit"]` - - `class FormatGrammar: …` + The breakpoint mode. Always `explicit`. - A grammar defined by the user. + - `"explicit"` - - `definition: str` + - `status: Literal["in_progress", "completed", "incomplete"]` - The grammar definition. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `syntax: Literal["lark", "regex"]` + - `"in_progress"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"completed"` - - `"lark"` + - `"incomplete"` - - `"regex"` + - `type: Literal["function_call_output"]` - - `type: Literal["grammar"]` + The type of the function tool call output. Always `function_call_output`. - Grammar format. Always `grammar`. + - `"function_call_output"` - - `"grammar"` + - `agent: Optional[Agent]` - - `class BetaNamespaceTool: …` + The agent that produced this item. - Groups function/custom tools under a shared namespace. + - `agent_name: str` - - `description: str` + The canonical name of the agent that produced this item. - A description of the namespace shown to the model. + - `caller: Optional[Caller]` - - `name: str` + The execution context that produced this tool call. - The namespace name used in tool calls (for example, `crm`). + - `class CallerDirect: …` - - `tools: List[Tool]` + - `type: Literal["direct"]` - The function/custom tools available inside this namespace. + The caller type. Always `direct`. - - `class ToolFunction: …` + - `"direct"` - - `name: str` + - `class CallerProgram: …` - - `type: Literal["function"]` + - `caller_id: str` - - `"function"` + The call ID of the program item that produced this tool call. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["program"]` - The tool invocation context(s). + The caller type. Always `program`. - - `"direct"` + - `"program"` - - `"programmatic"` + - `created_by: Optional[str]` - - `defer_loading: Optional[bool]` + The identifier of the actor that created the item. - Whether this function should be deferred and discovered via tool search. + - `class AgentMessage: …` - - `description: Optional[str]` + - `id: str` - - `output_schema: Optional[Dict[str, object]]` + The unique ID of the agent message. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `author: str` - - `parameters: Optional[object]` + The sending agent identity. - - `strict: Optional[bool]` + - `content: List[AgentMessageContent]` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + Encrypted content sent between agents. - - `class BetaCustomTool: …` + - `class BetaResponseInputText: …` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A text input to the model. - - `type: Literal["namespace"]` + - `class BetaResponseOutputText: …` - The type of the tool. Always `namespace`. + A text output from the model. - - `"namespace"` + - `class AgentMessageContentText: …` - - `class BetaToolSearchTool: …` + A text content. - Hosted or BYOT tool search configuration for deferred tools. + - `text: str` - - `type: Literal["tool_search"]` + - `type: Literal["text"]` - The type of the tool. Always `tool_search`. + - `"text"` - - `"tool_search"` + - `class AgentMessageContentSummaryText: …` - - `description: Optional[str]` + A summary text from the model. - Description shown to the model for a client-executed tool search tool. + - `text: str` - - `execution: Optional[Literal["server", "client"]]` + A summary of the reasoning output from the model so far. - Whether tool search is executed by the server or by the client. + - `type: Literal["summary_text"]` - - `"server"` + The type of the object. Always `summary_text`. - - `"client"` + - `"summary_text"` - - `parameters: Optional[object]` + - `class AgentMessageContentReasoningText: …` - Parameter schema for a client-executed tool search tool. + Reasoning text from the model. - - `class BetaWebSearchPreviewTool: …` + - `text: str` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The reasoning text from the model. + + - `type: Literal["reasoning_text"]` + + The type of the reasoning text. Always `reasoning_text`. - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + - `"reasoning_text"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `class BetaResponseOutputRefusal: …` - - `"web_search_preview"` + A refusal from the model. - - `"web_search_preview_2025_03_11"` + - `class BetaResponseInputImage: …` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"text"` + - `class AgentMessageContentComputerScreenshot: …` - - `"image"` + A screenshot of a computer. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `detail: Literal["low", "high", "auto", "original"]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `"low"` - - `"medium"` - - `"high"` - - `user_location: Optional[UserLocation]` + - `"auto"` - The user's location. + - `"original"` - - `type: Literal["approximate"]` + - `file_id: Optional[str]` - The type of location approximation. Always `approximate`. + The identifier of an uploaded file that contains the screenshot. - - `"approximate"` + - `image_url: Optional[str]` - - `city: Optional[str]` + The URL of the screenshot image. - Free text input for the city of the user, e.g. `San Francisco`. + - `type: Literal["computer_screenshot"]` - - `country: Optional[str]` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"computer_screenshot"` - - `region: Optional[str]` + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - Free text input for the region of the user, e.g. `California`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `timezone: Optional[str]` + - `mode: Literal["explicit"]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The breakpoint mode. Always `explicit`. - - `class BetaApplyPatchTool: …` + - `"explicit"` - Allows the assistant to create, delete, or update files using unified diffs. + - `class BetaResponseInputFile: …` - - `type: Literal["apply_patch"]` + A file input to the model. - The type of the tool. Always `apply_patch`. + - `class AgentMessageContentEncryptedContent: …` - - `"apply_patch"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `encrypted_content: str` - The tool invocation context(s). + Opaque encrypted content. - - `"direct"` + - `type: Literal["encrypted_content"]` - - `"programmatic"` + The type of the input item. Always `encrypted_content`. - - `type: Literal["tool_search_output"]` + - `"encrypted_content"` - The item type. Always `tool_search_output`. + - `recipient: str` - - `"tool_search_output"` + The destination agent identity. - - `id: Optional[str]` + - `type: Literal["agent_message"]` - The unique ID of this tool search output. + The type of the item. Always `agent_message`. - - `agent: Optional[Agent]` + - `"agent_message"` + + - `agent: Optional[AgentMessageAgent]` The agent that produced this item. @@ -99059,208 +108719,203 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `call_id: Optional[str]` + - `class MultiAgentCall: …` - The unique ID of the tool search call generated by the model. + - `id: str` - - `execution: Optional[Literal["server", "client"]]` + The unique ID of the multi-agent call item. - Whether tool search was executed by the server or by the client. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"server"` + The multi-agent action to execute. - - `"client"` + - `"spawn_agent"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"interrupt_agent"` - The status of the tool search output. + - `"list_agents"` - - `"in_progress"` + - `"send_message"` - - `"completed"` + - `"followup_task"` - - `"incomplete"` + - `"wait_agent"` - - `class AdditionalTools: …` + - `arguments: str` - - `role: Literal["developer"]` + The JSON string of arguments generated for the action. - The role that provided the additional tools. Only `developer` is supported. + - `call_id: str` - - `"developer"` + The unique ID linking this call to its output. - - `tools: List[BetaTool]` + - `type: Literal["multi_agent_call"]` - A list of additional tools made available at this item. + The type of the multi-agent call. Always `multi_agent_call`. - - `class BetaFunctionTool: …` + - `"multi_agent_call"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `agent: Optional[MultiAgentCallAgent]` - - `class BetaFileSearchTool: …` + The agent that produced this item. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `agent_name: str` - - `class BetaComputerTool: …` + The canonical name of the agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class MultiAgentCallOutput: …` - - `class BetaComputerUsePreviewTool: …` + - `id: str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The unique ID of the multi-agent call output item. - - `class BetaWebSearchTool: …` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The multi-agent action that produced this result. - - `class Mcp: …` + - `"spawn_agent"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"interrupt_agent"` - - `class CodeInterpreter: …` + - `"list_agents"` - A tool that runs Python code to help generate a response to a prompt. + - `"send_message"` - - `class ProgrammaticToolCalling: …` + - `"followup_task"` - - `class ImageGeneration: …` + - `"wait_agent"` - A tool that generates images using the GPT image models. + - `call_id: str` - - `class LocalShell: …` + The unique ID of the multi-agent call. - A tool that allows the model to execute shell commands in a local environment. + - `output: List[BetaResponseOutputText]` - - `class BetaFunctionShellTool: …` + Text output returned by the multi-agent action. - A tool that allows the model to execute shell commands. + - `annotations: List[Annotation]` - - `class BetaCustomTool: …` + The annotations of the text output. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `text: str` - - `class BetaNamespaceTool: …` + The text output from the model. - Groups function/custom tools under a shared namespace. + - `type: Literal["output_text"]` - - `class BetaToolSearchTool: …` + The type of the output text. Always `output_text`. - Hosted or BYOT tool search configuration for deferred tools. + - `logprobs: Optional[List[Logprob]]` - - `class BetaWebSearchPreviewTool: …` + - `type: Literal["multi_agent_call_output"]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The type of the multi-agent result. Always `multi_agent_call_output`. - - `class BetaApplyPatchTool: …` + - `"multi_agent_call_output"` - Allows the assistant to create, delete, or update files using unified diffs. + - `agent: Optional[MultiAgentCallOutputAgent]` - - `type: Literal["additional_tools"]` + The agent that produced this item. - The item type. Always `additional_tools`. + - `agent_name: str` - - `"additional_tools"` + The canonical name of the agent that produced this item. - - `id: Optional[str]` + - `class BetaResponseFunctionWebSearch: …` - The unique ID of this additional tools item. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `agent: Optional[AdditionalToolsAgent]` + - `id: str` - The agent that produced this item. + The unique ID of the web search tool call. - - `agent_name: str` + - `action: Action` - The canonical name of the agent that produced this item. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `class BetaResponseReasoningItem: …` + - `class ActionSearch: …` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + Action type "search" - Performs a web search query. - - `id: str` + - `type: Literal["search"]` - The unique identifier of the reasoning content. + The action type. - - `summary: List[Summary]` + - `"search"` - Reasoning summary content. + - `queries: Optional[List[str]]` - - `text: str` + The search queries. - A summary of the reasoning output from the model so far. + - `query: Optional[str]` - - `type: Literal["summary_text"]` + The search query. - The type of the object. Always `summary_text`. + - `sources: Optional[List[ActionSearchSource]]` - - `"summary_text"` + The sources used in the search. - - `type: Literal["reasoning"]` + - `type: Literal["url"]` - The type of the object. Always `reasoning`. + The type of source. Always `url`. - - `"reasoning"` + - `"url"` - - `agent: Optional[Agent]` + - `url: str` - The agent that produced this item. + The URL of the source. - - `agent_name: str` + - `class ActionOpenPage: …` - The canonical name of the agent that produced this item. + Action type "open_page" - Opens a specific URL from search results. - - `content: Optional[List[Content]]` + - `type: Literal["open_page"]` - Reasoning text content. + The action type. - - `text: str` + - `"open_page"` - The reasoning text from the model. + - `url: Optional[str]` - - `type: Literal["reasoning_text"]` + The URL opened by the model. - The type of the reasoning text. Always `reasoning_text`. + - `class ActionFindInPage: …` - - `"reasoning_text"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `encrypted_content: Optional[str]` + - `pattern: str` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The pattern or text to search for within the page. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `type: Literal["find_in_page"]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The action type. - - `"in_progress"` + - `"find_in_page"` - - `"completed"` + - `url: str` - - `"incomplete"` + The URL of the page searched for the pattern. - - `class BetaResponseCompactionItemParam: …` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The status of the web search tool call. - - `encrypted_content: str` + - `"in_progress"` - The encrypted content of the compaction summary. + - `"searching"` - - `type: Literal["compaction"]` + - `"completed"` - The type of the item. Always `compaction`. + - `"failed"` - - `"compaction"` + - `type: Literal["web_search_call"]` - - `id: Optional[str]` + The type of the web search tool call. Always `web_search_call`. - The ID of the compaction item. + - `"web_search_call"` - `agent: Optional[Agent]` @@ -99270,258 +108925,289 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ImageGenerationCall: …` + - `class BetaResponseComputerToolCall: …` - An image generation request made by the model. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: str` - The unique ID of the image generation call. + The unique ID of the computer call. - - `result: Optional[str]` + - `call_id: str` - The generated image encoded in base64. + An identifier used when responding to the tool call with output. - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `pending_safety_checks: List[PendingSafetyCheck]` - The status of the image generation call. + The pending safety checks for the computer call. + + - `id: str` + + The ID of the pending safety check. + + - `code: Optional[str]` + + The type of the pending safety check. + + - `message: Optional[str]` + + Details about the pending safety check. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` - `"completed"` - - `"generating"` + - `"incomplete"` - - `"failed"` + - `type: Literal["computer_call"]` - - `type: Literal["image_generation_call"]` + The type of the computer call. Always `computer_call`. - The type of the image generation call. Always `image_generation_call`. + - `"computer_call"` - - `"image_generation_call"` + - `action: Optional[BetaComputerAction]` - - `agent: Optional[ImageGenerationCallAgent]` + A click action. - The agent that produced this item. + - `class Click: …` - - `agent_name: str` + A click action. - The canonical name of the agent that produced this item. + - `button: Literal["left", "right", "wheel", 2 more]` - - `class BetaResponseCodeInterpreterToolCall: …` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - A tool call to run code. + - `"left"` - - `id: str` + - `"right"` - The unique ID of the code interpreter tool call. + - `"wheel"` - - `code: Optional[str]` + - `"back"` - The code to run, or null if not available. + - `"forward"` - - `container_id: str` + - `type: Literal["click"]` - The ID of the container used to run the code. + Specifies the event type. For a click action, this property is always `click`. - - `outputs: Optional[List[Output]]` + - `"click"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `x: int` - - `class OutputLogs: …` + The x-coordinate where the click occurred. - The logs output from the code interpreter. + - `y: int` - - `logs: str` + The y-coordinate where the click occurred. - The logs output from the code interpreter. + - `keys: Optional[List[str]]` - - `type: Literal["logs"]` + The keys being held while clicking. - The type of the output. Always `logs`. + - `class DoubleClick: …` - - `"logs"` + A double click action. - - `class OutputImage: …` + - `keys: Optional[List[str]]` - The image output from the code interpreter. + The keys being held while double-clicking. - - `type: Literal["image"]` + - `type: Literal["double_click"]` - The type of the output. Always `image`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"image"` + - `"double_click"` - - `url: str` + - `x: int` - The URL of the image output from the code interpreter. + The x-coordinate where the double click occurred. - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + - `y: int` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The y-coordinate where the double click occurred. - - `"in_progress"` + - `class Drag: …` - - `"completed"` + A drag action. - - `"incomplete"` + - `path: List[DragPath]` - - `"interpreting"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"failed"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `type: Literal["code_interpreter_call"]` + - `x: int` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The x-coordinate. - - `"code_interpreter_call"` + - `y: int` - - `agent: Optional[Agent]` + The y-coordinate. - The agent that produced this item. + - `type: Literal["drag"]` - - `agent_name: str` + Specifies the event type. For a drag action, this property is always set to `drag`. - The canonical name of the agent that produced this item. + - `"drag"` - - `class LocalShellCall: …` + - `keys: Optional[List[str]]` - A tool call to run a command on the local shell. + The keys being held while dragging the mouse. - - `id: str` + - `class Keypress: …` - The unique ID of the local shell call. + A collection of keypresses the model would like to perform. - - `action: LocalShellCallAction` + - `keys: List[str]` - Execute a shell command on the server. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `command: List[str]` + - `type: Literal["keypress"]` - The command to run. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `env: Dict[str, str]` + - `"keypress"` - Environment variables to set for the command. + - `class Move: …` - - `type: Literal["exec"]` + A mouse move action. - The type of the local shell action. Always `exec`. + - `type: Literal["move"]` - - `"exec"` + Specifies the event type. For a move action, this property is always set to `move`. - - `timeout_ms: Optional[int]` + - `"move"` - Optional timeout in milliseconds for the command. + - `x: int` - - `user: Optional[str]` + The x-coordinate to move to. - Optional user to run the command as. + - `y: int` - - `working_directory: Optional[str]` + The y-coordinate to move to. - Optional working directory to run the command in. + - `keys: Optional[List[str]]` - - `call_id: str` + The keys being held while moving the mouse. - The unique ID of the local shell tool call generated by the model. + - `class Screenshot: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + A screenshot action. - The status of the local shell call. + - `type: Literal["screenshot"]` - - `"in_progress"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"completed"` + - `"screenshot"` - - `"incomplete"` + - `class Scroll: …` - - `type: Literal["local_shell_call"]` + A scroll action. - The type of the local shell call. Always `local_shell_call`. + - `scroll_x: int` - - `"local_shell_call"` + The horizontal scroll distance. - - `agent: Optional[LocalShellCallAgent]` + - `scroll_y: int` - The agent that produced this item. + The vertical scroll distance. - - `agent_name: str` + - `type: Literal["scroll"]` - The canonical name of the agent that produced this item. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `class LocalShellCallOutput: …` + - `"scroll"` - The output of a local shell tool call. + - `x: int` - - `id: str` + The x-coordinate where the scroll occurred. - The unique ID of the local shell tool call generated by the model. + - `y: int` - - `output: str` + The y-coordinate where the scroll occurred. - A JSON string of the output of the local shell tool call. + - `keys: Optional[List[str]]` - - `type: Literal["local_shell_call_output"]` + The keys being held while scrolling. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `class Type: …` - - `"local_shell_call_output"` + An action to type in text. - - `agent: Optional[LocalShellCallOutputAgent]` + - `text: str` - The agent that produced this item. + The text to type. - - `agent_name: str` + - `type: Literal["type"]` - The canonical name of the agent that produced this item. + Specifies the event type. For a type action, this property is always set to `type`. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"type"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `class Wait: …` - - `"in_progress"` + A wait action. - - `"completed"` + - `type: Literal["wait"]` - - `"incomplete"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `class ShellCall: …` + - `"wait"` - A tool representing a request to execute one or more shell commands. + - `actions: Optional[BetaComputerActionList]` - - `action: ShellCallAction` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The shell commands and limits that describe how to run the tool call. + - `class Click: …` - - `commands: List[str]` + A click action. - Ordered shell commands for the execution environment to run. + - `class DoubleClick: …` - - `max_output_length: Optional[int]` + A double click action. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `class Drag: …` - - `timeout_ms: Optional[int]` + A drag action. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `class Keypress: …` - - `call_id: str` + A collection of keypresses the model would like to perform. - The unique ID of the shell tool call generated by the model. + - `class Move: …` - - `type: Literal["shell_call"]` + A mouse move action. - The type of the item. Always `shell_call`. + - `class Screenshot: …` - - `"shell_call"` + A screenshot action. - - `id: Optional[str]` + - `class Scroll: …` - The unique ID of the shell tool call. Populated when this item is returned via API. + A scroll action. - - `agent: Optional[ShellCallAgent]` + - `class Type: …` + + An action to type in text. + + - `class Wait: …` + + A wait action. + + - `agent: Optional[Agent]` The agent that produced this item. @@ -99529,107 +109215,115 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ShellCallCaller]` + - `class BetaResponseComputerToolCallOutputItem: …` - The execution context that produced this tool call. + - `id: str` - - `class ShellCallCallerDirect: …` + The unique ID of the computer call tool output. - - `type: Literal["direct"]` + - `call_id: str` - The caller type. Always `direct`. + The ID of the computer tool call that produced the output. - - `"direct"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `class ShellCallCallerProgram: …` + A computer screenshot image used with the computer use tool. - - `caller_id: str` + - `type: Literal["computer_screenshot"]` - The call ID of the program item that produced this tool call. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `type: Literal["program"]` + - `"computer_screenshot"` - The caller type. Always `program`. + - `file_id: Optional[str]` - - `"program"` + The identifier of an uploaded file that contains the screenshot. - - `environment: Optional[ShellCallEnvironment]` + - `image_url: Optional[str]` - The environment to execute the shell commands in. + The URL of the screenshot image. - - `class BetaLocalEnvironment: …` + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - `class BetaContainerReference: …` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"completed"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"incomplete"` + + - `"failed"` - `"in_progress"` - - `"completed"` + - `type: Literal["computer_call_output"]` - - `"incomplete"` + The type of the computer tool call output. Always `computer_call_output`. - - `class ShellCallOutput: …` + - `"computer_call_output"` - The streamed output items emitted by a shell tool call. + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - - `call_id: str` + The safety checks reported by the API that have been acknowledged by the + developer. - The unique ID of the shell tool call generated by the model. + - `id: str` - - `output: List[BetaResponseFunctionShellCallOutputContent]` + The ID of the pending safety check. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `code: Optional[str]` - - `outcome: Outcome` + The type of the pending safety check. - The exit or timeout outcome associated with this shell call. + - `message: Optional[str]` - - `class OutcomeTimeout: …` + Details about the pending safety check. - Indicates that the shell call exceeded its configured time limit. + - `agent: Optional[Agent]` - - `type: Literal["timeout"]` + The agent that produced this item. - The outcome type. Always `timeout`. + - `agent_name: str` - - `"timeout"` + The canonical name of the agent that produced this item. - - `class OutcomeExit: …` + - `created_by: Optional[str]` - Indicates that the shell commands finished and returned an exit code. + The identifier of the actor that created the item. - - `exit_code: int` + - `class BetaResponseReasoningItem: …` - The exit code returned by the shell process. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `type: Literal["exit"]` + - `id: str` - The outcome type. Always `exit`. + The unique identifier of the reasoning content. - - `"exit"` + - `summary: List[Summary]` - - `stderr: str` + Reasoning summary content. - Captured stderr output for the shell call. + - `text: str` - - `stdout: str` + A summary of the reasoning output from the model so far. - Captured stdout output for the shell call. + - `type: Literal["summary_text"]` - - `type: Literal["shell_call_output"]` + The type of the object. Always `summary_text`. - The type of the item. Always `shell_call_output`. + - `"summary_text"` - - `"shell_call_output"` + - `type: Literal["reasoning"]` - - `id: Optional[str]` + The type of the object. Always `reasoning`. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"reasoning"` - - `agent: Optional[ShellCallOutputAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -99637,37 +109331,29 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ShellCallOutputCaller]` - - The execution context that produced this tool call. - - - `class ShellCallOutputCallerDirect: …` - - - `type: Literal["direct"]` - - The caller type. Always `direct`. - - - `"direct"` + - `content: Optional[List[Content]]` - - `class ShellCallOutputCallerProgram: …` + Reasoning text content. - - `caller_id: str` + - `text: str` - The call ID of the program item that produced this tool call. + The reasoning text from the model. - - `type: Literal["program"]` + - `type: Literal["reasoning_text"]` - The caller type. Always `program`. + The type of the reasoning text. Always `reasoning_text`. - - `"program"` + - `"reasoning_text"` - - `max_output_length: Optional[int]` + - `encrypted_content: Optional[str]` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the shell call output. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -99675,87 +109361,113 @@ print(compacted_response) - `"incomplete"` - - `class ApplyPatchCall: …` + - `class Program: …` - A tool call representing a request to create, delete, or update files using diff patches. + - `id: str` + + The unique ID of the program item. - `call_id: str` - The unique ID of the apply patch tool call generated by the model. + The stable call ID of the program item. - - `operation: ApplyPatchCallOperation` + - `code: str` - The specific create, delete, or update instruction for the apply_patch tool call. + The JavaScript source executed by programmatic tool calling. - - `class ApplyPatchCallOperationCreateFile: …` + - `fingerprint: str` - Instruction for creating a new file via the apply_patch tool. + Opaque program replay fingerprint that must be round-tripped. - - `diff: str` + - `type: Literal["program"]` - Unified diff content to apply when creating the file. + The type of the item. Always `program`. - - `path: str` + - `"program"` - Path of the file to create relative to the workspace root. + - `agent: Optional[ProgramAgent]` - - `type: Literal["create_file"]` + The agent that produced this item. - The operation type. Always `create_file`. + - `agent_name: str` - - `"create_file"` + The canonical name of the agent that produced this item. - - `class ApplyPatchCallOperationDeleteFile: …` + - `class ProgramOutput: …` - Instruction for deleting an existing file via the apply_patch tool. + - `id: str` - - `path: str` + The unique ID of the program output item. - Path of the file to delete relative to the workspace root. + - `call_id: str` - - `type: Literal["delete_file"]` + The call ID of the program item. - The operation type. Always `delete_file`. + - `result: str` - - `"delete_file"` + The result produced by the program item. - - `class ApplyPatchCallOperationUpdateFile: …` + - `status: Literal["completed", "incomplete"]` - Instruction for updating an existing file via the apply_patch tool. + The terminal status of the program output item. - - `diff: str` + - `"completed"` - Unified diff content to apply to the existing file. + - `"incomplete"` - - `path: str` + - `type: Literal["program_output"]` - Path of the file to update relative to the workspace root. + The type of the item. Always `program_output`. - - `type: Literal["update_file"]` + - `"program_output"` - The operation type. Always `update_file`. + - `agent: Optional[ProgramOutputAgent]` - - `"update_file"` + The agent that produced this item. - - `status: Literal["in_progress", "completed"]` + - `agent_name: str` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The canonical name of the agent that produced this item. + + - `class BetaResponseToolSearchCall: …` + + - `id: str` + + The unique ID of the tool search call item. + + - `arguments: object` + + Arguments used for the tool search call. + + - `call_id: Optional[str]` + + The unique ID of the tool search call generated by the model. + + - `execution: Literal["server", "client"]` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the tool search call item that was recorded. - `"in_progress"` - `"completed"` - - `type: Literal["apply_patch_call"]` - - The type of the item. Always `apply_patch_call`. + - `"incomplete"` - - `"apply_patch_call"` + - `type: Literal["tool_search_call"]` - - `id: Optional[str]` + The type of the item. Always `tool_search_call`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"tool_search_call"` - - `agent: Optional[ApplyPatchCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -99763,1237 +109475,1279 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ApplyPatchCallCaller]` + - `created_by: Optional[str]` - The execution context that produced this tool call. + The identifier of the actor that created the item. - - `class ApplyPatchCallCallerDirect: …` + - `class BetaResponseToolSearchOutputItem: …` - - `type: Literal["direct"]` + - `id: str` - The caller type. Always `direct`. + The unique ID of the tool search output item. - - `"direct"` + - `call_id: Optional[str]` - - `class ApplyPatchCallCallerProgram: …` + The unique ID of the tool search call generated by the model. - - `caller_id: str` + - `execution: Literal["server", "client"]` - The call ID of the program item that produced this tool call. + Whether tool search was executed by the server or by the client. - - `type: Literal["program"]` + - `"server"` - The caller type. Always `program`. + - `"client"` - - `"program"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `class ApplyPatchCallOutput: …` + The status of the tool search output item that was recorded. - The streamed output emitted by an apply patch tool call. + - `"in_progress"` - - `call_id: str` + - `"completed"` - The unique ID of the apply patch tool call generated by the model. + - `"incomplete"` - - `status: Literal["completed", "failed"]` + - `tools: List[BetaTool]` - The status of the apply patch tool call output. One of `completed` or `failed`. + The loaded tool definitions returned by tool search. - - `"completed"` + - `class BetaFunctionTool: …` - - `"failed"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `type: Literal["apply_patch_call_output"]` + - `name: str` - The type of the item. Always `apply_patch_call_output`. + The name of the function to call. - - `"apply_patch_call_output"` + - `parameters: Optional[Dict[str, object]]` - - `id: Optional[str]` + A JSON schema object describing the parameters of the function. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `strict: Optional[bool]` - - `agent: Optional[ApplyPatchCallOutputAgent]` + Whether strict parameter validation is enforced for this function tool. - The agent that produced this item. + - `type: Literal["function"]` - - `agent_name: str` + The type of the function tool. Always `function`. - The canonical name of the agent that produced this item. + - `"function"` - - `caller: Optional[ApplyPatchCallOutputCaller]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The execution context that produced this tool call. + The tool invocation context(s). - - `class ApplyPatchCallOutputCallerDirect: …` + - `"direct"` - - `type: Literal["direct"]` + - `"programmatic"` - The caller type. Always `direct`. + - `defer_loading: Optional[bool]` - - `"direct"` + Whether this function is deferred and loaded via tool search. - - `class ApplyPatchCallOutputCallerProgram: …` + - `description: Optional[str]` - - `caller_id: str` + A description of the function. Used by the model to determine whether or not to call the function. - The call ID of the program item that produced this tool call. + - `output_schema: Optional[Dict[str, object]]` - - `type: Literal["program"]` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The caller type. Always `program`. + - `class BetaFileSearchTool: …` - - `"program"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `output: Optional[str]` + - `type: Literal["file_search"]` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The type of the file search tool. Always `file_search`. - - `class McpListTools: …` + - `"file_search"` - A list of tools available on an MCP server. + - `vector_store_ids: List[str]` - - `id: str` + The IDs of the vector stores to search. - The unique ID of the list. + - `filters: Optional[Filters]` - - `server_label: str` + A filter to apply. - The label of the MCP server. + - `class FiltersComparisonFilter: …` - - `tools: List[McpListToolsTool]` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The tools available on the server. + - `key: str` - - `input_schema: object` + The key to compare against the value. - The JSON schema describing the tool's input. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `name: str` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The name of the tool. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `annotations: Optional[object]` + - `"eq"` - Additional annotations about the tool. + - `"ne"` - - `description: Optional[str]` + - `"gt"` - The description of the tool. + - `"gte"` - - `type: Literal["mcp_list_tools"]` + - `"lt"` - The type of the item. Always `mcp_list_tools`. + - `"lte"` - - `"mcp_list_tools"` + - `"in"` - - `agent: Optional[McpListToolsAgent]` + - `"nin"` - The agent that produced this item. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `agent_name: str` + The value to compare against the attribute key; supports string, number, or boolean types. - The canonical name of the agent that produced this item. + - `str` - - `error: Optional[str]` + - `float` - Error message if the server could not list tools. + - `bool` - - `class McpApprovalRequest: …` + - `List[Union[str, float]]` - A request for human approval of a tool invocation. + - `str` - - `id: str` + - `float` - The unique ID of the approval request. + - `class FiltersCompoundFilter: …` - - `arguments: str` + Combine multiple filters using `and` or `or`. - A JSON string of arguments for the tool. + - `filters: List[FiltersCompoundFilterFilter]` - - `name: str` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The name of the tool to run. + - `class FiltersCompoundFilterFilterComparisonFilter: …` - - `server_label: str` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The label of the MCP server making the request. + - `key: str` - - `type: Literal["mcp_approval_request"]` + The key to compare against the value. - The type of the item. Always `mcp_approval_request`. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `"mcp_approval_request"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `agent: Optional[McpApprovalRequestAgent]` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The agent that produced this item. + - `"eq"` - - `agent_name: str` + - `"ne"` - The canonical name of the agent that produced this item. + - `"gt"` - - `class McpApprovalResponse: …` + - `"gte"` - A response to an MCP approval request. + - `"lt"` - - `approval_request_id: str` + - `"lte"` - The ID of the approval request being answered. + - `"in"` - - `approve: bool` + - `"nin"` - Whether the request was approved. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `type: Literal["mcp_approval_response"]` + The value to compare against the attribute key; supports string, number, or boolean types. - The type of the item. Always `mcp_approval_response`. + - `str` - - `"mcp_approval_response"` + - `float` - - `id: Optional[str]` + - `bool` - The unique ID of the approval response + - `List[Union[str, float]]` - - `agent: Optional[McpApprovalResponseAgent]` + - `str` - The agent that produced this item. + - `float` - - `agent_name: str` + - `object` - The canonical name of the agent that produced this item. + - `type: Literal["and", "or"]` - - `reason: Optional[str]` + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: Optional[int]` - Optional reason for the decision. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `class McpCall: …` + - `ranking_options: Optional[RankingOptions]` - An invocation of a tool on an MCP server. + Ranking options for search. - - `id: str` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - The unique ID of the tool call. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `arguments: str` + - `embedding_weight: float` - A JSON string of the arguments passed to the tool. + The weight of the embedding in the reciprocal ranking fusion. - - `name: str` + - `text_weight: float` - The name of the tool that was run. + The weight of the text in the reciprocal ranking fusion. - - `server_label: str` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - The label of the MCP server running the tool. + The ranker to use for the file search. - - `type: Literal["mcp_call"]` + - `"auto"` - The type of the item. Always `mcp_call`. + - `"default-2024-11-15"` - - `"mcp_call"` + - `score_threshold: Optional[float]` - - `agent: Optional[McpCallAgent]` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The agent that produced this item. + - `class BetaComputerTool: …` - - `agent_name: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The canonical name of the agent that produced this item. + - `type: Literal["computer"]` - - `approval_request_id: Optional[str]` + The type of the computer tool. Always `computer`. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `"computer"` - - `error: Optional[str]` + - `class BetaComputerUsePreviewTool: …` - The error from the tool call, if any. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `output: Optional[str]` + - `display_height: int` - The output from the tool call. + The height of the computer display. - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `display_width: int` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The width of the computer display. - - `"in_progress"` + - `environment: Literal["windows", "mac", "linux", 2 more]` - - `"completed"` + The type of computer environment to control. - - `"incomplete"` + - `"windows"` - - `"calling"` + - `"mac"` - - `"failed"` + - `"linux"` - - `class BetaResponseCustomToolCallOutput: …` + - `"ubuntu"` - The output of a custom tool call from your code, being sent back to the model. + - `"browser"` - - `call_id: str` + - `type: Literal["computer_use_preview"]` - The call ID, used to map this custom tool call output to a custom tool call. + The type of the computer use tool. Always `computer_use_preview`. - - `output: Union[str, List[OutputOutputContentList]]` + - `"computer_use_preview"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `class BetaWebSearchTool: …` - - `str` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - A string of the output of the custom tool call. + - `type: Literal["web_search", "web_search_2025_08_26"]` - - `List[OutputOutputContentList]` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - Text, image, or file output of the custom tool call. + - `"web_search"` - - `class BetaResponseInputText: …` + - `"web_search_2025_08_26"` - A text input to the model. + - `filters: Optional[Filters]` - - `class BetaResponseInputImage: …` + Filters for the search. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `allowed_domains: Optional[List[str]]` - - `class BetaResponseInputFile: …` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - A file input to the model. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `type: Literal["custom_tool_call_output"]` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The type of the custom tool call output. Always `custom_tool_call_output`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `"custom_tool_call_output"` + - `"low"` - - `id: Optional[str]` + - `"medium"` - The unique ID of the custom tool call output in the OpenAI platform. + - `"high"` - - `agent: Optional[Agent]` + - `user_location: Optional[UserLocation]` - The agent that produced this item. + The approximate location of the user. - - `agent_name: str` + - `city: Optional[str]` - The canonical name of the agent that produced this item. + Free text input for the city of the user, e.g. `San Francisco`. - - `caller: Optional[Caller]` + - `country: Optional[str]` - The execution context that produced this tool call. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `class CallerDirect: …` + - `region: Optional[str]` - - `type: Literal["direct"]` + Free text input for the region of the user, e.g. `California`. - The caller type. Always `direct`. + - `timezone: Optional[str]` - - `"direct"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `class CallerProgram: …` + - `type: Optional[Literal["approximate"]]` - - `caller_id: str` + The type of location approximation. Always `approximate`. - The call ID of the program item that produced this tool call. + - `"approximate"` - - `type: Literal["program"]` + - `class Mcp: …` - The caller type. Always `program`. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"program"` + - `server_label: str` - - `class BetaResponseCustomToolCall: …` + A label for this MCP server, used to identify it in tool calls. - A call to a custom tool created by the model. + - `type: Literal["mcp"]` - - `call_id: str` + The type of the MCP tool. Always `mcp`. - An identifier used to map this custom tool call to a tool call output. + - `"mcp"` - - `input: str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The input for the custom tool call generated by the model. + The tool invocation context(s). - - `name: str` + - `"direct"` - The name of the custom tool being called. + - `"programmatic"` - - `type: Literal["custom_tool_call"]` + - `allowed_tools: Optional[McpAllowedTools]` - The type of the custom tool call. Always `custom_tool_call`. + List of allowed tool names or a filter object. - - `"custom_tool_call"` + - `List[str]` - - `id: Optional[str]` + A string array of allowed tool names - The unique ID of the custom tool call in the OpenAI platform. + - `class McpAllowedToolsMcpToolFilter: …` - - `agent: Optional[Agent]` + A filter object to specify which tools are allowed. - The agent that produced this item. + - `read_only: Optional[bool]` - - `agent_name: str` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The canonical name of the agent that produced this item. + - `tool_names: Optional[List[str]]` - - `caller: Optional[Caller]` + List of allowed tool names. - The execution context that produced this tool call. + - `authorization: Optional[str]` - - `class CallerDirect: …` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `type: Literal["direct"]` + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `"direct"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `class CallerProgram: …` + Currently supported `connector_id` values are: - - `caller_id: str` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The call ID of the program item that produced this tool call. + - `"connector_dropbox"` - - `type: Literal["program"]` + - `"connector_gmail"` - - `"program"` + - `"connector_googlecalendar"` - - `namespace: Optional[str]` + - `"connector_googledrive"` - The namespace of the custom tool being called. + - `"connector_microsoftteams"` - - `class CompactionTrigger: …` + - `"connector_outlookcalendar"` - Compacts the current context. Must be the final input item. + - `"connector_outlookemail"` - - `type: Literal["compaction_trigger"]` + - `"connector_sharepoint"` - The type of the item. Always `compaction_trigger`. + - `defer_loading: Optional[bool]` - - `"compaction_trigger"` + Whether this MCP tool is deferred and discovered via tool search. - - `agent: Optional[CompactionTriggerAgent]` + - `headers: Optional[Dict[str, str]]` - The agent that produced this item. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `agent_name: str` + - `require_approval: Optional[McpRequireApproval]` - The canonical name of the agent that produced this item. + Specify which of the MCP server's tools require approval. - - `class ItemReference: …` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - An internal identifier for an item to reference. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `id: str` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - The ID of the item to reference. + A filter object to specify which tools are allowed. - - `agent: Optional[ItemReferenceAgent]` + - `read_only: Optional[bool]` - The agent that produced this item. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `agent_name: str` + - `tool_names: Optional[List[str]]` - The canonical name of the agent that produced this item. + List of allowed tool names. - - `type: Optional[Literal["item_reference"]]` + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - The type of item to reference. Always `item_reference`. + A filter object to specify which tools are allowed. - - `"item_reference"` + - `read_only: Optional[bool]` - - `class Program: …` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `id: str` + - `tool_names: Optional[List[str]]` - The unique ID of this program item. + List of allowed tool names. - - `call_id: str` + - `Literal["always", "never"]` - The stable call ID of the program item. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `code: str` + - `"always"` - The JavaScript source executed by programmatic tool calling. + - `"never"` - - `fingerprint: str` + - `server_description: Optional[str]` - Opaque program replay fingerprint that must be round-tripped. + Optional description of the MCP server, used to provide more context. - - `type: Literal["program"]` + - `server_url: Optional[str]` - The item type. Always `program`. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"program"` + - `tunnel_id: Optional[str]` - - `agent: Optional[ProgramAgent]` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The agent that produced this item. + - `class CodeInterpreter: …` - - `agent_name: str` + A tool that runs Python code to help generate a response to a prompt. - The canonical name of the agent that produced this item. + - `container: CodeInterpreterContainer` - - `class ProgramOutput: …` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `id: str` + - `str` - The unique ID of this program output item. + The container ID. - - `call_id: str` + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - The call ID of the program item. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `result: str` + - `type: Literal["auto"]` - The result produced by the program item. + Always `auto`. - - `status: Literal["completed", "incomplete"]` + - `"auto"` - The terminal status of the program output. + - `file_ids: Optional[List[str]]` - - `"completed"` + An optional list of uploaded files to make available to your code. - - `"incomplete"` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `type: Literal["program_output"]` + The memory limit for the code interpreter container. - The item type. Always `program_output`. + - `"1g"` - - `"program_output"` + - `"4g"` - - `agent: Optional[ProgramOutputAgent]` + - `"16g"` - The agent that produced this item. + - `"64g"` - - `agent_name: str` + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - The canonical name of the agent that produced this item. + Network access policy for the container. -### Beta Response Input Audio + - `class BetaContainerNetworkPolicyDisabled: …` -- `class BetaResponseInputAudio: …` + - `type: Literal["disabled"]` - An audio input to the model. + Disable outbound network access. Always `disabled`. - - `input_audio: InputAudio` + - `"disabled"` - - `data: str` + - `class BetaContainerNetworkPolicyAllowlist: …` - Base64-encoded audio data. + - `allowed_domains: List[str]` - - `format: Literal["mp3", "wav"]` + A list of allowed domains when type is `allowlist`. - The format of the audio data. Currently supported formats are `mp3` and - `wav`. + - `type: Literal["allowlist"]` - - `"mp3"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"wav"` + - `"allowlist"` - - `type: Literal["input_audio"]` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - The type of the input item. Always `input_audio`. + Optional domain-scoped secrets for allowlisted domains. - - `"input_audio"` + - `domain: str` -### Beta Response Input Content + The domain associated with the secret. -- `BetaResponseInputContent` + - `name: str` - A text input to the model. + The name of the secret to inject for the domain. - - `class BetaResponseInputText: …` + - `value: str` - A text input to the model. + The secret value to inject for the domain. - - `text: str` + - `type: Literal["code_interpreter"]` - The text input to the model. + The type of the code interpreter tool. Always `code_interpreter`. - - `type: Literal["input_text"]` + - `"code_interpreter"` - The type of the input item. Always `input_text`. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"input_text"` + The tool invocation context(s). - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"direct"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"programmatic"` - - `mode: Literal["explicit"]` + - `class ProgrammaticToolCalling: …` - The breakpoint mode. Always `explicit`. + - `type: Literal["programmatic_tool_calling"]` - - `"explicit"` + The type of the tool. Always `programmatic_tool_calling`. - - `class BetaResponseInputImage: …` + - `"programmatic_tool_calling"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class ImageGeneration: …` - - `detail: Literal["low", "high", "auto", "original"]` + A tool that generates images using the GPT image models. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: Literal["image_generation"]` - - `"low"` + The type of the image generation tool. Always `image_generation`. - - `"high"` + - `"image_generation"` - - `"auto"` + - `action: Optional[Literal["generate", "edit", "auto"]]` - - `"original"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `type: Literal["input_image"]` + - `"generate"` - The type of the input item. Always `input_image`. + - `"edit"` - - `"input_image"` + - `"auto"` - - `file_id: Optional[str]` + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - The ID of the file to be sent to the model. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `image_url: Optional[str]` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"transparent"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"opaque"` - - `mode: Literal["explicit"]` + - `"auto"` - The breakpoint mode. Always `explicit`. + - `input_fidelity: Optional[Literal["high", "low"]]` - - `"explicit"` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `class BetaResponseInputFile: …` + - `"high"` - A file input to the model. + - `"low"` - - `type: Literal["input_file"]` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - The type of the input item. Always `input_file`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"input_file"` + - `file_id: Optional[str]` - - `detail: Optional[Literal["auto", "low", "high"]]` + File ID for the mask image. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `image_url: Optional[str]` - - `"auto"` + Base64-encoded mask image. - - `"low"` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - - `"high"` + The image generation model to use. Default: `gpt-image-1`. - - `file_data: Optional[str]` + - `str` - The content of the file to be sent to the model. + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `file_id: Optional[str]` + The image generation model to use. Default: `gpt-image-1`. - The ID of the file to be sent to the model. + - `"gpt-image-1"` - - `file_url: Optional[str]` + - `"gpt-image-1-mini"` - The URL of the file to be sent to the model. + - `"gpt-image-2"` - - `filename: Optional[str]` + - `"gpt-image-2-2026-04-21"` - The name of the file to be sent to the model. + - `"gpt-image-1.5"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"chatgpt-image-latest"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `moderation: Optional[Literal["auto", "low"]]` - - `mode: Literal["explicit"]` + Moderation level for the generated image. Default: `auto`. - The breakpoint mode. Always `explicit`. + - `"auto"` - - `"explicit"` + - `"low"` -### Beta Response Input File + - `output_compression: Optional[int]` -- `class BetaResponseInputFile: …` + Compression level for the output image. Default: 100. - A file input to the model. + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `type: Literal["input_file"]` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The type of the input item. Always `input_file`. + - `"png"` - - `"input_file"` + - `"webp"` - - `detail: Optional[Literal["auto", "low", "high"]]` + - `"jpeg"` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `partial_images: Optional[int]` - - `"auto"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"low"` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - - `"high"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `file_data: Optional[str]` + - `"low"` - The content of the file to be sent to the model. + - `"medium"` - - `file_id: Optional[str]` + - `"high"` - The ID of the file to be sent to the model. + - `"auto"` - - `file_url: Optional[str]` + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - The URL of the file to be sent to the model. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `filename: Optional[str]` + - `str` - The name of the file to be sent to the model. + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"1024x1024"` - - `mode: Literal["explicit"]` + - `"1024x1536"` - The breakpoint mode. Always `explicit`. + - `"1536x1024"` - - `"explicit"` + - `"auto"` -### Beta Response Input File Content + - `class LocalShell: …` -- `class BetaResponseInputFileContent: …` + A tool that allows the model to execute shell commands in a local environment. - A file input to the model. + - `type: Literal["local_shell"]` - - `type: Literal["input_file"]` + The type of the local shell tool. Always `local_shell`. - The type of the input item. Always `input_file`. + - `"local_shell"` - - `"input_file"` + - `class BetaFunctionShellTool: …` - - `detail: Optional[Literal["auto", "low", "high"]]` + A tool that allows the model to execute shell commands. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `type: Literal["shell"]` - - `"auto"` + The type of the shell tool. Always `shell`. - - `"low"` + - `"shell"` - - `"high"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `file_data: Optional[str]` + The tool invocation context(s). - The base64-encoded data of the file to be sent to the model. + - `"direct"` - - `file_id: Optional[str]` + - `"programmatic"` - The ID of the file to be sent to the model. + - `environment: Optional[Environment]` - - `file_url: Optional[str]` + - `class BetaContainerAuto: …` - The URL of the file to be sent to the model. + - `type: Literal["container_auto"]` - - `filename: Optional[str]` + Automatically creates a container for this request - The name of the file to be sent to the model. + - `"container_auto"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `file_ids: Optional[List[str]]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + An optional list of uploaded files to make available to your code. - - `mode: Literal["explicit"]` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The breakpoint mode. Always `explicit`. + The memory limit for the container. - - `"explicit"` + - `"1g"` -### Beta Response Input Image + - `"4g"` -- `class BetaResponseInputImage: …` + - `"16g"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"64g"` - - `detail: Literal["low", "high", "auto", "original"]` + - `network_policy: Optional[NetworkPolicy]` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Network access policy for the container. - - `"low"` + - `class BetaContainerNetworkPolicyDisabled: …` - - `"high"` + - `class BetaContainerNetworkPolicyAllowlist: …` - - `"auto"` + - `skills: Optional[List[Skill]]` - - `"original"` + An optional list of skills referenced by id or inline data. - - `type: Literal["input_image"]` + - `class BetaSkillReference: …` - The type of the input item. Always `input_image`. + - `skill_id: str` - - `"input_image"` + The ID of the referenced skill. - - `file_id: Optional[str]` + - `type: Literal["skill_reference"]` - The ID of the file to be sent to the model. + References a skill created with the /v1/skills endpoint. - - `image_url: Optional[str]` + - `"skill_reference"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `version: Optional[str]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class BetaInlineSkill: …` - - `mode: Literal["explicit"]` + - `description: str` - The breakpoint mode. Always `explicit`. + The description of the skill. - - `"explicit"` + - `name: str` -### Beta Response Input Image Content + The name of the skill. -- `class BetaResponseInputImageContent: …` + - `source: BetaInlineSkillSource` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + Inline skill payload - - `type: Literal["input_image"]` + - `data: str` - The type of the input item. Always `input_image`. + Base64-encoded skill zip bundle. - - `"input_image"` + - `media_type: Literal["application/zip"]` - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + The media type of the inline skill payload. Must be `application/zip`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"application/zip"` - - `"low"` + - `type: Literal["base64"]` - - `"high"` + The type of the inline skill source. Must be `base64`. - - `"auto"` + - `"base64"` - - `"original"` + - `type: Literal["inline"]` - - `file_id: Optional[str]` + Defines an inline skill for this request. - The ID of the file to be sent to the model. + - `"inline"` - - `image_url: Optional[str]` + - `class BetaLocalEnvironment: …` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: Literal["local"]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + Use a local computer environment. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"local"` - - `mode: Literal["explicit"]` + - `skills: Optional[List[BetaLocalSkill]]` - The breakpoint mode. Always `explicit`. + An optional list of skills. - - `"explicit"` + - `description: str` -### Beta Response Input Item + The description of the skill. -- `BetaResponseInputItem` + - `name: str` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The name of the skill. - - `class BetaEasyInputMessage: …` + - `path: str` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The path to the directory containing the skill. - - `content: Union[str, BetaResponseInputMessageContentList]` + - `class BetaContainerReference: …` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `container_id: str` - - `str` + The ID of the referenced container. - A text input to the model. + - `type: Literal["container_reference"]` - - `List[BetaResponseInputContent]` + References a container created with the /v1/containers endpoint - - `class BetaResponseInputText: …` + - `"container_reference"` - A text input to the model. + - `class BetaCustomTool: …` - - `text: str` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The text input to the model. + - `name: str` - - `type: Literal["input_text"]` + The name of the custom tool, used to identify it in tool calls. - The type of the input item. Always `input_text`. + - `type: Literal["custom"]` - - `"input_text"` + The type of the custom tool. Always `custom`. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"custom"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `mode: Literal["explicit"]` + The tool invocation context(s). - The breakpoint mode. Always `explicit`. + - `"direct"` - - `"explicit"` + - `"programmatic"` - - `class BetaResponseInputImage: …` + - `defer_loading: Optional[bool]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Whether this tool should be deferred and discovered via tool search. - - `detail: Literal["low", "high", "auto", "original"]` + - `description: Optional[str]` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Optional description of the custom tool, used to provide more context. - - `"low"` + - `format: Optional[Format]` - - `"high"` + The input format for the custom tool. Default is unconstrained text. - - `"auto"` + - `class FormatText: …` - - `"original"` + Unconstrained free-form text. - - `type: Literal["input_image"]` + - `type: Literal["text"]` - The type of the input item. Always `input_image`. + Unconstrained text format. Always `text`. - - `"input_image"` + - `"text"` - - `file_id: Optional[str]` + - `class FormatGrammar: …` - The ID of the file to be sent to the model. + A grammar defined by the user. - - `image_url: Optional[str]` + - `definition: str` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The grammar definition. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `syntax: Literal["lark", "regex"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The syntax of the grammar definition. One of `lark` or `regex`. - - `mode: Literal["explicit"]` + - `"lark"` - The breakpoint mode. Always `explicit`. + - `"regex"` - - `"explicit"` + - `type: Literal["grammar"]` - - `class BetaResponseInputFile: …` + Grammar format. Always `grammar`. - A file input to the model. + - `"grammar"` - - `type: Literal["input_file"]` + - `class BetaNamespaceTool: …` - The type of the input item. Always `input_file`. + Groups function/custom tools under a shared namespace. - - `"input_file"` + - `description: str` - - `detail: Optional[Literal["auto", "low", "high"]]` + A description of the namespace shown to the model. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `name: str` - - `"auto"` + The namespace name used in tool calls (for example, `crm`). - - `"low"` + - `tools: List[Tool]` - - `"high"` + The function/custom tools available inside this namespace. - - `file_data: Optional[str]` + - `class ToolFunction: …` - The content of the file to be sent to the model. + - `name: str` - - `file_id: Optional[str]` + - `type: Literal["function"]` - The ID of the file to be sent to the model. + - `"function"` - - `file_url: Optional[str]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The URL of the file to be sent to the model. + The tool invocation context(s). - - `filename: Optional[str]` + - `"direct"` - The name of the file to be sent to the model. + - `"programmatic"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `defer_loading: Optional[bool]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Whether this function should be deferred and discovered via tool search. - - `mode: Literal["explicit"]` + - `description: Optional[str]` - The breakpoint mode. Always `explicit`. + - `output_schema: Optional[Dict[str, object]]` - - `"explicit"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `role: Literal["user", "assistant", "system", "developer"]` + - `parameters: Optional[object]` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `strict: Optional[bool]` - - `"user"` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `"assistant"` + - `class BetaCustomTool: …` - - `"system"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `"developer"` + - `type: Literal["namespace"]` - - `phase: Optional[Literal["commentary"]]` + The type of the tool. Always `namespace`. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `"namespace"` - - `"commentary"` + - `class BetaToolSearchTool: …` - - `type: Optional[Literal["message"]]` + Hosted or BYOT tool search configuration for deferred tools. - The type of the message input. Always `message`. + - `type: Literal["tool_search"]` - - `"message"` + The type of the tool. Always `tool_search`. - - `class Message: …` + - `"tool_search"` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + - `description: Optional[str]` - - `content: BetaResponseInputMessageContentList` + Description shown to the model for a client-executed tool search tool. - A list of one or many input items to the model, containing different content - types. + - `execution: Optional[Literal["server", "client"]]` - - `class BetaResponseInputText: …` + Whether tool search is executed by the server or by the client. - A text input to the model. + - `"server"` - - `class BetaResponseInputImage: …` + - `"client"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `parameters: Optional[object]` - - `class BetaResponseInputFile: …` + Parameter schema for a client-executed tool search tool. - A file input to the model. + - `class BetaWebSearchPreviewTool: …` - - `role: Literal["user", "system", "developer"]` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The role of the message input. One of `user`, `system`, or `developer`. + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - - `"user"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"system"` + - `"web_search_preview"` - - `"developer"` + - `"web_search_preview_2025_03_11"` - - `agent: Optional[MessageAgent]` + - `search_content_types: Optional[List[Literal["text", "image"]]]` - The agent that produced this item. + - `"text"` - - `agent_name: str` + - `"image"` - The canonical name of the agent that produced this item. + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"low"` - - `"in_progress"` + - `"medium"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `user_location: Optional[UserLocation]` - - `type: Optional[Literal["message"]]` + The user's location. - The type of the message input. Always set to `message`. + - `type: Literal["approximate"]` - - `"message"` + The type of location approximation. Always `approximate`. - - `class BetaResponseOutputMessage: …` + - `"approximate"` - An output message from the model. + - `city: Optional[str]` - - `id: str` + Free text input for the city of the user, e.g. `San Francisco`. - The unique ID of the output message. + - `country: Optional[str]` - - `content: List[Content]` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The content of the output message. + - `region: Optional[str]` - - `class BetaResponseOutputText: …` + Free text input for the region of the user, e.g. `California`. - A text output from the model. + - `timezone: Optional[str]` - - `annotations: List[Annotation]` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The annotations of the text output. + - `class BetaApplyPatchTool: …` - - `class AnnotationFileCitation: …` + Allows the assistant to create, delete, or update files using unified diffs. - A citation to a file. + - `type: Literal["apply_patch"]` - - `file_id: str` + The type of the tool. Always `apply_patch`. - The ID of the file. + - `"apply_patch"` - - `filename: str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The filename of the file cited. + The tool invocation context(s). - - `index: int` + - `"direct"` - The index of the file in the list of files. + - `"programmatic"` - - `type: Literal["file_citation"]` + - `type: Literal["tool_search_output"]` - The type of the file citation. Always `file_citation`. + The type of the item. Always `tool_search_output`. - - `"file_citation"` + - `"tool_search_output"` - - `class AnnotationURLCitation: …` + - `agent: Optional[Agent]` - A citation for a web resource used to generate a model response. + The agent that produced this item. - - `end_index: int` + - `agent_name: str` - The index of the last character of the URL citation in the message. + The canonical name of the agent that produced this item. - - `start_index: int` + - `created_by: Optional[str]` - The index of the first character of the URL citation in the message. + The identifier of the actor that created the item. - - `title: str` + - `class AdditionalTools: …` - The title of the web resource. + - `id: str` - - `type: Literal["url_citation"]` + The unique ID of the additional tools item. - The type of the URL citation. Always `url_citation`. + - `role: Literal["unknown", "user", "assistant", 5 more]` - - `"url_citation"` + The role that provided the additional tools. - - `url: str` + - `"unknown"` - The URL of the web resource. + - `"user"` - - `class AnnotationContainerFileCitation: …` + - `"assistant"` - A citation for a container file used to generate a model response. + - `"system"` - - `container_id: str` + - `"critic"` - The ID of the container file. + - `"discriminator"` - - `end_index: int` + - `"developer"` - The index of the last character of the container file citation in the message. + - `"tool"` - - `file_id: str` + - `tools: List[BetaTool]` - The ID of the file. + The additional tool definitions made available at this item. - - `filename: str` + - `class BetaFunctionTool: …` - The filename of the container file cited. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `start_index: int` + - `class BetaFileSearchTool: …` - The index of the first character of the container file citation in the message. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: Literal["container_file_citation"]` + - `class BetaComputerTool: …` - The type of the container file citation. Always `container_file_citation`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"container_file_citation"` + - `class BetaComputerUsePreviewTool: …` - - `class AnnotationFilePath: …` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A path to a file. + - `class BetaWebSearchTool: …` - - `file_id: str` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The ID of the file. + - `class Mcp: …` - - `index: int` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The index of the file in the list of files. + - `class CodeInterpreter: …` - - `type: Literal["file_path"]` + A tool that runs Python code to help generate a response to a prompt. - The type of the file path. Always `file_path`. + - `class ProgrammaticToolCalling: …` - - `"file_path"` + - `class ImageGeneration: …` - - `text: str` + A tool that generates images using the GPT image models. - The text output from the model. + - `class LocalShell: …` - - `type: Literal["output_text"]` + A tool that allows the model to execute shell commands in a local environment. - The type of the output text. Always `output_text`. + - `class BetaFunctionShellTool: …` - - `"output_text"` + A tool that allows the model to execute shell commands. - - `logprobs: Optional[List[Logprob]]` + - `class BetaCustomTool: …` - - `token: str` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `bytes: List[int]` + - `class BetaNamespaceTool: …` - - `logprob: float` + Groups function/custom tools under a shared namespace. - - `top_logprobs: List[LogprobTopLogprob]` + - `class BetaToolSearchTool: …` - - `token: str` + Hosted or BYOT tool search configuration for deferred tools. - - `bytes: List[int]` + - `class BetaWebSearchPreviewTool: …` - - `logprob: float` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class BetaResponseOutputRefusal: …` + - `class BetaApplyPatchTool: …` - A refusal from the model. + Allows the assistant to create, delete, or update files using unified diffs. - - `refusal: str` + - `type: Literal["additional_tools"]` - The refusal explanation from the model. + The type of the item. Always `additional_tools`. - - `type: Literal["refusal"]` + - `"additional_tools"` - The type of the refusal. Always `refusal`. + - `agent: Optional[AdditionalToolsAgent]` - - `"refusal"` + The agent that produced this item. - - `role: Literal["assistant"]` + - `agent_name: str` - The role of the output message. Always `assistant`. + The canonical name of the agent that produced this item. - - `"assistant"` + - `class BetaResponseCompactionItem: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `id: str` - - `"in_progress"` + The unique ID of the compaction item. - - `"completed"` + - `encrypted_content: str` - - `"incomplete"` + The encrypted content that was produced by compaction. - - `type: Literal["message"]` + - `type: Literal["compaction"]` - The type of the output message. Always `message`. + The type of the item. Always `compaction`. - - `"message"` + - `"compaction"` - `agent: Optional[Agent]` @@ -101003,49 +110757,41 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `phase: Optional[Literal["commentary"]]` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `created_by: Optional[str]` - - `"commentary"` + The identifier of the actor that created the item. - - `class BetaResponseFileSearchToolCall: …` + - `class ImageGenerationCall: …` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + An image generation request made by the model. - `id: str` - The unique ID of the file search tool call. + The unique ID of the image generation call. - - `queries: List[str]` + - `result: Optional[str]` - The queries used to search for files. + The generated image encoded in base64. - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The status of the image generation call. - `"in_progress"` - - `"searching"` - - `"completed"` - - `"incomplete"` + - `"generating"` - `"failed"` - - `type: Literal["file_search_call"]` + - `type: Literal["image_generation_call"]` - The type of the file search tool call. Always `file_search_call`. + The type of the image generation call. Always `image_generation_call`. - - `"file_search_call"` + - `"image_generation_call"` - - `agent: Optional[Agent]` + - `agent: Optional[ImageGenerationCallAgent]` The agent that produced this item. @@ -101053,73 +110799,58 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `results: Optional[List[Result]]` - - The results of the file search tool call. - - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - - 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, booleans, or numbers. - - - `str` - - - `float` + - `class BetaResponseCodeInterpreterToolCall: …` - - `bool` + A tool call to run code. - - `file_id: Optional[str]` + - `id: str` - The unique ID of the file. + The unique ID of the code interpreter tool call. - - `filename: Optional[str]` + - `code: Optional[str]` - The name of the file. + The code to run, or null if not available. - - `score: Optional[float]` + - `container_id: str` - The relevance score of the file - a value between 0 and 1. + The ID of the container used to run the code. - - `text: Optional[str]` + - `outputs: Optional[List[Output]]` - The text that was retrieved from the file. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `class BetaResponseComputerToolCall: …` + - `class OutputLogs: …` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The logs output from the code interpreter. - - `id: str` + - `logs: str` - The unique ID of the computer call. + The logs output from the code interpreter. - - `call_id: str` + - `type: Literal["logs"]` - An identifier used when responding to the tool call with output. + The type of the output. Always `logs`. - - `pending_safety_checks: List[PendingSafetyCheck]` + - `"logs"` - The pending safety checks for the computer call. + - `class OutputImage: …` - - `id: str` + The image output from the code interpreter. - The ID of the pending safety check. + - `type: Literal["image"]` - - `code: Optional[str]` + The type of the output. Always `image`. - The type of the pending safety check. + - `"image"` - - `message: Optional[str]` + - `url: str` - Details about the pending safety check. + The URL of the image output from the code interpreter. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `"in_progress"` @@ -101127,310 +110858,303 @@ print(compacted_response) - `"incomplete"` - - `type: Literal["computer_call"]` + - `"interpreting"` - The type of the computer call. Always `computer_call`. + - `"failed"` - - `"computer_call"` + - `type: Literal["code_interpreter_call"]` - - `action: Optional[BetaComputerAction]` + The type of the code interpreter tool call. Always `code_interpreter_call`. - A click action. + - `"code_interpreter_call"` - - `class Click: …` + - `agent: Optional[Agent]` - A click action. + The agent that produced this item. - - `button: Literal["left", "right", "wheel", 2 more]` + - `agent_name: str` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The canonical name of the agent that produced this item. - - `"left"` + - `class LocalShellCall: …` - - `"right"` + A tool call to run a command on the local shell. - - `"wheel"` + - `id: str` - - `"back"` + The unique ID of the local shell call. - - `"forward"` + - `action: LocalShellCallAction` - - `type: Literal["click"]` + Execute a shell command on the server. - Specifies the event type. For a click action, this property is always `click`. + - `command: List[str]` - - `"click"` + The command to run. - - `x: int` + - `env: Dict[str, str]` - The x-coordinate where the click occurred. + Environment variables to set for the command. - - `y: int` + - `type: Literal["exec"]` - The y-coordinate where the click occurred. + The type of the local shell action. Always `exec`. - - `keys: Optional[List[str]]` + - `"exec"` - The keys being held while clicking. + - `timeout_ms: Optional[int]` - - `class DoubleClick: …` + Optional timeout in milliseconds for the command. - A double click action. + - `user: Optional[str]` - - `keys: Optional[List[str]]` + Optional user to run the command as. - The keys being held while double-clicking. + - `working_directory: Optional[str]` - - `type: Literal["double_click"]` + Optional working directory to run the command in. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `call_id: str` - - `"double_click"` + The unique ID of the local shell tool call generated by the model. - - `x: int` + - `status: Literal["in_progress", "completed", "incomplete"]` - The x-coordinate where the double click occurred. + The status of the local shell call. - - `y: int` + - `"in_progress"` - The y-coordinate where the double click occurred. + - `"completed"` - - `class Drag: …` + - `"incomplete"` - A drag action. + - `type: Literal["local_shell_call"]` - - `path: List[DragPath]` + The type of the local shell call. Always `local_shell_call`. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"local_shell_call"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `agent: Optional[LocalShellCallAgent]` - - `x: int` + The agent that produced this item. - The x-coordinate. + - `agent_name: str` - - `y: int` + The canonical name of the agent that produced this item. - The y-coordinate. + - `class LocalShellCallOutput: …` - - `type: Literal["drag"]` + The output of a local shell tool call. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `id: str` - - `"drag"` + The unique ID of the local shell tool call generated by the model. - - `keys: Optional[List[str]]` + - `output: str` - The keys being held while dragging the mouse. + A JSON string of the output of the local shell tool call. - - `class Keypress: …` + - `type: Literal["local_shell_call_output"]` - A collection of keypresses the model would like to perform. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `keys: List[str]` + - `"local_shell_call_output"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `agent: Optional[LocalShellCallOutputAgent]` - - `type: Literal["keypress"]` + The agent that produced this item. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `agent_name: str` - - `"keypress"` + The canonical name of the agent that produced this item. - - `class Move: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A mouse move action. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `type: Literal["move"]` + - `"in_progress"` - Specifies the event type. For a move action, this property is always set to `move`. + - `"completed"` - - `"move"` + - `"incomplete"` - - `x: int` + - `class BetaResponseFunctionShellToolCall: …` - The x-coordinate to move to. + A tool call that executes one or more shell commands in a managed environment. - - `y: int` + - `id: str` - The y-coordinate to move to. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `keys: Optional[List[str]]` + - `action: Action` - The keys being held while moving the mouse. + The shell commands and limits that describe how to run the tool call. - - `class Screenshot: …` + - `commands: List[str]` - A screenshot action. + - `max_output_length: Optional[int]` - - `type: Literal["screenshot"]` + Optional maximum number of characters to return from each command. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `timeout_ms: Optional[int]` - - `"screenshot"` + Optional timeout in milliseconds for the commands. - - `class Scroll: …` + - `call_id: str` - A scroll action. + The unique ID of the shell tool call generated by the model. - - `scroll_x: int` + - `environment: Optional[Environment]` - The horizontal scroll distance. + Represents the use of a local environment to perform shell actions. - - `scroll_y: int` + - `class BetaResponseLocalEnvironment: …` - The vertical scroll distance. + Represents the use of a local environment to perform shell actions. - - `type: Literal["scroll"]` + - `type: Literal["local"]` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The environment type. Always `local`. - - `"scroll"` + - `"local"` - - `x: int` + - `class BetaResponseContainerReference: …` - The x-coordinate where the scroll occurred. + Represents a container created with /v1/containers. - - `y: int` + - `container_id: str` - The y-coordinate where the scroll occurred. + - `type: Literal["container_reference"]` - - `keys: Optional[List[str]]` + The environment type. Always `container_reference`. - The keys being held while scrolling. + - `"container_reference"` - - `class Type: …` + - `status: Literal["in_progress", "completed", "incomplete"]` - An action to type in text. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `text: str` + - `"in_progress"` - The text to type. + - `"completed"` - - `type: Literal["type"]` + - `"incomplete"` - Specifies the event type. For a type action, this property is always set to `type`. + - `type: Literal["shell_call"]` - - `"type"` + The type of the item. Always `shell_call`. - - `class Wait: …` + - `"shell_call"` - A wait action. + - `agent: Optional[Agent]` - - `type: Literal["wait"]` + The agent that produced this item. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `agent_name: str` - - `"wait"` + The canonical name of the agent that produced this item. - - `actions: Optional[BetaComputerActionList]` + - `caller: Optional[Caller]` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The execution context that produced this tool call. - - `class Click: …` + - `class CallerDirect: …` - A click action. + - `type: Literal["direct"]` - - `class DoubleClick: …` + - `"direct"` - A double click action. + - `class CallerProgram: …` - - `class Drag: …` + - `caller_id: str` - A drag action. + The call ID of the program item that produced this tool call. - - `class Keypress: …` + - `type: Literal["program"]` - A collection of keypresses the model would like to perform. + - `"program"` - - `class Move: …` + - `created_by: Optional[str]` - A mouse move action. + The ID of the entity that created this tool call. - - `class Screenshot: …` + - `class BetaResponseFunctionShellToolCallOutput: …` - A screenshot action. + The output of a shell tool call that was emitted. - - `class Scroll: …` + - `id: str` - A scroll action. + The unique ID of the shell call output. Populated when this item is returned via API. - - `class Type: …` + - `call_id: str` - An action to type in text. + The unique ID of the shell tool call generated by the model. - - `class Wait: …` + - `max_output_length: Optional[int]` - A wait action. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `agent: Optional[Agent]` + - `output: List[Output]` - The agent that produced this item. + An array of shell call output contents - - `agent_name: str` + - `outcome: OutputOutcome` - The canonical name of the agent that produced this item. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `class ComputerCallOutput: …` + - `class OutputOutcomeTimeout: …` - The output of a computer tool call. + Indicates that the shell call exceeded its configured time limit. - - `call_id: str` + - `type: Literal["timeout"]` - The ID of the computer tool call that produced the output. + The outcome type. Always `timeout`. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"timeout"` - A computer screenshot image used with the computer use tool. + - `class OutputOutcomeExit: …` - - `type: Literal["computer_screenshot"]` + Indicates that the shell commands finished and returned an exit code. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `exit_code: int` - - `"computer_screenshot"` + Exit code from the shell process. - - `file_id: Optional[str]` + - `type: Literal["exit"]` - The identifier of an uploaded file that contains the screenshot. + The outcome type. Always `exit`. - - `image_url: Optional[str]` + - `"exit"` - The URL of the screenshot image. + - `stderr: str` - - `type: Literal["computer_call_output"]` + The standard error output that was captured. - The type of the computer tool call output. Always `computer_call_output`. + - `stdout: str` - - `"computer_call_output"` + The standard output that was captured. - - `id: Optional[str]` + - `created_by: Optional[str]` - The ID of the computer tool call output. + The identifier of the actor that created the item. - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The safety checks reported by the API that have been acknowledged by the developer. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `id: str` + - `"in_progress"` - The ID of the pending safety check. + - `"completed"` - - `code: Optional[str]` + - `"incomplete"` - The type of the pending safety check. + - `type: Literal["shell_call_output"]` - - `message: Optional[str]` + The type of the shell call output. Always `shell_call_output`. - Details about the pending safety check. + - `"shell_call_output"` - - `agent: Optional[ComputerCallOutputAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -101438,111 +111162,109 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `caller: Optional[Caller]` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The execution context that produced this tool call. - - `"in_progress"` + - `class CallerDirect: …` - - `"completed"` + - `type: Literal["direct"]` - - `"incomplete"` + - `"direct"` - - `class BetaResponseFunctionWebSearch: …` + - `class CallerProgram: …` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `caller_id: str` - - `id: str` + The call ID of the program item that produced this tool call. - The unique ID of the web search tool call. + - `type: Literal["program"]` - - `action: Action` + - `"program"` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `created_by: Optional[str]` - - `class ActionSearch: …` + The identifier of the actor that created the item. - Action type "search" - Performs a web search query. + - `class BetaResponseApplyPatchToolCall: …` - - `type: Literal["search"]` + A tool call that applies file diffs by creating, deleting, or updating files. - The action type. + - `id: str` - - `"search"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `queries: Optional[List[str]]` + - `call_id: str` - The search queries. + The unique ID of the apply patch tool call generated by the model. - - `query: Optional[str]` + - `operation: Operation` - The search query. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `sources: Optional[List[ActionSearchSource]]` + - `class OperationCreateFile: …` - The sources used in the search. + Instruction describing how to create a file via the apply_patch tool. - - `type: Literal["url"]` + - `diff: str` - The type of source. Always `url`. + Diff to apply. - - `"url"` + - `path: str` - - `url: str` + Path of the file to create. - The URL of the source. + - `type: Literal["create_file"]` - - `class ActionOpenPage: …` + Create a new file with the provided diff. - Action type "open_page" - Opens a specific URL from search results. + - `"create_file"` - - `type: Literal["open_page"]` + - `class OperationDeleteFile: …` - The action type. + Instruction describing how to delete a file via the apply_patch tool. - - `"open_page"` + - `path: str` - - `url: Optional[str]` + Path of the file to delete. - The URL opened by the model. + - `type: Literal["delete_file"]` - - `class ActionFindInPage: …` + Delete the specified file. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"delete_file"` - - `pattern: str` + - `class OperationUpdateFile: …` - The pattern or text to search for within the page. + Instruction describing how to update a file via the apply_patch tool. - - `type: Literal["find_in_page"]` + - `diff: str` - The action type. + Diff to apply. - - `"find_in_page"` + - `path: str` - - `url: str` + Path of the file to update. - The URL of the page searched for the pattern. + - `type: Literal["update_file"]` - - `status: Literal["in_progress", "searching", "completed", "failed"]` + Update an existing file with the provided diff. - The status of the web search tool call. + - `"update_file"` - - `"in_progress"` + - `status: Literal["in_progress", "completed"]` - - `"searching"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"completed"` + - `"in_progress"` - - `"failed"` + - `"completed"` - - `type: Literal["web_search_call"]` + - `type: Literal["apply_patch_call"]` - The type of the web search tool call. Always `web_search_call`. + The type of the item. Always `apply_patch_call`. - - `"web_search_call"` + - `"apply_patch_call"` - `agent: Optional[Agent]` @@ -101552,32 +111274,55 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall: …` + - `caller: Optional[Caller]` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The execution context that produced this tool call. - - `arguments: str` + - `class CallerDirect: …` - A JSON string of the arguments to pass to the function. + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `created_by: Optional[str]` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput: …` + + The output emitted by an apply patch tool call. + + - `id: str` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id: str` - The unique ID of the function tool call generated by the model. + The unique ID of the apply patch tool call generated by the model. - - `name: str` + - `status: Literal["completed", "failed"]` - The name of the function to run. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `type: Literal["function_call"]` + - `"completed"` - The type of the function tool call. Always `function_call`. + - `"failed"` - - `"function_call"` + - `type: Literal["apply_patch_call_output"]` - - `id: Optional[str]` + The type of the item. Always `apply_patch_call_output`. - The unique ID of the function tool call. + - `"apply_patch_call_output"` - `agent: Optional[Agent]` @@ -101607,160 +111352,152 @@ print(compacted_response) - `"program"` - - `namespace: Optional[str]` - - The namespace of the function to run. - - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` + - `created_by: Optional[str]` - - `"completed"` + The ID of the entity that created this tool call output. - - `"incomplete"` + - `output: Optional[str]` - - `class FunctionCallOutput: …` + Optional textual output returned by the apply patch tool. - The output of a function tool call. + - `class McpCall: …` - - `call_id: str` + An invocation of a tool on an MCP server. - The unique ID of the function tool call generated by the model. + - `id: str` - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + The unique ID of the tool call. - Text, image, or file output of the function tool call. + - `arguments: str` - - `str` + A JSON string of the arguments passed to the tool. - A JSON string of the output of the function tool call. + - `name: str` - - `List[BetaResponseFunctionCallOutputItem]` + The name of the tool that was run. - - `class BetaResponseInputTextContent: …` + - `server_label: str` - A text input to the model. + The label of the MCP server running the tool. - - `text: str` + - `type: Literal["mcp_call"]` - The text input to the model. + The type of the item. Always `mcp_call`. - - `type: Literal["input_text"]` + - `"mcp_call"` - The type of the input item. Always `input_text`. + - `agent: Optional[McpCallAgent]` - - `"input_text"` + The agent that produced this item. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `agent_name: str` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The canonical name of the agent that produced this item. - - `mode: Literal["explicit"]` + - `approval_request_id: Optional[str]` - The breakpoint mode. Always `explicit`. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `"explicit"` + - `error: Optional[str]` - - `class BetaResponseInputImageContent: …` + The error from the tool call, if any. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `output: Optional[str]` - - `type: Literal["input_image"]` + The output from the tool call. - The type of the input item. Always `input_image`. + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - `"input_image"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + - `"in_progress"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"completed"` - - `"low"` + - `"incomplete"` - - `"high"` + - `"calling"` - - `"auto"` + - `"failed"` - - `"original"` + - `class McpListTools: …` - - `file_id: Optional[str]` + A list of tools available on an MCP server. - The ID of the file to be sent to the model. + - `id: str` - - `image_url: Optional[str]` + The unique ID of the list. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `server_label: str` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The label of the MCP server. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `tools: List[McpListToolsTool]` - - `mode: Literal["explicit"]` + The tools available on the server. - The breakpoint mode. Always `explicit`. + - `input_schema: object` - - `"explicit"` + The JSON schema describing the tool's input. - - `class BetaResponseInputFileContent: …` + - `name: str` - A file input to the model. + The name of the tool. - - `type: Literal["input_file"]` + - `annotations: Optional[object]` - The type of the input item. Always `input_file`. + Additional annotations about the tool. - - `"input_file"` + - `description: Optional[str]` - - `detail: Optional[Literal["auto", "low", "high"]]` + The description of the tool. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `type: Literal["mcp_list_tools"]` - - `"auto"` + The type of the item. Always `mcp_list_tools`. - - `"low"` + - `"mcp_list_tools"` - - `"high"` + - `agent: Optional[McpListToolsAgent]` - - `file_data: Optional[str]` + The agent that produced this item. - The base64-encoded data of the file to be sent to the model. + - `agent_name: str` - - `file_id: Optional[str]` + The canonical name of the agent that produced this item. - The ID of the file to be sent to the model. + - `error: Optional[str]` - - `file_url: Optional[str]` + Error message if the server could not list tools. - The URL of the file to be sent to the model. + - `class McpApprovalRequest: …` - - `filename: Optional[str]` + A request for human approval of a tool invocation. - The name of the file to be sent to the model. + - `id: str` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The unique ID of the approval request. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `arguments: str` - - `mode: Literal["explicit"]` + A JSON string of arguments for the tool. - The breakpoint mode. Always `explicit`. + - `name: str` - - `"explicit"` + The name of the tool to run. - - `type: Literal["function_call_output"]` + - `server_label: str` - The type of the function tool call output. Always `function_call_output`. + The label of the MCP server making the request. - - `"function_call_output"` + - `type: Literal["mcp_approval_request"]` - - `id: Optional[str]` + The type of the item. Always `mcp_approval_request`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"mcp_approval_request"` - - `agent: Optional[FunctionCallOutputAgent]` + - `agent: Optional[McpApprovalRequestAgent]` The agent that produced this item. @@ -101768,181 +111505,168 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[FunctionCallOutputCaller]` + - `class McpApprovalResponse: …` - The execution context that produced this tool call. + A response to an MCP approval request. - - `class FunctionCallOutputCallerDirect: …` + - `id: str` - - `type: Literal["direct"]` + The unique ID of the approval response - The caller type. Always `direct`. + - `approval_request_id: str` - - `"direct"` + The ID of the approval request being answered. - - `class FunctionCallOutputCallerProgram: …` + - `approve: bool` - - `caller_id: str` + Whether the request was approved. - The call ID of the program item that produced this tool call. + - `type: Literal["mcp_approval_response"]` - - `type: Literal["program"]` + The type of the item. Always `mcp_approval_response`. - The caller type. Always `program`. + - `"mcp_approval_response"` - - `"program"` + - `agent: Optional[McpApprovalResponseAgent]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The agent that produced this item. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `agent_name: str` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"completed"` + - `reason: Optional[str]` - - `"incomplete"` + Optional reason for the decision. - - `class AgentMessage: …` + - `class BetaResponseCustomToolCall: …` - A message routed between agents. + A call to a custom tool created by the model. - - `author: str` + - `call_id: str` - The sending agent identity. + An identifier used to map this custom tool call to a tool call output. - - `content: List[AgentMessageContent]` + - `input: str` - Plaintext, image, or encrypted content sent between agents. + The input for the custom tool call generated by the model. - - `class BetaResponseInputTextContent: …` + - `name: str` - A text input to the model. + The name of the custom tool being called. - - `class BetaResponseInputImageContent: …` + - `type: Literal["custom_tool_call"]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The type of the custom tool call. Always `custom_tool_call`. - - `class AgentMessageContentEncryptedContent: …` + - `"custom_tool_call"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `id: Optional[str]` - - `encrypted_content: str` + The unique ID of the custom tool call in the OpenAI platform. - Opaque encrypted content. + - `agent: Optional[Agent]` - - `type: Literal["encrypted_content"]` + The agent that produced this item. - The type of the input item. Always `encrypted_content`. + - `agent_name: str` - - `"encrypted_content"` + The canonical name of the agent that produced this item. - - `recipient: str` + - `caller: Optional[Caller]` - The destination agent identity. + The execution context that produced this tool call. - - `type: Literal["agent_message"]` + - `class CallerDirect: …` - The item type. Always `agent_message`. + - `type: Literal["direct"]` - - `"agent_message"` + - `"direct"` - - `id: Optional[str]` + - `class CallerProgram: …` - The unique ID of this agent message item. + - `caller_id: str` - - `agent: Optional[AgentMessageAgent]` + The call ID of the program item that produced this tool call. - The agent that produced this item. + - `type: Literal["program"]` - - `agent_name: str` + - `"program"` - The canonical name of the agent that produced this item. + - `namespace: Optional[str]` - - `class MultiAgentCall: …` + The namespace of the custom tool being called. - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `class BetaResponseCustomToolCallOutputItem: …` - The multi-agent action that was executed. + The output of a custom tool call from your code, being sent back to the model. - - `"spawn_agent"` + - `id: str` - - `"interrupt_agent"` + The unique ID of the custom tool call output item. - - `"list_agents"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"send_message"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"followup_task"` + - `"in_progress"` - - `"wait_agent"` + - `"completed"` - - `arguments: str` + - `"incomplete"` - The action arguments as a JSON string. + - `created_by: Optional[str]` - - `call_id: str` + The identifier of the actor that created the item. - The unique ID linking this call to its output. + - `output_index: int` - - `type: Literal["multi_agent_call"]` + The index of the output item that was marked done. - The item type. Always `multi_agent_call`. + - `sequence_number: int` - - `"multi_agent_call"` + The sequence number of this event. - - `id: Optional[str]` + - `type: Literal["response.output_item.done"]` - The unique ID of this multi-agent call. + The type of the event. Always `response.output_item.done`. - - `agent: Optional[MultiAgentCallAgent]` + - `"response.output_item.done"` - The agent that produced this item. + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput: …` - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` +### Beta Response Output Message - - `call_id: str` +- `class BetaResponseOutputMessage: …` - The unique ID of the multi-agent call. + An output message from the model. - - `output: List[MultiAgentCallOutputOutput]` + - `id: str` - Text output returned by the multi-agent action. + The unique ID of the output message. - - `text: str` + - `content: List[Content]` - The text content. + The content of the output message. - - `type: Literal["output_text"]` + - `class BetaResponseOutputText: …` - The content type. Always `output_text`. + A text output from the model. - - `"output_text"` + - `annotations: List[Annotation]` - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + The annotations of the text output. - Citations associated with the text content. + - `class AnnotationFileCitation: …` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + A citation to a file. - `file_id: str` @@ -101958,47 +111682,51 @@ print(compacted_response) - `type: Literal["file_citation"]` - The citation type. Always `file_citation`. + The type of the file citation. Always `file_citation`. - `"file_citation"` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + - `class AnnotationURLCitation: …` + + A citation for a web resource used to generate a model response. - `end_index: int` - The index of the last character of the citation in the message. + The index of the last character of the URL citation in the message. - `start_index: int` - The index of the first character of the citation in the message. + The index of the first character of the URL citation in the message. - `title: str` - The title of the cited resource. + The title of the web resource. - `type: Literal["url_citation"]` - The citation type. Always `url_citation`. + The type of the URL citation. Always `url_citation`. - `"url_citation"` - `url: str` - The URL of the cited resource. + The URL of the web resource. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `class AnnotationContainerFileCitation: …` + + A citation for a container file used to generate a model response. - `container_id: str` - The ID of the container. + The ID of the container file. - `end_index: int` - The index of the last character of the citation in the message. + The index of the last character of the container file citation in the message. - `file_id: str` - The ID of the container file. + The ID of the file. - `filename: str` @@ -102006,71 +111734,82 @@ print(compacted_response) - `start_index: int` - The index of the first character of the citation in the message. + The index of the first character of the container file citation in the message. - `type: Literal["container_file_citation"]` - The citation type. Always `container_file_citation`. + The type of the container file citation. Always `container_file_citation`. - `"container_file_citation"` - - `type: Literal["multi_agent_call_output"]` + - `class AnnotationFilePath: …` - The item type. Always `multi_agent_call_output`. + A path to a file. - - `"multi_agent_call_output"` + - `file_id: str` - - `id: Optional[str]` + The ID of the file. - The unique ID of this multi-agent call output. + - `index: int` - - `agent: Optional[MultiAgentCallOutputAgent]` + The index of the file in the list of files. - The agent that produced this item. + - `type: Literal["file_path"]` - - `agent_name: str` + The type of the file path. Always `file_path`. - The canonical name of the agent that produced this item. + - `"file_path"` - - `class ToolSearchCall: …` + - `text: str` - - `arguments: object` + The text output from the model. - The arguments supplied to the tool search call. + - `type: Literal["output_text"]` - - `type: Literal["tool_search_call"]` + The type of the output text. Always `output_text`. - The item type. Always `tool_search_call`. + - `"output_text"` - - `"tool_search_call"` + - `logprobs: Optional[List[Logprob]]` - - `id: Optional[str]` + - `token: str` - The unique ID of this tool search call. + - `bytes: List[int]` - - `agent: Optional[ToolSearchCallAgent]` + - `logprob: float` - The agent that produced this item. + - `top_logprobs: List[LogprobTopLogprob]` - - `agent_name: str` + - `token: str` - The canonical name of the agent that produced this item. + - `bytes: List[int]` + + - `logprob: float` + + - `class BetaResponseOutputRefusal: …` + + A refusal from the model. + + - `refusal: str` + + The refusal explanation from the model. - - `call_id: Optional[str]` + - `type: Literal["refusal"]` - The unique ID of the tool search call generated by the model. + The type of the refusal. Always `refusal`. - - `execution: Optional[Literal["server", "client"]]` + - `"refusal"` - Whether tool search was executed by the server or by the client. + - `role: Literal["assistant"]` - - `"server"` + The role of the output message. Always `assistant`. - - `"client"` + - `"assistant"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the tool search call. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"in_progress"` @@ -102078,1262 +111817,1223 @@ print(compacted_response) - `"incomplete"` - - `class BetaResponseToolSearchOutputItemParam: …` - - - `tools: List[BetaTool]` - - The loaded tool definitions returned by the tool search output. - - - `class BetaFunctionTool: …` + - `type: Literal["message"]` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The type of the output message. Always `message`. - - `name: str` + - `"message"` - The name of the function to call. + - `agent: Optional[Agent]` - - `parameters: Optional[Dict[str, object]]` + The agent that produced this item. - A JSON schema object describing the parameters of the function. + - `agent_name: str` - - `strict: Optional[bool]` + The canonical name of the agent that produced this item. - Whether strict parameter validation is enforced for this function tool. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `type: Literal["function"]` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - The type of the function tool. Always `function`. + - `"commentary"` - - `"function"` + - `"final_answer"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` +### Beta Response Output Refusal - The tool invocation context(s). +- `class BetaResponseOutputRefusal: …` - - `"direct"` + A refusal from the model. - - `"programmatic"` + - `refusal: str` - - `defer_loading: Optional[bool]` + The refusal explanation from the model. - Whether this function is deferred and loaded via tool search. + - `type: Literal["refusal"]` - - `description: Optional[str]` + The type of the refusal. Always `refusal`. - A description of the function. Used by the model to determine whether or not to call the function. + - `"refusal"` - - `output_schema: Optional[Dict[str, object]]` +### Beta Response Output Text - A JSON schema object describing the JSON value encoded in string outputs for this function. +- `class BetaResponseOutputText: …` - - `class BetaFileSearchTool: …` + A text output from the model. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `annotations: List[Annotation]` - - `type: Literal["file_search"]` + The annotations of the text output. - The type of the file search tool. Always `file_search`. + - `class AnnotationFileCitation: …` - - `"file_search"` + A citation to a file. - - `vector_store_ids: List[str]` + - `file_id: str` - The IDs of the vector stores to search. + The ID of the file. - - `filters: Optional[Filters]` + - `filename: str` - A filter to apply. + The filename of the file cited. - - `class FiltersComparisonFilter: …` + - `index: int` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The index of the file in the list of files. - - `key: str` + - `type: Literal["file_citation"]` - The key to compare against the value. + The type of the file citation. Always `file_citation`. - - `type: Literal["eq", "ne", "gt", 5 more]` + - `"file_citation"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `class AnnotationURLCitation: …` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + A citation for a web resource used to generate a model response. - - `"eq"` + - `end_index: int` - - `"ne"` + The index of the last character of the URL citation in the message. - - `"gt"` + - `start_index: int` - - `"gte"` + The index of the first character of the URL citation in the message. - - `"lt"` + - `title: str` - - `"lte"` + The title of the web resource. - - `"in"` + - `type: Literal["url_citation"]` - - `"nin"` + The type of the URL citation. Always `url_citation`. - - `value: Union[str, float, bool, List[object]]` + - `"url_citation"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `url: str` - - `str` + The URL of the web resource. - - `float` + - `class AnnotationContainerFileCitation: …` - - `bool` + A citation for a container file used to generate a model response. - - `List[object]` + - `container_id: str` - - `class FiltersCompoundFilter: …` + The ID of the container file. - Combine multiple filters using `and` or `or`. + - `end_index: int` - - `filters: List[FiltersCompoundFilterFilter]` + The index of the last character of the container file citation in the message. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `file_id: str` - - `class FiltersCompoundFilterFilterComparisonFilter: …` + The ID of the file. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `filename: str` - - `key: str` + The filename of the container file cited. - The key to compare against the value. + - `start_index: int` - - `type: Literal["eq", "ne", "gt", 5 more]` + The index of the first character of the container file citation in the message. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `type: Literal["container_file_citation"]` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The type of the container file citation. Always `container_file_citation`. - - `"eq"` + - `"container_file_citation"` - - `"ne"` + - `class AnnotationFilePath: …` - - `"gt"` + A path to a file. - - `"gte"` + - `file_id: str` - - `"lt"` + The ID of the file. - - `"lte"` + - `index: int` - - `"in"` + The index of the file in the list of files. - - `"nin"` + - `type: Literal["file_path"]` - - `value: Union[str, float, bool, List[object]]` + The type of the file path. Always `file_path`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `"file_path"` - - `str` + - `text: str` - - `float` + The text output from the model. - - `bool` + - `type: Literal["output_text"]` - - `List[object]` + The type of the output text. Always `output_text`. - - `object` + - `"output_text"` - - `type: Literal["and", "or"]` + - `logprobs: Optional[List[Logprob]]` - Type of operation: `and` or `or`. + - `token: str` - - `"and"` + - `bytes: List[int]` - - `"or"` + - `logprob: float` - - `max_num_results: Optional[int]` + - `top_logprobs: List[LogprobTopLogprob]` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `token: str` - - `ranking_options: Optional[RankingOptions]` + - `bytes: List[int]` - Ranking options for search. + - `logprob: float` - - `hybrid_search: Optional[RankingOptionsHybridSearch]` +### Beta Response Output Text Annotation Added Event - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. +- `class BetaResponseOutputTextAnnotationAddedEvent: …` - - `embedding_weight: float` + Emitted when an annotation is added to output text content. - The weight of the embedding in the reciprocal ranking fusion. + - `annotation: object` - - `text_weight: float` + The annotation object being added. (See annotation schema for details.) - The weight of the text in the reciprocal ranking fusion. + - `annotation_index: int` - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + The index of the annotation within the content part. - The ranker to use for the file search. + - `content_index: int` - - `"auto"` + The index of the content part within the output item. - - `"default-2024-11-15"` + - `item_id: str` - - `score_threshold: Optional[float]` + The unique identifier of the item to which the annotation is being added. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `output_index: int` - - `class BetaComputerTool: …` + The index of the output item in the response's output array. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `sequence_number: int` - - `type: Literal["computer"]` + The sequence number of this event. - The type of the computer tool. Always `computer`. + - `type: Literal["response.output_text.annotation.added"]` - - `"computer"` + The type of the event. Always 'response.output_text.annotation.added'. - - `class BetaComputerUsePreviewTool: …` + - `"response.output_text.annotation.added"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent: Optional[Agent]` - - `display_height: int` + The agent that owns this multi-agent streaming event. - The height of the computer display. + - `agent_name: str` - - `display_width: int` + The canonical name of the agent that produced this item. - The width of the computer display. +### Beta Response Prompt - - `environment: Literal["windows", "mac", "linux", 2 more]` +- `class BetaResponsePrompt: …` - The type of computer environment to control. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `"windows"` + - `id: str` - - `"mac"` + The unique identifier of the prompt template to use. - - `"linux"` + - `variables: Optional[Dict[str, Variables]]` - - `"ubuntu"` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `"browser"` + - `str` - - `type: Literal["computer_use_preview"]` + - `class BetaResponseInputText: …` - The type of the computer use tool. Always `computer_use_preview`. + A text input to the model. - - `"computer_use_preview"` + - `text: str` - - `class BetaWebSearchTool: …` + The text input to the model. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `type: Literal["input_text"]` - - `type: Literal["web_search", "web_search_2025_08_26"]` + The type of the input item. Always `input_text`. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"input_text"` - - `"web_search"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"web_search_2025_08_26"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `filters: Optional[Filters]` + - `mode: Literal["explicit"]` - Filters for the search. + The breakpoint mode. Always `explicit`. - - `allowed_domains: Optional[List[str]]` + - `"explicit"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `class BetaResponseInputImage: …` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `detail: Literal["low", "high", "auto", "original"]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `"low"` - - `"medium"` - - `"high"` - - `user_location: Optional[UserLocation]` + - `"auto"` - The approximate location of the user. + - `"original"` - - `city: Optional[str]` + - `type: Literal["input_image"]` - Free text input for the city of the user, e.g. `San Francisco`. + The type of the input item. Always `input_image`. - - `country: Optional[str]` + - `"input_image"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `file_id: Optional[str]` - - `region: Optional[str]` + The ID of the file to be sent to the model. - Free text input for the region of the user, e.g. `California`. + - `image_url: Optional[str]` - - `timezone: Optional[str]` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `type: Optional[Literal["approximate"]]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The type of location approximation. Always `approximate`. + - `mode: Literal["explicit"]` - - `"approximate"` + The breakpoint mode. Always `explicit`. - - `class Mcp: …` + - `"explicit"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `class BetaResponseInputFile: …` - - `server_label: str` + A file input to the model. - A label for this MCP server, used to identify it in tool calls. + - `type: Literal["input_file"]` - - `type: Literal["mcp"]` + The type of the input item. Always `input_file`. - The type of the MCP tool. Always `mcp`. + - `"input_file"` - - `"mcp"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The tool invocation context(s). + - `"auto"` - - `"direct"` + - `"low"` - - `"programmatic"` + - `"high"` - - `allowed_tools: Optional[McpAllowedTools]` + - `file_data: Optional[str]` - List of allowed tool names or a filter object. + The content of the file to be sent to the model. - - `List[str]` + - `file_id: Optional[str]` - A string array of allowed tool names + The ID of the file to be sent to the model. - - `class McpAllowedToolsMcpToolFilter: …` + - `file_url: Optional[str]` - A filter object to specify which tools are allowed. + The URL of the file to be sent to the model. - - `read_only: Optional[bool]` + - `filename: Optional[str]` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The name of the file to be sent to the model. - - `tool_names: Optional[List[str]]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - List of allowed tool names. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `authorization: Optional[str]` + - `mode: Literal["explicit"]` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The breakpoint mode. Always `explicit`. - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + - `"explicit"` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `version: Optional[str]` - Currently supported `connector_id` values are: + Optional version of the prompt template. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` +### Beta Response Queued Event - - `"connector_dropbox"` +- `class BetaResponseQueuedEvent: …` - - `"connector_gmail"` + Emitted when a response is queued and waiting to be processed. - - `"connector_googlecalendar"` + - `response: BetaResponse` - - `"connector_googledrive"` + The full response object that is queued. - - `"connector_microsoftteams"` + - `id: str` - - `"connector_outlookcalendar"` + Unique identifier for this Response. - - `"connector_outlookemail"` + - `created_at: float` - - `"connector_sharepoint"` + Unix timestamp (in seconds) of when this Response was created. - - `defer_loading: Optional[bool]` + - `error: Optional[BetaResponseError]` - Whether this MCP tool is deferred and discovered via tool search. + An error object returned when the model fails to generate a Response. - - `headers: Optional[Dict[str, str]]` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The error code for the response. - - `require_approval: Optional[McpRequireApproval]` + - `"server_error"` - Specify which of the MCP server's tools require approval. + - `"rate_limit_exceeded"` - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `"invalid_prompt"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"bio_policy"` - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `"vector_store_timeout"` - A filter object to specify which tools are allowed. + - `"invalid_image"` - - `read_only: Optional[bool]` + - `"invalid_image_format"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"invalid_base64_image"` - - `tool_names: Optional[List[str]]` + - `"invalid_image_url"` - List of allowed tool names. + - `"image_too_large"` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + - `"image_too_small"` - A filter object to specify which tools are allowed. + - `"image_parse_error"` - - `read_only: Optional[bool]` + - `"image_content_policy_violation"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"invalid_image_mode"` - - `tool_names: Optional[List[str]]` + - `"image_file_too_large"` - List of allowed tool names. + - `"unsupported_image_media_type"` - - `Literal["always", "never"]` + - `"empty_image_file"` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `"failed_to_download_image"` - - `"always"` + - `"image_file_not_found"` - - `"never"` + - `message: str` - - `server_description: Optional[str]` + A human-readable description of the error. - Optional description of the MCP server, used to provide more context. + - `incomplete_details: Optional[IncompleteDetails]` - - `server_url: Optional[str]` + Details about why the response is incomplete. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` - - `tunnel_id: Optional[str]` + The reason why the response is incomplete. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `"max_output_tokens"` - - `class CodeInterpreter: …` + - `"content_filter"` - A tool that runs Python code to help generate a response to a prompt. + - `instructions: Union[str, List[BetaResponseInputItem], null]` - - `container: CodeInterpreterContainer` + A system (or developer) message inserted into the model's context. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - `str` - The container ID. - - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - - `type: Literal["auto"]` - - Always `auto`. - - - `"auto"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `file_ids: Optional[List[str]]` + - `List[BetaResponseInputItem]` - An optional list of uploaded files to make available to your code. + A list of one or many input items to the model, containing + different content types. - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `class BetaEasyInputMessage: …` - The memory limit for the code interpreter container. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `"1g"` + - `content: Union[str, BetaResponseInputMessageContentList]` - - `"4g"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"16g"` + - `str` - - `"64g"` + A text input to the model. - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `List[BetaResponseInputContent]` - Network access policy for the container. + - `class BetaResponseInputText: …` - - `class BetaContainerNetworkPolicyDisabled: …` + A text input to the model. - - `type: Literal["disabled"]` + - `text: str` - Disable outbound network access. Always `disabled`. + The text input to the model. - - `"disabled"` + - `type: Literal["input_text"]` - - `class BetaContainerNetworkPolicyAllowlist: …` + The type of the input item. Always `input_text`. - - `allowed_domains: List[str]` + - `"input_text"` - A list of allowed domains when type is `allowlist`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `type: Literal["allowlist"]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Allow outbound network access only to specified domains. Always `allowlist`. + - `mode: Literal["explicit"]` - - `"allowlist"` + The breakpoint mode. Always `explicit`. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `"explicit"` - Optional domain-scoped secrets for allowlisted domains. + - `class BetaResponseInputImage: …` - - `domain: str` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The domain associated with the secret. + - `detail: Literal["low", "high", "auto", "original"]` - - `name: str` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The name of the secret to inject for the domain. + - `"low"` - - `value: str` + - `"high"` - The secret value to inject for the domain. + - `"auto"` - - `type: Literal["code_interpreter"]` + - `"original"` - The type of the code interpreter tool. Always `code_interpreter`. + - `type: Literal["input_image"]` - - `"code_interpreter"` + The type of the input item. Always `input_image`. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"input_image"` - The tool invocation context(s). + - `file_id: Optional[str]` - - `"direct"` + The ID of the file to be sent to the model. - - `"programmatic"` + - `image_url: Optional[str]` - - `class ProgrammaticToolCalling: …` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: Literal["programmatic_tool_calling"]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The type of the tool. Always `programmatic_tool_calling`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"programmatic_tool_calling"` + - `mode: Literal["explicit"]` - - `class ImageGeneration: …` + The breakpoint mode. Always `explicit`. - A tool that generates images using the GPT image models. + - `"explicit"` - - `type: Literal["image_generation"]` + - `class BetaResponseInputFile: …` - The type of the image generation tool. Always `image_generation`. + A file input to the model. - - `"image_generation"` + - `type: Literal["input_file"]` - - `action: Optional[Literal["generate", "edit", "auto"]]` + The type of the input item. Always `input_file`. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"input_file"` - - `"generate"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"edit"` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - `"auto"` - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + - `"low"` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `"high"` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `file_data: Optional[str]` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The content of the file to be sent to the model. - - `"transparent"` + - `file_id: Optional[str]` - - `"opaque"` + The ID of the file to be sent to the model. - - `"auto"` + - `file_url: Optional[str]` - - `input_fidelity: Optional[Literal["high", "low"]]` + The URL of the file to be sent to the model. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `filename: Optional[str]` - - `"high"` + The name of the file to be sent to the model. - - `"low"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `mode: Literal["explicit"]` - - `file_id: Optional[str]` + The breakpoint mode. Always `explicit`. - File ID for the mask image. + - `"explicit"` - - `image_url: Optional[str]` + - `role: Literal["user", "assistant", "system", "developer"]` - Base64-encoded mask image. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + - `"user"` - The image generation model to use. Default: `gpt-image-1`. + - `"assistant"` - - `str` + - `"system"` - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `"developer"` - The image generation model to use. Default: `gpt-image-1`. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `"gpt-image-1"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `"gpt-image-1-mini"` + - `"commentary"` - - `"gpt-image-2"` + - `"final_answer"` - - `"gpt-image-2-2026-04-21"` + - `type: Optional[Literal["message"]]` - - `"gpt-image-1.5"` + The type of the message input. Always `message`. - - `"chatgpt-image-latest"` + - `"message"` - - `moderation: Optional[Literal["auto", "low"]]` + - `class Message: …` - Moderation level for the generated image. Default: `auto`. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `"auto"` + - `content: BetaResponseInputMessageContentList` - - `"low"` + A list of one or many input items to the model, containing different content + types. - - `output_compression: Optional[int]` + - `class BetaResponseInputText: …` - Compression level for the output image. Default: 100. + A text input to the model. - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + - `class BetaResponseInputImage: …` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"png"` + - `class BetaResponseInputFile: …` - - `"webp"` + A file input to the model. - - `"jpeg"` + - `role: Literal["user", "system", "developer"]` - - `partial_images: Optional[int]` + The role of the message input. One of `user`, `system`, or `developer`. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"user"` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + - `"system"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"developer"` - - `"low"` + - `agent: Optional[MessageAgent]` - - `"medium"` + The agent that produced this item. - - `"high"` + - `agent_name: str` - - `"auto"` + The canonical name of the agent that produced this item. - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `str` + - `"in_progress"` - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `"completed"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"incomplete"` - - `"1024x1024"` + - `type: Optional[Literal["message"]]` - - `"1024x1536"` + The type of the message input. Always set to `message`. - - `"1536x1024"` + - `"message"` - - `"auto"` + - `class BetaResponseOutputMessage: …` - - `class LocalShell: …` + An output message from the model. - A tool that allows the model to execute shell commands in a local environment. + - `id: str` - - `type: Literal["local_shell"]` + The unique ID of the output message. - The type of the local shell tool. Always `local_shell`. + - `content: List[Content]` - - `"local_shell"` + The content of the output message. - - `class BetaFunctionShellTool: …` + - `class BetaResponseOutputText: …` - A tool that allows the model to execute shell commands. + A text output from the model. - - `type: Literal["shell"]` + - `annotations: List[Annotation]` - The type of the shell tool. Always `shell`. + The annotations of the text output. - - `"shell"` + - `class AnnotationFileCitation: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + A citation to a file. - The tool invocation context(s). + - `file_id: str` - - `"direct"` + The ID of the file. - - `"programmatic"` + - `filename: str` - - `environment: Optional[Environment]` + The filename of the file cited. - - `class BetaContainerAuto: …` + - `index: int` - - `type: Literal["container_auto"]` + The index of the file in the list of files. - Automatically creates a container for this request + - `type: Literal["file_citation"]` - - `"container_auto"` + The type of the file citation. Always `file_citation`. - - `file_ids: Optional[List[str]]` + - `"file_citation"` - An optional list of uploaded files to make available to your code. + - `class AnnotationURLCitation: …` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + A citation for a web resource used to generate a model response. - The memory limit for the container. + - `end_index: int` - - `"1g"` + The index of the last character of the URL citation in the message. - - `"4g"` + - `start_index: int` - - `"16g"` + The index of the first character of the URL citation in the message. - - `"64g"` + - `title: str` - - `network_policy: Optional[NetworkPolicy]` + The title of the web resource. - Network access policy for the container. + - `type: Literal["url_citation"]` - - `class BetaContainerNetworkPolicyDisabled: …` + The type of the URL citation. Always `url_citation`. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `"url_citation"` - - `skills: Optional[List[Skill]]` + - `url: str` - An optional list of skills referenced by id or inline data. + The URL of the web resource. - - `class BetaSkillReference: …` + - `class AnnotationContainerFileCitation: …` - - `skill_id: str` + A citation for a container file used to generate a model response. - The ID of the referenced skill. + - `container_id: str` - - `type: Literal["skill_reference"]` + The ID of the container file. - References a skill created with the /v1/skills endpoint. + - `end_index: int` - - `"skill_reference"` + The index of the last character of the container file citation in the message. - - `version: Optional[str]` + - `file_id: str` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The ID of the file. - - `class BetaInlineSkill: …` + - `filename: str` - - `description: str` + The filename of the container file cited. - The description of the skill. + - `start_index: int` - - `name: str` + The index of the first character of the container file citation in the message. - The name of the skill. + - `type: Literal["container_file_citation"]` - - `source: BetaInlineSkillSource` + The type of the container file citation. Always `container_file_citation`. - Inline skill payload + - `"container_file_citation"` - - `data: str` + - `class AnnotationFilePath: …` - Base64-encoded skill zip bundle. + A path to a file. - - `media_type: Literal["application/zip"]` + - `file_id: str` - The media type of the inline skill payload. Must be `application/zip`. + The ID of the file. - - `"application/zip"` + - `index: int` - - `type: Literal["base64"]` + The index of the file in the list of files. - The type of the inline skill source. Must be `base64`. + - `type: Literal["file_path"]` - - `"base64"` + The type of the file path. Always `file_path`. - - `type: Literal["inline"]` + - `"file_path"` - Defines an inline skill for this request. + - `text: str` - - `"inline"` + The text output from the model. - - `class BetaLocalEnvironment: …` + - `type: Literal["output_text"]` - - `type: Literal["local"]` + The type of the output text. Always `output_text`. - Use a local computer environment. + - `"output_text"` - - `"local"` + - `logprobs: Optional[List[Logprob]]` - - `skills: Optional[List[BetaLocalSkill]]` + - `token: str` - An optional list of skills. + - `bytes: List[int]` - - `description: str` + - `logprob: float` - The description of the skill. + - `top_logprobs: List[LogprobTopLogprob]` - - `name: str` + - `token: str` - The name of the skill. + - `bytes: List[int]` - - `path: str` + - `logprob: float` - The path to the directory containing the skill. + - `class BetaResponseOutputRefusal: …` - - `class BetaContainerReference: …` + A refusal from the model. - - `container_id: str` + - `refusal: str` - The ID of the referenced container. + The refusal explanation from the model. - - `type: Literal["container_reference"]` + - `type: Literal["refusal"]` - References a container created with the /v1/containers endpoint + The type of the refusal. Always `refusal`. - - `"container_reference"` + - `"refusal"` - - `class BetaCustomTool: …` + - `role: Literal["assistant"]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The role of the output message. Always `assistant`. - - `name: str` + - `"assistant"` - The name of the custom tool, used to identify it in tool calls. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["custom"]` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The type of the custom tool. Always `custom`. + - `"in_progress"` - - `"custom"` + - `"completed"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"incomplete"` - The tool invocation context(s). + - `type: Literal["message"]` - - `"direct"` + The type of the output message. Always `message`. - - `"programmatic"` + - `"message"` - - `defer_loading: Optional[bool]` + - `agent: Optional[Agent]` - Whether this tool should be deferred and discovered via tool search. + The agent that produced this item. - - `description: Optional[str]` + - `agent_name: str` - Optional description of the custom tool, used to provide more context. + The canonical name of the agent that produced this item. - - `format: Optional[Format]` + - `phase: Optional[Literal["commentary", "final_answer"]]` - The input format for the custom tool. Default is unconstrained text. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `class FormatText: …` + - `"commentary"` - Unconstrained free-form text. + - `"final_answer"` - - `type: Literal["text"]` + - `class BetaResponseFileSearchToolCall: …` - Unconstrained text format. Always `text`. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `"text"` + - `id: str` - - `class FormatGrammar: …` + The unique ID of the file search tool call. - A grammar defined by the user. + - `queries: List[str]` - - `definition: str` + The queries used to search for files. - The grammar definition. + - `status: Literal["in_progress", "searching", "completed", 2 more]` - - `syntax: Literal["lark", "regex"]` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The syntax of the grammar definition. One of `lark` or `regex`. + - `"in_progress"` - - `"lark"` + - `"searching"` - - `"regex"` + - `"completed"` - - `type: Literal["grammar"]` + - `"incomplete"` - Grammar format. Always `grammar`. + - `"failed"` - - `"grammar"` + - `type: Literal["file_search_call"]` - - `class BetaNamespaceTool: …` + The type of the file search tool call. Always `file_search_call`. - Groups function/custom tools under a shared namespace. + - `"file_search_call"` - - `description: str` + - `agent: Optional[Agent]` - A description of the namespace shown to the model. + The agent that produced this item. - - `name: str` + - `agent_name: str` - The namespace name used in tool calls (for example, `crm`). + The canonical name of the agent that produced this item. - - `tools: List[Tool]` + - `results: Optional[List[Result]]` - The function/custom tools available inside this namespace. + The results of the file search tool call. - - `class ToolFunction: …` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - - `name: str` + 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, booleans, or numbers. - - `type: Literal["function"]` + - `str` - - `"function"` + - `float` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `bool` - The tool invocation context(s). + - `file_id: Optional[str]` - - `"direct"` + The unique ID of the file. - - `"programmatic"` + - `filename: Optional[str]` - - `defer_loading: Optional[bool]` + The name of the file. - Whether this function should be deferred and discovered via tool search. + - `score: Optional[float]` - - `description: Optional[str]` + The relevance score of the file - a value between 0 and 1. - - `output_schema: Optional[Dict[str, object]]` + - `text: Optional[str]` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The text that was retrieved from the file. - - `parameters: Optional[object]` + - `class BetaResponseComputerToolCall: …` - - `strict: Optional[bool]` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `id: str` - - `class BetaCustomTool: …` + The unique ID of the computer call. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `call_id: str` - - `type: Literal["namespace"]` + An identifier used when responding to the tool call with output. - The type of the tool. Always `namespace`. + - `pending_safety_checks: List[PendingSafetyCheck]` - - `"namespace"` + The pending safety checks for the computer call. - - `class BetaToolSearchTool: …` + - `id: str` - Hosted or BYOT tool search configuration for deferred tools. + The ID of the pending safety check. - - `type: Literal["tool_search"]` + - `code: Optional[str]` - The type of the tool. Always `tool_search`. + The type of the pending safety check. - - `"tool_search"` + - `message: Optional[str]` - - `description: Optional[str]` + Details about the pending safety check. - Description shown to the model for a client-executed tool search tool. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `execution: Optional[Literal["server", "client"]]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Whether tool search is executed by the server or by the client. + - `"in_progress"` - - `"server"` + - `"completed"` - - `"client"` + - `"incomplete"` - - `parameters: Optional[object]` + - `type: Literal["computer_call"]` - Parameter schema for a client-executed tool search tool. + The type of the computer call. Always `computer_call`. - - `class BetaWebSearchPreviewTool: …` + - `"computer_call"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `action: Optional[BetaComputerAction]` - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + A click action. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `class Click: …` - - `"web_search_preview"` + A click action. - - `"web_search_preview_2025_03_11"` + - `button: Literal["left", "right", "wheel", 2 more]` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"text"` + - `"left"` - - `"image"` + - `"right"` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `"wheel"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"back"` - - `"low"` + - `"forward"` - - `"medium"` + - `type: Literal["click"]` - - `"high"` + Specifies the event type. For a click action, this property is always `click`. - - `user_location: Optional[UserLocation]` + - `"click"` - The user's location. + - `x: int` - - `type: Literal["approximate"]` + The x-coordinate where the click occurred. - The type of location approximation. Always `approximate`. + - `y: int` - - `"approximate"` + The y-coordinate where the click occurred. - - `city: Optional[str]` + - `keys: Optional[List[str]]` - Free text input for the city of the user, e.g. `San Francisco`. + The keys being held while clicking. - - `country: Optional[str]` + - `class DoubleClick: …` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + A double click action. - - `region: Optional[str]` + - `keys: Optional[List[str]]` - Free text input for the region of the user, e.g. `California`. + The keys being held while double-clicking. - - `timezone: Optional[str]` + - `type: Literal["double_click"]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `class BetaApplyPatchTool: …` + - `"double_click"` - Allows the assistant to create, delete, or update files using unified diffs. + - `x: int` - - `type: Literal["apply_patch"]` + The x-coordinate where the double click occurred. - The type of the tool. Always `apply_patch`. + - `y: int` - - `"apply_patch"` + The y-coordinate where the double click occurred. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `class Drag: …` - The tool invocation context(s). + A drag action. - - `"direct"` + - `path: List[DragPath]` - - `"programmatic"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `type: Literal["tool_search_output"]` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The item type. Always `tool_search_output`. + - `x: int` - - `"tool_search_output"` + The x-coordinate. - - `id: Optional[str]` + - `y: int` - The unique ID of this tool search output. + The y-coordinate. - - `agent: Optional[Agent]` + - `type: Literal["drag"]` - The agent that produced this item. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `agent_name: str` + - `"drag"` - The canonical name of the agent that produced this item. + - `keys: Optional[List[str]]` - - `call_id: Optional[str]` + The keys being held while dragging the mouse. - The unique ID of the tool search call generated by the model. + - `class Keypress: …` - - `execution: Optional[Literal["server", "client"]]` + A collection of keypresses the model would like to perform. - Whether tool search was executed by the server or by the client. + - `keys: List[str]` - - `"server"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"client"` + - `type: Literal["keypress"]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The status of the tool search output. + - `"keypress"` - - `"in_progress"` + - `class Move: …` - - `"completed"` + A mouse move action. - - `"incomplete"` + - `type: Literal["move"]` - - `class AdditionalTools: …` + Specifies the event type. For a move action, this property is always set to `move`. - - `role: Literal["developer"]` + - `"move"` - The role that provided the additional tools. Only `developer` is supported. + - `x: int` - - `"developer"` + The x-coordinate to move to. - - `tools: List[BetaTool]` + - `y: int` - A list of additional tools made available at this item. + The y-coordinate to move to. - - `class BetaFunctionTool: …` + - `keys: Optional[List[str]]` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The keys being held while moving the mouse. - - `class BetaFileSearchTool: …` + - `class Screenshot: …` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + A screenshot action. - - `class BetaComputerTool: …` + - `type: Literal["screenshot"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `class BetaComputerUsePreviewTool: …` + - `"screenshot"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class Scroll: …` - - `class BetaWebSearchTool: …` + A scroll action. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `scroll_x: int` - - `class Mcp: …` + The horizontal scroll distance. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `scroll_y: int` - - `class CodeInterpreter: …` + The vertical scroll distance. - A tool that runs Python code to help generate a response to a prompt. + - `type: Literal["scroll"]` - - `class ProgrammaticToolCalling: …` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `class ImageGeneration: …` + - `"scroll"` - A tool that generates images using the GPT image models. + - `x: int` - - `class LocalShell: …` + The x-coordinate where the scroll occurred. - A tool that allows the model to execute shell commands in a local environment. + - `y: int` - - `class BetaFunctionShellTool: …` + The y-coordinate where the scroll occurred. - A tool that allows the model to execute shell commands. + - `keys: Optional[List[str]]` - - `class BetaCustomTool: …` + The keys being held while scrolling. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `class Type: …` - - `class BetaNamespaceTool: …` + An action to type in text. - Groups function/custom tools under a shared namespace. + - `text: str` - - `class BetaToolSearchTool: …` + The text to type. - Hosted or BYOT tool search configuration for deferred tools. + - `type: Literal["type"]` - - `class BetaWebSearchPreviewTool: …` + Specifies the event type. For a type action, this property is always set to `type`. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"type"` - - `class BetaApplyPatchTool: …` + - `class Wait: …` - Allows the assistant to create, delete, or update files using unified diffs. + A wait action. - - `type: Literal["additional_tools"]` + - `type: Literal["wait"]` - The item type. Always `additional_tools`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"additional_tools"` + - `"wait"` - - `id: Optional[str]` + - `actions: Optional[BetaComputerActionList]` - The unique ID of this additional tools item. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `agent: Optional[AdditionalToolsAgent]` + - `class Click: …` - The agent that produced this item. + A click action. - - `agent_name: str` + - `class DoubleClick: …` - The canonical name of the agent that produced this item. + A double click action. - - `class BetaResponseReasoningItem: …` + - `class Drag: …` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + A drag action. - - `id: str` + - `class Keypress: …` - The unique identifier of the reasoning content. + A collection of keypresses the model would like to perform. - - `summary: List[Summary]` + - `class Move: …` - Reasoning summary content. + A mouse move action. - - `text: str` + - `class Screenshot: …` - A summary of the reasoning output from the model so far. + A screenshot action. - - `type: Literal["summary_text"]` + - `class Scroll: …` - The type of the object. Always `summary_text`. + A scroll action. - - `"summary_text"` + - `class Type: …` - - `type: Literal["reasoning"]` + An action to type in text. - The type of the object. Always `reasoning`. + - `class Wait: …` - - `"reasoning"` + A wait action. - `agent: Optional[Agent]` @@ -103343,55 +113043,60 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `content: Optional[List[Content]]` + - `class ComputerCallOutput: …` - Reasoning text content. + The output of a computer tool call. - - `text: str` + - `call_id: str` - The reasoning text from the model. + The ID of the computer tool call that produced the output. - - `type: Literal["reasoning_text"]` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The type of the reasoning text. Always `reasoning_text`. + A computer screenshot image used with the computer use tool. - - `"reasoning_text"` + - `type: Literal["computer_screenshot"]` - - `encrypted_content: Optional[str]` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"computer_screenshot"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `file_id: Optional[str]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The identifier of an uploaded file that contains the screenshot. - - `"in_progress"` + - `image_url: Optional[str]` - - `"completed"` + The URL of the screenshot image. - - `"incomplete"` + - `type: Literal["computer_call_output"]` - - `class BetaResponseCompactionItemParam: …` + The type of the computer tool call output. Always `computer_call_output`. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"computer_call_output"` - - `encrypted_content: str` + - `id: Optional[str]` - The encrypted content of the compaction summary. + The ID of the computer tool call output. - - `type: Literal["compaction"]` + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - The type of the item. Always `compaction`. + The safety checks reported by the API that have been acknowledged by the developer. - - `"compaction"` + - `id: str` - - `id: Optional[str]` + The ID of the pending safety check. - The ID of the compaction item. + - `code: Optional[str]` - - `agent: Optional[Agent]` + The type of the pending safety check. + + - `message: Optional[str]` + + Details about the pending safety check. + + - `agent: Optional[ComputerCallOutputAgent]` The agent that produced this item. @@ -103399,112 +113104,111 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ImageGenerationCall: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - An image generation request made by the model. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `id: str` + - `"in_progress"` - The unique ID of the image generation call. + - `"completed"` - - `result: Optional[str]` + - `"incomplete"` - The generated image encoded in base64. + - `class BetaResponseFunctionWebSearch: …` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The status of the image generation call. + - `id: str` - - `"in_progress"` + The unique ID of the web search tool call. - - `"completed"` + - `action: Action` - - `"generating"` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `"failed"` + - `class ActionSearch: …` - - `type: Literal["image_generation_call"]` + Action type "search" - Performs a web search query. - The type of the image generation call. Always `image_generation_call`. + - `type: Literal["search"]` - - `"image_generation_call"` + The action type. - - `agent: Optional[ImageGenerationCallAgent]` + - `"search"` - The agent that produced this item. + - `queries: Optional[List[str]]` - - `agent_name: str` + The search queries. - The canonical name of the agent that produced this item. + - `query: Optional[str]` - - `class BetaResponseCodeInterpreterToolCall: …` + The search query. - A tool call to run code. + - `sources: Optional[List[ActionSearchSource]]` - - `id: str` + The sources used in the search. - The unique ID of the code interpreter tool call. + - `type: Literal["url"]` - - `code: Optional[str]` + The type of source. Always `url`. - The code to run, or null if not available. + - `"url"` - - `container_id: str` + - `url: str` - The ID of the container used to run the code. + The URL of the source. - - `outputs: Optional[List[Output]]` + - `class ActionOpenPage: …` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Action type "open_page" - Opens a specific URL from search results. - - `class OutputLogs: …` + - `type: Literal["open_page"]` - The logs output from the code interpreter. + The action type. - - `logs: str` + - `"open_page"` - The logs output from the code interpreter. + - `url: Optional[str]` - - `type: Literal["logs"]` + The URL opened by the model. - The type of the output. Always `logs`. + - `class ActionFindInPage: …` - - `"logs"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `class OutputImage: …` + - `pattern: str` - The image output from the code interpreter. + The pattern or text to search for within the page. - - `type: Literal["image"]` + - `type: Literal["find_in_page"]` - The type of the output. Always `image`. + The action type. - - `"image"` + - `"find_in_page"` - `url: str` - The URL of the image output from the code interpreter. + The URL of the page searched for the pattern. - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The status of the web search tool call. - `"in_progress"` - - `"completed"` - - - `"incomplete"` + - `"searching"` - - `"interpreting"` + - `"completed"` - `"failed"` - - `type: Literal["code_interpreter_call"]` + - `type: Literal["web_search_call"]` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the web search tool call. Always `web_search_call`. - - `"code_interpreter_call"` + - `"web_search_call"` - `agent: Optional[Agent]` @@ -103514,65 +113218,34 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCall: …` - - A tool call to run a command on the local shell. - - - `id: str` - - The unique ID of the local shell call. - - - `action: LocalShellCallAction` - - Execute a shell command on the server. - - - `command: List[str]` - - The command to run. - - - `env: Dict[str, str]` - - Environment variables to set for the command. - - - `type: Literal["exec"]` - - The type of the local shell action. Always `exec`. - - - `"exec"` - - - `timeout_ms: Optional[int]` - - Optional timeout in milliseconds for the command. - - - `user: Optional[str]` + - `class BetaResponseFunctionToolCall: …` - Optional user to run the command as. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `working_directory: Optional[str]` + - `arguments: str` - Optional working directory to run the command in. + A JSON string of the arguments to pass to the function. - `call_id: str` - The unique ID of the local shell tool call generated by the model. - - - `status: Literal["in_progress", "completed", "incomplete"]` + The unique ID of the function tool call generated by the model. - The status of the local shell call. + - `name: str` - - `"in_progress"` + The name of the function to run. - - `"completed"` + - `type: Literal["function_call"]` - - `"incomplete"` + The type of the function tool call. Always `function_call`. - - `type: Literal["local_shell_call"]` + - `"function_call"` - The type of the local shell call. Always `local_shell_call`. + - `id: Optional[str]` - - `"local_shell_call"` + The unique ID of the function tool call. - - `agent: Optional[LocalShellCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -103580,35 +113253,34 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCallOutput: …` - - The output of a local shell tool call. + - `caller: Optional[Caller]` - - `id: str` + The execution context that produced this tool call. - The unique ID of the local shell tool call generated by the model. + - `class CallerDirect: …` - - `output: str` + - `type: Literal["direct"]` - A JSON string of the output of the local shell tool call. + - `"direct"` - - `type: Literal["local_shell_call_output"]` + - `class CallerProgram: …` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `caller_id: str` - - `"local_shell_call_output"` + The call ID of the program item that produced this tool call. - - `agent: Optional[LocalShellCallOutputAgent]` + - `type: Literal["program"]` - The agent that produced this item. + - `"program"` - - `agent_name: str` + - `namespace: Optional[str]` - The canonical name of the agent that produced this item. + The namespace of the function to run. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -103616,149 +113288,145 @@ print(compacted_response) - `"incomplete"` - - `class ShellCall: …` - - A tool representing a request to execute one or more shell commands. - - - `action: ShellCallAction` + - `class FunctionCallOutput: …` - The shell commands and limits that describe how to run the tool call. + The output of a function tool call. - - `commands: List[str]` + - `call_id: str` - Ordered shell commands for the execution environment to run. + The unique ID of the function tool call generated by the model. - - `max_output_length: Optional[int]` + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Text, image, or file output of the function tool call. - - `timeout_ms: Optional[int]` + - `str` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + A JSON string of the output of the function tool call. - - `call_id: str` + - `List[BetaResponseFunctionCallOutputItem]` - The unique ID of the shell tool call generated by the model. + - `class BetaResponseInputTextContent: …` - - `type: Literal["shell_call"]` + A text input to the model. - The type of the item. Always `shell_call`. + - `text: str` - - `"shell_call"` + The text input to the model. - - `id: Optional[str]` + - `type: Literal["input_text"]` - The unique ID of the shell tool call. Populated when this item is returned via API. + The type of the input item. Always `input_text`. - - `agent: Optional[ShellCallAgent]` + - `"input_text"` - The agent that produced this item. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `agent_name: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The canonical name of the agent that produced this item. + - `mode: Literal["explicit"]` - - `caller: Optional[ShellCallCaller]` + The breakpoint mode. Always `explicit`. - The execution context that produced this tool call. + - `"explicit"` - - `class ShellCallCallerDirect: …` + - `class BetaResponseInputImageContent: …` - - `type: Literal["direct"]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The caller type. Always `direct`. + - `type: Literal["input_image"]` - - `"direct"` + The type of the input item. Always `input_image`. - - `class ShellCallCallerProgram: …` + - `"input_image"` - - `caller_id: str` + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - The call ID of the program item that produced this tool call. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: Literal["program"]` + - `"low"` - The caller type. Always `program`. + - `"high"` - - `"program"` + - `"auto"` - - `environment: Optional[ShellCallEnvironment]` + - `"original"` - The environment to execute the shell commands in. + - `file_id: Optional[str]` - - `class BetaLocalEnvironment: …` + The ID of the file to be sent to the model. - - `class BetaContainerReference: …` + - `image_url: Optional[str]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"in_progress"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"completed"` + - `mode: Literal["explicit"]` - - `"incomplete"` + The breakpoint mode. Always `explicit`. - - `class ShellCallOutput: …` + - `"explicit"` - The streamed output items emitted by a shell tool call. + - `class BetaResponseInputFileContent: …` - - `call_id: str` + A file input to the model. - The unique ID of the shell tool call generated by the model. + - `type: Literal["input_file"]` - - `output: List[BetaResponseFunctionShellCallOutputContent]` + The type of the input item. Always `input_file`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"input_file"` - - `outcome: Outcome` + - `detail: Optional[Literal["auto", "low", "high"]]` - The exit or timeout outcome associated with this shell call. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `class OutcomeTimeout: …` + - `"auto"` - Indicates that the shell call exceeded its configured time limit. + - `"low"` - - `type: Literal["timeout"]` + - `"high"` - The outcome type. Always `timeout`. + - `file_data: Optional[str]` - - `"timeout"` + The base64-encoded data of the file to be sent to the model. - - `class OutcomeExit: …` + - `file_id: Optional[str]` - Indicates that the shell commands finished and returned an exit code. + The ID of the file to be sent to the model. - - `exit_code: int` + - `file_url: Optional[str]` - The exit code returned by the shell process. + The URL of the file to be sent to the model. - - `type: Literal["exit"]` + - `filename: Optional[str]` - The outcome type. Always `exit`. + The name of the file to be sent to the model. - - `"exit"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `stderr: str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Captured stderr output for the shell call. + - `mode: Literal["explicit"]` - - `stdout: str` + The breakpoint mode. Always `explicit`. - Captured stdout output for the shell call. + - `"explicit"` - - `type: Literal["shell_call_output"]` + - `type: Literal["function_call_output"]` - The type of the item. Always `shell_call_output`. + The type of the function tool call output. Always `function_call_output`. - - `"shell_call_output"` + - `"function_call_output"` - `id: Optional[str]` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `agent: Optional[ShellCallOutputAgent]` + - `agent: Optional[FunctionCallOutputAgent]` The agent that produced this item. @@ -103766,11 +113434,11 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ShellCallOutputCaller]` + - `caller: Optional[FunctionCallOutputCaller]` The execution context that produced this tool call. - - `class ShellCallOutputCallerDirect: …` + - `class FunctionCallOutputCallerDirect: …` - `type: Literal["direct"]` @@ -103778,7 +113446,7 @@ print(compacted_response) - `"direct"` - - `class ShellCallOutputCallerProgram: …` + - `class FunctionCallOutputCallerProgram: …` - `caller_id: str` @@ -103790,13 +113458,9 @@ print(compacted_response) - `"program"` - - `max_output_length: Optional[int]` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the shell call output. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -103804,87 +113468,99 @@ print(compacted_response) - `"incomplete"` - - `class ApplyPatchCall: …` + - `class AgentMessage: …` - A tool call representing a request to create, delete, or update files using diff patches. + A message routed between agents. - - `call_id: str` + - `author: str` - The unique ID of the apply patch tool call generated by the model. + The sending agent identity. - - `operation: ApplyPatchCallOperation` + - `content: List[AgentMessageContent]` - The specific create, delete, or update instruction for the apply_patch tool call. + Plaintext, image, or encrypted content sent between agents. - - `class ApplyPatchCallOperationCreateFile: …` + - `class BetaResponseInputTextContent: …` - Instruction for creating a new file via the apply_patch tool. + A text input to the model. - - `diff: str` + - `class BetaResponseInputImageContent: …` - Unified diff content to apply when creating the file. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `path: str` + - `class AgentMessageContentEncryptedContent: …` - Path of the file to create relative to the workspace root. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `type: Literal["create_file"]` + - `encrypted_content: str` - The operation type. Always `create_file`. + Opaque encrypted content. - - `"create_file"` + - `type: Literal["encrypted_content"]` - - `class ApplyPatchCallOperationDeleteFile: …` + The type of the input item. Always `encrypted_content`. - Instruction for deleting an existing file via the apply_patch tool. + - `"encrypted_content"` - - `path: str` + - `recipient: str` - Path of the file to delete relative to the workspace root. + The destination agent identity. - - `type: Literal["delete_file"]` + - `type: Literal["agent_message"]` - The operation type. Always `delete_file`. + The item type. Always `agent_message`. - - `"delete_file"` + - `"agent_message"` - - `class ApplyPatchCallOperationUpdateFile: …` + - `id: Optional[str]` - Instruction for updating an existing file via the apply_patch tool. + The unique ID of this agent message item. - - `diff: str` + - `agent: Optional[AgentMessageAgent]` - Unified diff content to apply to the existing file. + The agent that produced this item. - - `path: str` + - `agent_name: str` - Path of the file to update relative to the workspace root. + The canonical name of the agent that produced this item. - - `type: Literal["update_file"]` + - `class MultiAgentCall: …` - The operation type. Always `update_file`. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"update_file"` + The multi-agent action that was executed. - - `status: Literal["in_progress", "completed"]` + - `"spawn_agent"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"interrupt_agent"` - - `"in_progress"` + - `"list_agents"` - - `"completed"` + - `"send_message"` - - `type: Literal["apply_patch_call"]` + - `"followup_task"` - The type of the item. Always `apply_patch_call`. + - `"wait_agent"` - - `"apply_patch_call"` + - `arguments: str` + + The action arguments as a JSON string. + + - `call_id: str` + + The unique ID linking this call to its output. + + - `type: Literal["multi_agent_call"]` + + The item type. Always `multi_agent_call`. + + - `"multi_agent_call"` - `id: Optional[str]` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of this multi-agent call. - - `agent: Optional[ApplyPatchCallAgent]` + - `agent: Optional[MultiAgentCallAgent]` The agent that produced this item. @@ -103892,131 +113568,153 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ApplyPatchCallCaller]` + - `class MultiAgentCallOutput: …` - The execution context that produced this tool call. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `class ApplyPatchCallCallerDirect: …` + The multi-agent action that produced this result. - - `type: Literal["direct"]` + - `"spawn_agent"` - The caller type. Always `direct`. + - `"interrupt_agent"` - - `"direct"` + - `"list_agents"` - - `class ApplyPatchCallCallerProgram: …` + - `"send_message"` - - `caller_id: str` + - `"followup_task"` - The call ID of the program item that produced this tool call. + - `"wait_agent"` - - `type: Literal["program"]` + - `call_id: str` - The caller type. Always `program`. + The unique ID of the multi-agent call. - - `"program"` + - `output: List[MultiAgentCallOutputOutput]` - - `class ApplyPatchCallOutput: …` + Text output returned by the multi-agent action. - The streamed output emitted by an apply patch tool call. + - `text: str` - - `call_id: str` + The text content. - The unique ID of the apply patch tool call generated by the model. + - `type: Literal["output_text"]` - - `status: Literal["completed", "failed"]` + The content type. Always `output_text`. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"output_text"` - - `"completed"` + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - - `"failed"` + Citations associated with the text content. - - `type: Literal["apply_patch_call_output"]` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - The type of the item. Always `apply_patch_call_output`. + - `file_id: str` - - `"apply_patch_call_output"` + The ID of the file. - - `id: Optional[str]` + - `filename: str` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The filename of the file cited. - - `agent: Optional[ApplyPatchCallOutputAgent]` + - `index: int` - The agent that produced this item. + The index of the file in the list of files. - - `agent_name: str` + - `type: Literal["file_citation"]` - The canonical name of the agent that produced this item. + The citation type. Always `file_citation`. - - `caller: Optional[ApplyPatchCallOutputCaller]` + - `"file_citation"` - The execution context that produced this tool call. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` - - `class ApplyPatchCallOutputCallerDirect: …` + - `end_index: int` - - `type: Literal["direct"]` + The index of the last character of the citation in the message. - The caller type. Always `direct`. + - `start_index: int` - - `"direct"` + The index of the first character of the citation in the message. - - `class ApplyPatchCallOutputCallerProgram: …` + - `title: str` - - `caller_id: str` + The title of the cited resource. - The call ID of the program item that produced this tool call. + - `type: Literal["url_citation"]` - - `type: Literal["program"]` + The citation type. Always `url_citation`. - The caller type. Always `program`. + - `"url_citation"` - - `"program"` + - `url: str` - - `output: Optional[str]` + The URL of the cited resource. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` - - `class McpListTools: …` + - `container_id: str` - A list of tools available on an MCP server. + The ID of the container. - - `id: str` + - `end_index: int` - The unique ID of the list. + The index of the last character of the citation in the message. - - `server_label: str` + - `file_id: str` - The label of the MCP server. + The ID of the container file. - - `tools: List[McpListToolsTool]` + - `filename: str` - The tools available on the server. + The filename of the container file cited. - - `input_schema: object` + - `start_index: int` - The JSON schema describing the tool's input. + The index of the first character of the citation in the message. - - `name: str` + - `type: Literal["container_file_citation"]` - The name of the tool. + The citation type. Always `container_file_citation`. - - `annotations: Optional[object]` + - `"container_file_citation"` - Additional annotations about the tool. + - `type: Literal["multi_agent_call_output"]` - - `description: Optional[str]` + The item type. Always `multi_agent_call_output`. - The description of the tool. + - `"multi_agent_call_output"` - - `type: Literal["mcp_list_tools"]` + - `id: Optional[str]` - The type of the item. Always `mcp_list_tools`. + The unique ID of this multi-agent call output. - - `"mcp_list_tools"` + - `agent: Optional[MultiAgentCallOutputAgent]` - - `agent: Optional[McpListToolsAgent]` + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class ToolSearchCall: …` + + - `arguments: object` + + The arguments supplied to the tool search call. + + - `type: Literal["tool_search_call"]` + + The item type. Always `tool_search_call`. + + - `"tool_search_call"` + + - `id: Optional[str]` + + The unique ID of this tool search call. + + - `agent: Optional[ToolSearchCallAgent]` The agent that produced this item. @@ -104024,1097 +113722,1137 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `error: Optional[str]` + - `call_id: Optional[str]` - Error message if the server could not list tools. + The unique ID of the tool search call generated by the model. - - `class McpApprovalRequest: …` + - `execution: Optional[Literal["server", "client"]]` - A request for human approval of a tool invocation. + Whether tool search was executed by the server or by the client. - - `id: str` + - `"server"` - The unique ID of the approval request. + - `"client"` - - `arguments: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A JSON string of arguments for the tool. + The status of the tool search call. - - `name: str` + - `"in_progress"` - The name of the tool to run. + - `"completed"` - - `server_label: str` + - `"incomplete"` - The label of the MCP server making the request. + - `class BetaResponseToolSearchOutputItemParam: …` - - `type: Literal["mcp_approval_request"]` + - `tools: List[BetaTool]` - The type of the item. Always `mcp_approval_request`. + The loaded tool definitions returned by the tool search output. - - `"mcp_approval_request"` + - `class BetaFunctionTool: …` - - `agent: Optional[McpApprovalRequestAgent]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The agent that produced this item. + - `name: str` - - `agent_name: str` + The name of the function to call. - The canonical name of the agent that produced this item. + - `parameters: Optional[Dict[str, object]]` - - `class McpApprovalResponse: …` + A JSON schema object describing the parameters of the function. - A response to an MCP approval request. + - `strict: Optional[bool]` - - `approval_request_id: str` + Whether strict parameter validation is enforced for this function tool. - The ID of the approval request being answered. + - `type: Literal["function"]` - - `approve: bool` + The type of the function tool. Always `function`. - Whether the request was approved. + - `"function"` - - `type: Literal["mcp_approval_response"]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The type of the item. Always `mcp_approval_response`. + The tool invocation context(s). - - `"mcp_approval_response"` + - `"direct"` - - `id: Optional[str]` + - `"programmatic"` - The unique ID of the approval response + - `defer_loading: Optional[bool]` - - `agent: Optional[McpApprovalResponseAgent]` + Whether this function is deferred and loaded via tool search. - The agent that produced this item. + - `description: Optional[str]` - - `agent_name: str` + A description of the function. Used by the model to determine whether or not to call the function. - The canonical name of the agent that produced this item. + - `output_schema: Optional[Dict[str, object]]` - - `reason: Optional[str]` + A JSON schema object describing the JSON value encoded in string outputs for this function. - Optional reason for the decision. + - `class BetaFileSearchTool: …` - - `class McpCall: …` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - An invocation of a tool on an MCP server. + - `type: Literal["file_search"]` - - `id: str` + The type of the file search tool. Always `file_search`. - The unique ID of the tool call. + - `"file_search"` - - `arguments: str` + - `vector_store_ids: List[str]` - A JSON string of the arguments passed to the tool. + The IDs of the vector stores to search. - - `name: str` + - `filters: Optional[Filters]` - The name of the tool that was run. + A filter to apply. - - `server_label: str` + - `class FiltersComparisonFilter: …` - The label of the MCP server running the tool. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: Literal["mcp_call"]` + - `key: str` - The type of the item. Always `mcp_call`. + The key to compare against the value. - - `"mcp_call"` + - `type: Literal["eq", "ne", "gt", 5 more]` - - `agent: Optional[McpCallAgent]` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The agent that produced this item. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `agent_name: str` + - `"eq"` - The canonical name of the agent that produced this item. + - `"ne"` - - `approval_request_id: Optional[str]` + - `"gt"` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `"gte"` - - `error: Optional[str]` + - `"lt"` - The error from the tool call, if any. + - `"lte"` - - `output: Optional[str]` + - `"in"` - The output from the tool call. + - `"nin"` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"in_progress"` + - `str` - - `"completed"` + - `float` - - `"incomplete"` + - `bool` - - `"calling"` + - `List[Union[str, float]]` - - `"failed"` + - `str` - - `class BetaResponseCustomToolCallOutput: …` + - `float` - The output of a custom tool call from your code, being sent back to the model. + - `class FiltersCompoundFilter: …` - - `call_id: str` + Combine multiple filters using `and` or `or`. - The call ID, used to map this custom tool call output to a custom tool call. + - `filters: List[FiltersCompoundFilterFilter]` - - `output: Union[str, List[OutputOutputContentList]]` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `class FiltersCompoundFilterFilterComparisonFilter: …` - - `str` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A string of the output of the custom tool call. + - `key: str` - - `List[OutputOutputContentList]` + The key to compare against the value. - Text, image, or file output of the custom tool call. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `class BetaResponseInputText: …` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A text input to the model. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `class BetaResponseInputImage: …` + - `"eq"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"ne"` - - `class BetaResponseInputFile: …` + - `"gt"` - A file input to the model. + - `"gte"` - - `type: Literal["custom_tool_call_output"]` + - `"lt"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"lte"` - - `"custom_tool_call_output"` + - `"in"` - - `id: Optional[str]` + - `"nin"` - The unique ID of the custom tool call output in the OpenAI platform. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `agent: Optional[Agent]` + The value to compare against the attribute key; supports string, number, or boolean types. - The agent that produced this item. + - `str` - - `agent_name: str` + - `float` - The canonical name of the agent that produced this item. + - `bool` - - `caller: Optional[Caller]` + - `List[Union[str, float]]` - The execution context that produced this tool call. + - `str` - - `class CallerDirect: …` + - `float` - - `type: Literal["direct"]` + - `object` - The caller type. Always `direct`. + - `type: Literal["and", "or"]` - - `"direct"` + Type of operation: `and` or `or`. - - `class CallerProgram: …` + - `"and"` - - `caller_id: str` + - `"or"` - The call ID of the program item that produced this tool call. + - `max_num_results: Optional[int]` - - `type: Literal["program"]` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The caller type. Always `program`. + - `ranking_options: Optional[RankingOptions]` - - `"program"` + Ranking options for search. - - `class BetaResponseCustomToolCall: …` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - A call to a custom tool created by the model. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `call_id: str` + - `embedding_weight: float` - An identifier used to map this custom tool call to a tool call output. + The weight of the embedding in the reciprocal ranking fusion. - - `input: str` + - `text_weight: float` - The input for the custom tool call generated by the model. + The weight of the text in the reciprocal ranking fusion. - - `name: str` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - The name of the custom tool being called. + The ranker to use for the file search. - - `type: Literal["custom_tool_call"]` + - `"auto"` - The type of the custom tool call. Always `custom_tool_call`. + - `"default-2024-11-15"` - - `"custom_tool_call"` + - `score_threshold: Optional[float]` - - `id: Optional[str]` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The unique ID of the custom tool call in the OpenAI platform. + - `class BetaComputerTool: …` - - `agent: Optional[Agent]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The agent that produced this item. + - `type: Literal["computer"]` - - `agent_name: str` + The type of the computer tool. Always `computer`. - The canonical name of the agent that produced this item. + - `"computer"` - - `caller: Optional[Caller]` + - `class BetaComputerUsePreviewTool: …` - The execution context that produced this tool call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class CallerDirect: …` + - `display_height: int` - - `type: Literal["direct"]` + The height of the computer display. - - `"direct"` + - `display_width: int` - - `class CallerProgram: …` + The width of the computer display. - - `caller_id: str` + - `environment: Literal["windows", "mac", "linux", 2 more]` - The call ID of the program item that produced this tool call. + The type of computer environment to control. - - `type: Literal["program"]` + - `"windows"` - - `"program"` + - `"mac"` - - `namespace: Optional[str]` + - `"linux"` - The namespace of the custom tool being called. + - `"ubuntu"` - - `class CompactionTrigger: …` + - `"browser"` - Compacts the current context. Must be the final input item. + - `type: Literal["computer_use_preview"]` - - `type: Literal["compaction_trigger"]` + The type of the computer use tool. Always `computer_use_preview`. - The type of the item. Always `compaction_trigger`. + - `"computer_use_preview"` - - `"compaction_trigger"` + - `class BetaWebSearchTool: …` - - `agent: Optional[CompactionTriggerAgent]` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The agent that produced this item. + - `type: Literal["web_search", "web_search_2025_08_26"]` - - `agent_name: str` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The canonical name of the agent that produced this item. + - `"web_search"` - - `class ItemReference: …` + - `"web_search_2025_08_26"` - An internal identifier for an item to reference. + - `filters: Optional[Filters]` - - `id: str` + Filters for the search. - The ID of the item to reference. + - `allowed_domains: Optional[List[str]]` - - `agent: Optional[ItemReferenceAgent]` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The agent that produced this item. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `agent_name: str` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The canonical name of the agent that produced this item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `type: Optional[Literal["item_reference"]]` + - `"low"` - The type of item to reference. Always `item_reference`. + - `"medium"` - - `"item_reference"` + - `"high"` - - `class Program: …` + - `user_location: Optional[UserLocation]` - - `id: str` + The approximate location of the user. - The unique ID of this program item. + - `city: Optional[str]` - - `call_id: str` + Free text input for the city of the user, e.g. `San Francisco`. - The stable call ID of the program item. + - `country: Optional[str]` - - `code: str` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The JavaScript source executed by programmatic tool calling. + - `region: Optional[str]` - - `fingerprint: str` + Free text input for the region of the user, e.g. `California`. - Opaque program replay fingerprint that must be round-tripped. + - `timezone: Optional[str]` - - `type: Literal["program"]` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The item type. Always `program`. + - `type: Optional[Literal["approximate"]]` - - `"program"` + The type of location approximation. Always `approximate`. - - `agent: Optional[ProgramAgent]` + - `"approximate"` - The agent that produced this item. + - `class Mcp: …` - - `agent_name: str` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The canonical name of the agent that produced this item. + - `server_label: str` - - `class ProgramOutput: …` + A label for this MCP server, used to identify it in tool calls. - - `id: str` + - `type: Literal["mcp"]` - The unique ID of this program output item. + The type of the MCP tool. Always `mcp`. - - `call_id: str` + - `"mcp"` - The call ID of the program item. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `result: str` + The tool invocation context(s). - The result produced by the program item. + - `"direct"` - - `status: Literal["completed", "incomplete"]` + - `"programmatic"` - The terminal status of the program output. + - `allowed_tools: Optional[McpAllowedTools]` - - `"completed"` + List of allowed tool names or a filter object. - - `"incomplete"` + - `List[str]` - - `type: Literal["program_output"]` + A string array of allowed tool names - The item type. Always `program_output`. + - `class McpAllowedToolsMcpToolFilter: …` - - `"program_output"` + A filter object to specify which tools are allowed. - - `agent: Optional[ProgramOutputAgent]` + - `read_only: Optional[bool]` - The agent that produced this item. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `agent_name: str` + - `tool_names: Optional[List[str]]` - The canonical name of the agent that produced this item. + List of allowed tool names. -### Beta Response Input Message Content List + - `authorization: Optional[str]` -- `List[BetaResponseInputContent]` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - A list of one or many input items to the model, containing different content - types. + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `class BetaResponseInputText: …` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - A text input to the model. + Currently supported `connector_id` values are: - - `text: str` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The text input to the model. + - `"connector_dropbox"` - - `type: Literal["input_text"]` + - `"connector_gmail"` - The type of the input item. Always `input_text`. + - `"connector_googlecalendar"` - - `"input_text"` + - `"connector_googledrive"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"connector_microsoftteams"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"connector_outlookcalendar"` - - `mode: Literal["explicit"]` + - `"connector_outlookemail"` - The breakpoint mode. Always `explicit`. + - `"connector_sharepoint"` - - `"explicit"` + - `defer_loading: Optional[bool]` - - `class BetaResponseInputImage: …` + Whether this MCP tool is deferred and discovered via tool search. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `headers: Optional[Dict[str, str]]` - - `detail: Literal["low", "high", "auto", "original"]` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `require_approval: Optional[McpRequireApproval]` - - `"low"` + Specify which of the MCP server's tools require approval. - - `"high"` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - - `"auto"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"original"` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `type: Literal["input_image"]` + A filter object to specify which tools are allowed. - The type of the input item. Always `input_image`. + - `read_only: Optional[bool]` - - `"input_image"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `file_id: Optional[str]` + - `tool_names: Optional[List[str]]` - The ID of the file to be sent to the model. + List of allowed tool names. - - `image_url: Optional[str]` + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + A filter object to specify which tools are allowed. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `read_only: Optional[bool]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `mode: Literal["explicit"]` + - `tool_names: Optional[List[str]]` - The breakpoint mode. Always `explicit`. + List of allowed tool names. - - `"explicit"` + - `Literal["always", "never"]` - - `class BetaResponseInputFile: …` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - A file input to the model. + - `"always"` - - `type: Literal["input_file"]` + - `"never"` - The type of the input item. Always `input_file`. + - `server_description: Optional[str]` - - `"input_file"` + Optional description of the MCP server, used to provide more context. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `server_url: Optional[str]` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"auto"` + - `tunnel_id: Optional[str]` - - `"low"` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `"high"` + - `class CodeInterpreter: …` - - `file_data: Optional[str]` + A tool that runs Python code to help generate a response to a prompt. - The content of the file to be sent to the model. + - `container: CodeInterpreterContainer` - - `file_id: Optional[str]` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The ID of the file to be sent to the model. + - `str` - - `file_url: Optional[str]` + The container ID. - The URL of the file to be sent to the model. + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `filename: Optional[str]` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The name of the file to be sent to the model. + - `type: Literal["auto"]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + Always `auto`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"auto"` - - `mode: Literal["explicit"]` + - `file_ids: Optional[List[str]]` - The breakpoint mode. Always `explicit`. + An optional list of uploaded files to make available to your code. - - `"explicit"` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` -### Beta Response Input Message Item + The memory limit for the code interpreter container. -- `class BetaResponseInputMessageItem: …` + - `"1g"` - - `id: str` + - `"4g"` - The unique ID of the message input. + - `"16g"` - - `content: BetaResponseInputMessageContentList` + - `"64g"` - A list of one or many input items to the model, containing different content - types. + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - - `class BetaResponseInputText: …` + Network access policy for the container. - A text input to the model. + - `class BetaContainerNetworkPolicyDisabled: …` - - `text: str` + - `type: Literal["disabled"]` - The text input to the model. + Disable outbound network access. Always `disabled`. - - `type: Literal["input_text"]` + - `"disabled"` - The type of the input item. Always `input_text`. + - `class BetaContainerNetworkPolicyAllowlist: …` - - `"input_text"` + - `allowed_domains: List[str]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + A list of allowed domains when type is `allowlist`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: Literal["allowlist"]` - - `mode: Literal["explicit"]` + Allow outbound network access only to specified domains. Always `allowlist`. - The breakpoint mode. Always `explicit`. + - `"allowlist"` - - `"explicit"` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `class BetaResponseInputImage: …` + Optional domain-scoped secrets for allowlisted domains. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `domain: str` - - `detail: Literal["low", "high", "auto", "original"]` + The domain associated with the secret. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `name: str` - - `"low"` + The name of the secret to inject for the domain. - - `"high"` + - `value: str` - - `"auto"` + The secret value to inject for the domain. - - `"original"` + - `type: Literal["code_interpreter"]` - - `type: Literal["input_image"]` + The type of the code interpreter tool. Always `code_interpreter`. - The type of the input item. Always `input_image`. + - `"code_interpreter"` - - `"input_image"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `file_id: Optional[str]` + The tool invocation context(s). - The ID of the file to be sent to the model. + - `"direct"` - - `image_url: Optional[str]` + - `"programmatic"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `class ProgrammaticToolCalling: …` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["programmatic_tool_calling"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The type of the tool. Always `programmatic_tool_calling`. - - `mode: Literal["explicit"]` + - `"programmatic_tool_calling"` - The breakpoint mode. Always `explicit`. + - `class ImageGeneration: …` - - `"explicit"` + A tool that generates images using the GPT image models. - - `class BetaResponseInputFile: …` + - `type: Literal["image_generation"]` - A file input to the model. + The type of the image generation tool. Always `image_generation`. - - `type: Literal["input_file"]` + - `"image_generation"` - The type of the input item. Always `input_file`. + - `action: Optional[Literal["generate", "edit", "auto"]]` - - `"input_file"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `"generate"` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"edit"` - `"auto"` - - `"low"` - - - `"high"` + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `file_data: Optional[str]` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - The content of the file to be sent to the model. + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `file_id: Optional[str]` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - The ID of the file to be sent to the model. + - `"transparent"` - - `file_url: Optional[str]` + - `"opaque"` - The URL of the file to be sent to the model. + - `"auto"` - - `filename: Optional[str]` + - `input_fidelity: Optional[Literal["high", "low"]]` - The name of the file to be sent to the model. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"high"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"low"` - - `mode: Literal["explicit"]` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - The breakpoint mode. Always `explicit`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"explicit"` + - `file_id: Optional[str]` - - `role: Literal["user", "system", "developer"]` + File ID for the mask image. - The role of the message input. One of `user`, `system`, or `developer`. + - `image_url: Optional[str]` - - `"user"` + Base64-encoded mask image. - - `"system"` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - - `"developer"` + The image generation model to use. Default: `gpt-image-1`. - - `type: Literal["message"]` + - `str` - The type of the message input. Always set to `message`. + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `"message"` + The image generation model to use. Default: `gpt-image-1`. - - `agent: Optional[Agent]` + - `"gpt-image-1"` - The agent that produced this item. + - `"gpt-image-1-mini"` - - `agent_name: str` + - `"gpt-image-2"` - The canonical name of the agent that produced this item. + - `"gpt-image-2-2026-04-21"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"gpt-image-1.5"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"chatgpt-image-latest"` - - `"in_progress"` + - `moderation: Optional[Literal["auto", "low"]]` - - `"completed"` + Moderation level for the generated image. Default: `auto`. - - `"incomplete"` + - `"auto"` -### Beta Response Input Text + - `"low"` -- `class BetaResponseInputText: …` + - `output_compression: Optional[int]` - A text input to the model. + Compression level for the output image. Default: 100. - - `text: str` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - The text input to the model. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `type: Literal["input_text"]` + - `"png"` - The type of the input item. Always `input_text`. + - `"webp"` - - `"input_text"` + - `"jpeg"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `partial_images: Optional[int]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `mode: Literal["explicit"]` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - The breakpoint mode. Always `explicit`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"explicit"` + - `"low"` -### Beta Response Input Text Content + - `"medium"` -- `class BetaResponseInputTextContent: …` + - `"high"` - A text input to the model. + - `"auto"` - - `text: str` + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - The text input to the model. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `type: Literal["input_text"]` + - `str` - The type of the input item. Always `input_text`. + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `"input_text"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"1024x1024"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"1024x1536"` - - `mode: Literal["explicit"]` + - `"1536x1024"` - The breakpoint mode. Always `explicit`. + - `"auto"` - - `"explicit"` + - `class LocalShell: …` -### Beta Response Item + A tool that allows the model to execute shell commands in a local environment. -- `BetaResponseItem` + - `type: Literal["local_shell"]` - Content item used to generate a response. + The type of the local shell tool. Always `local_shell`. - - `class BetaResponseInputMessageItem: …` + - `"local_shell"` - - `id: str` + - `class BetaFunctionShellTool: …` - The unique ID of the message input. + A tool that allows the model to execute shell commands. - - `content: BetaResponseInputMessageContentList` + - `type: Literal["shell"]` - A list of one or many input items to the model, containing different content - types. + The type of the shell tool. Always `shell`. - - `class BetaResponseInputText: …` + - `"shell"` - A text input to the model. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `text: str` + The tool invocation context(s). - The text input to the model. + - `"direct"` - - `type: Literal["input_text"]` + - `"programmatic"` - The type of the input item. Always `input_text`. + - `environment: Optional[Environment]` - - `"input_text"` + - `class BetaContainerAuto: …` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["container_auto"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Automatically creates a container for this request - - `mode: Literal["explicit"]` + - `"container_auto"` - The breakpoint mode. Always `explicit`. + - `file_ids: Optional[List[str]]` - - `"explicit"` + An optional list of uploaded files to make available to your code. - - `class BetaResponseInputImage: …` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The memory limit for the container. - - `detail: Literal["low", "high", "auto", "original"]` + - `"1g"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"4g"` - - `"low"` + - `"16g"` - - `"high"` + - `"64g"` - - `"auto"` + - `network_policy: Optional[NetworkPolicy]` - - `"original"` + Network access policy for the container. - - `type: Literal["input_image"]` + - `class BetaContainerNetworkPolicyDisabled: …` - The type of the input item. Always `input_image`. + - `class BetaContainerNetworkPolicyAllowlist: …` - - `"input_image"` + - `skills: Optional[List[Skill]]` - - `file_id: Optional[str]` + An optional list of skills referenced by id or inline data. - The ID of the file to be sent to the model. + - `class BetaSkillReference: …` - - `image_url: Optional[str]` + - `skill_id: str` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The ID of the referenced skill. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["skill_reference"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + References a skill created with the /v1/skills endpoint. - - `mode: Literal["explicit"]` + - `"skill_reference"` - The breakpoint mode. Always `explicit`. + - `version: Optional[str]` - - `"explicit"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `class BetaResponseInputFile: …` + - `class BetaInlineSkill: …` - A file input to the model. + - `description: str` - - `type: Literal["input_file"]` + The description of the skill. - The type of the input item. Always `input_file`. + - `name: str` - - `"input_file"` + The name of the skill. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `source: BetaInlineSkillSource` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + Inline skill payload - - `"auto"` + - `data: str` - - `"low"` + Base64-encoded skill zip bundle. - - `"high"` + - `media_type: Literal["application/zip"]` - - `file_data: Optional[str]` + The media type of the inline skill payload. Must be `application/zip`. - The content of the file to be sent to the model. + - `"application/zip"` - - `file_id: Optional[str]` + - `type: Literal["base64"]` - The ID of the file to be sent to the model. + The type of the inline skill source. Must be `base64`. - - `file_url: Optional[str]` + - `"base64"` - The URL of the file to be sent to the model. + - `type: Literal["inline"]` - - `filename: Optional[str]` + Defines an inline skill for this request. - The name of the file to be sent to the model. + - `"inline"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `class BetaLocalEnvironment: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: Literal["local"]` - - `mode: Literal["explicit"]` + Use a local computer environment. - The breakpoint mode. Always `explicit`. + - `"local"` - - `"explicit"` + - `skills: Optional[List[BetaLocalSkill]]` - - `role: Literal["user", "system", "developer"]` + An optional list of skills. - The role of the message input. One of `user`, `system`, or `developer`. + - `description: str` - - `"user"` + The description of the skill. - - `"system"` + - `name: str` - - `"developer"` + The name of the skill. - - `type: Literal["message"]` + - `path: str` - The type of the message input. Always set to `message`. + The path to the directory containing the skill. - - `"message"` + - `class BetaContainerReference: …` - - `agent: Optional[Agent]` + - `container_id: str` - The agent that produced this item. + The ID of the referenced container. - - `agent_name: str` + - `type: Literal["container_reference"]` - The canonical name of the agent that produced this item. + References a container created with the /v1/containers endpoint - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"container_reference"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class BetaCustomTool: …` - - `"in_progress"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `"completed"` + - `name: str` - - `"incomplete"` + The name of the custom tool, used to identify it in tool calls. - - `class BetaResponseOutputMessage: …` + - `type: Literal["custom"]` - An output message from the model. + The type of the custom tool. Always `custom`. - - `id: str` + - `"custom"` - The unique ID of the output message. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `content: List[Content]` + The tool invocation context(s). - The content of the output message. + - `"direct"` - - `class BetaResponseOutputText: …` + - `"programmatic"` - A text output from the model. + - `defer_loading: Optional[bool]` - - `annotations: List[Annotation]` + Whether this tool should be deferred and discovered via tool search. - The annotations of the text output. + - `description: Optional[str]` - - `class AnnotationFileCitation: …` + Optional description of the custom tool, used to provide more context. - A citation to a file. + - `format: Optional[Format]` - - `file_id: str` + The input format for the custom tool. Default is unconstrained text. - The ID of the file. + - `class FormatText: …` - - `filename: str` + Unconstrained free-form text. - The filename of the file cited. + - `type: Literal["text"]` - - `index: int` + Unconstrained text format. Always `text`. - The index of the file in the list of files. + - `"text"` - - `type: Literal["file_citation"]` + - `class FormatGrammar: …` - The type of the file citation. Always `file_citation`. + A grammar defined by the user. - - `"file_citation"` + - `definition: str` - - `class AnnotationURLCitation: …` + The grammar definition. - A citation for a web resource used to generate a model response. + - `syntax: Literal["lark", "regex"]` - - `end_index: int` + The syntax of the grammar definition. One of `lark` or `regex`. - The index of the last character of the URL citation in the message. + - `"lark"` - - `start_index: int` + - `"regex"` - The index of the first character of the URL citation in the message. + - `type: Literal["grammar"]` - - `title: str` + Grammar format. Always `grammar`. - The title of the web resource. + - `"grammar"` - - `type: Literal["url_citation"]` + - `class BetaNamespaceTool: …` - The type of the URL citation. Always `url_citation`. + Groups function/custom tools under a shared namespace. - - `"url_citation"` + - `description: str` - - `url: str` + A description of the namespace shown to the model. - The URL of the web resource. + - `name: str` - - `class AnnotationContainerFileCitation: …` + The namespace name used in tool calls (for example, `crm`). - A citation for a container file used to generate a model response. + - `tools: List[Tool]` - - `container_id: str` + The function/custom tools available inside this namespace. - The ID of the container file. + - `class ToolFunction: …` - - `end_index: int` + - `name: str` - The index of the last character of the container file citation in the message. + - `type: Literal["function"]` - - `file_id: str` + - `"function"` - The ID of the file. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `filename: str` + The tool invocation context(s). - The filename of the container file cited. + - `"direct"` - - `start_index: int` + - `"programmatic"` - The index of the first character of the container file citation in the message. + - `defer_loading: Optional[bool]` - - `type: Literal["container_file_citation"]` + Whether this function should be deferred and discovered via tool search. - The type of the container file citation. Always `container_file_citation`. + - `description: Optional[str]` - - `"container_file_citation"` + - `output_schema: Optional[Dict[str, object]]` - - `class AnnotationFilePath: …` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - A path to a file. + - `parameters: Optional[object]` - - `file_id: str` + - `strict: Optional[bool]` - The ID of the file. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `index: int` + - `class BetaCustomTool: …` - The index of the file in the list of files. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `type: Literal["file_path"]` + - `type: Literal["namespace"]` - The type of the file path. Always `file_path`. + The type of the tool. Always `namespace`. - - `"file_path"` + - `"namespace"` - - `text: str` + - `class BetaToolSearchTool: …` - The text output from the model. + Hosted or BYOT tool search configuration for deferred tools. - - `type: Literal["output_text"]` + - `type: Literal["tool_search"]` - The type of the output text. Always `output_text`. + The type of the tool. Always `tool_search`. - - `"output_text"` + - `"tool_search"` - - `logprobs: Optional[List[Logprob]]` + - `description: Optional[str]` - - `token: str` + Description shown to the model for a client-executed tool search tool. - - `bytes: List[int]` + - `execution: Optional[Literal["server", "client"]]` - - `logprob: float` + Whether tool search is executed by the server or by the client. - - `top_logprobs: List[LogprobTopLogprob]` + - `"server"` - - `token: str` + - `"client"` - - `bytes: List[int]` + - `parameters: Optional[object]` - - `logprob: float` + Parameter schema for a client-executed tool search tool. - - `class BetaResponseOutputRefusal: …` + - `class BetaWebSearchPreviewTool: …` - A refusal from the model. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `refusal: str` + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - The refusal explanation from the model. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `type: Literal["refusal"]` + - `"web_search_preview"` - The type of the refusal. Always `refusal`. + - `"web_search_preview_2025_03_11"` - - `"refusal"` + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `role: Literal["assistant"]` + - `"text"` - The role of the output message. Always `assistant`. + - `"image"` - - `"assistant"` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `status: Literal["in_progress", "completed", "incomplete"]` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"low"` - - `"in_progress"` + - `"medium"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `user_location: Optional[UserLocation]` - - `type: Literal["message"]` + The user's location. - The type of the output message. Always `message`. + - `type: Literal["approximate"]` - - `"message"` + The type of location approximation. Always `approximate`. - - `agent: Optional[Agent]` + - `"approximate"` - The agent that produced this item. + - `city: Optional[str]` - - `agent_name: str` + Free text input for the city of the user, e.g. `San Francisco`. - The canonical name of the agent that produced this item. + - `country: Optional[str]` - - `phase: Optional[Literal["commentary"]]` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `region: Optional[str]` - - `"commentary"` + Free text input for the region of the user, e.g. `California`. - - `class BetaResponseFileSearchToolCall: …` + - `timezone: Optional[str]` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `id: str` + - `class BetaApplyPatchTool: …` - The unique ID of the file search tool call. + Allows the assistant to create, delete, or update files using unified diffs. - - `queries: List[str]` + - `type: Literal["apply_patch"]` - The queries used to search for files. + The type of the tool. Always `apply_patch`. - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `"apply_patch"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"in_progress"` + The tool invocation context(s). - - `"searching"` + - `"direct"` - - `"completed"` + - `"programmatic"` - - `"incomplete"` + - `type: Literal["tool_search_output"]` - - `"failed"` + The item type. Always `tool_search_output`. - - `type: Literal["file_search_call"]` + - `"tool_search_output"` - The type of the file search tool call. Always `file_search_call`. + - `id: Optional[str]` - - `"file_search_call"` + The unique ID of this tool search output. - `agent: Optional[Agent]` @@ -105124,321 +114862,323 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `results: Optional[List[Result]]` + - `call_id: Optional[str]` - The results of the file search tool call. + The unique ID of the tool search call generated by the model. - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + - `execution: Optional[Literal["server", "client"]]` - 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, booleans, or numbers. + Whether tool search was executed by the server or by the client. - - `str` + - `"server"` - - `float` + - `"client"` - - `bool` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `file_id: Optional[str]` + The status of the tool search output. - The unique ID of the file. + - `"in_progress"` - - `filename: Optional[str]` + - `"completed"` - The name of the file. + - `"incomplete"` - - `score: Optional[float]` + - `class AdditionalTools: …` - The relevance score of the file - a value between 0 and 1. + - `role: Literal["developer"]` - - `text: Optional[str]` + The role that provided the additional tools. Only `developer` is supported. - The text that was retrieved from the file. + - `"developer"` - - `class BetaResponseComputerToolCall: …` + - `tools: List[BetaTool]` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + A list of additional tools made available at this item. - - `id: str` + - `class BetaFunctionTool: …` - The unique ID of the computer call. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `call_id: str` + - `class BetaFileSearchTool: …` - An identifier used when responding to the tool call with output. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `pending_safety_checks: List[PendingSafetyCheck]` + - `class BetaComputerTool: …` - The pending safety checks for the computer call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `id: str` + - `class BetaComputerUsePreviewTool: …` - The ID of the pending safety check. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `code: Optional[str]` + - `class BetaWebSearchTool: …` - The type of the pending safety check. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `message: Optional[str]` + - `class Mcp: …` - Details about the pending safety check. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `status: Literal["in_progress", "completed", "incomplete"]` + - `class CodeInterpreter: …` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A tool that runs Python code to help generate a response to a prompt. - - `"in_progress"` + - `class ProgrammaticToolCalling: …` - - `"completed"` + - `class ImageGeneration: …` - - `"incomplete"` + A tool that generates images using the GPT image models. - - `type: Literal["computer_call"]` + - `class LocalShell: …` - The type of the computer call. Always `computer_call`. + A tool that allows the model to execute shell commands in a local environment. - - `"computer_call"` + - `class BetaFunctionShellTool: …` - - `action: Optional[BetaComputerAction]` + A tool that allows the model to execute shell commands. - A click action. + - `class BetaCustomTool: …` - - `class Click: …` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - A click action. + - `class BetaNamespaceTool: …` - - `button: Literal["left", "right", "wheel", 2 more]` + Groups function/custom tools under a shared namespace. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `class BetaToolSearchTool: …` - - `"left"` + Hosted or BYOT tool search configuration for deferred tools. - - `"right"` + - `class BetaWebSearchPreviewTool: …` - - `"wheel"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"back"` + - `class BetaApplyPatchTool: …` - - `"forward"` + Allows the assistant to create, delete, or update files using unified diffs. - - `type: Literal["click"]` + - `type: Literal["additional_tools"]` - Specifies the event type. For a click action, this property is always `click`. + The item type. Always `additional_tools`. - - `"click"` + - `"additional_tools"` - - `x: int` + - `id: Optional[str]` - The x-coordinate where the click occurred. + The unique ID of this additional tools item. - - `y: int` + - `agent: Optional[AdditionalToolsAgent]` - The y-coordinate where the click occurred. + The agent that produced this item. - - `keys: Optional[List[str]]` + - `agent_name: str` - The keys being held while clicking. + The canonical name of the agent that produced this item. - - `class DoubleClick: …` + - `class BetaResponseReasoningItem: …` - A double click action. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `keys: Optional[List[str]]` + - `id: str` - The keys being held while double-clicking. + The unique identifier of the reasoning content. - - `type: Literal["double_click"]` + - `summary: List[Summary]` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Reasoning summary content. - - `"double_click"` + - `text: str` - - `x: int` + A summary of the reasoning output from the model so far. - The x-coordinate where the double click occurred. + - `type: Literal["summary_text"]` - - `y: int` + The type of the object. Always `summary_text`. - The y-coordinate where the double click occurred. + - `"summary_text"` - - `class Drag: …` + - `type: Literal["reasoning"]` - A drag action. + The type of the object. Always `reasoning`. - - `path: List[DragPath]` + - `"reasoning"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `agent: Optional[Agent]` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The agent that produced this item. - - `x: int` + - `agent_name: str` - The x-coordinate. + The canonical name of the agent that produced this item. - - `y: int` + - `content: Optional[List[Content]]` - The y-coordinate. + Reasoning text content. - - `type: Literal["drag"]` + - `text: str` - Specifies the event type. For a drag action, this property is always set to `drag`. + The reasoning text from the model. - - `"drag"` + - `type: Literal["reasoning_text"]` - - `keys: Optional[List[str]]` + The type of the reasoning text. Always `reasoning_text`. - The keys being held while dragging the mouse. + - `"reasoning_text"` - - `class Keypress: …` + - `encrypted_content: Optional[str]` - A collection of keypresses the model would like to perform. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `keys: List[str]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: Literal["keypress"]` + - `"in_progress"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"completed"` - - `"keypress"` + - `"incomplete"` - - `class Move: …` + - `class BetaResponseCompactionItemParam: …` - A mouse move action. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `type: Literal["move"]` + - `encrypted_content: str` - Specifies the event type. For a move action, this property is always set to `move`. + The encrypted content of the compaction summary. - - `"move"` + - `type: Literal["compaction"]` - - `x: int` + The type of the item. Always `compaction`. - The x-coordinate to move to. + - `"compaction"` - - `y: int` + - `id: Optional[str]` - The y-coordinate to move to. + The ID of the compaction item. - - `keys: Optional[List[str]]` + - `agent: Optional[Agent]` - The keys being held while moving the mouse. + The agent that produced this item. - - `class Screenshot: …` + - `agent_name: str` - A screenshot action. + The canonical name of the agent that produced this item. - - `type: Literal["screenshot"]` + - `class ImageGenerationCall: …` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + An image generation request made by the model. - - `"screenshot"` + - `id: str` - - `class Scroll: …` + The unique ID of the image generation call. - A scroll action. + - `result: Optional[str]` - - `scroll_x: int` + The generated image encoded in base64. - The horizontal scroll distance. + - `status: Literal["in_progress", "completed", "generating", "failed"]` - - `scroll_y: int` + The status of the image generation call. - The vertical scroll distance. + - `"in_progress"` - - `type: Literal["scroll"]` + - `"completed"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"generating"` - - `"scroll"` + - `"failed"` - - `x: int` + - `type: Literal["image_generation_call"]` - The x-coordinate where the scroll occurred. + The type of the image generation call. Always `image_generation_call`. - - `y: int` + - `"image_generation_call"` - The y-coordinate where the scroll occurred. + - `agent: Optional[ImageGenerationCallAgent]` - - `keys: Optional[List[str]]` + The agent that produced this item. - The keys being held while scrolling. + - `agent_name: str` - - `class Type: …` + The canonical name of the agent that produced this item. - An action to type in text. + - `class BetaResponseCodeInterpreterToolCall: …` - - `text: str` + A tool call to run code. - The text to type. + - `id: str` - - `type: Literal["type"]` + The unique ID of the code interpreter tool call. - Specifies the event type. For a type action, this property is always set to `type`. + - `code: Optional[str]` - - `"type"` + The code to run, or null if not available. - - `class Wait: …` + - `container_id: str` - A wait action. + The ID of the container used to run the code. - - `type: Literal["wait"]` + - `outputs: Optional[List[Output]]` - Specifies the event type. For a wait action, this property is always set to `wait`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"wait"` + - `class OutputLogs: …` - - `actions: Optional[BetaComputerActionList]` + The logs output from the code interpreter. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `logs: str` - - `class Click: …` + The logs output from the code interpreter. - A click action. + - `type: Literal["logs"]` - - `class DoubleClick: …` + The type of the output. Always `logs`. - A double click action. + - `"logs"` - - `class Drag: …` + - `class OutputImage: …` - A drag action. + The image output from the code interpreter. - - `class Keypress: …` + - `type: Literal["image"]` - A collection of keypresses the model would like to perform. + The type of the output. Always `image`. - - `class Move: …` + - `"image"` - A mouse move action. + - `url: str` - - `class Screenshot: …` + The URL of the image output from the code interpreter. - A screenshot action. + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - - `class Scroll: …` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - A scroll action. + - `"in_progress"` - - `class Type: …` + - `"completed"` - An action to type in text. + - `"incomplete"` - - `class Wait: …` + - `"interpreting"` - A wait action. + - `"failed"` + + - `type: Literal["code_interpreter_call"]` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` - `agent: Optional[Agent]` @@ -105448,72 +115188,65 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem: …` - - - `id: str` - - The unique ID of the computer call tool output. + - `class LocalShellCall: …` - - `call_id: str` + A tool call to run a command on the local shell. - The ID of the computer tool call that produced the output. + - `id: str` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The unique ID of the local shell call. - A computer screenshot image used with the computer use tool. + - `action: LocalShellCallAction` - - `type: Literal["computer_screenshot"]` + Execute a shell command on the server. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `command: List[str]` - - `"computer_screenshot"` + The command to run. - - `file_id: Optional[str]` + - `env: Dict[str, str]` - The identifier of an uploaded file that contains the screenshot. + Environment variables to set for the command. - - `image_url: Optional[str]` + - `type: Literal["exec"]` - The URL of the screenshot image. + The type of the local shell action. Always `exec`. - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + - `"exec"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `timeout_ms: Optional[int]` - - `"completed"` + Optional timeout in milliseconds for the command. - - `"incomplete"` + - `user: Optional[str]` - - `"failed"` + Optional user to run the command as. - - `"in_progress"` + - `working_directory: Optional[str]` - - `type: Literal["computer_call_output"]` + Optional working directory to run the command in. - The type of the computer tool call output. Always `computer_call_output`. + - `call_id: str` - - `"computer_call_output"` + The unique ID of the local shell tool call generated by the model. - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The safety checks reported by the API that have been acknowledged by the - developer. + The status of the local shell call. - - `id: str` + - `"in_progress"` - The ID of the pending safety check. + - `"completed"` - - `code: Optional[str]` + - `"incomplete"` - The type of the pending safety check. + - `type: Literal["local_shell_call"]` - - `message: Optional[str]` + The type of the local shell call. Always `local_shell_call`. - Details about the pending safety check. + - `"local_shell_call"` - - `agent: Optional[Agent]` + - `agent: Optional[LocalShellCallAgent]` The agent that produced this item. @@ -105521,127 +115254,119 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `class BetaResponseFunctionWebSearch: …` + - `class LocalShellCallOutput: …` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The output of a local shell tool call. - `id: str` - The unique ID of the web search tool call. + The unique ID of the local shell tool call generated by the model. - - `action: Action` + - `output: str` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + A JSON string of the output of the local shell tool call. - - `class ActionSearch: …` + - `type: Literal["local_shell_call_output"]` - Action type "search" - Performs a web search query. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `type: Literal["search"]` + - `"local_shell_call_output"` - The action type. + - `agent: Optional[LocalShellCallOutputAgent]` - - `"search"` + The agent that produced this item. - - `queries: Optional[List[str]]` + - `agent_name: str` - The search queries. + The canonical name of the agent that produced this item. - - `query: Optional[str]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The search query. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `sources: Optional[List[ActionSearchSource]]` + - `"in_progress"` - The sources used in the search. + - `"completed"` - - `type: Literal["url"]` + - `"incomplete"` - The type of source. Always `url`. + - `class ShellCall: …` - - `"url"` + A tool representing a request to execute one or more shell commands. - - `url: str` + - `action: ShellCallAction` - The URL of the source. + The shell commands and limits that describe how to run the tool call. - - `class ActionOpenPage: …` + - `commands: List[str]` - Action type "open_page" - Opens a specific URL from search results. + Ordered shell commands for the execution environment to run. - - `type: Literal["open_page"]` + - `max_output_length: Optional[int]` - The action type. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `"open_page"` + - `timeout_ms: Optional[int]` - - `url: Optional[str]` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The URL opened by the model. + - `call_id: str` - - `class ActionFindInPage: …` + The unique ID of the shell tool call generated by the model. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `type: Literal["shell_call"]` - - `pattern: str` + The type of the item. Always `shell_call`. - The pattern or text to search for within the page. + - `"shell_call"` - - `type: Literal["find_in_page"]` + - `id: Optional[str]` - The action type. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"find_in_page"` + - `agent: Optional[ShellCallAgent]` - - `url: str` + The agent that produced this item. - The URL of the page searched for the pattern. + - `agent_name: str` - - `status: Literal["in_progress", "searching", "completed", "failed"]` + The canonical name of the agent that produced this item. - The status of the web search tool call. + - `caller: Optional[ShellCallCaller]` - - `"in_progress"` + The execution context that produced this tool call. - - `"searching"` + - `class ShellCallCallerDirect: …` - - `"completed"` + - `type: Literal["direct"]` - - `"failed"` + The caller type. Always `direct`. - - `type: Literal["web_search_call"]` + - `"direct"` - The type of the web search tool call. Always `web_search_call`. + - `class ShellCallCallerProgram: …` - - `"web_search_call"` + - `caller_id: str` - - `agent: Optional[Agent]` + The call ID of the program item that produced this tool call. - The agent that produced this item. + - `type: Literal["program"]` - - `agent_name: str` + The caller type. Always `program`. - The canonical name of the agent that produced this item. + - `"program"` - - `class BetaResponseFunctionToolCallItem: …` + - `environment: Optional[ShellCallEnvironment]` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The environment to execute the shell commands in. - - `id: str` + - `class BetaLocalEnvironment: …` - The unique ID of the function tool call. + - `class BetaContainerReference: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -105649,63 +115374,65 @@ print(compacted_response) - `"incomplete"` - - `created_by: Optional[str]` + - `class ShellCallOutput: …` - The identifier of the actor that created the item. + The streamed output items emitted by a shell tool call. - - `class BetaResponseFunctionToolCallOutputItem: …` + - `call_id: str` - - `id: str` + The unique ID of the shell tool call generated by the model. - The unique ID of the function call tool output. + - `output: List[BetaResponseFunctionShellCallOutputContent]` - - `call_id: str` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The unique ID of the function tool call generated by the model. + - `outcome: Outcome` - - `output: Union[str, List[OutputOutputContentList]]` + The exit or timeout outcome associated with this shell call. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `class OutcomeTimeout: …` - - `str` + Indicates that the shell call exceeded its configured time limit. - A string of the output of the function call. + - `type: Literal["timeout"]` - - `List[OutputOutputContentList]` + The outcome type. Always `timeout`. - Text, image, or file output of the function call. + - `"timeout"` - - `class BetaResponseInputText: …` + - `class OutcomeExit: …` - A text input to the model. + Indicates that the shell commands finished and returned an exit code. - - `class BetaResponseInputImage: …` + - `exit_code: int` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The exit code returned by the shell process. - - `class BetaResponseInputFile: …` + - `type: Literal["exit"]` - A file input to the model. + The outcome type. Always `exit`. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"exit"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `stderr: str` - - `"in_progress"` + Captured stderr output for the shell call. - - `"completed"` + - `stdout: str` - - `"incomplete"` + Captured stdout output for the shell call. - - `type: Literal["function_call_output"]` + - `type: Literal["shell_call_output"]` - The type of the function tool call output. Always `function_call_output`. + The type of the item. Always `shell_call_output`. - - `"function_call_output"` + - `"shell_call_output"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: Optional[ShellCallOutputAgent]` The agent that produced this item. @@ -105713,11 +115440,11 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ShellCallOutputCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ShellCallOutputCallerDirect: …` - `type: Literal["direct"]` @@ -105725,7 +115452,7 @@ print(compacted_response) - `"direct"` - - `class CallerProgram: …` + - `class ShellCallOutputCallerProgram: …` - `caller_id: str` @@ -105737,249 +115464,233 @@ print(compacted_response) - `"program"` - - `created_by: Optional[str]` - - The identifier of the actor that created the item. + - `max_output_length: Optional[int]` - - `class AgentMessage: …` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `id: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The unique ID of the agent message. + The status of the shell call output. - - `author: str` + - `"in_progress"` - The sending agent identity. + - `"completed"` - - `content: List[AgentMessageContent]` + - `"incomplete"` - Encrypted content sent between agents. + - `class ApplyPatchCall: …` - - `class BetaResponseInputText: …` + A tool call representing a request to create, delete, or update files using diff patches. - A text input to the model. + - `call_id: str` - - `class BetaResponseOutputText: …` + The unique ID of the apply patch tool call generated by the model. - A text output from the model. + - `operation: ApplyPatchCallOperation` - - `class AgentMessageContentText: …` + The specific create, delete, or update instruction for the apply_patch tool call. - A text content. + - `class ApplyPatchCallOperationCreateFile: …` - - `text: str` + Instruction for creating a new file via the apply_patch tool. - - `type: Literal["text"]` + - `diff: str` - - `"text"` + Unified diff content to apply when creating the file. - - `class AgentMessageContentSummaryText: …` + - `path: str` - A summary text from the model. + Path of the file to create relative to the workspace root. - - `text: str` + - `type: Literal["create_file"]` - A summary of the reasoning output from the model so far. + The operation type. Always `create_file`. - - `type: Literal["summary_text"]` + - `"create_file"` - The type of the object. Always `summary_text`. + - `class ApplyPatchCallOperationDeleteFile: …` - - `"summary_text"` + Instruction for deleting an existing file via the apply_patch tool. - - `class AgentMessageContentReasoningText: …` + - `path: str` - Reasoning text from the model. + Path of the file to delete relative to the workspace root. - - `text: str` + - `type: Literal["delete_file"]` - The reasoning text from the model. + The operation type. Always `delete_file`. - - `type: Literal["reasoning_text"]` + - `"delete_file"` - The type of the reasoning text. Always `reasoning_text`. + - `class ApplyPatchCallOperationUpdateFile: …` - - `"reasoning_text"` + Instruction for updating an existing file via the apply_patch tool. - - `class BetaResponseOutputRefusal: …` + - `diff: str` - A refusal from the model. + Unified diff content to apply to the existing file. - - `class BetaResponseInputImage: …` + - `path: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Path of the file to update relative to the workspace root. - - `class AgentMessageContentComputerScreenshot: …` + - `type: Literal["update_file"]` - A screenshot of a computer. + The operation type. Always `update_file`. - - `detail: Literal["low", "high", "auto", "original"]` + - `"update_file"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `status: Literal["in_progress", "completed"]` - - `"low"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"high"` + - `"in_progress"` - - `"auto"` + - `"completed"` - - `"original"` + - `type: Literal["apply_patch_call"]` - - `file_id: Optional[str]` + The type of the item. Always `apply_patch_call`. - The identifier of an uploaded file that contains the screenshot. + - `"apply_patch_call"` - - `image_url: Optional[str]` + - `id: Optional[str]` - The URL of the screenshot image. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `type: Literal["computer_screenshot"]` + - `agent: Optional[ApplyPatchCallAgent]` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The agent that produced this item. - - `"computer_screenshot"` + - `agent_name: str` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + The canonical name of the agent that produced this item. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `caller: Optional[ApplyPatchCallCaller]` - - `mode: Literal["explicit"]` + The execution context that produced this tool call. - The breakpoint mode. Always `explicit`. + - `class ApplyPatchCallCallerDirect: …` - - `"explicit"` + - `type: Literal["direct"]` - - `class BetaResponseInputFile: …` + The caller type. Always `direct`. - A file input to the model. + - `"direct"` - - `class AgentMessageContentEncryptedContent: …` + - `class ApplyPatchCallCallerProgram: …` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `caller_id: str` - - `encrypted_content: str` + The call ID of the program item that produced this tool call. - Opaque encrypted content. + - `type: Literal["program"]` - - `type: Literal["encrypted_content"]` + The caller type. Always `program`. - The type of the input item. Always `encrypted_content`. + - `"program"` - - `"encrypted_content"` + - `class ApplyPatchCallOutput: …` - - `recipient: str` + The streamed output emitted by an apply patch tool call. - The destination agent identity. + - `call_id: str` - - `type: Literal["agent_message"]` + The unique ID of the apply patch tool call generated by the model. - The type of the item. Always `agent_message`. + - `status: Literal["completed", "failed"]` - - `"agent_message"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `agent: Optional[AgentMessageAgent]` + - `"completed"` - The agent that produced this item. + - `"failed"` - - `agent_name: str` + - `type: Literal["apply_patch_call_output"]` - The canonical name of the agent that produced this item. + The type of the item. Always `apply_patch_call_output`. - - `class MultiAgentCall: …` + - `"apply_patch_call_output"` - - `id: str` + - `id: Optional[str]` - The unique ID of the multi-agent call item. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `agent: Optional[ApplyPatchCallOutputAgent]` - The multi-agent action to execute. + The agent that produced this item. - - `"spawn_agent"` + - `agent_name: str` - - `"interrupt_agent"` + The canonical name of the agent that produced this item. - - `"list_agents"` + - `caller: Optional[ApplyPatchCallOutputCaller]` - - `"send_message"` + The execution context that produced this tool call. - - `"followup_task"` + - `class ApplyPatchCallOutputCallerDirect: …` - - `"wait_agent"` + - `type: Literal["direct"]` - - `arguments: str` + The caller type. Always `direct`. - The JSON string of arguments generated for the action. + - `"direct"` - - `call_id: str` + - `class ApplyPatchCallOutputCallerProgram: …` - The unique ID linking this call to its output. + - `caller_id: str` - - `type: Literal["multi_agent_call"]` + The call ID of the program item that produced this tool call. - The type of the multi-agent call. Always `multi_agent_call`. + - `type: Literal["program"]` - - `"multi_agent_call"` + The caller type. Always `program`. - - `agent: Optional[MultiAgentCallAgent]` + - `"program"` - The agent that produced this item. + - `output: Optional[str]` - - `agent_name: str` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - The canonical name of the agent that produced this item. + - `class McpListTools: …` - - `class MultiAgentCallOutput: …` + A list of tools available on an MCP server. - `id: str` - The unique ID of the multi-agent call output item. - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` + The unique ID of the list. - - `"wait_agent"` + - `server_label: str` - - `call_id: str` + The label of the MCP server. - The unique ID of the multi-agent call. + - `tools: List[McpListToolsTool]` - - `output: List[BetaResponseOutputText]` + The tools available on the server. - Text output returned by the multi-agent action. + - `input_schema: object` - - `annotations: List[Annotation]` + The JSON schema describing the tool's input. - The annotations of the text output. + - `name: str` - - `text: str` + The name of the tool. - The text output from the model. + - `annotations: Optional[object]` - - `type: Literal["output_text"]` + Additional annotations about the tool. - The type of the output text. Always `output_text`. + - `description: Optional[str]` - - `logprobs: Optional[List[Logprob]]` + The description of the tool. - - `type: Literal["multi_agent_call_output"]` + - `type: Literal["mcp_list_tools"]` - The type of the multi-agent result. Always `multi_agent_call_output`. + The type of the item. Always `mcp_list_tools`. - - `"multi_agent_call_output"` + - `"mcp_list_tools"` - - `agent: Optional[MultiAgentCallOutputAgent]` + - `agent: Optional[McpListToolsAgent]` The agent that produced this item. @@ -105987,45 +115698,37 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall: …` - - - `id: str` - - The unique ID of the tool search call item. - - - `arguments: object` - - Arguments used for the tool search call. + - `error: Optional[str]` - - `call_id: Optional[str]` + Error message if the server could not list tools. - The unique ID of the tool search call generated by the model. + - `class McpApprovalRequest: …` - - `execution: Literal["server", "client"]` + A request for human approval of a tool invocation. - Whether tool search was executed by the server or by the client. + - `id: str` - - `"server"` + The unique ID of the approval request. - - `"client"` + - `arguments: str` - - `status: Literal["in_progress", "completed", "incomplete"]` + A JSON string of arguments for the tool. - The status of the tool search call item that was recorded. + - `name: str` - - `"in_progress"` + The name of the tool to run. - - `"completed"` + - `server_label: str` - - `"incomplete"` + The label of the MCP server making the request. - - `type: Literal["tool_search_call"]` + - `type: Literal["mcp_approval_request"]` - The type of the item. Always `tool_search_call`. + The type of the item. Always `mcp_approval_request`. - - `"tool_search_call"` + - `"mcp_approval_request"` - - `agent: Optional[Agent]` + - `agent: Optional[McpApprovalRequestAgent]` The agent that produced this item. @@ -106033,1133 +115736,1106 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` + - `class McpApprovalResponse: …` - The identifier of the actor that created the item. + A response to an MCP approval request. - - `class BetaResponseToolSearchOutputItem: …` + - `approval_request_id: str` - - `id: str` + The ID of the approval request being answered. - The unique ID of the tool search output item. + - `approve: bool` - - `call_id: Optional[str]` + Whether the request was approved. - The unique ID of the tool search call generated by the model. + - `type: Literal["mcp_approval_response"]` - - `execution: Literal["server", "client"]` + The type of the item. Always `mcp_approval_response`. - Whether tool search was executed by the server or by the client. + - `"mcp_approval_response"` - - `"server"` + - `id: Optional[str]` - - `"client"` + The unique ID of the approval response - - `status: Literal["in_progress", "completed", "incomplete"]` + - `agent: Optional[McpApprovalResponseAgent]` - The status of the tool search output item that was recorded. + The agent that produced this item. - - `"in_progress"` + - `agent_name: str` - - `"completed"` + The canonical name of the agent that produced this item. - - `"incomplete"` + - `reason: Optional[str]` - - `tools: List[BetaTool]` + Optional reason for the decision. - The loaded tool definitions returned by tool search. + - `class McpCall: …` - - `class BetaFunctionTool: …` + An invocation of a tool on an MCP server. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `id: str` - - `name: str` + The unique ID of the tool call. - The name of the function to call. + - `arguments: str` - - `parameters: Optional[Dict[str, object]]` + A JSON string of the arguments passed to the tool. - A JSON schema object describing the parameters of the function. + - `name: str` - - `strict: Optional[bool]` + The name of the tool that was run. - Whether strict parameter validation is enforced for this function tool. + - `server_label: str` - - `type: Literal["function"]` + The label of the MCP server running the tool. - The type of the function tool. Always `function`. + - `type: Literal["mcp_call"]` - - `"function"` + The type of the item. Always `mcp_call`. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"mcp_call"` - The tool invocation context(s). + - `agent: Optional[McpCallAgent]` - - `"direct"` + The agent that produced this item. - - `"programmatic"` + - `agent_name: str` - - `defer_loading: Optional[bool]` + The canonical name of the agent that produced this item. - Whether this function is deferred and loaded via tool search. + - `approval_request_id: Optional[str]` - - `description: Optional[str]` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - A description of the function. Used by the model to determine whether or not to call the function. + - `error: Optional[str]` - - `output_schema: Optional[Dict[str, object]]` + The error from the tool call, if any. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `output: Optional[str]` - - `class BetaFileSearchTool: …` + The output from the tool call. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - `type: Literal["file_search"]` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The type of the file search tool. Always `file_search`. + - `"in_progress"` - - `"file_search"` + - `"completed"` - - `vector_store_ids: List[str]` + - `"incomplete"` - The IDs of the vector stores to search. + - `"calling"` - - `filters: Optional[Filters]` + - `"failed"` - A filter to apply. + - `class BetaResponseCustomToolCallOutput: …` - - `class FiltersComparisonFilter: …` + The output of a custom tool call from your code, being sent back to the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `call_id: str` - - `key: str` + The call ID, used to map this custom tool call output to a custom tool call. - The key to compare against the value. + - `output: Union[str, List[OutputOutputContentList]]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `str` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + A string of the output of the custom tool call. - - `"eq"` + - `List[OutputOutputContentList]` - - `"ne"` + Text, image, or file output of the custom tool call. - - `"gt"` + - `class BetaResponseInputText: …` - - `"gte"` + A text input to the model. - - `"lt"` + - `class BetaResponseInputImage: …` - - `"lte"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"in"` + - `class BetaResponseInputFile: …` - - `"nin"` + A file input to the model. - - `value: Union[str, float, bool, List[object]]` + - `type: Literal["custom_tool_call_output"]` - The value to compare against the attribute key; supports string, number, or boolean types. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `str` + - `"custom_tool_call_output"` - - `float` + - `id: Optional[str]` - - `bool` + The unique ID of the custom tool call output in the OpenAI platform. - - `List[object]` + - `agent: Optional[Agent]` - - `class FiltersCompoundFilter: …` + The agent that produced this item. - Combine multiple filters using `and` or `or`. + - `agent_name: str` - - `filters: List[FiltersCompoundFilterFilter]` + The canonical name of the agent that produced this item. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `caller: Optional[Caller]` - - `class FiltersCompoundFilterFilterComparisonFilter: …` + The execution context that produced this tool call. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `class CallerDirect: …` - - `key: str` + - `type: Literal["direct"]` - The key to compare against the value. + The caller type. Always `direct`. - - `type: Literal["eq", "ne", "gt", 5 more]` + - `"direct"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `class CallerProgram: …` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `caller_id: str` - - `"eq"` + The call ID of the program item that produced this tool call. - - `"ne"` + - `type: Literal["program"]` - - `"gt"` + The caller type. Always `program`. - - `"gte"` + - `"program"` - - `"lt"` + - `class BetaResponseCustomToolCall: …` - - `"lte"` + A call to a custom tool created by the model. - - `"in"` + - `call_id: str` - - `"nin"` + An identifier used to map this custom tool call to a tool call output. - - `value: Union[str, float, bool, List[object]]` + - `input: str` - The value to compare against the attribute key; supports string, number, or boolean types. + The input for the custom tool call generated by the model. - - `str` + - `name: str` - - `float` + The name of the custom tool being called. - - `bool` + - `type: Literal["custom_tool_call"]` - - `List[object]` + The type of the custom tool call. Always `custom_tool_call`. - - `object` + - `"custom_tool_call"` - - `type: Literal["and", "or"]` + - `id: Optional[str]` - Type of operation: `and` or `or`. + The unique ID of the custom tool call in the OpenAI platform. - - `"and"` + - `agent: Optional[Agent]` - - `"or"` + The agent that produced this item. - - `max_num_results: Optional[int]` + - `agent_name: str` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The canonical name of the agent that produced this item. - - `ranking_options: Optional[RankingOptions]` + - `caller: Optional[Caller]` - Ranking options for search. + The execution context that produced this tool call. - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + - `class CallerDirect: …` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `type: Literal["direct"]` - - `embedding_weight: float` + - `"direct"` - The weight of the embedding in the reciprocal ranking fusion. + - `class CallerProgram: …` - - `text_weight: float` + - `caller_id: str` - The weight of the text in the reciprocal ranking fusion. + The call ID of the program item that produced this tool call. - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + - `type: Literal["program"]` - The ranker to use for the file search. + - `"program"` - - `"auto"` + - `namespace: Optional[str]` - - `"default-2024-11-15"` + The namespace of the custom tool being called. - - `score_threshold: Optional[float]` + - `class CompactionTrigger: …` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + Compacts the current context. Must be the final input item. - - `class BetaComputerTool: …` + - `type: Literal["compaction_trigger"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the item. Always `compaction_trigger`. - - `type: Literal["computer"]` + - `"compaction_trigger"` - The type of the computer tool. Always `computer`. + - `agent: Optional[CompactionTriggerAgent]` - - `"computer"` + The agent that produced this item. - - `class BetaComputerUsePreviewTool: …` + - `agent_name: str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The canonical name of the agent that produced this item. - - `display_height: int` + - `class ItemReference: …` - The height of the computer display. + An internal identifier for an item to reference. - - `display_width: int` + - `id: str` - The width of the computer display. + The ID of the item to reference. - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `agent: Optional[ItemReferenceAgent]` - The type of computer environment to control. + The agent that produced this item. - - `"windows"` + - `agent_name: str` - - `"mac"` + The canonical name of the agent that produced this item. - - `"linux"` + - `type: Optional[Literal["item_reference"]]` - - `"ubuntu"` + The type of item to reference. Always `item_reference`. - - `"browser"` + - `"item_reference"` - - `type: Literal["computer_use_preview"]` + - `class Program: …` - The type of the computer use tool. Always `computer_use_preview`. + - `id: str` - - `"computer_use_preview"` + The unique ID of this program item. - - `class BetaWebSearchTool: …` + - `call_id: str` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The stable call ID of the program item. - - `type: Literal["web_search", "web_search_2025_08_26"]` + - `code: str` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The JavaScript source executed by programmatic tool calling. - - `"web_search"` + - `fingerprint: str` - - `"web_search_2025_08_26"` + Opaque program replay fingerprint that must be round-tripped. - - `filters: Optional[Filters]` + - `type: Literal["program"]` - Filters for the search. + The item type. Always `program`. - - `allowed_domains: Optional[List[str]]` + - `"program"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `agent: Optional[ProgramAgent]` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The agent that produced this item. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `agent_name: str` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The canonical name of the agent that produced this item. - - `"low"` + - `class ProgramOutput: …` - - `"medium"` + - `id: str` - - `"high"` + The unique ID of this program output item. - - `user_location: Optional[UserLocation]` + - `call_id: str` - The approximate location of the user. + The call ID of the program item. - - `city: Optional[str]` + - `result: str` - Free text input for the city of the user, e.g. `San Francisco`. + The result produced by the program item. - - `country: Optional[str]` + - `status: Literal["completed", "incomplete"]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The terminal status of the program output. - - `region: Optional[str]` + - `"completed"` - Free text input for the region of the user, e.g. `California`. + - `"incomplete"` - - `timezone: Optional[str]` + - `type: Literal["program_output"]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The item type. Always `program_output`. - - `type: Optional[Literal["approximate"]]` + - `"program_output"` - The type of location approximation. Always `approximate`. + - `agent: Optional[ProgramOutputAgent]` - - `"approximate"` + The agent that produced this item. - - `class Mcp: …` + - `agent_name: str` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The canonical name of the agent that produced this item. - - `server_label: str` + - `metadata: Optional[Dict[str, str]]` - A label for this MCP server, used to identify it in tool calls. + 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. - - `type: Literal["mcp"]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of the MCP tool. Always `mcp`. + - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` - - `"mcp"` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` - The tool invocation context(s). + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `"direct"` + - `"gpt-5.6-sol"` - - `"programmatic"` + - `"gpt-5.6-terra"` - - `allowed_tools: Optional[McpAllowedTools]` + - `"gpt-5.6-luna"` - List of allowed tool names or a filter object. + - `"gpt-5.4"` - - `List[str]` + - `"gpt-5.4-mini"` - A string array of allowed tool names + - `"gpt-5.4-nano"` - - `class McpAllowedToolsMcpToolFilter: …` + - `"gpt-5.4-mini-2026-03-17"` - A filter object to specify which tools are allowed. + - `"gpt-5.4-nano-2026-03-17"` - - `read_only: Optional[bool]` + - `"gpt-5.3-chat-latest"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"gpt-5.2"` - - `tool_names: Optional[List[str]]` + - `"gpt-5.2-2025-12-11"` - List of allowed tool names. + - `"gpt-5.2-chat-latest"` - - `authorization: Optional[str]` + - `"gpt-5.2-pro"` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `"gpt-5.2-pro-2025-12-11"` - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + - `"gpt-5.1"` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `"gpt-5.1-2025-11-13"` - Currently supported `connector_id` values are: + - `"gpt-5.1-codex"` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `"gpt-5.1-mini"` - - `"connector_dropbox"` + - `"gpt-5.1-chat-latest"` - - `"connector_gmail"` + - `"gpt-5"` - - `"connector_googlecalendar"` + - `"gpt-5-mini"` - - `"connector_googledrive"` + - `"gpt-5-nano"` - - `"connector_microsoftteams"` + - `"gpt-5-2025-08-07"` - - `"connector_outlookcalendar"` + - `"gpt-5-mini-2025-08-07"` - - `"connector_outlookemail"` + - `"gpt-5-nano-2025-08-07"` - - `"connector_sharepoint"` + - `"gpt-5-chat-latest"` - - `defer_loading: Optional[bool]` + - `"gpt-4.1"` - Whether this MCP tool is deferred and discovered via tool search. + - `"gpt-4.1-mini"` - - `headers: Optional[Dict[str, str]]` + - `"gpt-4.1-nano"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"gpt-4.1-2025-04-14"` - - `require_approval: Optional[McpRequireApproval]` + - `"gpt-4.1-mini-2025-04-14"` - Specify which of the MCP server's tools require approval. + - `"gpt-4.1-nano-2025-04-14"` - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `"o4-mini"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"o4-mini-2025-04-16"` - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `"o3"` - A filter object to specify which tools are allowed. + - `"o3-2025-04-16"` - - `read_only: Optional[bool]` + - `"o3-mini"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"o3-mini-2025-01-31"` - - `tool_names: Optional[List[str]]` + - `"o1"` - List of allowed tool names. + - `"o1-2024-12-17"` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + - `"o1-preview"` - A filter object to specify which tools are allowed. + - `"o1-preview-2024-09-12"` - - `read_only: Optional[bool]` + - `"o1-mini"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"o1-mini-2024-09-12"` - - `tool_names: Optional[List[str]]` + - `"gpt-4o"` - List of allowed tool names. + - `"gpt-4o-2024-11-20"` - - `Literal["always", "never"]` + - `"gpt-4o-2024-08-06"` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `"gpt-4o-2024-05-13"` - - `"always"` + - `"gpt-4o-audio-preview"` - - `"never"` + - `"gpt-4o-audio-preview-2024-10-01"` - - `server_description: Optional[str]` + - `"gpt-4o-audio-preview-2024-12-17"` - Optional description of the MCP server, used to provide more context. + - `"gpt-4o-audio-preview-2025-06-03"` - - `server_url: Optional[str]` + - `"gpt-4o-mini-audio-preview"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `tunnel_id: Optional[str]` + - `"gpt-4o-search-preview"` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `"gpt-4o-mini-search-preview"` - - `class CodeInterpreter: …` + - `"gpt-4o-search-preview-2025-03-11"` - A tool that runs Python code to help generate a response to a prompt. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `container: CodeInterpreterContainer` + - `"chatgpt-4o-latest"` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `"codex-mini-latest"` - - `str` + - `"gpt-4o-mini"` - The container ID. + - `"gpt-4o-mini-2024-07-18"` - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `"gpt-4-turbo"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"gpt-4-turbo-2024-04-09"` - - `type: Literal["auto"]` + - `"gpt-4-0125-preview"` - Always `auto`. + - `"gpt-4-turbo-preview"` - - `"auto"` + - `"gpt-4-1106-preview"` - - `file_ids: Optional[List[str]]` + - `"gpt-4-vision-preview"` - An optional list of uploaded files to make available to your code. + - `"gpt-4"` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `"gpt-4-0314"` - The memory limit for the code interpreter container. + - `"gpt-4-0613"` - - `"1g"` + - `"gpt-4-32k"` - - `"4g"` + - `"gpt-4-32k-0314"` - - `"16g"` + - `"gpt-4-32k-0613"` - - `"64g"` + - `"gpt-3.5-turbo"` - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `"gpt-3.5-turbo-16k"` - Network access policy for the container. + - `"gpt-3.5-turbo-0301"` - - `class BetaContainerNetworkPolicyDisabled: …` + - `"gpt-3.5-turbo-0613"` - - `type: Literal["disabled"]` + - `"gpt-3.5-turbo-1106"` - Disable outbound network access. Always `disabled`. + - `"gpt-3.5-turbo-0125"` - - `"disabled"` + - `"gpt-3.5-turbo-16k-0613"` - - `class BetaContainerNetworkPolicyAllowlist: …` + - `"o1-pro"` - - `allowed_domains: List[str]` + - `"o1-pro-2025-03-19"` - A list of allowed domains when type is `allowlist`. + - `"o3-pro"` - - `type: Literal["allowlist"]` + - `"o3-pro-2025-06-10"` - Allow outbound network access only to specified domains. Always `allowlist`. + - `"o3-deep-research"` - - `"allowlist"` + - `"o3-deep-research-2025-06-26"` - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `"o4-mini-deep-research"` - Optional domain-scoped secrets for allowlisted domains. + - `"o4-mini-deep-research-2025-06-26"` - - `domain: str` + - `"computer-use-preview"` - The domain associated with the secret. + - `"computer-use-preview-2025-03-11"` - - `name: str` + - `"gpt-5-codex"` - The name of the secret to inject for the domain. + - `"gpt-5-pro"` - - `value: str` + - `"gpt-5-pro-2025-10-06"` - The secret value to inject for the domain. + - `"gpt-5.1-codex-max"` - - `type: Literal["code_interpreter"]` + - `str` - The type of the code interpreter tool. Always `code_interpreter`. + - `object: Literal["response"]` - - `"code_interpreter"` + The object type of this resource - always set to `response`. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"response"` - The tool invocation context(s). + - `output: List[BetaResponseOutputItem]` - - `"direct"` + An array of content items generated by the model. - - `"programmatic"` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `class ProgrammaticToolCalling: …` + - `class BetaResponseOutputMessage: …` - - `type: Literal["programmatic_tool_calling"]` + An output message from the model. - The type of the tool. Always `programmatic_tool_calling`. + - `class BetaResponseFileSearchToolCall: …` - - `"programmatic_tool_calling"` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `class ImageGeneration: …` + - `class BetaResponseFunctionToolCall: …` - A tool that generates images using the GPT image models. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `type: Literal["image_generation"]` + - `class BetaResponseFunctionToolCallOutputItem: …` - The type of the image generation tool. Always `image_generation`. + - `id: str` - - `"image_generation"` + The unique ID of the function call tool output. - - `action: Optional[Literal["generate", "edit", "auto"]]` + - `call_id: str` - Whether to generate a new image or edit an existing image. Default: `auto`. + The unique ID of the function tool call generated by the model. - - `"generate"` + - `output: Union[str, List[OutputOutputContentList]]` - - `"edit"` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `"auto"` + - `str` - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + A string of the output of the function call. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `List[OutputOutputContentList]` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + Text, image, or file output of the function call. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `class BetaResponseInputText: …` - - `"transparent"` + A text input to the model. - - `"opaque"` + - `class BetaResponseInputImage: …` - - `"auto"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `input_fidelity: Optional[Literal["high", "low"]]` + - `class BetaResponseInputFile: …` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + A file input to the model. - - `"high"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"low"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + - `"in_progress"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"completed"` - - `file_id: Optional[str]` + - `"incomplete"` - File ID for the mask image. + - `type: Literal["function_call_output"]` - - `image_url: Optional[str]` + The type of the function tool call output. Always `function_call_output`. - Base64-encoded mask image. + - `"function_call_output"` - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + - `agent: Optional[Agent]` - The image generation model to use. Default: `gpt-image-1`. + The agent that produced this item. - - `str` + - `agent_name: str` - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + The canonical name of the agent that produced this item. - The image generation model to use. Default: `gpt-image-1`. + - `caller: Optional[Caller]` - - `"gpt-image-1"` + The execution context that produced this tool call. - - `"gpt-image-1-mini"` + - `class CallerDirect: …` - - `"gpt-image-2"` + - `type: Literal["direct"]` - - `"gpt-image-2-2026-04-21"` + The caller type. Always `direct`. - - `"gpt-image-1.5"` + - `"direct"` - - `"chatgpt-image-latest"` + - `class CallerProgram: …` - - `moderation: Optional[Literal["auto", "low"]]` + - `caller_id: str` - Moderation level for the generated image. Default: `auto`. + The call ID of the program item that produced this tool call. - - `"auto"` + - `type: Literal["program"]` - - `"low"` + The caller type. Always `program`. - - `output_compression: Optional[int]` + - `"program"` - Compression level for the output image. Default: 100. + - `created_by: Optional[str]` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + The identifier of the actor that created the item. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `class AgentMessage: …` - - `"png"` + - `id: str` - - `"webp"` + The unique ID of the agent message. - - `"jpeg"` + - `author: str` - - `partial_images: Optional[int]` + The sending agent identity. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `content: List[AgentMessageContent]` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + Encrypted content sent between agents. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `class BetaResponseInputText: …` - - `"low"` + A text input to the model. - - `"medium"` + - `class BetaResponseOutputText: …` - - `"high"` + A text output from the model. - - `"auto"` + - `class AgentMessageContentText: …` - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + A text content. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `text: str` - - `str` + - `type: Literal["text"]` - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `"text"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `class AgentMessageContentSummaryText: …` - - `"1024x1024"` + A summary text from the model. - - `"1024x1536"` + - `text: str` - - `"1536x1024"` + A summary of the reasoning output from the model so far. - - `"auto"` + - `type: Literal["summary_text"]` - - `class LocalShell: …` + The type of the object. Always `summary_text`. - A tool that allows the model to execute shell commands in a local environment. + - `"summary_text"` - - `type: Literal["local_shell"]` + - `class AgentMessageContentReasoningText: …` - The type of the local shell tool. Always `local_shell`. + Reasoning text from the model. - - `"local_shell"` + - `text: str` - - `class BetaFunctionShellTool: …` + The reasoning text from the model. - A tool that allows the model to execute shell commands. + - `type: Literal["reasoning_text"]` - - `type: Literal["shell"]` + The type of the reasoning text. Always `reasoning_text`. - The type of the shell tool. Always `shell`. + - `"reasoning_text"` - - `"shell"` + - `class BetaResponseOutputRefusal: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + A refusal from the model. - The tool invocation context(s). + - `class BetaResponseInputImage: …` - - `"direct"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"programmatic"` + - `class AgentMessageContentComputerScreenshot: …` - - `environment: Optional[Environment]` + A screenshot of a computer. - - `class BetaContainerAuto: …` + - `detail: Literal["low", "high", "auto", "original"]` - - `type: Literal["container_auto"]` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Automatically creates a container for this request + - `"low"` - - `"container_auto"` + - `"high"` - - `file_ids: Optional[List[str]]` + - `"auto"` - An optional list of uploaded files to make available to your code. + - `"original"` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `file_id: Optional[str]` - The memory limit for the container. + The identifier of an uploaded file that contains the screenshot. - - `"1g"` + - `image_url: Optional[str]` - - `"4g"` + The URL of the screenshot image. - - `"16g"` + - `type: Literal["computer_screenshot"]` - - `"64g"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `network_policy: Optional[NetworkPolicy]` + - `"computer_screenshot"` - Network access policy for the container. + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - - `class BetaContainerNetworkPolicyDisabled: …` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `mode: Literal["explicit"]` - - `skills: Optional[List[Skill]]` + The breakpoint mode. Always `explicit`. - An optional list of skills referenced by id or inline data. + - `"explicit"` - - `class BetaSkillReference: …` + - `class BetaResponseInputFile: …` - - `skill_id: str` + A file input to the model. - The ID of the referenced skill. + - `class AgentMessageContentEncryptedContent: …` - - `type: Literal["skill_reference"]` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - References a skill created with the /v1/skills endpoint. + - `encrypted_content: str` - - `"skill_reference"` + Opaque encrypted content. - - `version: Optional[str]` + - `type: Literal["encrypted_content"]` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The type of the input item. Always `encrypted_content`. - - `class BetaInlineSkill: …` + - `"encrypted_content"` - - `description: str` + - `recipient: str` - The description of the skill. + The destination agent identity. - - `name: str` + - `type: Literal["agent_message"]` - The name of the skill. + The type of the item. Always `agent_message`. - - `source: BetaInlineSkillSource` + - `"agent_message"` - Inline skill payload + - `agent: Optional[AgentMessageAgent]` - - `data: str` + The agent that produced this item. - Base64-encoded skill zip bundle. + - `agent_name: str` - - `media_type: Literal["application/zip"]` + The canonical name of the agent that produced this item. - The media type of the inline skill payload. Must be `application/zip`. + - `class MultiAgentCall: …` - - `"application/zip"` + - `id: str` - - `type: Literal["base64"]` + The unique ID of the multi-agent call item. - The type of the inline skill source. Must be `base64`. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"base64"` + The multi-agent action to execute. - - `type: Literal["inline"]` + - `"spawn_agent"` - Defines an inline skill for this request. + - `"interrupt_agent"` - - `"inline"` + - `"list_agents"` - - `class BetaLocalEnvironment: …` + - `"send_message"` - - `type: Literal["local"]` + - `"followup_task"` - Use a local computer environment. + - `"wait_agent"` - - `"local"` + - `arguments: str` - - `skills: Optional[List[BetaLocalSkill]]` + The JSON string of arguments generated for the action. - An optional list of skills. + - `call_id: str` - - `description: str` + The unique ID linking this call to its output. - The description of the skill. + - `type: Literal["multi_agent_call"]` - - `name: str` + The type of the multi-agent call. Always `multi_agent_call`. - The name of the skill. + - `"multi_agent_call"` - - `path: str` + - `agent: Optional[MultiAgentCallAgent]` - The path to the directory containing the skill. + The agent that produced this item. - - `class BetaContainerReference: …` + - `agent_name: str` - - `container_id: str` + The canonical name of the agent that produced this item. - The ID of the referenced container. + - `class MultiAgentCallOutput: …` - - `type: Literal["container_reference"]` + - `id: str` - References a container created with the /v1/containers endpoint + The unique ID of the multi-agent call output item. - - `"container_reference"` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `class BetaCustomTool: …` + The multi-agent action that produced this result. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"spawn_agent"` - - `name: str` + - `"interrupt_agent"` - The name of the custom tool, used to identify it in tool calls. + - `"list_agents"` - - `type: Literal["custom"]` + - `"send_message"` - The type of the custom tool. Always `custom`. + - `"followup_task"` - - `"custom"` + - `"wait_agent"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `call_id: str` - The tool invocation context(s). + The unique ID of the multi-agent call. - - `"direct"` + - `output: List[BetaResponseOutputText]` - - `"programmatic"` + Text output returned by the multi-agent action. - - `defer_loading: Optional[bool]` + - `annotations: List[Annotation]` - Whether this tool should be deferred and discovered via tool search. + The annotations of the text output. - - `description: Optional[str]` + - `text: str` - Optional description of the custom tool, used to provide more context. + The text output from the model. - - `format: Optional[Format]` + - `type: Literal["output_text"]` - The input format for the custom tool. Default is unconstrained text. + The type of the output text. Always `output_text`. - - `class FormatText: …` + - `logprobs: Optional[List[Logprob]]` - Unconstrained free-form text. + - `type: Literal["multi_agent_call_output"]` - - `type: Literal["text"]` + The type of the multi-agent result. Always `multi_agent_call_output`. - Unconstrained text format. Always `text`. + - `"multi_agent_call_output"` - - `"text"` + - `agent: Optional[MultiAgentCallOutputAgent]` - - `class FormatGrammar: …` + The agent that produced this item. - A grammar defined by the user. + - `agent_name: str` - - `definition: str` + The canonical name of the agent that produced this item. - The grammar definition. + - `class BetaResponseFunctionWebSearch: …` - - `syntax: Literal["lark", "regex"]` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The syntax of the grammar definition. One of `lark` or `regex`. + - `class BetaResponseComputerToolCall: …` - - `"lark"` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `"regex"` + - `class BetaResponseComputerToolCallOutputItem: …` - - `type: Literal["grammar"]` + - `id: str` - Grammar format. Always `grammar`. + The unique ID of the computer call tool output. - - `"grammar"` + - `call_id: str` - - `class BetaNamespaceTool: …` + The ID of the computer tool call that produced the output. - Groups function/custom tools under a shared namespace. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `description: str` + A computer screenshot image used with the computer use tool. - A description of the namespace shown to the model. + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - `name: str` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The namespace name used in tool calls (for example, `crm`). + - `"completed"` - - `tools: List[Tool]` + - `"incomplete"` - The function/custom tools available inside this namespace. + - `"failed"` - - `class ToolFunction: …` + - `"in_progress"` - - `name: str` + - `type: Literal["computer_call_output"]` - - `type: Literal["function"]` + The type of the computer tool call output. Always `computer_call_output`. - - `"function"` + - `"computer_call_output"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - The tool invocation context(s). + The safety checks reported by the API that have been acknowledged by the + developer. - - `"direct"` + - `id: str` - - `"programmatic"` + The ID of the pending safety check. - - `defer_loading: Optional[bool]` + - `code: Optional[str]` - Whether this function should be deferred and discovered via tool search. + The type of the pending safety check. - - `description: Optional[str]` + - `message: Optional[str]` - - `output_schema: Optional[Dict[str, object]]` + Details about the pending safety check. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `agent: Optional[Agent]` - - `parameters: Optional[object]` + The agent that produced this item. - - `strict: Optional[bool]` + - `agent_name: str` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The canonical name of the agent that produced this item. - - `class BetaCustomTool: …` + - `created_by: Optional[str]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The identifier of the actor that created the item. - - `type: Literal["namespace"]` + - `class BetaResponseReasoningItem: …` - The type of the tool. Always `namespace`. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `"namespace"` + - `class Program: …` - - `class BetaToolSearchTool: …` + - `id: str` - Hosted or BYOT tool search configuration for deferred tools. + The unique ID of the program item. - - `type: Literal["tool_search"]` + - `call_id: str` - The type of the tool. Always `tool_search`. + The stable call ID of the program item. - - `"tool_search"` + - `code: str` - - `description: Optional[str]` + The JavaScript source executed by programmatic tool calling. - Description shown to the model for a client-executed tool search tool. + - `fingerprint: str` - - `execution: Optional[Literal["server", "client"]]` + Opaque program replay fingerprint that must be round-tripped. - Whether tool search is executed by the server or by the client. + - `type: Literal["program"]` - - `"server"` + The type of the item. Always `program`. - - `"client"` + - `"program"` - - `parameters: Optional[object]` + - `agent: Optional[ProgramAgent]` - Parameter schema for a client-executed tool search tool. + The agent that produced this item. - - `class BetaWebSearchPreviewTool: …` + - `agent_name: str` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The canonical name of the agent that produced this item. - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + - `class ProgramOutput: …` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `id: str` - - `"web_search_preview"` + The unique ID of the program output item. - - `"web_search_preview_2025_03_11"` + - `call_id: str` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + The call ID of the program item. - - `"text"` + - `result: str` - - `"image"` + The result produced by the program item. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `status: Literal["completed", "incomplete"]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The terminal status of the program output item. - - `"low"` + - `"completed"` - - `"medium"` + - `"incomplete"` - - `"high"` + - `type: Literal["program_output"]` - - `user_location: Optional[UserLocation]` + The type of the item. Always `program_output`. - The user's location. + - `"program_output"` - - `type: Literal["approximate"]` + - `agent: Optional[ProgramOutputAgent]` - The type of location approximation. Always `approximate`. + The agent that produced this item. - - `"approximate"` + - `agent_name: str` - - `city: Optional[str]` + The canonical name of the agent that produced this item. - Free text input for the city of the user, e.g. `San Francisco`. + - `class BetaResponseToolSearchCall: …` - - `country: Optional[str]` + - `id: str` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The unique ID of the tool search call item. - - `region: Optional[str]` + - `arguments: object` - Free text input for the region of the user, e.g. `California`. + Arguments used for the tool search call. - - `timezone: Optional[str]` + - `call_id: Optional[str]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The unique ID of the tool search call generated by the model. - - `class BetaApplyPatchTool: …` + - `execution: Literal["server", "client"]` - Allows the assistant to create, delete, or update files using unified diffs. + Whether tool search was executed by the server or by the client. - - `type: Literal["apply_patch"]` + - `"server"` - The type of the tool. Always `apply_patch`. + - `"client"` - - `"apply_patch"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The status of the tool search call item that was recorded. - The tool invocation context(s). + - `"in_progress"` - - `"direct"` + - `"completed"` - - `"programmatic"` + - `"incomplete"` - - `type: Literal["tool_search_output"]` + - `type: Literal["tool_search_call"]` - The type of the item. Always `tool_search_output`. + The type of the item. Always `tool_search_call`. - - `"tool_search_output"` + - `"tool_search_call"` - `agent: Optional[Agent]` @@ -107173,35 +116849,37 @@ print(compacted_response) The identifier of the actor that created the item. - - `class AdditionalTools: …` + - `class BetaResponseToolSearchOutputItem: …` - `id: str` - The unique ID of the additional tools item. + The unique ID of the tool search output item. - - `role: Literal["unknown", "user", "assistant", 5 more]` + - `call_id: Optional[str]` - The role that provided the additional tools. + The unique ID of the tool search call generated by the model. - - `"unknown"` + - `execution: Literal["server", "client"]` - - `"user"` + Whether tool search was executed by the server or by the client. - - `"assistant"` + - `"server"` - - `"system"` + - `"client"` - - `"critic"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"discriminator"` + The status of the tool search output item that was recorded. - - `"developer"` + - `"in_progress"` - - `"tool"` + - `"completed"` + + - `"incomplete"` - `tools: List[BetaTool]` - The additional tool definitions made available at this item. + The loaded tool definitions returned by tool search. - `class BetaFunctionTool: …` @@ -107267,13 +116945,13 @@ print(compacted_response) Allows the assistant to create, delete, or update files using unified diffs. - - `type: Literal["additional_tools"]` + - `type: Literal["tool_search_output"]` - The type of the item. Always `additional_tools`. + The type of the item. Always `tool_search_output`. - - `"additional_tools"` + - `"tool_search_output"` - - `agent: Optional[AdditionalToolsAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -107281,136 +116959,111 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseReasoningItem: …` - - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). - - - `id: str` - - The unique identifier of the reasoning content. - - - `summary: List[Summary]` - - Reasoning summary content. - - - `text: str` - - A summary of the reasoning output from the model so far. - - - `type: Literal["summary_text"]` - - The type of the object. Always `summary_text`. - - - `"summary_text"` - - - `type: Literal["reasoning"]` + - `created_by: Optional[str]` - The type of the object. Always `reasoning`. + The identifier of the actor that created the item. - - `"reasoning"` + - `class AdditionalTools: …` - - `agent: Optional[Agent]` + - `id: str` - The agent that produced this item. + The unique ID of the additional tools item. - - `agent_name: str` + - `role: Literal["unknown", "user", "assistant", 5 more]` - The canonical name of the agent that produced this item. + The role that provided the additional tools. - - `content: Optional[List[Content]]` + - `"unknown"` - Reasoning text content. + - `"user"` - - `text: str` + - `"assistant"` - The reasoning text from the model. + - `"system"` - - `type: Literal["reasoning_text"]` + - `"critic"` - The type of the reasoning text. Always `reasoning_text`. + - `"discriminator"` - - `"reasoning_text"` + - `"developer"` - - `encrypted_content: Optional[str]` + - `"tool"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `tools: List[BetaTool]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The additional tool definitions made available at this item. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class BetaFunctionTool: …` - - `"in_progress"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"completed"` + - `class BetaFileSearchTool: …` - - `"incomplete"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `class Program: …` + - `class BetaComputerTool: …` - - `id: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The unique ID of the program item. + - `class BetaComputerUsePreviewTool: …` - - `call_id: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The stable call ID of the program item. + - `class BetaWebSearchTool: …` - - `code: str` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The JavaScript source executed by programmatic tool calling. + - `class Mcp: …` - - `fingerprint: str` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - Opaque program replay fingerprint that must be round-tripped. + - `class CodeInterpreter: …` - - `type: Literal["program"]` + A tool that runs Python code to help generate a response to a prompt. - The type of the item. Always `program`. + - `class ProgrammaticToolCalling: …` - - `"program"` + - `class ImageGeneration: …` - - `agent: Optional[ProgramAgent]` + A tool that generates images using the GPT image models. - The agent that produced this item. + - `class LocalShell: …` - - `agent_name: str` + A tool that allows the model to execute shell commands in a local environment. - The canonical name of the agent that produced this item. + - `class BetaFunctionShellTool: …` - - `class ProgramOutput: …` + A tool that allows the model to execute shell commands. - - `id: str` + - `class BetaCustomTool: …` - The unique ID of the program output item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `call_id: str` + - `class BetaNamespaceTool: …` - The call ID of the program item. + Groups function/custom tools under a shared namespace. - - `result: str` + - `class BetaToolSearchTool: …` - The result produced by the program item. + Hosted or BYOT tool search configuration for deferred tools. - - `status: Literal["completed", "incomplete"]` + - `class BetaWebSearchPreviewTool: …` - The terminal status of the program output item. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"completed"` + - `class BetaApplyPatchTool: …` - - `"incomplete"` + Allows the assistant to create, delete, or update files using unified diffs. - - `type: Literal["program_output"]` + - `type: Literal["additional_tools"]` - The type of the item. Always `program_output`. + The type of the item. Always `additional_tools`. - - `"program_output"` + - `"additional_tools"` - - `agent: Optional[ProgramOutputAgent]` + - `agent: Optional[AdditionalToolsAgent]` The agent that produced this item. @@ -107490,79 +117143,6 @@ print(compacted_response) A tool call to run code. - - `id: str` - - The unique ID of the code interpreter tool call. - - - `code: Optional[str]` - - The code to run, or null if not available. - - - `container_id: str` - - The ID of the container used to run the code. - - - `outputs: Optional[List[Output]]` - - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. - - - `class OutputLogs: …` - - The logs output from the code interpreter. - - - `logs: str` - - The logs output from the code interpreter. - - - `type: Literal["logs"]` - - The type of the output. Always `logs`. - - - `"logs"` - - - `class OutputImage: …` - - The image output from the code interpreter. - - - `type: Literal["image"]` - - The type of the output. Always `image`. - - - `"image"` - - - `url: str` - - The URL of the image output from the code interpreter. - - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"interpreting"` - - - `"failed"` - - - `type: Literal["code_interpreter_call"]` - - The type of the code interpreter tool call. Always `code_interpreter_call`. - - - `"code_interpreter_call"` - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - `class LocalShellCall: …` A tool call to run a command on the local shell. @@ -107985,279 +117565,1128 @@ print(compacted_response) The ID of the entity that created this tool call. - - `class BetaResponseApplyPatchToolCallOutput: …` + - `class BetaResponseApplyPatchToolCallOutput: …` + + The output emitted by an apply patch tool call. + + - `id: str` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `call_id: str` + + The unique ID of the apply patch tool call generated by the model. + + - `status: Literal["completed", "failed"]` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: Literal["apply_patch_call_output"]` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `created_by: Optional[str]` + + The ID of the entity that created this tool call output. + + - `output: Optional[str]` + + Optional textual output returned by the apply patch tool. + + - `class McpCall: …` + + An invocation of a tool on an MCP server. + + - `id: str` + + The unique ID of the tool call. + + - `arguments: str` + + A JSON string of the arguments passed to the tool. + + - `name: str` + + The name of the tool that was run. + + - `server_label: str` + + The label of the MCP server running the tool. + + - `type: Literal["mcp_call"]` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `agent: Optional[McpCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `approval_request_id: Optional[str]` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: Optional[str]` + + The error from the tool call, if any. + + - `output: Optional[str]` + + The output from the tool call. + + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `class McpListTools: …` + + A list of tools available on an MCP server. + + - `id: str` + + The unique ID of the list. + + - `server_label: str` + + The label of the MCP server. + + - `tools: List[McpListToolsTool]` + + The tools available on the server. + + - `input_schema: object` + + The JSON schema describing the tool's input. + + - `name: str` + + The name of the tool. + + - `annotations: Optional[object]` + + Additional annotations about the tool. + + - `description: Optional[str]` + + The description of the tool. + + - `type: Literal["mcp_list_tools"]` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `agent: Optional[McpListToolsAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `error: Optional[str]` + + Error message if the server could not list tools. + + - `class McpApprovalRequest: …` + + A request for human approval of a tool invocation. + + - `id: str` + + The unique ID of the approval request. + + - `arguments: str` + + A JSON string of arguments for the tool. + + - `name: str` + + The name of the tool to run. + + - `server_label: str` + + The label of the MCP server making the request. + + - `type: Literal["mcp_approval_request"]` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `agent: Optional[McpApprovalRequestAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse: …` + + A response to an MCP approval request. + + - `id: str` + + The unique ID of the approval response + + - `approval_request_id: str` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: Literal["mcp_approval_response"]` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `agent: Optional[McpApprovalResponseAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `reason: Optional[str]` + + Optional reason for the decision. + + - `class BetaResponseCustomToolCall: …` + + A call to a custom tool created by the model. + + - `class BetaResponseCustomToolCallOutputItem: …` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: str` + + The unique ID of the custom tool call output item. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `parallel_tool_calls: bool` + + Whether to allow the model to run tool calls in parallel. + + - `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. + We generally recommend altering this or `top_p` but not both. + + - `tool_choice: ToolChoice` + + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. + + - `Literal["none", "auto", "required"]` + + - `"none"` + + - `"auto"` + + - `"required"` + + - `class BetaToolChoiceAllowed: …` + + Constrains the tools available to the model to a pre-defined set. + + - `mode: Literal["auto", "required"]` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `"auto"` + + - `"required"` + + - `tools: List[Dict[str, object]]` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `type: Literal["allowed_tools"]` + + Allowed tool configuration type. Always `allowed_tools`. + + - `"allowed_tools"` + + - `class BetaToolChoiceTypes: …` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `"file_search"` + + - `"web_search_preview"` + + - `"computer"` + + - `"computer_use_preview"` + + - `"computer_use"` + + - `"web_search_preview_2025_03_11"` + + - `"image_generation"` + + - `"code_interpreter"` + + - `class BetaToolChoiceFunction: …` + + Use this option to force the model to call a specific function. + + - `name: str` + + The name of the function to call. + + - `type: Literal["function"]` + + For function calling, the type is always `function`. + + - `"function"` + + - `class BetaToolChoiceMcp: …` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `server_label: str` + + The label of the MCP server to use. + + - `type: Literal["mcp"]` + + For MCP tools, the type is always `mcp`. + + - `"mcp"` + + - `name: Optional[str]` + + The name of the tool to call on the server. + + - `class BetaToolChoiceCustom: …` + + Use this option to force the model to call a specific custom tool. + + - `name: str` + + The name of the custom tool to call. + + - `type: Literal["custom"]` + + For custom tool calling, the type is always `custom`. + + - `"custom"` + + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + + - `type: Literal["programmatic_tool_calling"]` + + The tool to call. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + + - `class BetaToolChoiceApplyPatch: …` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `type: Literal["apply_patch"]` + + The tool to call. Always `apply_patch`. + + - `"apply_patch"` + + - `class BetaToolChoiceShell: …` + + Forces the model to call the shell tool when a tool call is required. + + - `type: Literal["shell"]` + + The tool to call. Always `shell`. + + - `"shell"` + + - `tools: List[BetaTool]` + + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. + + - `class BetaFunctionTool: …` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool: …` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool: …` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class Mcp: …` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `class CodeInterpreter: …` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling: …` + + - `class ImageGeneration: …` + + A tool that generates images using the GPT image models. + + - `class LocalShell: …` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool: …` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool: …` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool: …` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool: …` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool: …` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `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. + + - `background: Optional[bool]` + + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + + - `completed_at: Optional[float]` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `conversation: Optional[Conversation]` + + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + + - `id: str` + + The unique ID of the conversation that this response was associated with. + + - `max_output_tokens: Optional[int]` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + + - `max_tool_calls: Optional[int]` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `moderation: Optional[Moderation]` + + Moderation results for the response input and output, if moderated completions were requested. + + - `input: ModerationInput` + + Moderation for the response input. + + - `class ModerationInputModerationResult: …` + + A moderation result produced for the response input or output. + + - `categories: Dict[str, bool]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: Dict[str, float]` + + A dictionary of moderation categories to scores. + + - `flagged: bool` + + A boolean indicating whether the content was flagged by any category. + + - `model: str` + + The moderation model that produced this result. + + - `type: Literal["moderation_result"]` + + The object type, which was always `moderation_result` for successful moderation results. + + - `"moderation_result"` + + - `class ModerationInputError: …` + + An error produced while attempting moderation for the response input or output. + + - `code: str` + + The error code. + + - `message: str` + + The error message. + + - `type: Literal["error"]` + + The object type, which was always `error` for moderation failures. + + - `"error"` + + - `output: ModerationOutput` + + Moderation for the response output. + + - `class ModerationOutputModerationResult: …` + + A moderation result produced for the response input or output. + + - `categories: Dict[str, bool]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: Dict[str, float]` + + A dictionary of moderation categories to scores. + + - `flagged: bool` + + A boolean indicating whether the content was flagged by any category. + + - `model: str` + + The moderation model that produced this result. + + - `type: Literal["moderation_result"]` + + The object type, which was always `moderation_result` for successful moderation results. + + - `"moderation_result"` + + - `class ModerationOutputError: …` + + An error produced while attempting moderation for the response input or output. + + - `code: str` + + The error code. + + - `message: str` + + The error message. + + - `type: Literal["error"]` + + The object type, which was always `error` for moderation failures. + + - `"error"` + + - `previous_response_id: Optional[str]` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `prompt: Optional[BetaResponsePrompt]` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `id: str` + + The unique identifier of the prompt template to use. + + - `variables: Optional[Dict[str, Variables]]` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `str` + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `version: Optional[str]` + + Optional version of the prompt template. + + - `prompt_cache_key: Optional[str]` + + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + + - `prompt_cache_options: Optional[PromptCacheOptions]` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: Literal["implicit", "explicit"]` + + Whether implicit prompt-cache breakpoints were enabled. + + - `"implicit"` + + - `"explicit"` + + - `ttl: Literal["30m"]` + + The minimum lifetime applied to each cache breakpoint. + + - `"30m"` + + - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + + - `"in_memory"` + + - `"24h"` + + - `reasoning: Optional[Reasoning]` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. + + - `"auto"` + + - `"current_turn"` + + - `"all_turns"` + + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. + + - `"none"` + + - `"minimal"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `"max"` + + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` - The output emitted by an apply patch tool call. + Controls the reasoning execution mode for the request. - - `id: str` + When returned on a response, this is the effective execution mode. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `str` - - `call_id: str` + - `Literal["standard", "pro"]` - The unique ID of the apply patch tool call generated by the model. + Controls the reasoning execution mode for the request. - - `status: Literal["completed", "failed"]` + When returned on a response, this is the effective execution mode. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"standard"` - - `"completed"` + - `"pro"` - - `"failed"` + - `summary: Optional[Literal["auto", "concise", "detailed"]]` - - `type: Literal["apply_patch_call_output"]` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The type of the item. Always `apply_patch_call_output`. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `"apply_patch_call_output"` + - `"auto"` - - `agent: Optional[Agent]` + - `"concise"` - The agent that produced this item. + - `"detailed"` - - `agent_name: str` + - `safety_identifier: Optional[str]` - The canonical name of the agent that produced this item. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `caller: Optional[Caller]` + - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` - The execution context that produced this tool call. + Specifies the processing type used for serving the request. - - `class CallerDirect: …` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `type: Literal["direct"]` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `"direct"` + - `"auto"` - - `class CallerProgram: …` + - `"default"` - - `caller_id: str` + - `"flex"` - The call ID of the program item that produced this tool call. + - `"scale"` - - `type: Literal["program"]` + - `"priority"` - - `"program"` + - `status: Optional[BetaResponseStatus]` - - `created_by: Optional[str]` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The ID of the entity that created this tool call output. + - `"completed"` - - `output: Optional[str]` + - `"failed"` - Optional textual output returned by the apply patch tool. + - `"in_progress"` - - `class McpListTools: …` + - `"cancelled"` - A list of tools available on an MCP server. + - `"queued"` - - `id: str` + - `"incomplete"` - The unique ID of the list. + - `text: Optional[BetaResponseTextConfig]` - - `server_label: str` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The label of the MCP server. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `tools: List[McpListToolsTool]` + - `format: Optional[BetaResponseFormatTextConfig]` - The tools available on the server. + An object specifying the format that the model must output. - - `input_schema: object` + Configuring `{ "type": "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). - The JSON schema describing the tool's input. + The default format is `{ "type": "text" }` with no additional options. - - `name: str` + **Not recommended for gpt-4o and newer models:** - The name of the tool. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `annotations: Optional[object]` + - `class Text: …` - Additional annotations about the tool. + Default response format. Used to generate text responses. - - `description: Optional[str]` + - `type: Literal["text"]` - The description of the tool. + The type of response format being defined. Always `text`. - - `type: Literal["mcp_list_tools"]` + - `"text"` - The type of the item. Always `mcp_list_tools`. + - `class BetaResponseFormatTextJSONSchemaConfig: …` - - `"mcp_list_tools"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `agent: Optional[McpListToolsAgent]` + - `name: str` - The agent that produced this item. + 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. - - `agent_name: str` + - `schema: Dict[str, object]` - The canonical name of the agent that produced this item. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `error: Optional[str]` + - `type: Literal["json_schema"]` - Error message if the server could not list tools. + The type of response format being defined. Always `json_schema`. - - `class McpApprovalRequest: …` + - `"json_schema"` - A request for human approval of a tool invocation. + - `description: Optional[str]` - - `id: str` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The unique ID of the approval request. + - `strict: Optional[bool]` - - `arguments: str` + 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). - A JSON string of arguments for the tool. + - `class JSONObject: …` - - `name: str` + 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. - The name of the tool to run. + - `type: Literal["json_object"]` - - `server_label: str` + The type of response format being defined. Always `json_object`. - The label of the MCP server making the request. + - `"json_object"` - - `type: Literal["mcp_approval_request"]` + - `verbosity: Optional[Literal["low", "medium", "high"]]` - The type of the item. Always `mcp_approval_request`. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `"mcp_approval_request"` + - `"low"` - - `agent: Optional[McpApprovalRequestAgent]` + - `"medium"` - The agent that produced this item. + - `"high"` - - `agent_name: str` + - `top_logprobs: Optional[int]` - The canonical name of the agent that produced this item. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `class McpApprovalResponse: …` + - `truncation: Optional[Literal["auto", "disabled"]]` - A response to an MCP approval request. + The truncation strategy to use for the model response. - - `id: str` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The unique ID of the approval response + - `"auto"` - - `approval_request_id: str` + - `"disabled"` - The ID of the approval request being answered. + - `usage: Optional[BetaResponseUsage]` - - `approve: bool` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - Whether the request was approved. + - `input_tokens: int` - - `type: Literal["mcp_approval_response"]` + The number of input tokens. - The type of the item. Always `mcp_approval_response`. + - `input_tokens_details: InputTokensDetails` - - `"mcp_approval_response"` + A detailed breakdown of the input tokens. - - `agent: Optional[McpApprovalResponseAgent]` + - `cache_write_tokens: int` - The agent that produced this item. + The number of input tokens that were written to the cache. - - `agent_name: str` + - `cached_tokens: int` - The canonical name of the agent that produced this item. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `reason: Optional[str]` + - `output_tokens: int` - Optional reason for the decision. + The number of output tokens. - - `class McpCall: …` + - `output_tokens_details: OutputTokensDetails` - An invocation of a tool on an MCP server. + A detailed breakdown of the output tokens. - - `id: str` + - `reasoning_tokens: int` - The unique ID of the tool call. + The number of reasoning tokens. - - `arguments: str` + - `total_tokens: int` - A JSON string of the arguments passed to the tool. + The total number of tokens used. - - `name: str` + - `user: Optional[str]` - The name of the tool that was run. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `server_label: str` + - `sequence_number: int` - The label of the MCP server running the tool. + The sequence number for this event. - - `type: Literal["mcp_call"]` + - `type: Literal["response.queued"]` - The type of the item. Always `mcp_call`. + The type of the event. Always 'response.queued'. - - `"mcp_call"` + - `"response.queued"` - - `agent: Optional[McpCallAgent]` + - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `approval_request_id: Optional[str]` +### Beta Response Reasoning Item - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. +- `class BetaResponseReasoningItem: …` - - `error: Optional[str]` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - The error from the tool call, if any. + - `id: str` - - `output: Optional[str]` + The unique identifier of the reasoning content. - The output from the tool call. + - `summary: List[Summary]` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + Reasoning summary content. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `text: str` - - `"in_progress"` + A summary of the reasoning output from the model so far. - - `"completed"` + - `type: Literal["summary_text"]` - - `"incomplete"` + The type of the object. Always `summary_text`. - - `"calling"` + - `"summary_text"` - - `"failed"` + - `type: Literal["reasoning"]` - - `class BetaResponseCustomToolCallItem: …` + The type of the object. Always `reasoning`. - A call to a custom tool created by the model. + - `"reasoning"` - - `id: str` + - `agent: Optional[Agent]` - The unique ID of the custom tool call item. + The agent that produced this item. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `agent_name: str` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The canonical name of the agent that produced this item. - - `"in_progress"` + - `content: Optional[List[Content]]` - - `"completed"` + Reasoning text content. - - `"incomplete"` + - `text: str` - - `created_by: Optional[str]` + The reasoning text from the model. - The identifier of the actor that created the item. + - `type: Literal["reasoning_text"]` - - `class BetaResponseCustomToolCallOutputItem: …` + The type of the reasoning text. Always `reasoning_text`. - The output of a custom tool call from your code, being sent back to the model. + - `"reasoning_text"` - - `id: str` + - `encrypted_content: Optional[str]` - The unique ID of the custom tool call output item. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -108268,49 +118697,47 @@ print(compacted_response) - `"incomplete"` - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - -### Beta Response Local Environment - -- `class BetaResponseLocalEnvironment: …` +### Beta Response Reasoning Summary Part Added Event - Represents the use of a local environment to perform shell actions. +- `class BetaResponseReasoningSummaryPartAddedEvent: …` - - `type: Literal["local"]` + Emitted when a new reasoning summary part is added. - The environment type. Always `local`. + - `item_id: str` - - `"local"` + The ID of the item this summary part is associated with. -### Beta Response Mcp Call Arguments Delta Event + - `output_index: int` -- `class BetaResponseMcpCallArgumentsDeltaEvent: …` + The index of the output item this summary part is associated with. - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + - `part: Part` - - `delta: str` + The summary part that was added. - A JSON string containing the partial update to the arguments for the MCP tool call. + - `text: str` - - `item_id: str` + The text of the summary part. - The unique identifier of the MCP tool call item being processed. + - `type: Literal["summary_text"]` - - `output_index: int` + The type of the summary part. Always `summary_text`. - The index of the output item in the response's output array. + - `"summary_text"` - `sequence_number: int` The sequence number of this event. - - `type: Literal["response.mcp_call_arguments.delta"]` + - `summary_index: int` - The type of the event. Always 'response.mcp_call_arguments.delta'. + The index of the summary part within the reasoning summary. - - `"response.mcp_call_arguments.delta"` + - `type: Literal["response.reasoning_summary_part.added"]` + + The type of the event. Always `response.reasoning_summary_part.added`. + + - `"response.reasoning_summary_part.added"` - `agent: Optional[Agent]` @@ -108320,33 +118747,47 @@ print(compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp Call Arguments Done Event - -- `class BetaResponseMcpCallArgumentsDoneEvent: …` - - Emitted when the arguments for an MCP tool call are finalized. +### Beta Response Reasoning Summary Part Done Event - - `arguments: str` +- `class BetaResponseReasoningSummaryPartDoneEvent: …` - A JSON string containing the finalized arguments for the MCP tool call. + Emitted when a reasoning summary part is completed. - `item_id: str` - The unique identifier of the MCP tool call item being processed. + The ID of the item this summary part is associated with. - `output_index: int` - The index of the output item in the response's output array. + The index of the output item this summary part is associated with. + + - `part: Part` + + The completed summary part. + + - `text: str` + + The text of the summary part. + + - `type: Literal["summary_text"]` + + The type of the summary part. Always `summary_text`. + + - `"summary_text"` - `sequence_number: int` The sequence number of this event. - - `type: Literal["response.mcp_call_arguments.done"]` + - `summary_index: int` - The type of the event. Always 'response.mcp_call_arguments.done'. + The index of the summary part within the reasoning summary. - - `"response.mcp_call_arguments.done"` + - `type: Literal["response.reasoning_summary_part.done"]` + + The type of the event. Always `response.reasoning_summary_part.done`. + + - `"response.reasoning_summary_part.done"` - `agent: Optional[Agent]` @@ -108356,29 +118797,44 @@ print(compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp Call Completed Event + - `status: Optional[Literal["incomplete"]]` -- `class BetaResponseMcpCallCompletedEvent: …` + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - Emitted when an MCP tool call has completed successfully. + - `"incomplete"` + +### Beta Response Reasoning Summary Text Delta Event + +- `class BetaResponseReasoningSummaryTextDeltaEvent: …` + + Emitted when a delta is added to a reasoning summary text. + + - `delta: str` + + The text delta that was added to the summary. - `item_id: str` - The ID of the MCP tool call item that completed. + The ID of the item this summary text delta is associated with. - `output_index: int` - The index of the output item that completed. + The index of the output item this summary text delta is associated with. - `sequence_number: int` The sequence number of this event. - - `type: Literal["response.mcp_call.completed"]` + - `summary_index: int` - The type of the event. Always 'response.mcp_call.completed'. + The index of the summary part within the reasoning summary. - - `"response.mcp_call.completed"` + - `type: Literal["response.reasoning_summary_text.delta"]` + + The type of the event. Always `response.reasoning_summary_text.delta`. + + - `"response.reasoning_summary_text.delta"` - `agent: Optional[Agent]` @@ -108388,29 +118844,37 @@ print(compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp Call Failed Event +### Beta Response Reasoning Summary Text Done Event -- `class BetaResponseMcpCallFailedEvent: …` +- `class BetaResponseReasoningSummaryTextDoneEvent: …` - Emitted when an MCP tool call has failed. + Emitted when a reasoning summary text is completed. - `item_id: str` - The ID of the MCP tool call item that failed. + The ID of the item this summary text is associated with. - `output_index: int` - The index of the output item that failed. + The index of the output item this summary text is associated with. - `sequence_number: int` The sequence number of this event. - - `type: Literal["response.mcp_call.failed"]` + - `summary_index: int` - The type of the event. Always 'response.mcp_call.failed'. + The index of the summary part within the reasoning summary. - - `"response.mcp_call.failed"` + - `text: str` + + The full text of the completed reasoning summary. + + - `type: Literal["response.reasoning_summary_text.done"]` + + The type of the event. Always `response.reasoning_summary_text.done`. + + - `"response.reasoning_summary_text.done"` - `agent: Optional[Agent]` @@ -108420,29 +118884,37 @@ print(compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp Call In Progress Event +### Beta Response Reasoning Text Delta Event -- `class BetaResponseMcpCallInProgressEvent: …` +- `class BetaResponseReasoningTextDeltaEvent: …` - Emitted when an MCP tool call is in progress. + Emitted when a delta is added to a reasoning text. + + - `content_index: int` + + The index of the reasoning content part this delta is associated with. + + - `delta: str` + + The text delta that was added to the reasoning content. - `item_id: str` - The unique identifier of the MCP tool call item being processed. + The ID of the item this reasoning text delta is associated with. - `output_index: int` - The index of the output item in the response's output array. + The index of the output item this reasoning text delta is associated with. - `sequence_number: int` The sequence number of this event. - - `type: Literal["response.mcp_call.in_progress"]` + - `type: Literal["response.reasoning_text.delta"]` - The type of the event. Always 'response.mcp_call.in_progress'. + The type of the event. Always `response.reasoning_text.delta`. - - `"response.mcp_call.in_progress"` + - `"response.reasoning_text.delta"` - `agent: Optional[Agent]` @@ -108452,29 +118924,37 @@ print(compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp List Tools Completed Event +### Beta Response Reasoning Text Done Event -- `class BetaResponseMcpListToolsCompletedEvent: …` +- `class BetaResponseReasoningTextDoneEvent: …` - Emitted when the list of available MCP tools has been successfully retrieved. + Emitted when a reasoning text is completed. + + - `content_index: int` + + The index of the reasoning content part. - `item_id: str` - The ID of the MCP tool call item that produced this output. + The ID of the item this reasoning text is associated with. - `output_index: int` - The index of the output item that was processed. + The index of the output item this reasoning text is associated with. - `sequence_number: int` The sequence number of this event. - - `type: Literal["response.mcp_list_tools.completed"]` + - `text: str` - The type of the event. Always 'response.mcp_list_tools.completed'. + The full text of the completed reasoning content. - - `"response.mcp_list_tools.completed"` + - `type: Literal["response.reasoning_text.done"]` + + The type of the event. Always `response.reasoning_text.done`. + + - `"response.reasoning_text.done"` - `agent: Optional[Agent]` @@ -108484,29 +118964,37 @@ print(compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp List Tools Failed Event +### Beta Response Refusal Delta Event -- `class BetaResponseMcpListToolsFailedEvent: …` +- `class BetaResponseRefusalDeltaEvent: …` - Emitted when the attempt to list available MCP tools has failed. + Emitted when there is a partial refusal text. + + - `content_index: int` + + The index of the content part that the refusal text is added to. + + - `delta: str` + + The refusal text that is added. - `item_id: str` - The ID of the MCP tool call item that failed. + The ID of the output item that the refusal text is added to. - `output_index: int` - The index of the output item that failed. + The index of the output item that the refusal text is added to. - `sequence_number: int` The sequence number of this event. - - `type: Literal["response.mcp_list_tools.failed"]` + - `type: Literal["response.refusal.delta"]` - The type of the event. Always 'response.mcp_list_tools.failed'. + The type of the event. Always `response.refusal.delta`. - - `"response.mcp_list_tools.failed"` + - `"response.refusal.delta"` - `agent: Optional[Agent]` @@ -108516,29 +119004,37 @@ print(compacted_response) The canonical name of the agent that produced this item. -### Beta Response Mcp List Tools In Progress Event +### Beta Response Refusal Done Event -- `class BetaResponseMcpListToolsInProgressEvent: …` +- `class BetaResponseRefusalDoneEvent: …` - Emitted when the system is in the process of retrieving the list of available MCP tools. + Emitted when refusal text is finalized. + + - `content_index: int` + + The index of the content part that the refusal text is finalized. - `item_id: str` - The ID of the MCP tool call item that is being processed. + The ID of the output item that the refusal text is finalized. - `output_index: int` - The index of the output item that is being processed. + The index of the output item that the refusal text is finalized. + + - `refusal: str` + + The refusal text that is finalized. - `sequence_number: int` The sequence number of this event. - - `type: Literal["response.mcp_list_tools.in_progress"]` + - `type: Literal["response.refusal.done"]` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + The type of the event. Always `response.refusal.done`. - - `"response.mcp_list_tools.in_progress"` + - `"response.refusal.done"` - `agent: Optional[Agent]` @@ -108548,395 +119044,399 @@ print(compacted_response) The canonical name of the agent that produced this item. -### Beta Response Output Audio +### Beta Response Status -- `class BetaResponseOutputAudio: …` +- `Literal["completed", "failed", "in_progress", 3 more]` - An audio output from the model. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `data: str` + - `"completed"` - Base64-encoded audio data from the model. + - `"failed"` - - `transcript: str` + - `"in_progress"` - The transcript of the audio data from the model. + - `"cancelled"` - - `type: Literal["output_audio"]` + - `"queued"` - The type of the output audio. Always `output_audio`. + - `"incomplete"` - - `"output_audio"` +### Beta Response Stream Event -### Beta Response Output Item +- `BetaResponseStreamEvent` -- `BetaResponseOutputItem` + Emitted when there is a partial audio response. - An output message from the model. + - `class BetaResponseAudioDeltaEvent: …` - - `class BetaResponseOutputMessage: …` + Emitted when there is a partial audio response. - An output message from the model. + - `delta: str` - - `id: str` + A chunk of Base64 encoded response audio bytes. - The unique ID of the output message. + - `sequence_number: int` - - `content: List[Content]` + A sequence number for this chunk of the stream response. - The content of the output message. + - `type: Literal["response.audio.delta"]` - - `class BetaResponseOutputText: …` + The type of the event. Always `response.audio.delta`. - A text output from the model. + - `"response.audio.delta"` - - `annotations: List[Annotation]` + - `agent: Optional[Agent]` - The annotations of the text output. + The agent that owns this multi-agent streaming event. - - `class AnnotationFileCitation: …` + - `agent_name: str` - A citation to a file. + The canonical name of the agent that produced this item. - - `file_id: str` + - `class BetaResponseAudioDoneEvent: …` - The ID of the file. + Emitted when the audio response is complete. - - `filename: str` + - `sequence_number: int` - The filename of the file cited. + The sequence number of the delta. - - `index: int` + - `type: Literal["response.audio.done"]` - The index of the file in the list of files. + The type of the event. Always `response.audio.done`. - - `type: Literal["file_citation"]` + - `"response.audio.done"` - The type of the file citation. Always `file_citation`. + - `agent: Optional[Agent]` - - `"file_citation"` + The agent that owns this multi-agent streaming event. - - `class AnnotationURLCitation: …` + - `agent_name: str` - A citation for a web resource used to generate a model response. + The canonical name of the agent that produced this item. - - `end_index: int` + - `class BetaResponseAudioTranscriptDeltaEvent: …` - The index of the last character of the URL citation in the message. + Emitted when there is a partial transcript of audio. - - `start_index: int` + - `delta: str` - The index of the first character of the URL citation in the message. + The partial transcript of the audio response. - - `title: str` + - `sequence_number: int` - The title of the web resource. + The sequence number of this event. - - `type: Literal["url_citation"]` + - `type: Literal["response.audio.transcript.delta"]` - The type of the URL citation. Always `url_citation`. + The type of the event. Always `response.audio.transcript.delta`. - - `"url_citation"` + - `"response.audio.transcript.delta"` - - `url: str` + - `agent: Optional[Agent]` - The URL of the web resource. + The agent that owns this multi-agent streaming event. - - `class AnnotationContainerFileCitation: …` + - `agent_name: str` - A citation for a container file used to generate a model response. + The canonical name of the agent that produced this item. - - `container_id: str` + - `class BetaResponseAudioTranscriptDoneEvent: …` - The ID of the container file. + Emitted when the full audio transcript is completed. - - `end_index: int` + - `sequence_number: int` - The index of the last character of the container file citation in the message. + The sequence number of this event. - - `file_id: str` + - `type: Literal["response.audio.transcript.done"]` - The ID of the file. + The type of the event. Always `response.audio.transcript.done`. - - `filename: str` + - `"response.audio.transcript.done"` - The filename of the container file cited. + - `agent: Optional[Agent]` - - `start_index: int` + The agent that owns this multi-agent streaming event. - The index of the first character of the container file citation in the message. + - `agent_name: str` - - `type: Literal["container_file_citation"]` + The canonical name of the agent that produced this item. - The type of the container file citation. Always `container_file_citation`. + - `class BetaResponseCodeInterpreterCallCodeDeltaEvent: …` - - `"container_file_citation"` + Emitted when a partial code snippet is streamed by the code interpreter. - - `class AnnotationFilePath: …` + - `delta: str` - A path to a file. + The partial code snippet being streamed by the code interpreter. - - `file_id: str` + - `item_id: str` - The ID of the file. + The unique identifier of the code interpreter tool call item. - - `index: int` + - `output_index: int` - The index of the file in the list of files. + The index of the output item in the response for which the code is being streamed. - - `type: Literal["file_path"]` + - `sequence_number: int` - The type of the file path. Always `file_path`. + The sequence number of this event, used to order streaming events. - - `"file_path"` + - `type: Literal["response.code_interpreter_call_code.delta"]` - - `text: str` + The type of the event. Always `response.code_interpreter_call_code.delta`. - The text output from the model. + - `"response.code_interpreter_call_code.delta"` - - `type: Literal["output_text"]` + - `agent: Optional[Agent]` - The type of the output text. Always `output_text`. + The agent that owns this multi-agent streaming event. - - `"output_text"` + - `agent_name: str` - - `logprobs: Optional[List[Logprob]]` + The canonical name of the agent that produced this item. - - `token: str` + - `class BetaResponseCodeInterpreterCallCodeDoneEvent: …` - - `bytes: List[int]` + Emitted when the code snippet is finalized by the code interpreter. - - `logprob: float` + - `code: str` - - `top_logprobs: List[LogprobTopLogprob]` + The final code snippet output by the code interpreter. - - `token: str` + - `item_id: str` - - `bytes: List[int]` + The unique identifier of the code interpreter tool call item. - - `logprob: float` + - `output_index: int` - - `class BetaResponseOutputRefusal: …` + The index of the output item in the response for which the code is finalized. - A refusal from the model. + - `sequence_number: int` - - `refusal: str` + The sequence number of this event, used to order streaming events. - The refusal explanation from the model. + - `type: Literal["response.code_interpreter_call_code.done"]` - - `type: Literal["refusal"]` + The type of the event. Always `response.code_interpreter_call_code.done`. - The type of the refusal. Always `refusal`. + - `"response.code_interpreter_call_code.done"` - - `"refusal"` + - `agent: Optional[Agent]` - - `role: Literal["assistant"]` + The agent that owns this multi-agent streaming event. - The role of the output message. Always `assistant`. + - `agent_name: str` - - `"assistant"` + The canonical name of the agent that produced this item. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `class BetaResponseCodeInterpreterCallCompletedEvent: …` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Emitted when the code interpreter call is completed. - - `"in_progress"` + - `item_id: str` - - `"completed"` + The unique identifier of the code interpreter tool call item. - - `"incomplete"` + - `output_index: int` - - `type: Literal["message"]` + The index of the output item in the response for which the code interpreter call is completed. - The type of the output message. Always `message`. + - `sequence_number: int` - - `"message"` + The sequence number of this event, used to order streaming events. + + - `type: Literal["response.code_interpreter_call.completed"]` + + The type of the event. Always `response.code_interpreter_call.completed`. + + - `"response.code_interpreter_call.completed"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `phase: Optional[Literal["commentary"]]` + - `class BetaResponseCodeInterpreterCallInProgressEvent: …` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + Emitted when a code interpreter call is in progress. - - `"commentary"` + - `item_id: str` - - `class BetaResponseFileSearchToolCall: …` + The unique identifier of the code interpreter tool call item. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `output_index: int` - - `id: str` + The index of the output item in the response for which the code interpreter call is in progress. - The unique ID of the file search tool call. + - `sequence_number: int` - - `queries: List[str]` + The sequence number of this event, used to order streaming events. - The queries used to search for files. + - `type: Literal["response.code_interpreter_call.in_progress"]` - - `status: Literal["in_progress", "searching", "completed", 2 more]` + The type of the event. Always `response.code_interpreter_call.in_progress`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"response.code_interpreter_call.in_progress"` - - `"in_progress"` + - `agent: Optional[Agent]` - - `"searching"` + The agent that owns this multi-agent streaming event. - - `"completed"` + - `agent_name: str` - - `"incomplete"` + The canonical name of the agent that produced this item. - - `"failed"` + - `class BetaResponseCodeInterpreterCallInterpretingEvent: …` - - `type: Literal["file_search_call"]` + Emitted when the code interpreter is actively interpreting the code snippet. - The type of the file search tool call. Always `file_search_call`. + - `item_id: str` - - `"file_search_call"` + The unique identifier of the code interpreter tool call item. - - `agent: Optional[Agent]` + - `output_index: int` - The agent that produced this item. + The index of the output item in the response for which the code interpreter is interpreting code. - - `agent_name: str` + - `sequence_number: int` - The canonical name of the agent that produced this item. + The sequence number of this event, used to order streaming events. - - `results: Optional[List[Result]]` + - `type: Literal["response.code_interpreter_call.interpreting"]` - The results of the file search tool call. + The type of the event. Always `response.code_interpreter_call.interpreting`. - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + - `"response.code_interpreter_call.interpreting"` - 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, booleans, or numbers. + - `agent: Optional[Agent]` - - `str` + The agent that owns this multi-agent streaming event. - - `float` + - `agent_name: str` - - `bool` + The canonical name of the agent that produced this item. - - `file_id: Optional[str]` + - `class BetaResponseCompletedEvent: …` - The unique ID of the file. + Emitted when the model response is complete. - - `filename: Optional[str]` + - `response: BetaResponse` - The name of the file. + Properties of the completed response. - - `score: Optional[float]` + - `id: str` - The relevance score of the file - a value between 0 and 1. + Unique identifier for this Response. - - `text: Optional[str]` + - `created_at: float` - The text that was retrieved from the file. + Unix timestamp (in seconds) of when this Response was created. - - `class BetaResponseFunctionToolCall: …` + - `error: Optional[BetaResponseError]` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + An error object returned when the model fails to generate a Response. - - `arguments: str` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` - A JSON string of the arguments to pass to the function. + The error code for the response. - - `call_id: str` + - `"server_error"` - The unique ID of the function tool call generated by the model. + - `"rate_limit_exceeded"` - - `name: str` + - `"invalid_prompt"` - The name of the function to run. + - `"bio_policy"` - - `type: Literal["function_call"]` + - `"vector_store_timeout"` - The type of the function tool call. Always `function_call`. + - `"invalid_image"` - - `"function_call"` + - `"invalid_image_format"` - - `id: Optional[str]` + - `"invalid_base64_image"` - The unique ID of the function tool call. + - `"invalid_image_url"` - - `agent: Optional[Agent]` + - `"image_too_large"` - The agent that produced this item. + - `"image_too_small"` - - `agent_name: str` + - `"image_parse_error"` - The canonical name of the agent that produced this item. + - `"image_content_policy_violation"` - - `caller: Optional[Caller]` + - `"invalid_image_mode"` - The execution context that produced this tool call. + - `"image_file_too_large"` - - `class CallerDirect: …` + - `"unsupported_image_media_type"` - - `type: Literal["direct"]` + - `"empty_image_file"` - - `"direct"` + - `"failed_to_download_image"` - - `class CallerProgram: …` + - `"image_file_not_found"` - - `caller_id: str` + - `message: str` - The call ID of the program item that produced this tool call. + A human-readable description of the error. - - `type: Literal["program"]` + - `incomplete_details: Optional[IncompleteDetails]` - - `"program"` + Details about why the response is incomplete. - - `namespace: Optional[str]` + - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` - The namespace of the function to run. + The reason why the response is incomplete. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"max_output_tokens"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"content_filter"` - - `"in_progress"` + - `instructions: Union[str, List[BetaResponseInputItem], null]` - - `"completed"` + A system (or developer) message inserted into the model's context. - - `"incomplete"` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `class BetaResponseFunctionToolCallOutputItem: …` + - `str` - - `id: str` + A text input to the model, equivalent to a text input with the + `developer` role. - The unique ID of the function call tool output. + - `List[BetaResponseInputItem]` - - `call_id: str` + A list of one or many input items to the model, containing + different content types. - The unique ID of the function tool call generated by the model. + - `class BetaEasyInputMessage: …` - - `output: Union[str, List[OutputOutputContentList]]` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `content: Union[str, BetaResponseInputMessageContentList]` - - `str` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - A string of the output of the function call. + - `str` - - `List[OutputOutputContentList]` + A text input to the model. - Text, image, or file output of the function call. + - `List[BetaResponseInputContent]` - `class BetaResponseInputText: …` @@ -108990,338 +119490,266 @@ print(compacted_response) - `image_url: Optional[str]` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: Literal["explicit"]` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `class BetaResponseInputFile: …` - - A file input to the model. - - - `type: Literal["input_file"]` - - The type of the input item. Always `input_file`. - - - `"input_file"` - - - `detail: Optional[Literal["auto", "low", "high"]]` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: Optional[str]` - - The content of the file to be sent to the model. - - - `file_id: Optional[str]` - - The ID of the file to be sent to the model. - - - `file_url: Optional[str]` - - The URL of the file to be sent to the model. - - - `filename: Optional[str]` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: Literal["explicit"]` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `type: Literal["function_call_output"]` - - The type of the function tool call output. Always `function_call_output`. - - - `"function_call_output"` - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The canonical name of the agent that produced this item. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `caller: Optional[Caller]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The execution context that produced this tool call. + - `mode: Literal["explicit"]` - - `class CallerDirect: …` + The breakpoint mode. Always `explicit`. - - `type: Literal["direct"]` + - `"explicit"` - The caller type. Always `direct`. + - `class BetaResponseInputFile: …` - - `"direct"` + A file input to the model. - - `class CallerProgram: …` + - `type: Literal["input_file"]` - - `caller_id: str` + The type of the input item. Always `input_file`. - The call ID of the program item that produced this tool call. + - `"input_file"` - - `type: Literal["program"]` + - `detail: Optional[Literal["auto", "low", "high"]]` - The caller type. Always `program`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `"program"` + - `"auto"` - - `created_by: Optional[str]` + - `"low"` - The identifier of the actor that created the item. + - `"high"` - - `class AgentMessage: …` + - `file_data: Optional[str]` - - `id: str` + The content of the file to be sent to the model. - The unique ID of the agent message. + - `file_id: Optional[str]` - - `author: str` + The ID of the file to be sent to the model. - The sending agent identity. + - `file_url: Optional[str]` - - `content: List[AgentMessageContent]` + The URL of the file to be sent to the model. - Encrypted content sent between agents. + - `filename: Optional[str]` - - `class BetaResponseInputText: …` + The name of the file to be sent to the model. - A text input to the model. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `class BetaResponseOutputText: …` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - A text output from the model. + - `mode: Literal["explicit"]` - - `class AgentMessageContentText: …` + The breakpoint mode. Always `explicit`. - A text content. + - `"explicit"` - - `text: str` + - `role: Literal["user", "assistant", "system", "developer"]` - - `type: Literal["text"]` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `"text"` + - `"user"` - - `class AgentMessageContentSummaryText: …` + - `"assistant"` - A summary text from the model. + - `"system"` - - `text: str` + - `"developer"` - A summary of the reasoning output from the model so far. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `type: Literal["summary_text"]` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - The type of the object. Always `summary_text`. + - `"commentary"` - - `"summary_text"` + - `"final_answer"` - - `class AgentMessageContentReasoningText: …` + - `type: Optional[Literal["message"]]` - Reasoning text from the model. + The type of the message input. Always `message`. - - `text: str` + - `"message"` - The reasoning text from the model. + - `class Message: …` - - `type: Literal["reasoning_text"]` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - The type of the reasoning text. Always `reasoning_text`. + - `content: BetaResponseInputMessageContentList` - - `"reasoning_text"` + A list of one or many input items to the model, containing different content + types. - - `class BetaResponseOutputRefusal: …` + - `class BetaResponseInputText: …` - A refusal from the model. + A text input to the model. - `class BetaResponseInputImage: …` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class AgentMessageContentComputerScreenshot: …` + - `class BetaResponseInputFile: …` - A screenshot of a computer. + A file input to the model. - - `detail: Literal["low", "high", "auto", "original"]` + - `role: Literal["user", "system", "developer"]` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The role of the message input. One of `user`, `system`, or `developer`. - - `"low"` + - `"user"` - - `"high"` + - `"system"` - - `"auto"` + - `"developer"` - - `"original"` + - `agent: Optional[MessageAgent]` - - `file_id: Optional[str]` + The agent that produced this item. - The identifier of an uploaded file that contains the screenshot. + - `agent_name: str` - - `image_url: Optional[str]` + The canonical name of the agent that produced this item. - The URL of the screenshot image. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `type: Literal["computer_screenshot"]` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"in_progress"` - - `"computer_screenshot"` + - `"completed"` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `"incomplete"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: Optional[Literal["message"]]` - - `mode: Literal["explicit"]` + The type of the message input. Always set to `message`. - The breakpoint mode. Always `explicit`. + - `"message"` - - `"explicit"` + - `class BetaResponseOutputMessage: …` - - `class BetaResponseInputFile: …` + An output message from the model. - A file input to the model. + - `id: str` - - `class AgentMessageContentEncryptedContent: …` + The unique ID of the output message. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `content: List[Content]` - - `encrypted_content: str` + The content of the output message. - Opaque encrypted content. + - `class BetaResponseOutputText: …` - - `type: Literal["encrypted_content"]` + A text output from the model. - The type of the input item. Always `encrypted_content`. + - `annotations: List[Annotation]` - - `"encrypted_content"` + The annotations of the text output. - - `recipient: str` + - `class AnnotationFileCitation: …` - The destination agent identity. + A citation to a file. - - `type: Literal["agent_message"]` + - `file_id: str` - The type of the item. Always `agent_message`. + The ID of the file. - - `"agent_message"` + - `filename: str` - - `agent: Optional[AgentMessageAgent]` + The filename of the file cited. - The agent that produced this item. + - `index: int` - - `agent_name: str` + The index of the file in the list of files. - The canonical name of the agent that produced this item. + - `type: Literal["file_citation"]` - - `class MultiAgentCall: …` + The type of the file citation. Always `file_citation`. - - `id: str` + - `"file_citation"` - The unique ID of the multi-agent call item. + - `class AnnotationURLCitation: …` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + A citation for a web resource used to generate a model response. - The multi-agent action to execute. + - `end_index: int` - - `"spawn_agent"` + The index of the last character of the URL citation in the message. - - `"interrupt_agent"` + - `start_index: int` - - `"list_agents"` + The index of the first character of the URL citation in the message. - - `"send_message"` + - `title: str` - - `"followup_task"` + The title of the web resource. - - `"wait_agent"` + - `type: Literal["url_citation"]` - - `arguments: str` + The type of the URL citation. Always `url_citation`. - The JSON string of arguments generated for the action. + - `"url_citation"` - - `call_id: str` + - `url: str` - The unique ID linking this call to its output. + The URL of the web resource. - - `type: Literal["multi_agent_call"]` + - `class AnnotationContainerFileCitation: …` - The type of the multi-agent call. Always `multi_agent_call`. + A citation for a container file used to generate a model response. - - `"multi_agent_call"` + - `container_id: str` - - `agent: Optional[MultiAgentCallAgent]` + The ID of the container file. - The agent that produced this item. + - `end_index: int` - - `agent_name: str` + The index of the last character of the container file citation in the message. - The canonical name of the agent that produced this item. + - `file_id: str` - - `class MultiAgentCallOutput: …` + The ID of the file. - - `id: str` + - `filename: str` - The unique ID of the multi-agent call output item. + The filename of the container file cited. - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `start_index: int` - The multi-agent action that produced this result. + The index of the first character of the container file citation in the message. - - `"spawn_agent"` + - `type: Literal["container_file_citation"]` - - `"interrupt_agent"` + The type of the container file citation. Always `container_file_citation`. - - `"list_agents"` + - `"container_file_citation"` - - `"send_message"` + - `class AnnotationFilePath: …` - - `"followup_task"` + A path to a file. - - `"wait_agent"` + - `file_id: str` - - `call_id: str` + The ID of the file. - The unique ID of the multi-agent call. + - `index: int` - - `output: List[BetaResponseOutputText]` + The index of the file in the list of files. - Text output returned by the multi-agent action. + - `type: Literal["file_path"]` - - `annotations: List[Annotation]` + The type of the file path. Always `file_path`. - The annotations of the text output. + - `"file_path"` - `text: str` @@ -109331,103 +119759,96 @@ print(compacted_response) The type of the output text. Always `output_text`. - - `logprobs: Optional[List[Logprob]]` - - - `type: Literal["multi_agent_call_output"]` - - The type of the multi-agent result. Always `multi_agent_call_output`. - - - `"multi_agent_call_output"` - - - `agent: Optional[MultiAgentCallOutputAgent]` - - The agent that produced this item. + - `"output_text"` - - `agent_name: str` + - `logprobs: Optional[List[Logprob]]` - The canonical name of the agent that produced this item. + - `token: str` - - `class BetaResponseFunctionWebSearch: …` + - `bytes: List[int]` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `logprob: float` - - `id: str` + - `top_logprobs: List[LogprobTopLogprob]` - The unique ID of the web search tool call. + - `token: str` - - `action: Action` + - `bytes: List[int]` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `logprob: float` - - `class ActionSearch: …` + - `class BetaResponseOutputRefusal: …` - Action type "search" - Performs a web search query. + A refusal from the model. - - `type: Literal["search"]` + - `refusal: str` - The action type. + The refusal explanation from the model. - - `"search"` + - `type: Literal["refusal"]` - - `queries: Optional[List[str]]` + The type of the refusal. Always `refusal`. - The search queries. + - `"refusal"` - - `query: Optional[str]` + - `role: Literal["assistant"]` - The search query. + The role of the output message. Always `assistant`. - - `sources: Optional[List[ActionSearchSource]]` + - `"assistant"` - The sources used in the search. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["url"]` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The type of source. Always `url`. + - `"in_progress"` - - `"url"` + - `"completed"` - - `url: str` + - `"incomplete"` - The URL of the source. + - `type: Literal["message"]` - - `class ActionOpenPage: …` + The type of the output message. Always `message`. - Action type "open_page" - Opens a specific URL from search results. + - `"message"` - - `type: Literal["open_page"]` + - `agent: Optional[Agent]` - The action type. + The agent that produced this item. - - `"open_page"` + - `agent_name: str` - - `url: Optional[str]` + The canonical name of the agent that produced this item. - The URL opened by the model. + - `phase: Optional[Literal["commentary", "final_answer"]]` - - `class ActionFindInPage: …` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"commentary"` - - `pattern: str` + - `"final_answer"` - The pattern or text to search for within the page. + - `class BetaResponseFileSearchToolCall: …` - - `type: Literal["find_in_page"]` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The action type. + - `id: str` - - `"find_in_page"` + The unique ID of the file search tool call. - - `url: str` + - `queries: List[str]` - The URL of the page searched for the pattern. + The queries used to search for files. - - `status: Literal["in_progress", "searching", "completed", "failed"]` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - The status of the web search tool call. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `"in_progress"` @@ -109435,13 +119856,15 @@ print(compacted_response) - `"completed"` + - `"incomplete"` + - `"failed"` - - `type: Literal["web_search_call"]` + - `type: Literal["file_search_call"]` - The type of the web search tool call. Always `web_search_call`. + The type of the file search tool call. Always `file_search_call`. - - `"web_search_call"` + - `"file_search_call"` - `agent: Optional[Agent]` @@ -109451,6 +119874,40 @@ print(compacted_response) The canonical name of the agent that produced this item. + - `results: Optional[List[Result]]` + + The results of the file search tool call. + + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + + 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, booleans, or numbers. + + - `str` + + - `float` + + - `bool` + + - `file_id: Optional[str]` + + The unique ID of the file. + + - `filename: Optional[str]` + + The name of the file. + + - `score: Optional[float]` + + The relevance score of the file - a value between 0 and 1. + + - `text: Optional[str]` + + The text that was retrieved from the file. + - `class BetaResponseComputerToolCall: …` A tool call to a computer use tool. See the @@ -109741,11 +120198,9 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem: …` - - - `id: str` + - `class ComputerCallOutput: …` - The unique ID of the computer call tool output. + The output of a computer tool call. - `call_id: str` @@ -109770,29 +120225,19 @@ print(compacted_response) The URL of the screenshot image. - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - - - `"completed"` - - - `"incomplete"` - - - `"failed"` - - - `"in_progress"` - - `type: Literal["computer_call_output"]` The type of the computer tool call output. Always `computer_call_output`. - `"computer_call_output"` - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + - `id: Optional[str]` - The safety checks reported by the API that have been acknowledged by the - developer. + The ID of the computer tool call output. + + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + + The safety checks reported by the API that have been acknowledged by the developer. - `id: str` @@ -109806,7 +120251,7 @@ print(compacted_response) Details about the pending safety check. - - `agent: Optional[Agent]` + - `agent: Optional[ComputerCallOutputAgent]` The agent that produced this item. @@ -109814,40 +120259,111 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The identifier of the actor that created the item. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `class BetaResponseReasoningItem: …` + - `"in_progress"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `"completed"` + + - `"incomplete"` + + - `class BetaResponseFunctionWebSearch: …` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: str` - The unique identifier of the reasoning content. + The unique ID of the web search tool call. - - `summary: List[Summary]` + - `action: Action` - Reasoning summary content. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `text: str` + - `class ActionSearch: …` - A summary of the reasoning output from the model so far. + Action type "search" - Performs a web search query. - - `type: Literal["summary_text"]` + - `type: Literal["search"]` - The type of the object. Always `summary_text`. + The action type. - - `"summary_text"` + - `"search"` - - `type: Literal["reasoning"]` + - `queries: Optional[List[str]]` - The type of the object. Always `reasoning`. + The search queries. - - `"reasoning"` + - `query: Optional[str]` + + The search query. + + - `sources: Optional[List[ActionSearchSource]]` + + The sources used in the search. + + - `type: Literal["url"]` + + The type of source. Always `url`. + + - `"url"` + + - `url: str` + + The URL of the source. + + - `class ActionOpenPage: …` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: Literal["open_page"]` + + The action type. + + - `"open_page"` + + - `url: Optional[str]` + + The URL opened by the model. + + - `class ActionFindInPage: …` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: str` + + The pattern or text to search for within the page. + + - `type: Literal["find_in_page"]` + + The action type. + + - `"find_in_page"` + + - `url: str` + + The URL of the page searched for the pattern. + + - `status: Literal["in_progress", "searching", "completed", "failed"]` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: Literal["web_search_call"]` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` - `agent: Optional[Agent]` @@ -109857,24 +120373,64 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `content: Optional[List[Content]]` + - `class BetaResponseFunctionToolCall: …` - Reasoning text content. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `text: str` + - `arguments: str` - The reasoning text from the model. + A JSON string of the arguments to pass to the function. - - `type: Literal["reasoning_text"]` + - `call_id: str` - The type of the reasoning text. Always `reasoning_text`. + The unique ID of the function tool call generated by the model. - - `"reasoning_text"` + - `name: str` - - `encrypted_content: Optional[str]` + The name of the function to run. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `type: Literal["function_call"]` + + The type of the function tool call. Always `function_call`. + + - `"function_call"` + + - `id: Optional[str]` + + The unique ID of the function tool call. + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `caller: Optional[Caller]` + + The execution context that produced this tool call. + + - `class CallerDirect: …` + + - `type: Literal["direct"]` + + - `"direct"` + + - `class CallerProgram: …` + + - `caller_id: str` + + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + - `"program"` + + - `namespace: Optional[str]` + + The namespace of the function to run. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` @@ -109887,31 +120443,145 @@ print(compacted_response) - `"incomplete"` - - `class Program: …` - - - `id: str` + - `class FunctionCallOutput: …` - The unique ID of the program item. + The output of a function tool call. - `call_id: str` - The stable call ID of the program item. + The unique ID of the function tool call generated by the model. - - `code: str` + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - The JavaScript source executed by programmatic tool calling. + Text, image, or file output of the function tool call. - - `fingerprint: str` + - `str` - Opaque program replay fingerprint that must be round-tripped. + A JSON string of the output of the function tool call. - - `type: Literal["program"]` + - `List[BetaResponseFunctionCallOutputItem]` - The type of the item. Always `program`. + - `class BetaResponseInputTextContent: …` - - `"program"` + A text input to the model. - - `agent: Optional[ProgramAgent]` + - `text: str` + + The text input to the model. + + - `type: Literal["input_text"]` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputImageContent: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: Literal["input_image"]` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `detail: Optional[Literal["low", "high", "auto", "original"]]` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `image_url: Optional[str]` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputFileContent: …` + + A file input to the model. + + - `type: Literal["input_file"]` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: Optional[Literal["auto", "low", "high"]]` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: Optional[str]` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `file_url: Optional[str]` + + The URL of the file to be sent to the model. + + - `filename: Optional[str]` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `type: Literal["function_call_output"]` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: Optional[str]` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: Optional[FunctionCallOutputAgent]` The agent that produced this item. @@ -109919,35 +120589,89 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ProgramOutput: …` + - `caller: Optional[FunctionCallOutputCaller]` - - `id: str` + The execution context that produced this tool call. - The unique ID of the program output item. + - `class FunctionCallOutputCallerDirect: …` - - `call_id: str` + - `type: Literal["direct"]` - The call ID of the program item. + The caller type. Always `direct`. - - `result: str` + - `"direct"` - The result produced by the program item. + - `class FunctionCallOutputCallerProgram: …` - - `status: Literal["completed", "incomplete"]` + - `caller_id: str` - The terminal status of the program output item. + The call ID of the program item that produced this tool call. + + - `type: Literal["program"]` + + The caller type. Always `program`. + + - `"program"` + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"in_progress"` - `"completed"` - `"incomplete"` - - `type: Literal["program_output"]` + - `class AgentMessage: …` - The type of the item. Always `program_output`. + A message routed between agents. - - `"program_output"` + - `author: str` - - `agent: Optional[ProgramOutputAgent]` + The sending agent identity. + + - `content: List[AgentMessageContent]` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent: …` + + A text input to the model. + + - `class BetaResponseInputImageContent: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `class AgentMessageContentEncryptedContent: …` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: str` + + Opaque encrypted content. + + - `type: Literal["encrypted_content"]` + + The type of the input item. Always `encrypted_content`. + + - `"encrypted_content"` + + - `recipient: str` + + The destination agent identity. + + - `type: Literal["agent_message"]` + + The item type. Always `agent_message`. + + - `"agent_message"` + + - `id: Optional[str]` + + The unique ID of this agent message item. + + - `agent: Optional[AgentMessageAgent]` The agent that produced this item. @@ -109955,45 +120679,173 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall: …` + - `class MultiAgentCall: …` - - `id: str` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - The unique ID of the tool search call item. + The multi-agent action that was executed. - - `arguments: object` + - `"spawn_agent"` - Arguments used for the tool search call. + - `"interrupt_agent"` - - `call_id: Optional[str]` + - `"list_agents"` - The unique ID of the tool search call generated by the model. + - `"send_message"` - - `execution: Literal["server", "client"]` + - `"followup_task"` - Whether tool search was executed by the server or by the client. + - `"wait_agent"` - - `"server"` + - `arguments: str` - - `"client"` + The action arguments as a JSON string. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `call_id: str` - The status of the tool search call item that was recorded. + The unique ID linking this call to its output. - - `"in_progress"` + - `type: Literal["multi_agent_call"]` - - `"completed"` + The item type. Always `multi_agent_call`. - - `"incomplete"` + - `"multi_agent_call"` - - `type: Literal["tool_search_call"]` + - `id: Optional[str]` - The type of the item. Always `tool_search_call`. + The unique ID of this multi-agent call. - - `"tool_search_call"` + - `agent: Optional[MultiAgentCallAgent]` - - `agent: Optional[Agent]` + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCallOutput: …` + + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: str` + + The unique ID of the multi-agent call. + + - `output: List[MultiAgentCallOutputOutput]` + + Text output returned by the multi-agent action. + + - `text: str` + + The text content. + + - `type: Literal["output_text"]` + + The content type. Always `output_text`. + + - `"output_text"` + + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + + Citations associated with the text content. + + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + + - `file_id: str` + + The ID of the file. + + - `filename: str` + + The filename of the file cited. + + - `index: int` + + The index of the file in the list of files. + + - `type: Literal["file_citation"]` + + The citation type. Always `file_citation`. + + - `"file_citation"` + + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + + - `end_index: int` + + The index of the last character of the citation in the message. + + - `start_index: int` + + The index of the first character of the citation in the message. + + - `title: str` + + The title of the cited resource. + + - `type: Literal["url_citation"]` + + The citation type. Always `url_citation`. + + - `"url_citation"` + + - `url: str` + + The URL of the cited resource. + + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + + - `container_id: str` + + The ID of the container. + + - `end_index: int` + + The index of the last character of the citation in the message. + + - `file_id: str` + + The ID of the container file. + + - `filename: str` + + The filename of the container file cited. + + - `start_index: int` + + The index of the first character of the citation in the message. + + - `type: Literal["container_file_citation"]` + + The citation type. Always `container_file_citation`. + + - `"container_file_citation"` + + - `type: Literal["multi_agent_call_output"]` + + The item type. Always `multi_agent_call_output`. + + - `"multi_agent_call_output"` + + - `id: Optional[str]` + + The unique ID of this multi-agent call output. + + - `agent: Optional[MultiAgentCallOutputAgent]` The agent that produced this item. @@ -110001,21 +120853,35 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` + - `class ToolSearchCall: …` - The identifier of the actor that created the item. + - `arguments: object` - - `class BetaResponseToolSearchOutputItem: …` + The arguments supplied to the tool search call. - - `id: str` + - `type: Literal["tool_search_call"]` - The unique ID of the tool search output item. + The item type. Always `tool_search_call`. + + - `"tool_search_call"` + + - `id: Optional[str]` + + The unique ID of this tool search call. + + - `agent: Optional[ToolSearchCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. - `call_id: Optional[str]` The unique ID of the tool search call generated by the model. - - `execution: Literal["server", "client"]` + - `execution: Optional[Literal["server", "client"]]` Whether tool search was executed by the server or by the client. @@ -110023,9 +120889,9 @@ print(compacted_response) - `"client"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the tool search output item that was recorded. + The status of the tool search call. - `"in_progress"` @@ -110033,9 +120899,11 @@ print(compacted_response) - `"incomplete"` + - `class BetaResponseToolSearchOutputItemParam: …` + - `tools: List[BetaTool]` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool: …` @@ -110134,7 +121002,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -110144,7 +121012,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `class FiltersCompoundFilter: …` @@ -110191,7 +121063,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -110201,7 +121073,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `object` @@ -111125,10 +122001,14 @@ print(compacted_response) - `type: Literal["tool_search_output"]` - The type of the item. Always `tool_search_output`. + The item type. Always `tool_search_output`. - `"tool_search_output"` + - `id: Optional[str]` + + The unique ID of this tool search output. + - `agent: Optional[Agent]` The agent that produced this item. @@ -111137,39 +122017,39 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` + - `call_id: Optional[str]` - The identifier of the actor that created the item. + The unique ID of the tool search call generated by the model. - - `class AdditionalTools: …` + - `execution: Optional[Literal["server", "client"]]` - - `id: str` + Whether tool search was executed by the server or by the client. - The unique ID of the additional tools item. + - `"server"` - - `role: Literal["unknown", "user", "assistant", 5 more]` + - `"client"` - The role that provided the additional tools. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"unknown"` + The status of the tool search output. - - `"user"` + - `"in_progress"` - - `"assistant"` + - `"completed"` - - `"system"` + - `"incomplete"` - - `"critic"` + - `class AdditionalTools: …` - - `"discriminator"` + - `role: Literal["developer"]` - - `"developer"` + The role that provided the additional tools. Only `developer` is supported. - - `"tool"` + - `"developer"` - `tools: List[BetaTool]` - The additional tool definitions made available at this item. + A list of additional tools made available at this item. - `class BetaFunctionTool: …` @@ -111237,10 +122117,14 @@ print(compacted_response) - `type: Literal["additional_tools"]` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. - `"additional_tools"` + - `id: Optional[str]` + + The unique ID of this additional tools item. + - `agent: Optional[AdditionalToolsAgent]` The agent that produced this item. @@ -111249,17 +122133,82 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem: …` + - `class BetaResponseReasoningItem: …` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: str` - The unique ID of the compaction item. + The unique identifier of the reasoning content. + + - `summary: List[Summary]` + + Reasoning summary content. + + - `text: str` + + A summary of the reasoning output from the model so far. + + - `type: Literal["summary_text"]` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `type: Literal["reasoning"]` + + The type of the object. Always `reasoning`. + + - `"reasoning"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `content: Optional[List[Content]]` + + Reasoning text content. + + - `text: str` + + The reasoning text from the model. + + - `type: Literal["reasoning_text"]` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: Optional[str]` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class BetaResponseCompactionItemParam: …` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `encrypted_content: str` - The encrypted content that was produced by compaction. + The encrypted content of the compaction summary. - `type: Literal["compaction"]` @@ -111267,6 +122216,10 @@ print(compacted_response) - `"compaction"` + - `id: Optional[str]` + + The ID of the compaction item. + - `agent: Optional[Agent]` The agent that produced this item. @@ -111275,10 +122228,6 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - `class ImageGenerationCall: …` An image generation request made by the model. @@ -111496,75 +122445,41 @@ print(compacted_response) - `"incomplete"` - - `class BetaResponseFunctionShellToolCall: …` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: str` + - `class ShellCall: …` - The unique ID of the shell tool call. Populated when this item is returned via API. + A tool representing a request to execute one or more shell commands. - - `action: Action` + - `action: ShellCallAction` The shell commands and limits that describe how to run the tool call. - `commands: List[str]` + Ordered shell commands for the execution environment to run. + - `max_output_length: Optional[int]` - Optional maximum number of characters to return from each command. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `timeout_ms: Optional[int]` - Optional timeout in milliseconds for the commands. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - `call_id: str` The unique ID of the shell tool call generated by the model. - - `environment: Optional[Environment]` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment: …` - - Represents the use of a local environment to perform shell actions. - - - `type: Literal["local"]` - - The environment type. Always `local`. - - - `"local"` - - - `class BetaResponseContainerReference: …` - - Represents a container created with /v1/containers. - - - `container_id: str` - - - `type: Literal["container_reference"]` - - The environment type. Always `container_reference`. - - - `"container_reference"` - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `type: Literal["shell_call"]` The type of the item. Always `shell_call`. - `"shell_call"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: Optional[ShellCallAgent]` The agent that produced this item. @@ -111572,17 +122487,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ShellCallCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ShellCallCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ShellCallCallerProgram: …` - `caller_id: str` @@ -111590,37 +122507,45 @@ print(compacted_response) - `type: Literal["program"]` + The caller type. Always `program`. + - `"program"` - - `created_by: Optional[str]` + - `environment: Optional[ShellCallEnvironment]` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `class BetaResponseFunctionShellToolCallOutput: …` + - `class BetaLocalEnvironment: …` - The output of a shell tool call that was emitted. + - `class BetaContainerReference: …` - - `id: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The unique ID of the shell call output. Populated when this item is returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `call_id: str` + - `"in_progress"` - The unique ID of the shell tool call generated by the model. + - `"completed"` - - `max_output_length: Optional[int]` + - `"incomplete"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `class ShellCallOutput: …` - - `output: List[Output]` + The streamed output items emitted by a shell tool call. - An array of shell call output contents + - `call_id: str` - - `outcome: OutputOutcome` + The unique ID of the shell tool call generated by the model. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `output: List[BetaResponseFunctionShellCallOutputContent]` - - `class OutputOutcomeTimeout: …` + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: Outcome` + + The exit or timeout outcome associated with this shell call. + + - `class OutcomeTimeout: …` Indicates that the shell call exceeded its configured time limit. @@ -111630,13 +122555,13 @@ print(compacted_response) - `"timeout"` - - `class OutputOutcomeExit: …` + - `class OutcomeExit: …` Indicates that the shell commands finished and returned an exit code. - `exit_code: int` - Exit code from the shell process. + The exit code returned by the shell process. - `type: Literal["exit"]` @@ -111646,33 +122571,23 @@ print(compacted_response) - `stderr: str` - The standard error output that was captured. + Captured stderr output for the shell call. - `stdout: str` - The standard output that was captured. - - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` + Captured stdout output for the shell call. - `type: Literal["shell_call_output"]` - The type of the shell call output. Always `shell_call_output`. + The type of the item. Always `shell_call_output`. - `"shell_call_output"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: Optional[ShellCallOutputAgent]` The agent that produced this item. @@ -111680,17 +122595,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ShellCallOutputCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ShellCallOutputCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ShellCallOutputCallerProgram: …` - `caller_id: str` @@ -111698,75 +122615,83 @@ print(compacted_response) - `type: Literal["program"]` + The caller type. Always `program`. + - `"program"` - - `created_by: Optional[str]` + - `max_output_length: Optional[int]` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseApplyPatchToolCall: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A tool call that applies file diffs by creating, deleting, or updating files. + The status of the shell call output. - - `id: str` + - `"in_progress"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"completed"` + + - `"incomplete"` + + - `class ApplyPatchCall: …` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: str` The unique ID of the apply patch tool call generated by the model. - - `operation: Operation` + - `operation: ApplyPatchCallOperation` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - - `class OperationCreateFile: …` + - `class ApplyPatchCallOperationCreateFile: …` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `diff: str` - Diff to apply. + Unified diff content to apply when creating the file. - `path: str` - Path of the file to create. + Path of the file to create relative to the workspace root. - `type: Literal["create_file"]` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `"create_file"` - - `class OperationDeleteFile: …` + - `class ApplyPatchCallOperationDeleteFile: …` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `path: str` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `type: Literal["delete_file"]` - Delete the specified file. + The operation type. Always `delete_file`. - `"delete_file"` - - `class OperationUpdateFile: …` + - `class ApplyPatchCallOperationUpdateFile: …` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `diff: str` - Diff to apply. + Unified diff content to apply to the existing file. - `path: str` - Path of the file to update. + Path of the file to update relative to the workspace root. - `type: Literal["update_file"]` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `"update_file"` @@ -111784,7 +122709,11 @@ print(compacted_response) - `"apply_patch_call"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallAgent]` The agent that produced this item. @@ -111792,17 +122721,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ApplyPatchCallCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ApplyPatchCallCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ApplyPatchCallCallerProgram: …` - `caller_id: str` @@ -111810,19 +122741,13 @@ print(compacted_response) - `type: Literal["program"]` - - `"program"` - - - `created_by: Optional[str]` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput: …` + The caller type. Always `program`. - The output emitted by an apply patch tool call. + - `"program"` - - `id: str` + - `class ApplyPatchCallOutput: …` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The streamed output emitted by an apply patch tool call. - `call_id: str` @@ -111842,7 +122767,11 @@ print(compacted_response) - `"apply_patch_call_output"` - - `agent: Optional[Agent]` + - `id: Optional[str]` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallOutputAgent]` The agent that produced this item. @@ -111850,17 +122779,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ApplyPatchCallOutputCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ApplyPatchCallOutputCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ApplyPatchCallOutputCallerProgram: …` - `caller_id: str` @@ -111868,76 +122799,13 @@ print(compacted_response) - `type: Literal["program"]` - - `"program"` - - - `created_by: Optional[str]` - - The ID of the entity that created this tool call output. - - - `output: Optional[str]` - - Optional textual output returned by the apply patch tool. - - - `class McpCall: …` - - An invocation of a tool on an MCP server. - - - `id: str` - - The unique ID of the tool call. - - - `arguments: str` - - A JSON string of the arguments passed to the tool. - - - `name: str` - - The name of the tool that was run. - - - `server_label: str` - - The label of the MCP server running the tool. - - - `type: Literal["mcp_call"]` - - The type of the item. Always `mcp_call`. - - - `"mcp_call"` - - - `agent: Optional[McpCallAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `approval_request_id: Optional[str]` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: Optional[str]` + The caller type. Always `program`. - The error from the tool call, if any. + - `"program"` - `output: Optional[str]` - The output from the tool call. - - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"calling"` - - - `"failed"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `class McpListTools: …` @@ -112027,10 +122895,6 @@ print(compacted_response) A response to an MCP approval request. - - `id: str` - - The unique ID of the approval response - - `approval_request_id: str` The ID of the approval request being answered. @@ -112045,6 +122909,10 @@ print(compacted_response) - `"mcp_approval_response"` + - `id: Optional[str]` + + The unique ID of the approval response + - `agent: Optional[McpApprovalResponseAgent]` The agent that produced this item. @@ -112057,33 +122925,33 @@ print(compacted_response) Optional reason for the decision. - - `class BetaResponseCustomToolCall: …` + - `class McpCall: …` - A call to a custom tool created by the model. + An invocation of a tool on an MCP server. - - `call_id: str` + - `id: str` - An identifier used to map this custom tool call to a tool call output. + The unique ID of the tool call. - - `input: str` + - `arguments: str` - The input for the custom tool call generated by the model. + A JSON string of the arguments passed to the tool. - `name: str` - The name of the custom tool being called. + The name of the tool that was run. - - `type: Literal["custom_tool_call"]` + - `server_label: str` - The type of the custom tool call. Always `custom_tool_call`. + The label of the MCP server running the tool. - - `"custom_tool_call"` + - `type: Literal["mcp_call"]` - - `id: Optional[str]` + The type of the item. Always `mcp_call`. - The unique ID of the custom tool call in the OpenAI platform. + - `"mcp_call"` - - `agent: Optional[Agent]` + - `agent: Optional[McpCallAgent]` The agent that produced this item. @@ -112091,536 +122959,554 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `approval_request_id: Optional[str]` - The execution context that produced this tool call. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `class CallerDirect: …` + - `error: Optional[str]` - - `type: Literal["direct"]` + The error from the tool call, if any. - - `"direct"` + - `output: Optional[str]` - - `class CallerProgram: …` + The output from the tool call. - - `caller_id: str` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - The call ID of the program item that produced this tool call. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `type: Literal["program"]` + - `"in_progress"` - - `"program"` + - `"completed"` - - `namespace: Optional[str]` + - `"incomplete"` - The namespace of the custom tool being called. + - `"calling"` - - `class BetaResponseCustomToolCallOutputItem: …` + - `"failed"` + + - `class BetaResponseCustomToolCallOutput: …` The output of a custom tool call from your code, being sent back to the model. - - `id: str` + - `call_id: str` - The unique ID of the custom tool call output item. + The call ID, used to map this custom tool call output to a custom tool call. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `output: Union[str, List[OutputOutputContentList]]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"in_progress"` + - `str` - - `"completed"` + A string of the output of the custom tool call. - - `"incomplete"` + - `List[OutputOutputContentList]` - - `created_by: Optional[str]` + Text, image, or file output of the custom tool call. - The identifier of the actor that created the item. + - `class BetaResponseInputText: …` -### Beta Response Output Item Added Event + A text input to the model. -- `class BetaResponseOutputItemAddedEvent: …` + - `class BetaResponseInputImage: …` - Emitted when a new output item is added. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `item: BetaResponseOutputItem` + - `class BetaResponseInputFile: …` - The output item that was added. + A file input to the model. - - `class BetaResponseOutputMessage: …` + - `type: Literal["custom_tool_call_output"]` - An output message from the model. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `id: str` + - `"custom_tool_call_output"` - The unique ID of the output message. + - `id: Optional[str]` - - `content: List[Content]` + The unique ID of the custom tool call output in the OpenAI platform. - The content of the output message. + - `agent: Optional[Agent]` - - `class BetaResponseOutputText: …` + The agent that produced this item. - A text output from the model. + - `agent_name: str` - - `annotations: List[Annotation]` + The canonical name of the agent that produced this item. - The annotations of the text output. + - `caller: Optional[Caller]` - - `class AnnotationFileCitation: …` + The execution context that produced this tool call. - A citation to a file. + - `class CallerDirect: …` - - `file_id: str` + - `type: Literal["direct"]` - The ID of the file. + The caller type. Always `direct`. - - `filename: str` + - `"direct"` - The filename of the file cited. + - `class CallerProgram: …` - - `index: int` + - `caller_id: str` - The index of the file in the list of files. + The call ID of the program item that produced this tool call. - - `type: Literal["file_citation"]` + - `type: Literal["program"]` - The type of the file citation. Always `file_citation`. + The caller type. Always `program`. - - `"file_citation"` + - `"program"` - - `class AnnotationURLCitation: …` + - `class BetaResponseCustomToolCall: …` - A citation for a web resource used to generate a model response. + A call to a custom tool created by the model. - - `end_index: int` + - `call_id: str` - The index of the last character of the URL citation in the message. + An identifier used to map this custom tool call to a tool call output. - - `start_index: int` + - `input: str` - The index of the first character of the URL citation in the message. + The input for the custom tool call generated by the model. - - `title: str` + - `name: str` - The title of the web resource. + The name of the custom tool being called. - - `type: Literal["url_citation"]` + - `type: Literal["custom_tool_call"]` - The type of the URL citation. Always `url_citation`. + The type of the custom tool call. Always `custom_tool_call`. - - `"url_citation"` + - `"custom_tool_call"` - - `url: str` + - `id: Optional[str]` - The URL of the web resource. + The unique ID of the custom tool call in the OpenAI platform. - - `class AnnotationContainerFileCitation: …` + - `agent: Optional[Agent]` - A citation for a container file used to generate a model response. + The agent that produced this item. - - `container_id: str` + - `agent_name: str` - The ID of the container file. + The canonical name of the agent that produced this item. - - `end_index: int` + - `caller: Optional[Caller]` - The index of the last character of the container file citation in the message. + The execution context that produced this tool call. - - `file_id: str` + - `class CallerDirect: …` - The ID of the file. + - `type: Literal["direct"]` - - `filename: str` + - `"direct"` - The filename of the container file cited. + - `class CallerProgram: …` - - `start_index: int` + - `caller_id: str` - The index of the first character of the container file citation in the message. + The call ID of the program item that produced this tool call. - - `type: Literal["container_file_citation"]` + - `type: Literal["program"]` - The type of the container file citation. Always `container_file_citation`. + - `"program"` - - `"container_file_citation"` + - `namespace: Optional[str]` - - `class AnnotationFilePath: …` + The namespace of the custom tool being called. - A path to a file. + - `class CompactionTrigger: …` - - `file_id: str` + Compacts the current context. Must be the final input item. - The ID of the file. + - `type: Literal["compaction_trigger"]` - - `index: int` + The type of the item. Always `compaction_trigger`. - The index of the file in the list of files. + - `"compaction_trigger"` - - `type: Literal["file_path"]` + - `agent: Optional[CompactionTriggerAgent]` - The type of the file path. Always `file_path`. + The agent that produced this item. - - `"file_path"` + - `agent_name: str` - - `text: str` + The canonical name of the agent that produced this item. - The text output from the model. + - `class ItemReference: …` - - `type: Literal["output_text"]` + An internal identifier for an item to reference. - The type of the output text. Always `output_text`. + - `id: str` - - `"output_text"` + The ID of the item to reference. - - `logprobs: Optional[List[Logprob]]` + - `agent: Optional[ItemReferenceAgent]` - - `token: str` + The agent that produced this item. - - `bytes: List[int]` + - `agent_name: str` - - `logprob: float` + The canonical name of the agent that produced this item. - - `top_logprobs: List[LogprobTopLogprob]` + - `type: Optional[Literal["item_reference"]]` - - `token: str` + The type of item to reference. Always `item_reference`. - - `bytes: List[int]` + - `"item_reference"` - - `logprob: float` + - `class Program: …` - - `class BetaResponseOutputRefusal: …` + - `id: str` - A refusal from the model. + The unique ID of this program item. - - `refusal: str` + - `call_id: str` - The refusal explanation from the model. + The stable call ID of the program item. - - `type: Literal["refusal"]` + - `code: str` - The type of the refusal. Always `refusal`. + The JavaScript source executed by programmatic tool calling. - - `"refusal"` + - `fingerprint: str` - - `role: Literal["assistant"]` + Opaque program replay fingerprint that must be round-tripped. - The role of the output message. Always `assistant`. + - `type: Literal["program"]` - - `"assistant"` + The item type. Always `program`. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"program"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `agent: Optional[ProgramAgent]` - - `"in_progress"` + The agent that produced this item. - - `"completed"` + - `agent_name: str` - - `"incomplete"` + The canonical name of the agent that produced this item. - - `type: Literal["message"]` + - `class ProgramOutput: …` - The type of the output message. Always `message`. + - `id: str` - - `"message"` + The unique ID of this program output item. - - `agent: Optional[Agent]` + - `call_id: str` - The agent that produced this item. + The call ID of the program item. - - `agent_name: str` + - `result: str` - The canonical name of the agent that produced this item. + The result produced by the program item. - - `phase: Optional[Literal["commentary"]]` + - `status: Literal["completed", "incomplete"]` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The terminal status of the program output. - - `"commentary"` + - `"completed"` - - `class BetaResponseFileSearchToolCall: …` + - `"incomplete"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `type: Literal["program_output"]` - - `id: str` + The item type. Always `program_output`. - The unique ID of the file search tool call. + - `"program_output"` - - `queries: List[str]` + - `agent: Optional[ProgramOutputAgent]` - The queries used to search for files. + The agent that produced this item. - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `agent_name: str` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The canonical name of the agent that produced this item. - - `"in_progress"` + - `metadata: Optional[Dict[str, str]]` - - `"searching"` + 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. - - `"completed"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"incomplete"` + - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` - - `"failed"` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `type: Literal["file_search_call"]` + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` - The type of the file search tool call. Always `file_search_call`. + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `"file_search_call"` + - `"gpt-5.6-sol"` - - `agent: Optional[Agent]` + - `"gpt-5.6-terra"` - The agent that produced this item. + - `"gpt-5.6-luna"` - - `agent_name: str` + - `"gpt-5.4"` - The canonical name of the agent that produced this item. + - `"gpt-5.4-mini"` - - `results: Optional[List[Result]]` + - `"gpt-5.4-nano"` - The results of the file search tool call. + - `"gpt-5.4-mini-2026-03-17"` - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + - `"gpt-5.4-nano-2026-03-17"` - 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, booleans, or numbers. + - `"gpt-5.3-chat-latest"` - - `str` + - `"gpt-5.2"` - - `float` + - `"gpt-5.2-2025-12-11"` - - `bool` + - `"gpt-5.2-chat-latest"` - - `file_id: Optional[str]` + - `"gpt-5.2-pro"` - The unique ID of the file. + - `"gpt-5.2-pro-2025-12-11"` - - `filename: Optional[str]` + - `"gpt-5.1"` - The name of the file. + - `"gpt-5.1-2025-11-13"` - - `score: Optional[float]` + - `"gpt-5.1-codex"` - The relevance score of the file - a value between 0 and 1. + - `"gpt-5.1-mini"` - - `text: Optional[str]` + - `"gpt-5.1-chat-latest"` - The text that was retrieved from the file. + - `"gpt-5"` - - `class BetaResponseFunctionToolCall: …` + - `"gpt-5-mini"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"gpt-5-nano"` - - `arguments: str` + - `"gpt-5-2025-08-07"` - A JSON string of the arguments to pass to the function. + - `"gpt-5-mini-2025-08-07"` - - `call_id: str` + - `"gpt-5-nano-2025-08-07"` - The unique ID of the function tool call generated by the model. + - `"gpt-5-chat-latest"` - - `name: str` + - `"gpt-4.1"` - The name of the function to run. + - `"gpt-4.1-mini"` - - `type: Literal["function_call"]` + - `"gpt-4.1-nano"` - The type of the function tool call. Always `function_call`. + - `"gpt-4.1-2025-04-14"` - - `"function_call"` + - `"gpt-4.1-mini-2025-04-14"` - - `id: Optional[str]` + - `"gpt-4.1-nano-2025-04-14"` - The unique ID of the function tool call. + - `"o4-mini"` - - `agent: Optional[Agent]` + - `"o4-mini-2025-04-16"` - The agent that produced this item. + - `"o3"` - - `agent_name: str` + - `"o3-2025-04-16"` - The canonical name of the agent that produced this item. + - `"o3-mini"` - - `caller: Optional[Caller]` + - `"o3-mini-2025-01-31"` - The execution context that produced this tool call. + - `"o1"` - - `class CallerDirect: …` + - `"o1-2024-12-17"` - - `type: Literal["direct"]` + - `"o1-preview"` - - `"direct"` + - `"o1-preview-2024-09-12"` - - `class CallerProgram: …` + - `"o1-mini"` - - `caller_id: str` + - `"o1-mini-2024-09-12"` - The call ID of the program item that produced this tool call. + - `"gpt-4o"` - - `type: Literal["program"]` + - `"gpt-4o-2024-11-20"` - - `"program"` + - `"gpt-4o-2024-08-06"` - - `namespace: Optional[str]` + - `"gpt-4o-2024-05-13"` - The namespace of the function to run. + - `"gpt-4o-audio-preview"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"gpt-4o-audio-preview-2024-10-01"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"gpt-4o-audio-preview-2024-12-17"` - - `"in_progress"` + - `"gpt-4o-audio-preview-2025-06-03"` - - `"completed"` + - `"gpt-4o-mini-audio-preview"` - - `"incomplete"` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `class BetaResponseFunctionToolCallOutputItem: …` + - `"gpt-4o-search-preview"` - - `id: str` + - `"gpt-4o-mini-search-preview"` - The unique ID of the function call tool output. + - `"gpt-4o-search-preview-2025-03-11"` - - `call_id: str` + - `"gpt-4o-mini-search-preview-2025-03-11"` - The unique ID of the function tool call generated by the model. + - `"chatgpt-4o-latest"` - - `output: Union[str, List[OutputOutputContentList]]` + - `"codex-mini-latest"` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `"gpt-4o-mini"` - - `str` + - `"gpt-4o-mini-2024-07-18"` - A string of the output of the function call. + - `"gpt-4-turbo"` - - `List[OutputOutputContentList]` + - `"gpt-4-turbo-2024-04-09"` - Text, image, or file output of the function call. + - `"gpt-4-0125-preview"` - - `class BetaResponseInputText: …` + - `"gpt-4-turbo-preview"` - A text input to the model. + - `"gpt-4-1106-preview"` - - `text: str` + - `"gpt-4-vision-preview"` - The text input to the model. + - `"gpt-4"` - - `type: Literal["input_text"]` + - `"gpt-4-0314"` - The type of the input item. Always `input_text`. + - `"gpt-4-0613"` - - `"input_text"` + - `"gpt-4-32k"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"gpt-4-32k-0314"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"gpt-4-32k-0613"` - - `mode: Literal["explicit"]` + - `"gpt-3.5-turbo"` - The breakpoint mode. Always `explicit`. + - `"gpt-3.5-turbo-16k"` - - `"explicit"` + - `"gpt-3.5-turbo-0301"` - - `class BetaResponseInputImage: …` + - `"gpt-3.5-turbo-0613"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"gpt-3.5-turbo-1106"` - - `detail: Literal["low", "high", "auto", "original"]` + - `"gpt-3.5-turbo-0125"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"gpt-3.5-turbo-16k-0613"` - - `"low"` + - `"o1-pro"` - - `"high"` + - `"o1-pro-2025-03-19"` - - `"auto"` + - `"o3-pro"` - - `"original"` + - `"o3-pro-2025-06-10"` - - `type: Literal["input_image"]` + - `"o3-deep-research"` - The type of the input item. Always `input_image`. + - `"o3-deep-research-2025-06-26"` - - `"input_image"` + - `"o4-mini-deep-research"` - - `file_id: Optional[str]` + - `"o4-mini-deep-research-2025-06-26"` - The ID of the file to be sent to the model. + - `"computer-use-preview"` - - `image_url: Optional[str]` + - `"computer-use-preview-2025-03-11"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"gpt-5-codex"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"gpt-5-pro"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"gpt-5-pro-2025-10-06"` - - `mode: Literal["explicit"]` + - `"gpt-5.1-codex-max"` - The breakpoint mode. Always `explicit`. + - `str` - - `"explicit"` + - `object: Literal["response"]` - - `class BetaResponseInputFile: …` + The object type of this resource - always set to `response`. + + - `"response"` + + - `output: List[BetaResponseOutputItem]` + + An array of content items generated by the model. + + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. + + - `class BetaResponseOutputMessage: …` - A file input to the model. + An output message from the model. - - `type: Literal["input_file"]` + - `class BetaResponseFileSearchToolCall: …` - The type of the input item. Always `input_file`. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `"input_file"` + - `class BetaResponseFunctionToolCall: …` - - `detail: Optional[Literal["auto", "low", "high"]]` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `class BetaResponseFunctionToolCallOutputItem: …` - - `"auto"` + - `id: str` - - `"low"` + The unique ID of the function call tool output. - - `"high"` + - `call_id: str` - - `file_data: Optional[str]` + The unique ID of the function tool call generated by the model. - The content of the file to be sent to the model. + - `output: Union[str, List[OutputOutputContentList]]` - - `file_id: Optional[str]` + The output from the function call generated by your code. + Can be a string or an list of output content. - The ID of the file to be sent to the model. + - `str` - - `file_url: Optional[str]` + A string of the output of the function call. - The URL of the file to be sent to the model. + - `List[OutputOutputContentList]` - - `filename: Optional[str]` + Text, image, or file output of the function call. - The name of the file to be sent to the model. + - `class BetaResponseInputText: …` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + A text input to the model. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class BetaResponseInputImage: …` - - `mode: Literal["explicit"]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The breakpoint mode. Always `explicit`. + - `class BetaResponseInputFile: …` - - `"explicit"` + A file input to the model. - `status: Literal["in_progress", "completed", "incomplete"]` @@ -112926,395 +123812,11 @@ print(compacted_response) The results of a web search tool call. See the [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `id: str` - - The unique ID of the web search tool call. - - - `action: Action` - - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). - - - `class ActionSearch: …` - - Action type "search" - Performs a web search query. - - - `type: Literal["search"]` - - The action type. - - - `"search"` - - - `queries: Optional[List[str]]` - - The search queries. - - - `query: Optional[str]` - - The search query. - - - `sources: Optional[List[ActionSearchSource]]` - - The sources used in the search. - - - `type: Literal["url"]` - - The type of source. Always `url`. - - - `"url"` - - - `url: str` - - The URL of the source. - - - `class ActionOpenPage: …` - - Action type "open_page" - Opens a specific URL from search results. - - - `type: Literal["open_page"]` - - The action type. - - - `"open_page"` - - - `url: Optional[str]` - - The URL opened by the model. - - - `class ActionFindInPage: …` - - Action type "find_in_page": Searches for a pattern within a loaded page. - - - `pattern: str` - - The pattern or text to search for within the page. - - - `type: Literal["find_in_page"]` - - The action type. - - - `"find_in_page"` - - - `url: str` - - The URL of the page searched for the pattern. - - - `status: Literal["in_progress", "searching", "completed", "failed"]` - - The status of the web search tool call. - - - `"in_progress"` - - - `"searching"` - - - `"completed"` - - - `"failed"` - - - `type: Literal["web_search_call"]` - - The type of the web search tool call. Always `web_search_call`. - - - `"web_search_call"` - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCall: …` A tool call to a computer use tool. See the [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `id: str` - - The unique ID of the computer call. - - - `call_id: str` - - An identifier used when responding to the tool call with output. - - - `pending_safety_checks: List[PendingSafetyCheck]` - - The pending safety checks for the computer call. - - - `id: str` - - The ID of the pending safety check. - - - `code: Optional[str]` - - The type of the pending safety check. - - - `message: Optional[str]` - - Details about the pending safety check. - - - `status: Literal["in_progress", "completed", "incomplete"]` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `type: Literal["computer_call"]` - - The type of the computer call. Always `computer_call`. - - - `"computer_call"` - - - `action: Optional[BetaComputerAction]` - - A click action. - - - `class Click: …` - - A click action. - - - `button: Literal["left", "right", "wheel", 2 more]` - - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - - `"left"` - - - `"right"` - - - `"wheel"` - - - `"back"` - - - `"forward"` - - - `type: Literal["click"]` - - Specifies the event type. For a click action, this property is always `click`. - - - `"click"` - - - `x: int` - - The x-coordinate where the click occurred. - - - `y: int` - - The y-coordinate where the click occurred. - - - `keys: Optional[List[str]]` - - The keys being held while clicking. - - - `class DoubleClick: …` - - A double click action. - - - `keys: Optional[List[str]]` - - The keys being held while double-clicking. - - - `type: Literal["double_click"]` - - Specifies the event type. For a double click action, this property is always set to `double_click`. - - - `"double_click"` - - - `x: int` - - The x-coordinate where the double click occurred. - - - `y: int` - - The y-coordinate where the double click occurred. - - - `class Drag: …` - - A drag action. - - - `path: List[DragPath]` - - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` - - - `x: int` - - The x-coordinate. - - - `y: int` - - The y-coordinate. - - - `type: Literal["drag"]` - - Specifies the event type. For a drag action, this property is always set to `drag`. - - - `"drag"` - - - `keys: Optional[List[str]]` - - The keys being held while dragging the mouse. - - - `class Keypress: …` - - A collection of keypresses the model would like to perform. - - - `keys: List[str]` - - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - - `type: Literal["keypress"]` - - Specifies the event type. For a keypress action, this property is always set to `keypress`. - - - `"keypress"` - - - `class Move: …` - - A mouse move action. - - - `type: Literal["move"]` - - Specifies the event type. For a move action, this property is always set to `move`. - - - `"move"` - - - `x: int` - - The x-coordinate to move to. - - - `y: int` - - The y-coordinate to move to. - - - `keys: Optional[List[str]]` - - The keys being held while moving the mouse. - - - `class Screenshot: …` - - A screenshot action. - - - `type: Literal["screenshot"]` - - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - - `"screenshot"` - - - `class Scroll: …` - - A scroll action. - - - `scroll_x: int` - - The horizontal scroll distance. - - - `scroll_y: int` - - The vertical scroll distance. - - - `type: Literal["scroll"]` - - Specifies the event type. For a scroll action, this property is always set to `scroll`. - - - `"scroll"` - - - `x: int` - - The x-coordinate where the scroll occurred. - - - `y: int` - - The y-coordinate where the scroll occurred. - - - `keys: Optional[List[str]]` - - The keys being held while scrolling. - - - `class Type: …` - - An action to type in text. - - - `text: str` - - The text to type. - - - `type: Literal["type"]` - - Specifies the event type. For a type action, this property is always set to `type`. - - - `"type"` - - - `class Wait: …` - - A wait action. - - - `type: Literal["wait"]` - - Specifies the event type. For a wait action, this property is always set to `wait`. - - - `"wait"` - - - `actions: Optional[BetaComputerActionList]` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `class Click: …` - - A click action. - - - `class DoubleClick: …` - - A double click action. - - - `class Drag: …` - - A drag action. - - - `class Keypress: …` - - A collection of keypresses the model would like to perform. - - - `class Move: …` - - A mouse move action. - - - `class Screenshot: …` - - A screenshot action. - - - `class Scroll: …` - - A scroll action. - - - `class Type: …` - - An action to type in text. - - - `class Wait: …` - - A wait action. - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem: …` - `id: str` @@ -113329,21 +123831,6 @@ print(compacted_response) A computer screenshot image used with the computer use tool. - - `type: Literal["computer_screenshot"]` - - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. - - - `"computer_screenshot"` - - - `file_id: Optional[str]` - - The identifier of an uploaded file that contains the screenshot. - - - `image_url: Optional[str]` - - The URL of the screenshot image. - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` The status of the message input. One of `in_progress`, `completed`, or @@ -113399,68 +123886,6 @@ print(compacted_response) for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `id: str` - - The unique identifier of the reasoning content. - - - `summary: List[Summary]` - - Reasoning summary content. - - - `text: str` - - A summary of the reasoning output from the model so far. - - - `type: Literal["summary_text"]` - - The type of the object. Always `summary_text`. - - - `"summary_text"` - - - `type: Literal["reasoning"]` - - The type of the object. Always `reasoning`. - - - `"reasoning"` - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `content: Optional[List[Content]]` - - Reasoning text content. - - - `text: str` - - The reasoning text from the model. - - - `type: Literal["reasoning_text"]` - - The type of the reasoning text. Always `reasoning_text`. - - - `"reasoning_text"` - - - `encrypted_content: Optional[str]` - - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `class Program: …` - `id: str` @@ -113615,1135 +124040,1143 @@ print(compacted_response) Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `name: str` + - `class BetaFileSearchTool: …` - The name of the function to call. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `parameters: Optional[Dict[str, object]]` + - `class BetaComputerTool: …` - A JSON schema object describing the parameters of the function. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `strict: Optional[bool]` + - `class BetaComputerUsePreviewTool: …` - Whether strict parameter validation is enforced for this function tool. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: Literal["function"]` + - `class BetaWebSearchTool: …` - The type of the function tool. Always `function`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"function"` + - `class Mcp: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The tool invocation context(s). + - `class CodeInterpreter: …` - - `"direct"` + A tool that runs Python code to help generate a response to a prompt. - - `"programmatic"` + - `class ProgrammaticToolCalling: …` - - `defer_loading: Optional[bool]` + - `class ImageGeneration: …` - Whether this function is deferred and loaded via tool search. + A tool that generates images using the GPT image models. - - `description: Optional[str]` + - `class LocalShell: …` - A description of the function. Used by the model to determine whether or not to call the function. + A tool that allows the model to execute shell commands in a local environment. - - `output_schema: Optional[Dict[str, object]]` + - `class BetaFunctionShellTool: …` - A JSON schema object describing the JSON value encoded in string outputs for this function. + A tool that allows the model to execute shell commands. - - `class BetaFileSearchTool: …` + - `class BetaCustomTool: …` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `type: Literal["file_search"]` + - `class BetaNamespaceTool: …` - The type of the file search tool. Always `file_search`. + Groups function/custom tools under a shared namespace. - - `"file_search"` + - `class BetaToolSearchTool: …` - - `vector_store_ids: List[str]` + Hosted or BYOT tool search configuration for deferred tools. - The IDs of the vector stores to search. + - `class BetaWebSearchPreviewTool: …` - - `filters: Optional[Filters]` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - A filter to apply. + - `class BetaApplyPatchTool: …` - - `class FiltersComparisonFilter: …` + Allows the assistant to create, delete, or update files using unified diffs. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: Literal["tool_search_output"]` - - `key: str` + The type of the item. Always `tool_search_output`. - The key to compare against the value. + - `"tool_search_output"` - - `type: Literal["eq", "ne", "gt", 5 more]` + - `agent: Optional[Agent]` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The agent that produced this item. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `agent_name: str` - - `"eq"` + The canonical name of the agent that produced this item. - - `"ne"` + - `created_by: Optional[str]` - - `"gt"` + The identifier of the actor that created the item. - - `"gte"` + - `class AdditionalTools: …` - - `"lt"` + - `id: str` - - `"lte"` + The unique ID of the additional tools item. - - `"in"` + - `role: Literal["unknown", "user", "assistant", 5 more]` - - `"nin"` + The role that provided the additional tools. - - `value: Union[str, float, bool, List[object]]` + - `"unknown"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"user"` - - `str` + - `"assistant"` - - `float` + - `"system"` - - `bool` + - `"critic"` - - `List[object]` + - `"discriminator"` - - `class FiltersCompoundFilter: …` + - `"developer"` - Combine multiple filters using `and` or `or`. + - `"tool"` - - `filters: List[FiltersCompoundFilterFilter]` + - `tools: List[BetaTool]` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The additional tool definitions made available at this item. - - `class FiltersCompoundFilterFilterComparisonFilter: …` + - `class BetaFunctionTool: …` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `key: str` + - `class BetaFileSearchTool: …` - The key to compare against the value. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: Literal["eq", "ne", "gt", 5 more]` + - `class BetaComputerTool: …` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `class BetaComputerUsePreviewTool: …` - - `"eq"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"ne"` + - `class BetaWebSearchTool: …` - - `"gt"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"gte"` + - `class Mcp: …` - - `"lt"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"lte"` + - `class CodeInterpreter: …` - - `"in"` + A tool that runs Python code to help generate a response to a prompt. - - `"nin"` + - `class ProgrammaticToolCalling: …` - - `value: Union[str, float, bool, List[object]]` + - `class ImageGeneration: …` - The value to compare against the attribute key; supports string, number, or boolean types. + A tool that generates images using the GPT image models. - - `str` + - `class LocalShell: …` - - `float` + A tool that allows the model to execute shell commands in a local environment. - - `bool` + - `class BetaFunctionShellTool: …` - - `List[object]` + A tool that allows the model to execute shell commands. - - `object` + - `class BetaCustomTool: …` - - `type: Literal["and", "or"]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - Type of operation: `and` or `or`. + - `class BetaNamespaceTool: …` - - `"and"` + Groups function/custom tools under a shared namespace. - - `"or"` + - `class BetaToolSearchTool: …` - - `max_num_results: Optional[int]` + Hosted or BYOT tool search configuration for deferred tools. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `class BetaWebSearchPreviewTool: …` - - `ranking_options: Optional[RankingOptions]` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Ranking options for search. + - `class BetaApplyPatchTool: …` - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + Allows the assistant to create, delete, or update files using unified diffs. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `type: Literal["additional_tools"]` - - `embedding_weight: float` + The type of the item. Always `additional_tools`. - The weight of the embedding in the reciprocal ranking fusion. + - `"additional_tools"` - - `text_weight: float` + - `agent: Optional[AdditionalToolsAgent]` - The weight of the text in the reciprocal ranking fusion. + The agent that produced this item. - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + - `agent_name: str` - The ranker to use for the file search. + The canonical name of the agent that produced this item. - - `"auto"` + - `class BetaResponseCompactionItem: …` - - `"default-2024-11-15"` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `score_threshold: Optional[float]` + - `id: str` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The unique ID of the compaction item. - - `class BetaComputerTool: …` + - `encrypted_content: str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The encrypted content that was produced by compaction. - - `type: Literal["computer"]` + - `type: Literal["compaction"]` - The type of the computer tool. Always `computer`. + The type of the item. Always `compaction`. - - `"computer"` + - `"compaction"` - - `class BetaComputerUsePreviewTool: …` + - `agent: Optional[Agent]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The agent that produced this item. - - `display_height: int` + - `agent_name: str` - The height of the computer display. + The canonical name of the agent that produced this item. - - `display_width: int` + - `created_by: Optional[str]` - The width of the computer display. + The identifier of the actor that created the item. - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `class ImageGenerationCall: …` - The type of computer environment to control. + An image generation request made by the model. - - `"windows"` + - `id: str` - - `"mac"` + The unique ID of the image generation call. - - `"linux"` + - `result: Optional[str]` - - `"ubuntu"` + The generated image encoded in base64. - - `"browser"` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - - `type: Literal["computer_use_preview"]` + The status of the image generation call. - The type of the computer use tool. Always `computer_use_preview`. + - `"in_progress"` - - `"computer_use_preview"` + - `"completed"` - - `class BetaWebSearchTool: …` + - `"generating"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"failed"` - - `type: Literal["web_search", "web_search_2025_08_26"]` + - `type: Literal["image_generation_call"]` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The type of the image generation call. Always `image_generation_call`. - - `"web_search"` + - `"image_generation_call"` - - `"web_search_2025_08_26"` + - `agent: Optional[ImageGenerationCallAgent]` - - `filters: Optional[Filters]` + The agent that produced this item. - Filters for the search. + - `agent_name: str` - - `allowed_domains: Optional[List[str]]` + The canonical name of the agent that produced this item. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `class BetaResponseCodeInterpreterToolCall: …` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + A tool call to run code. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `class LocalShellCall: …` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + A tool call to run a command on the local shell. - - `"low"` + - `id: str` - - `"medium"` + The unique ID of the local shell call. - - `"high"` + - `action: LocalShellCallAction` - - `user_location: Optional[UserLocation]` + Execute a shell command on the server. - The approximate location of the user. + - `command: List[str]` - - `city: Optional[str]` + The command to run. - Free text input for the city of the user, e.g. `San Francisco`. + - `env: Dict[str, str]` - - `country: Optional[str]` + Environment variables to set for the command. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: Literal["exec"]` - - `region: Optional[str]` + The type of the local shell action. Always `exec`. - Free text input for the region of the user, e.g. `California`. + - `"exec"` - - `timezone: Optional[str]` + - `timeout_ms: Optional[int]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Optional timeout in milliseconds for the command. - - `type: Optional[Literal["approximate"]]` + - `user: Optional[str]` - The type of location approximation. Always `approximate`. + Optional user to run the command as. - - `"approximate"` + - `working_directory: Optional[str]` - - `class Mcp: …` + Optional working directory to run the command in. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `call_id: str` - - `server_label: str` + The unique ID of the local shell tool call generated by the model. - A label for this MCP server, used to identify it in tool calls. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `type: Literal["mcp"]` + The status of the local shell call. - The type of the MCP tool. Always `mcp`. + - `"in_progress"` - - `"mcp"` + - `"completed"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"incomplete"` - The tool invocation context(s). + - `type: Literal["local_shell_call"]` - - `"direct"` + The type of the local shell call. Always `local_shell_call`. - - `"programmatic"` + - `"local_shell_call"` - - `allowed_tools: Optional[McpAllowedTools]` + - `agent: Optional[LocalShellCallAgent]` - List of allowed tool names or a filter object. + The agent that produced this item. - - `List[str]` + - `agent_name: str` - A string array of allowed tool names + The canonical name of the agent that produced this item. - - `class McpAllowedToolsMcpToolFilter: …` + - `class LocalShellCallOutput: …` - A filter object to specify which tools are allowed. + The output of a local shell tool call. - - `read_only: Optional[bool]` + - `id: str` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The unique ID of the local shell tool call generated by the model. - - `tool_names: Optional[List[str]]` + - `output: str` - List of allowed tool names. + A JSON string of the output of the local shell tool call. - - `authorization: Optional[str]` + - `type: Literal["local_shell_call_output"]` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + - `"local_shell_call_output"` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `agent: Optional[LocalShellCallOutputAgent]` - Currently supported `connector_id` values are: + The agent that produced this item. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `agent_name: str` - - `"connector_dropbox"` + The canonical name of the agent that produced this item. - - `"connector_gmail"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"connector_googlecalendar"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"connector_googledrive"` + - `"in_progress"` - - `"connector_microsoftteams"` + - `"completed"` - - `"connector_outlookcalendar"` + - `"incomplete"` - - `"connector_outlookemail"` + - `class BetaResponseFunctionShellToolCall: …` - - `"connector_sharepoint"` + A tool call that executes one or more shell commands in a managed environment. - - `defer_loading: Optional[bool]` + - `id: str` - Whether this MCP tool is deferred and discovered via tool search. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `headers: Optional[Dict[str, str]]` + - `action: Action` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The shell commands and limits that describe how to run the tool call. - - `require_approval: Optional[McpRequireApproval]` + - `commands: List[str]` - Specify which of the MCP server's tools require approval. + - `max_output_length: Optional[int]` - - `class McpRequireApprovalMcpToolApprovalFilter: …` + Optional maximum number of characters to return from each command. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `timeout_ms: Optional[int]` - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + Optional timeout in milliseconds for the commands. - A filter object to specify which tools are allowed. + - `call_id: str` - - `read_only: Optional[bool]` + The unique ID of the shell tool call generated by the model. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `environment: Optional[Environment]` - - `tool_names: Optional[List[str]]` + Represents the use of a local environment to perform shell actions. - List of allowed tool names. + - `class BetaResponseLocalEnvironment: …` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + Represents the use of a local environment to perform shell actions. - A filter object to specify which tools are allowed. + - `type: Literal["local"]` - - `read_only: Optional[bool]` + The environment type. Always `local`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"local"` - - `tool_names: Optional[List[str]]` + - `class BetaResponseContainerReference: …` - List of allowed tool names. + Represents a container created with /v1/containers. - - `Literal["always", "never"]` + - `container_id: str` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `type: Literal["container_reference"]` - - `"always"` + The environment type. Always `container_reference`. - - `"never"` + - `"container_reference"` - - `server_description: Optional[str]` + - `status: Literal["in_progress", "completed", "incomplete"]` - Optional description of the MCP server, used to provide more context. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `server_url: Optional[str]` + - `"in_progress"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"completed"` - - `tunnel_id: Optional[str]` + - `"incomplete"` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `type: Literal["shell_call"]` - - `class CodeInterpreter: …` + The type of the item. Always `shell_call`. - A tool that runs Python code to help generate a response to a prompt. + - `"shell_call"` - - `container: CodeInterpreterContainer` + - `agent: Optional[Agent]` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The agent that produced this item. - - `str` + - `agent_name: str` - The container ID. + The canonical name of the agent that produced this item. - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `caller: Optional[Caller]` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The execution context that produced this tool call. - - `type: Literal["auto"]` + - `class CallerDirect: …` - Always `auto`. + - `type: Literal["direct"]` - - `"auto"` + - `"direct"` - - `file_ids: Optional[List[str]]` + - `class CallerProgram: …` - An optional list of uploaded files to make available to your code. + - `caller_id: str` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + The call ID of the program item that produced this tool call. - The memory limit for the code interpreter container. + - `type: Literal["program"]` + + - `"program"` + + - `created_by: Optional[str]` + + The ID of the entity that created this tool call. + + - `class BetaResponseFunctionShellToolCallOutput: …` + + The output of a shell tool call that was emitted. + + - `id: str` + + The unique ID of the shell call output. Populated when this item is returned via API. + + - `call_id: str` + + The unique ID of the shell tool call generated by the model. + + - `max_output_length: Optional[int]` + + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `"1g"` + - `output: List[Output]` - - `"4g"` + An array of shell call output contents - - `"16g"` + - `outcome: OutputOutcome` - - `"64g"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `class OutputOutcomeTimeout: …` - Network access policy for the container. + Indicates that the shell call exceeded its configured time limit. - - `class BetaContainerNetworkPolicyDisabled: …` + - `type: Literal["timeout"]` - - `type: Literal["disabled"]` + The outcome type. Always `timeout`. - Disable outbound network access. Always `disabled`. + - `"timeout"` - - `"disabled"` + - `class OutputOutcomeExit: …` - - `class BetaContainerNetworkPolicyAllowlist: …` + Indicates that the shell commands finished and returned an exit code. - - `allowed_domains: List[str]` + - `exit_code: int` - A list of allowed domains when type is `allowlist`. + Exit code from the shell process. - - `type: Literal["allowlist"]` + - `type: Literal["exit"]` - Allow outbound network access only to specified domains. Always `allowlist`. + The outcome type. Always `exit`. - - `"allowlist"` + - `"exit"` - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `stderr: str` - Optional domain-scoped secrets for allowlisted domains. + The standard error output that was captured. - - `domain: str` + - `stdout: str` - The domain associated with the secret. + The standard output that was captured. - - `name: str` + - `created_by: Optional[str]` - The name of the secret to inject for the domain. + The identifier of the actor that created the item. - - `value: str` + - `status: Literal["in_progress", "completed", "incomplete"]` - The secret value to inject for the domain. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `type: Literal["code_interpreter"]` + - `"in_progress"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"completed"` - - `"code_interpreter"` + - `"incomplete"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["shell_call_output"]` - The tool invocation context(s). + The type of the shell call output. Always `shell_call_output`. - - `"direct"` + - `"shell_call_output"` - - `"programmatic"` + - `agent: Optional[Agent]` - - `class ProgrammaticToolCalling: …` + The agent that produced this item. - - `type: Literal["programmatic_tool_calling"]` + - `agent_name: str` - The type of the tool. Always `programmatic_tool_calling`. + The canonical name of the agent that produced this item. - - `"programmatic_tool_calling"` + - `caller: Optional[Caller]` - - `class ImageGeneration: …` + The execution context that produced this tool call. - A tool that generates images using the GPT image models. + - `class CallerDirect: …` - - `type: Literal["image_generation"]` + - `type: Literal["direct"]` - The type of the image generation tool. Always `image_generation`. + - `"direct"` - - `"image_generation"` + - `class CallerProgram: …` - - `action: Optional[Literal["generate", "edit", "auto"]]` + - `caller_id: str` - Whether to generate a new image or edit an existing image. Default: `auto`. + The call ID of the program item that produced this tool call. - - `"generate"` + - `type: Literal["program"]` - - `"edit"` + - `"program"` - - `"auto"` + - `created_by: Optional[str]` - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + The identifier of the actor that created the item. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `class BetaResponseApplyPatchToolCall: …` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + A tool call that applies file diffs by creating, deleting, or updating files. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `id: str` - - `"transparent"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"opaque"` + - `call_id: str` - - `"auto"` + The unique ID of the apply patch tool call generated by the model. - - `input_fidelity: Optional[Literal["high", "low"]]` + - `operation: Operation` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `"high"` + - `class OperationCreateFile: …` - - `"low"` + Instruction describing how to create a file via the apply_patch tool. - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + - `diff: str` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + Diff to apply. - - `file_id: Optional[str]` + - `path: str` - File ID for the mask image. + Path of the file to create. - - `image_url: Optional[str]` + - `type: Literal["create_file"]` - Base64-encoded mask image. + Create a new file with the provided diff. - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + - `"create_file"` - The image generation model to use. Default: `gpt-image-1`. + - `class OperationDeleteFile: …` - - `str` + Instruction describing how to delete a file via the apply_patch tool. - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `path: str` - The image generation model to use. Default: `gpt-image-1`. + Path of the file to delete. - - `"gpt-image-1"` + - `type: Literal["delete_file"]` - - `"gpt-image-1-mini"` + Delete the specified file. - - `"gpt-image-2"` + - `"delete_file"` - - `"gpt-image-2-2026-04-21"` + - `class OperationUpdateFile: …` - - `"gpt-image-1.5"` + Instruction describing how to update a file via the apply_patch tool. - - `"chatgpt-image-latest"` + - `diff: str` - - `moderation: Optional[Literal["auto", "low"]]` + Diff to apply. - Moderation level for the generated image. Default: `auto`. + - `path: str` - - `"auto"` + Path of the file to update. - - `"low"` + - `type: Literal["update_file"]` - - `output_compression: Optional[int]` + Update an existing file with the provided diff. - Compression level for the output image. Default: 100. + - `"update_file"` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + - `status: Literal["in_progress", "completed"]` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"png"` + - `"in_progress"` - - `"webp"` + - `"completed"` - - `"jpeg"` + - `type: Literal["apply_patch_call"]` - - `partial_images: Optional[int]` + The type of the item. Always `apply_patch_call`. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"apply_patch_call"` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + - `agent: Optional[Agent]` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The agent that produced this item. - - `"low"` + - `agent_name: str` - - `"medium"` + The canonical name of the agent that produced this item. - - `"high"` + - `caller: Optional[Caller]` - - `"auto"` + The execution context that produced this tool call. - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + - `class CallerDirect: …` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `type: Literal["direct"]` - - `str` + - `"direct"` - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `class CallerProgram: …` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `caller_id: str` - - `"1024x1024"` + The call ID of the program item that produced this tool call. - - `"1024x1536"` + - `type: Literal["program"]` - - `"1536x1024"` + - `"program"` - - `"auto"` + - `created_by: Optional[str]` - - `class LocalShell: …` + The ID of the entity that created this tool call. - A tool that allows the model to execute shell commands in a local environment. + - `class BetaResponseApplyPatchToolCallOutput: …` - - `type: Literal["local_shell"]` + The output emitted by an apply patch tool call. - The type of the local shell tool. Always `local_shell`. + - `id: str` - - `"local_shell"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `class BetaFunctionShellTool: …` + - `call_id: str` - A tool that allows the model to execute shell commands. + The unique ID of the apply patch tool call generated by the model. - - `type: Literal["shell"]` + - `status: Literal["completed", "failed"]` - The type of the shell tool. Always `shell`. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"shell"` + - `"completed"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"failed"` - The tool invocation context(s). + - `type: Literal["apply_patch_call_output"]` - - `"direct"` + The type of the item. Always `apply_patch_call_output`. - - `"programmatic"` + - `"apply_patch_call_output"` - - `environment: Optional[Environment]` + - `agent: Optional[Agent]` - - `class BetaContainerAuto: …` + The agent that produced this item. - - `type: Literal["container_auto"]` + - `agent_name: str` - Automatically creates a container for this request + The canonical name of the agent that produced this item. - - `"container_auto"` + - `caller: Optional[Caller]` - - `file_ids: Optional[List[str]]` + The execution context that produced this tool call. - An optional list of uploaded files to make available to your code. + - `class CallerDirect: …` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `type: Literal["direct"]` - The memory limit for the container. + - `"direct"` - - `"1g"` + - `class CallerProgram: …` - - `"4g"` + - `caller_id: str` - - `"16g"` + The call ID of the program item that produced this tool call. - - `"64g"` + - `type: Literal["program"]` - - `network_policy: Optional[NetworkPolicy]` + - `"program"` - Network access policy for the container. + - `created_by: Optional[str]` - - `class BetaContainerNetworkPolicyDisabled: …` + The ID of the entity that created this tool call output. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `output: Optional[str]` - - `skills: Optional[List[Skill]]` + Optional textual output returned by the apply patch tool. - An optional list of skills referenced by id or inline data. + - `class McpCall: …` - - `class BetaSkillReference: …` + An invocation of a tool on an MCP server. - - `skill_id: str` + - `id: str` - The ID of the referenced skill. + The unique ID of the tool call. - - `type: Literal["skill_reference"]` + - `arguments: str` - References a skill created with the /v1/skills endpoint. + A JSON string of the arguments passed to the tool. - - `"skill_reference"` + - `name: str` - - `version: Optional[str]` + The name of the tool that was run. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `server_label: str` - - `class BetaInlineSkill: …` + The label of the MCP server running the tool. - - `description: str` + - `type: Literal["mcp_call"]` - The description of the skill. + The type of the item. Always `mcp_call`. - - `name: str` + - `"mcp_call"` - The name of the skill. + - `agent: Optional[McpCallAgent]` - - `source: BetaInlineSkillSource` + The agent that produced this item. - Inline skill payload + - `agent_name: str` - - `data: str` + The canonical name of the agent that produced this item. - Base64-encoded skill zip bundle. + - `approval_request_id: Optional[str]` - - `media_type: Literal["application/zip"]` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The media type of the inline skill payload. Must be `application/zip`. + - `error: Optional[str]` - - `"application/zip"` + The error from the tool call, if any. - - `type: Literal["base64"]` + - `output: Optional[str]` - The type of the inline skill source. Must be `base64`. + The output from the tool call. - - `"base64"` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - `type: Literal["inline"]` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - Defines an inline skill for this request. + - `"in_progress"` - - `"inline"` + - `"completed"` - - `class BetaLocalEnvironment: …` + - `"incomplete"` - - `type: Literal["local"]` + - `"calling"` - Use a local computer environment. + - `"failed"` - - `"local"` + - `class McpListTools: …` - - `skills: Optional[List[BetaLocalSkill]]` + A list of tools available on an MCP server. - An optional list of skills. + - `id: str` - - `description: str` + The unique ID of the list. - The description of the skill. + - `server_label: str` - - `name: str` + The label of the MCP server. - The name of the skill. + - `tools: List[McpListToolsTool]` - - `path: str` + The tools available on the server. - The path to the directory containing the skill. + - `input_schema: object` - - `class BetaContainerReference: …` + The JSON schema describing the tool's input. - - `container_id: str` + - `name: str` - The ID of the referenced container. + The name of the tool. - - `type: Literal["container_reference"]` + - `annotations: Optional[object]` - References a container created with the /v1/containers endpoint + Additional annotations about the tool. - - `"container_reference"` + - `description: Optional[str]` - - `class BetaCustomTool: …` + The description of the tool. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: Literal["mcp_list_tools"]` - - `name: str` + The type of the item. Always `mcp_list_tools`. - The name of the custom tool, used to identify it in tool calls. + - `"mcp_list_tools"` - - `type: Literal["custom"]` + - `agent: Optional[McpListToolsAgent]` - The type of the custom tool. Always `custom`. + The agent that produced this item. - - `"custom"` + - `agent_name: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `error: Optional[str]` - - `"direct"` + Error message if the server could not list tools. - - `"programmatic"` + - `class McpApprovalRequest: …` - - `defer_loading: Optional[bool]` + A request for human approval of a tool invocation. - Whether this tool should be deferred and discovered via tool search. + - `id: str` - - `description: Optional[str]` + The unique ID of the approval request. - Optional description of the custom tool, used to provide more context. + - `arguments: str` - - `format: Optional[Format]` + A JSON string of arguments for the tool. - The input format for the custom tool. Default is unconstrained text. + - `name: str` - - `class FormatText: …` + The name of the tool to run. - Unconstrained free-form text. + - `server_label: str` - - `type: Literal["text"]` + The label of the MCP server making the request. - Unconstrained text format. Always `text`. + - `type: Literal["mcp_approval_request"]` - - `"text"` + The type of the item. Always `mcp_approval_request`. - - `class FormatGrammar: …` + - `"mcp_approval_request"` - A grammar defined by the user. + - `agent: Optional[McpApprovalRequestAgent]` - - `definition: str` + The agent that produced this item. - The grammar definition. + - `agent_name: str` - - `syntax: Literal["lark", "regex"]` + The canonical name of the agent that produced this item. - The syntax of the grammar definition. One of `lark` or `regex`. + - `class McpApprovalResponse: …` - - `"lark"` + A response to an MCP approval request. - - `"regex"` + - `id: str` - - `type: Literal["grammar"]` + The unique ID of the approval response - Grammar format. Always `grammar`. + - `approval_request_id: str` - - `"grammar"` + The ID of the approval request being answered. - - `class BetaNamespaceTool: …` + - `approve: bool` - Groups function/custom tools under a shared namespace. + Whether the request was approved. - - `description: str` + - `type: Literal["mcp_approval_response"]` - A description of the namespace shown to the model. + The type of the item. Always `mcp_approval_response`. - - `name: str` + - `"mcp_approval_response"` - The namespace name used in tool calls (for example, `crm`). + - `agent: Optional[McpApprovalResponseAgent]` - - `tools: List[Tool]` + The agent that produced this item. - The function/custom tools available inside this namespace. + - `agent_name: str` - - `class ToolFunction: …` + The canonical name of the agent that produced this item. - - `name: str` + - `reason: Optional[str]` - - `type: Literal["function"]` + Optional reason for the decision. - - `"function"` + - `class BetaResponseCustomToolCall: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + A call to a custom tool created by the model. - The tool invocation context(s). + - `class BetaResponseCustomToolCallOutputItem: …` - - `"direct"` + The output of a custom tool call from your code, being sent back to the model. - - `"programmatic"` + - `id: str` - - `defer_loading: Optional[bool]` + The unique ID of the custom tool call output item. - Whether this function should be deferred and discovered via tool search. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `description: Optional[str]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `output_schema: Optional[Dict[str, object]]` + - `"in_progress"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `"completed"` - - `parameters: Optional[object]` + - `"incomplete"` - - `strict: Optional[bool]` + - `created_by: Optional[str]` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The identifier of the actor that created the item. - - `class BetaCustomTool: …` + - `parallel_tool_calls: bool` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + Whether to allow the model to run tool calls in parallel. - - `type: Literal["namespace"]` + - `temperature: Optional[float]` - The type of the tool. Always `namespace`. + 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. + We generally recommend altering this or `top_p` but not both. - - `"namespace"` + - `tool_choice: ToolChoice` - - `class BetaToolSearchTool: …` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - Hosted or BYOT tool search configuration for deferred tools. + - `Literal["none", "auto", "required"]` - - `type: Literal["tool_search"]` + - `"none"` - The type of the tool. Always `tool_search`. + - `"auto"` - - `"tool_search"` + - `"required"` - - `description: Optional[str]` + - `class BetaToolChoiceAllowed: …` - Description shown to the model for a client-executed tool search tool. + Constrains the tools available to the model to a pre-defined set. - - `execution: Optional[Literal["server", "client"]]` + - `mode: Literal["auto", "required"]` - Whether tool search is executed by the server or by the client. + Constrains the tools available to the model to a pre-defined set. - - `"server"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `"client"` + `required` requires the model to call one or more of the allowed tools. - - `parameters: Optional[object]` + - `"auto"` - Parameter schema for a client-executed tool search tool. + - `"required"` - - `class BetaWebSearchPreviewTool: …` + - `tools: List[Dict[str, object]]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A list of tool definitions that the model should be allowed to call. - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + For the Responses API, the list of tool definitions might look like: - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `"web_search_preview"` + - `type: Literal["allowed_tools"]` - - `"web_search_preview_2025_03_11"` + Allowed tool configuration type. Always `allowed_tools`. - - `search_content_types: Optional[List[Literal["text", "image"]]]` + - `"allowed_tools"` - - `"text"` + - `class BetaToolChoiceTypes: …` - - `"image"` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `"low"` + Allowed values are: - - `"medium"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `"high"` + - `"file_search"` - - `user_location: Optional[UserLocation]` + - `"web_search_preview"` - The user's location. + - `"computer"` - - `type: Literal["approximate"]` + - `"computer_use_preview"` - The type of location approximation. Always `approximate`. + - `"computer_use"` - - `"approximate"` + - `"web_search_preview_2025_03_11"` - - `city: Optional[str]` + - `"image_generation"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"code_interpreter"` - - `country: Optional[str]` + - `class BetaToolChoiceFunction: …` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Use this option to force the model to call a specific function. - - `region: Optional[str]` + - `name: str` - Free text input for the region of the user, e.g. `California`. + The name of the function to call. - - `timezone: Optional[str]` + - `type: Literal["function"]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + For function calling, the type is always `function`. - - `class BetaApplyPatchTool: …` + - `"function"` - Allows the assistant to create, delete, or update files using unified diffs. + - `class BetaToolChoiceMcp: …` - - `type: Literal["apply_patch"]` + Use this option to force the model to call a specific tool on a remote MCP server. - The type of the tool. Always `apply_patch`. + - `server_label: str` - - `"apply_patch"` + The label of the MCP server to use. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["mcp"]` - The tool invocation context(s). + For MCP tools, the type is always `mcp`. - - `"direct"` + - `"mcp"` - - `"programmatic"` + - `name: Optional[str]` - - `type: Literal["tool_search_output"]` + The name of the tool to call on the server. - The type of the item. Always `tool_search_output`. + - `class BetaToolChoiceCustom: …` - - `"tool_search_output"` + Use this option to force the model to call a specific custom tool. - - `agent: Optional[Agent]` + - `name: str` - The agent that produced this item. + The name of the custom tool to call. - - `agent_name: str` + - `type: Literal["custom"]` - The canonical name of the agent that produced this item. + For custom tool calling, the type is always `custom`. - - `created_by: Optional[str]` + - `"custom"` - The identifier of the actor that created the item. + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` - - `class AdditionalTools: …` + - `type: Literal["programmatic_tool_calling"]` - - `id: str` + The tool to call. Always `programmatic_tool_calling`. - The unique ID of the additional tools item. + - `"programmatic_tool_calling"` - - `role: Literal["unknown", "user", "assistant", 5 more]` + - `class BetaToolChoiceApplyPatch: …` - The role that provided the additional tools. + Forces the model to call the apply_patch tool when executing a tool call. - - `"unknown"` + - `type: Literal["apply_patch"]` - - `"user"` + The tool to call. Always `apply_patch`. - - `"assistant"` + - `"apply_patch"` - - `"system"` + - `class BetaToolChoiceShell: …` - - `"critic"` + Forces the model to call the shell tool when a tool call is required. - - `"discriminator"` + - `type: Literal["shell"]` - - `"developer"` + The tool to call. Always `shell`. - - `"tool"` + - `"shell"` - `tools: List[BetaTool]` - The additional tool definitions made available at this item. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - `class BetaFunctionTool: …` @@ -114809,2323 +125242,2417 @@ print(compacted_response) Allows the assistant to create, delete, or update files using unified diffs. - - `type: Literal["additional_tools"]` + - `top_p: Optional[float]` - The type of the item. Always `additional_tools`. + 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. - - `"additional_tools"` + We generally recommend altering this or `temperature` but not both. - - `agent: Optional[AdditionalToolsAgent]` + - `background: Optional[bool]` - The agent that produced this item. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `agent_name: str` + - `completed_at: Optional[float]` - The canonical name of the agent that produced this item. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `class BetaResponseCompactionItem: …` + - `conversation: Optional[Conversation]` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - `id: str` - The unique ID of the compaction item. + The unique ID of the conversation that this response was associated with. - - `encrypted_content: str` + - `max_output_tokens: Optional[int]` - The encrypted content that was produced by compaction. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `type: Literal["compaction"]` + - `max_tool_calls: Optional[int]` - The type of the item. Always `compaction`. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `"compaction"` + - `moderation: Optional[Moderation]` - - `agent: Optional[Agent]` + Moderation results for the response input and output, if moderated completions were requested. - The agent that produced this item. + - `input: ModerationInput` - - `agent_name: str` + Moderation for the response input. - The canonical name of the agent that produced this item. + - `class ModerationInputModerationResult: …` - - `created_by: Optional[str]` + A moderation result produced for the response input or output. - The identifier of the actor that created the item. + - `categories: Dict[str, bool]` - - `class ImageGenerationCall: …` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - An image generation request made by the model. + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - - `id: str` + Which modalities of input are reflected by the score for each category. - The unique ID of the image generation call. + - `"text"` - - `result: Optional[str]` + - `"image"` - The generated image encoded in base64. + - `category_scores: Dict[str, float]` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + A dictionary of moderation categories to scores. - The status of the image generation call. + - `flagged: bool` - - `"in_progress"` + A boolean indicating whether the content was flagged by any category. - - `"completed"` + - `model: str` - - `"generating"` + The moderation model that produced this result. - - `"failed"` + - `type: Literal["moderation_result"]` - - `type: Literal["image_generation_call"]` + The object type, which was always `moderation_result` for successful moderation results. - The type of the image generation call. Always `image_generation_call`. + - `"moderation_result"` - - `"image_generation_call"` + - `class ModerationInputError: …` - - `agent: Optional[ImageGenerationCallAgent]` + An error produced while attempting moderation for the response input or output. - The agent that produced this item. + - `code: str` - - `agent_name: str` + The error code. - The canonical name of the agent that produced this item. + - `message: str` - - `class BetaResponseCodeInterpreterToolCall: …` + The error message. - A tool call to run code. + - `type: Literal["error"]` - - `id: str` + The object type, which was always `error` for moderation failures. - The unique ID of the code interpreter tool call. + - `"error"` - - `code: Optional[str]` + - `output: ModerationOutput` - The code to run, or null if not available. + Moderation for the response output. - - `container_id: str` + - `class ModerationOutputModerationResult: …` - The ID of the container used to run the code. + A moderation result produced for the response input or output. - - `outputs: Optional[List[Output]]` + - `categories: Dict[str, bool]` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `class OutputLogs: …` + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - The logs output from the code interpreter. + Which modalities of input are reflected by the score for each category. - - `logs: str` + - `"text"` - The logs output from the code interpreter. + - `"image"` - - `type: Literal["logs"]` + - `category_scores: Dict[str, float]` - The type of the output. Always `logs`. + A dictionary of moderation categories to scores. - - `"logs"` + - `flagged: bool` - - `class OutputImage: …` + A boolean indicating whether the content was flagged by any category. - The image output from the code interpreter. + - `model: str` - - `type: Literal["image"]` + The moderation model that produced this result. - The type of the output. Always `image`. + - `type: Literal["moderation_result"]` - - `"image"` + The object type, which was always `moderation_result` for successful moderation results. - - `url: str` + - `"moderation_result"` - The URL of the image output from the code interpreter. + - `class ModerationOutputError: …` - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + An error produced while attempting moderation for the response input or output. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `code: str` - - `"in_progress"` + The error code. - - `"completed"` + - `message: str` - - `"incomplete"` + The error message. - - `"interpreting"` + - `type: Literal["error"]` - - `"failed"` + The object type, which was always `error` for moderation failures. - - `type: Literal["code_interpreter_call"]` + - `"error"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `previous_response_id: Optional[str]` - - `"code_interpreter_call"` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `agent: Optional[Agent]` + - `prompt: Optional[BetaResponsePrompt]` - The agent that produced this item. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `agent_name: str` + - `id: str` - The canonical name of the agent that produced this item. + The unique identifier of the prompt template to use. - - `class LocalShellCall: …` + - `variables: Optional[Dict[str, Variables]]` - A tool call to run a command on the local shell. + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `id: str` + - `str` - The unique ID of the local shell call. + - `class BetaResponseInputText: …` - - `action: LocalShellCallAction` + A text input to the model. - Execute a shell command on the server. + - `class BetaResponseInputImage: …` - - `command: List[str]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The command to run. + - `class BetaResponseInputFile: …` - - `env: Dict[str, str]` + A file input to the model. - Environment variables to set for the command. + - `version: Optional[str]` - - `type: Literal["exec"]` + Optional version of the prompt template. - The type of the local shell action. Always `exec`. + - `prompt_cache_key: Optional[str]` - - `"exec"` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `timeout_ms: Optional[int]` + - `prompt_cache_options: Optional[PromptCacheOptions]` - Optional timeout in milliseconds for the command. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `user: Optional[str]` + - `mode: Literal["implicit", "explicit"]` - Optional user to run the command as. + Whether implicit prompt-cache breakpoints were enabled. - - `working_directory: Optional[str]` + - `"implicit"` - Optional working directory to run the command in. + - `"explicit"` - - `call_id: str` + - `ttl: Literal["30m"]` - The unique ID of the local shell tool call generated by the model. + The minimum lifetime applied to each cache breakpoint. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"30m"` - The status of the local shell call. + - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` - - `"in_progress"` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `"completed"` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `"incomplete"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `type: Literal["local_shell_call"]` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The type of the local shell call. Always `local_shell_call`. + - `"in_memory"` - - `"local_shell_call"` + - `"24h"` - - `agent: Optional[LocalShellCallAgent]` + - `reasoning: Optional[Reasoning]` - The agent that produced this item. + **gpt-5 and o-series models only** - - `agent_name: str` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The canonical name of the agent that produced this item. + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` - - `class LocalShellCallOutput: …` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - The output of a local shell tool call. + - `"auto"` - - `id: str` + - `"current_turn"` - The unique ID of the local shell tool call generated by the model. + - `"all_turns"` - - `output: str` + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` - A JSON string of the output of the local shell tool call. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `type: Literal["local_shell_call_output"]` + - `"none"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `"minimal"` - - `"local_shell_call_output"` + - `"low"` - - `agent: Optional[LocalShellCallOutputAgent]` + - `"medium"` - The agent that produced this item. + - `"high"` - - `agent_name: str` + - `"xhigh"` - The canonical name of the agent that produced this item. + - `"max"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + **Deprecated:** use `summary` instead. - - `"in_progress"` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `"completed"` + - `"auto"` - - `"incomplete"` + - `"concise"` - - `class BetaResponseFunctionShellToolCall: …` + - `"detailed"` - A tool call that executes one or more shell commands in a managed environment. + - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` - - `id: str` + Controls the reasoning execution mode for the request. - The unique ID of the shell tool call. Populated when this item is returned via API. + When returned on a response, this is the effective execution mode. - - `action: Action` + - `str` - The shell commands and limits that describe how to run the tool call. + - `Literal["standard", "pro"]` - - `commands: List[str]` + Controls the reasoning execution mode for the request. - - `max_output_length: Optional[int]` + When returned on a response, this is the effective execution mode. - Optional maximum number of characters to return from each command. + - `"standard"` - - `timeout_ms: Optional[int]` + - `"pro"` - Optional timeout in milliseconds for the commands. + - `summary: Optional[Literal["auto", "concise", "detailed"]]` - - `call_id: str` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The unique ID of the shell tool call generated by the model. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `environment: Optional[Environment]` + - `"auto"` - Represents the use of a local environment to perform shell actions. + - `"concise"` + + - `"detailed"` + + - `safety_identifier: Optional[str]` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"scale"` + + - `"priority"` + + - `status: Optional[BetaResponseStatus]` + + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + + - `"completed"` + + - `"failed"` - - `class BetaResponseLocalEnvironment: …` + - `"in_progress"` - Represents the use of a local environment to perform shell actions. + - `"cancelled"` - - `type: Literal["local"]` + - `"queued"` - The environment type. Always `local`. + - `"incomplete"` - - `"local"` + - `text: Optional[BetaResponseTextConfig]` - - `class BetaResponseContainerReference: …` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - Represents a container created with /v1/containers. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `container_id: str` + - `format: Optional[BetaResponseFormatTextConfig]` - - `type: Literal["container_reference"]` + An object specifying the format that the model must output. - The environment type. Always `container_reference`. + Configuring `{ "type": "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). - - `"container_reference"` + The default format is `{ "type": "text" }` with no additional options. - - `status: Literal["in_progress", "completed", "incomplete"]` + **Not recommended for gpt-4o and newer models:** - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `"in_progress"` + - `class Text: …` - - `"completed"` + Default response format. Used to generate text responses. - - `"incomplete"` + - `type: Literal["text"]` - - `type: Literal["shell_call"]` + The type of response format being defined. Always `text`. - The type of the item. Always `shell_call`. + - `"text"` - - `"shell_call"` + - `class BetaResponseFormatTextJSONSchemaConfig: …` - - `agent: Optional[Agent]` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The agent that produced this item. + - `name: str` - - `agent_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. - The canonical name of the agent that produced this item. + - `schema: Dict[str, object]` - - `caller: Optional[Caller]` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The execution context that produced this tool call. + - `type: Literal["json_schema"]` - - `class CallerDirect: …` + The type of response format being defined. Always `json_schema`. - - `type: Literal["direct"]` + - `"json_schema"` - - `"direct"` + - `description: Optional[str]` - - `class CallerProgram: …` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `caller_id: str` + - `strict: Optional[bool]` - The call ID of the program item that produced this tool call. + 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["program"]` + - `class JSONObject: …` - - `"program"` + 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. - - `created_by: Optional[str]` + - `type: Literal["json_object"]` - The ID of the entity that created this tool call. + The type of response format being defined. Always `json_object`. - - `class BetaResponseFunctionShellToolCallOutput: …` + - `"json_object"` - The output of a shell tool call that was emitted. + - `verbosity: Optional[Literal["low", "medium", "high"]]` - - `id: str` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - The unique ID of the shell call output. Populated when this item is returned via API. + - `"low"` - - `call_id: str` + - `"medium"` - The unique ID of the shell tool call generated by the model. + - `"high"` - - `max_output_length: Optional[int]` + - `top_logprobs: Optional[int]` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `output: List[Output]` + - `truncation: Optional[Literal["auto", "disabled"]]` - An array of shell call output contents + The truncation strategy to use for the model response. - - `outcome: OutputOutcome` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `"auto"` - - `class OutputOutcomeTimeout: …` + - `"disabled"` - Indicates that the shell call exceeded its configured time limit. + - `usage: Optional[BetaResponseUsage]` - - `type: Literal["timeout"]` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The outcome type. Always `timeout`. + - `input_tokens: int` - - `"timeout"` + The number of input tokens. - - `class OutputOutcomeExit: …` + - `input_tokens_details: InputTokensDetails` - Indicates that the shell commands finished and returned an exit code. + A detailed breakdown of the input tokens. - - `exit_code: int` + - `cache_write_tokens: int` - Exit code from the shell process. + The number of input tokens that were written to the cache. - - `type: Literal["exit"]` + - `cached_tokens: int` - The outcome type. Always `exit`. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `"exit"` + - `output_tokens: int` - - `stderr: str` + The number of output tokens. - The standard error output that was captured. + - `output_tokens_details: OutputTokensDetails` - - `stdout: str` + A detailed breakdown of the output tokens. - The standard output that was captured. + - `reasoning_tokens: int` - - `created_by: Optional[str]` + The number of reasoning tokens. - The identifier of the actor that created the item. + - `total_tokens: int` - - `status: Literal["in_progress", "completed", "incomplete"]` + The total number of tokens used. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `user: Optional[str]` - - `"in_progress"` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `"completed"` + - `sequence_number: int` - - `"incomplete"` + The sequence number for this event. - - `type: Literal["shell_call_output"]` + - `type: Literal["response.completed"]` - The type of the shell call output. Always `shell_call_output`. + The type of the event. Always `response.completed`. - - `"shell_call_output"` + - `"response.completed"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `class BetaResponseContentPartAddedEvent: …` - The execution context that produced this tool call. + Emitted when a new content part is added. - - `class CallerDirect: …` + - `content_index: int` - - `type: Literal["direct"]` + The index of the content part that was added. - - `"direct"` + - `item_id: str` - - `class CallerProgram: …` + The ID of the output item that the content part was added to. - - `caller_id: str` + - `output_index: int` - The call ID of the program item that produced this tool call. + The index of the output item that the content part was added to. - - `type: Literal["program"]` + - `part: Part` - - `"program"` + The content part that was added. - - `created_by: Optional[str]` + - `class BetaResponseOutputText: …` - The identifier of the actor that created the item. + A text output from the model. - - `class BetaResponseApplyPatchToolCall: …` + - `class BetaResponseOutputRefusal: …` - A tool call that applies file diffs by creating, deleting, or updating files. + A refusal from the model. - - `id: str` + - `class PartReasoningText: …` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Reasoning text from the model. - - `call_id: str` + - `text: str` - The unique ID of the apply patch tool call generated by the model. + The reasoning text from the model. - - `operation: Operation` + - `type: Literal["reasoning_text"]` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The type of the reasoning text. Always `reasoning_text`. - - `class OperationCreateFile: …` + - `"reasoning_text"` - Instruction describing how to create a file via the apply_patch tool. + - `sequence_number: int` - - `diff: str` + The sequence number of this event. - Diff to apply. + - `type: Literal["response.content_part.added"]` - - `path: str` + The type of the event. Always `response.content_part.added`. - Path of the file to create. + - `"response.content_part.added"` - - `type: Literal["create_file"]` + - `agent: Optional[Agent]` - Create a new file with the provided diff. + The agent that owns this multi-agent streaming event. - - `"create_file"` + - `agent_name: str` - - `class OperationDeleteFile: …` + The canonical name of the agent that produced this item. - Instruction describing how to delete a file via the apply_patch tool. + - `class BetaResponseContentPartDoneEvent: …` - - `path: str` + Emitted when a content part is done. - Path of the file to delete. + - `content_index: int` - - `type: Literal["delete_file"]` + The index of the content part that is done. - Delete the specified file. + - `item_id: str` - - `"delete_file"` + The ID of the output item that the content part was added to. - - `class OperationUpdateFile: …` + - `output_index: int` - Instruction describing how to update a file via the apply_patch tool. + The index of the output item that the content part was added to. - - `diff: str` + - `part: Part` - Diff to apply. + The content part that is done. - - `path: str` + - `class BetaResponseOutputText: …` - Path of the file to update. + A text output from the model. - - `type: Literal["update_file"]` + - `class BetaResponseOutputRefusal: …` - Update an existing file with the provided diff. + A refusal from the model. - - `"update_file"` + - `class PartReasoningText: …` - - `status: Literal["in_progress", "completed"]` + Reasoning text from the model. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `text: str` - - `"in_progress"` + The reasoning text from the model. - - `"completed"` + - `type: Literal["reasoning_text"]` - - `type: Literal["apply_patch_call"]` + The type of the reasoning text. Always `reasoning_text`. - The type of the item. Always `apply_patch_call`. + - `"reasoning_text"` - - `"apply_patch_call"` + - `sequence_number: int` + + The sequence number of this event. + + - `type: Literal["response.content_part.done"]` + + The type of the event. Always `response.content_part.done`. + + - `"response.content_part.done"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `class BetaResponseCreatedEvent: …` - The execution context that produced this tool call. + An event that is emitted when a response is created. - - `class CallerDirect: …` + - `response: BetaResponse` - - `type: Literal["direct"]` + The response that was created. - - `"direct"` + - `sequence_number: int` - - `class CallerProgram: …` + The sequence number for this event. - - `caller_id: str` + - `type: Literal["response.created"]` - The call ID of the program item that produced this tool call. + The type of the event. Always `response.created`. - - `type: Literal["program"]` + - `"response.created"` - - `"program"` + - `agent: Optional[Agent]` - - `created_by: Optional[str]` + The agent that owns this multi-agent streaming event. - The ID of the entity that created this tool call. + - `agent_name: str` - - `class BetaResponseApplyPatchToolCallOutput: …` + The canonical name of the agent that produced this item. - The output emitted by an apply patch tool call. + - `class BetaResponseErrorEvent: …` - - `id: str` + Emitted when an error occurs. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `code: Optional[str]` - - `call_id: str` + The error code. - The unique ID of the apply patch tool call generated by the model. + - `message: str` - - `status: Literal["completed", "failed"]` + The error message. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `param: Optional[str]` - - `"completed"` + The error parameter. - - `"failed"` + - `sequence_number: int` - - `type: Literal["apply_patch_call_output"]` + The sequence number of this event. - The type of the item. Always `apply_patch_call_output`. + - `type: Literal["error"]` - - `"apply_patch_call_output"` + The type of the event. Always `error`. + + - `"error"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. + - `class BetaResponseFileSearchCallCompletedEvent: …` - - `class CallerDirect: …` + Emitted when a file search call is completed (results found). - - `type: Literal["direct"]` + - `item_id: str` - - `"direct"` + The ID of the output item that the file search call is initiated. - - `class CallerProgram: …` + - `output_index: int` - - `caller_id: str` + The index of the output item that the file search call is initiated. - The call ID of the program item that produced this tool call. + - `sequence_number: int` - - `type: Literal["program"]` + The sequence number of this event. - - `"program"` + - `type: Literal["response.file_search_call.completed"]` - - `created_by: Optional[str]` + The type of the event. Always `response.file_search_call.completed`. - The ID of the entity that created this tool call output. + - `"response.file_search_call.completed"` - - `output: Optional[str]` + - `agent: Optional[Agent]` - Optional textual output returned by the apply patch tool. + The agent that owns this multi-agent streaming event. - - `class McpCall: …` + - `agent_name: str` - An invocation of a tool on an MCP server. + The canonical name of the agent that produced this item. - - `id: str` + - `class BetaResponseFileSearchCallInProgressEvent: …` - The unique ID of the tool call. + Emitted when a file search call is initiated. - - `arguments: str` + - `item_id: str` - A JSON string of the arguments passed to the tool. + The ID of the output item that the file search call is initiated. - - `name: str` + - `output_index: int` - The name of the tool that was run. + The index of the output item that the file search call is initiated. - - `server_label: str` + - `sequence_number: int` - The label of the MCP server running the tool. + The sequence number of this event. - - `type: Literal["mcp_call"]` + - `type: Literal["response.file_search_call.in_progress"]` - The type of the item. Always `mcp_call`. + The type of the event. Always `response.file_search_call.in_progress`. - - `"mcp_call"` + - `"response.file_search_call.in_progress"` - - `agent: Optional[McpCallAgent]` + - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `approval_request_id: Optional[str]` + - `class BetaResponseFileSearchCallSearchingEvent: …` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + Emitted when a file search is currently searching. - - `error: Optional[str]` + - `item_id: str` - The error from the tool call, if any. + The ID of the output item that the file search call is initiated. - - `output: Optional[str]` + - `output_index: int` - The output from the tool call. + The index of the output item that the file search call is searching. - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `sequence_number: int` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The sequence number of this event. - - `"in_progress"` + - `type: Literal["response.file_search_call.searching"]` - - `"completed"` + The type of the event. Always `response.file_search_call.searching`. - - `"incomplete"` + - `"response.file_search_call.searching"` - - `"calling"` + - `agent: Optional[Agent]` - - `"failed"` + The agent that owns this multi-agent streaming event. - - `class McpListTools: …` + - `agent_name: str` - A list of tools available on an MCP server. + The canonical name of the agent that produced this item. - - `id: str` + - `class BetaResponseFunctionCallArgumentsDeltaEvent: …` - The unique ID of the list. + Emitted when there is a partial function-call arguments delta. - - `server_label: str` + - `delta: str` - The label of the MCP server. + The function-call arguments delta that is added. - - `tools: List[McpListToolsTool]` + - `item_id: str` - The tools available on the server. + The ID of the output item that the function-call arguments delta is added to. - - `input_schema: object` + - `output_index: int` - The JSON schema describing the tool's input. + The index of the output item that the function-call arguments delta is added to. - - `name: str` + - `sequence_number: int` - The name of the tool. + The sequence number of this event. - - `annotations: Optional[object]` + - `type: Literal["response.function_call_arguments.delta"]` - Additional annotations about the tool. + The type of the event. Always `response.function_call_arguments.delta`. - - `description: Optional[str]` + - `"response.function_call_arguments.delta"` - The description of the tool. + - `agent: Optional[Agent]` - - `type: Literal["mcp_list_tools"]` + The agent that owns this multi-agent streaming event. - The type of the item. Always `mcp_list_tools`. + - `agent_name: str` - - `"mcp_list_tools"` + The canonical name of the agent that produced this item. - - `agent: Optional[McpListToolsAgent]` + - `class BetaResponseFunctionCallArgumentsDoneEvent: …` - The agent that produced this item. + Emitted when function-call arguments are finalized. - - `agent_name: str` + - `arguments: str` - The canonical name of the agent that produced this item. + The function-call arguments. - - `error: Optional[str]` + - `item_id: str` - Error message if the server could not list tools. + The ID of the item. - - `class McpApprovalRequest: …` + - `name: str` - A request for human approval of a tool invocation. + The name of the function that was called. - - `id: str` + - `output_index: int` - The unique ID of the approval request. + The index of the output item. - - `arguments: str` + - `sequence_number: int` - A JSON string of arguments for the tool. + The sequence number of this event. - - `name: str` + - `type: Literal["response.function_call_arguments.done"]` - The name of the tool to run. + - `"response.function_call_arguments.done"` - - `server_label: str` + - `agent: Optional[Agent]` - The label of the MCP server making the request. + The agent that owns this multi-agent streaming event. - - `type: Literal["mcp_approval_request"]` + - `agent_name: str` - The type of the item. Always `mcp_approval_request`. + The canonical name of the agent that produced this item. - - `"mcp_approval_request"` + - `class BetaResponseInProgressEvent: …` - - `agent: Optional[McpApprovalRequestAgent]` + Emitted when the response is in progress. - The agent that produced this item. + - `response: BetaResponse` - - `agent_name: str` + The response that is in progress. - The canonical name of the agent that produced this item. + - `sequence_number: int` - - `class McpApprovalResponse: …` + The sequence number of this event. - A response to an MCP approval request. + - `type: Literal["response.in_progress"]` - - `id: str` + The type of the event. Always `response.in_progress`. - The unique ID of the approval response + - `"response.in_progress"` - - `approval_request_id: str` + - `agent: Optional[Agent]` - The ID of the approval request being answered. + The agent that owns this multi-agent streaming event. - - `approve: bool` + - `agent_name: str` - Whether the request was approved. + The canonical name of the agent that produced this item. - - `type: Literal["mcp_approval_response"]` + - `class BetaResponseFailedEvent: …` - The type of the item. Always `mcp_approval_response`. + An event that is emitted when a response fails. - - `"mcp_approval_response"` + - `response: BetaResponse` - - `agent: Optional[McpApprovalResponseAgent]` + The response that failed. - The agent that produced this item. + - `sequence_number: int` - - `agent_name: str` + The sequence number of this event. - The canonical name of the agent that produced this item. + - `type: Literal["response.failed"]` - - `reason: Optional[str]` + The type of the event. Always `response.failed`. - Optional reason for the decision. + - `"response.failed"` - - `class BetaResponseCustomToolCall: …` + - `agent: Optional[Agent]` - A call to a custom tool created by the model. + The agent that owns this multi-agent streaming event. - - `call_id: str` + - `agent_name: str` - An identifier used to map this custom tool call to a tool call output. + The canonical name of the agent that produced this item. - - `input: str` + - `class BetaResponseIncompleteEvent: …` - The input for the custom tool call generated by the model. + An event that is emitted when a response finishes as incomplete. - - `name: str` + - `response: BetaResponse` - The name of the custom tool being called. + The response that was incomplete. - - `type: Literal["custom_tool_call"]` + - `sequence_number: int` - The type of the custom tool call. Always `custom_tool_call`. + The sequence number of this event. - - `"custom_tool_call"` + - `type: Literal["response.incomplete"]` - - `id: Optional[str]` + The type of the event. Always `response.incomplete`. - The unique ID of the custom tool call in the OpenAI platform. + - `"response.incomplete"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` + - `class BetaResponseOutputItemAddedEvent: …` - - `type: Literal["direct"]` + Emitted when a new output item is added. - - `"direct"` + - `item: BetaResponseOutputItem` - - `class CallerProgram: …` + The output item that was added. - - `caller_id: str` + - `class BetaResponseOutputMessage: …` - The call ID of the program item that produced this tool call. + An output message from the model. - - `type: Literal["program"]` + - `class BetaResponseFileSearchToolCall: …` - - `"program"` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `namespace: Optional[str]` + - `class BetaResponseFunctionToolCall: …` - The namespace of the custom tool being called. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `class BetaResponseCustomToolCallOutputItem: …` + - `class BetaResponseFunctionToolCallOutputItem: …` - The output of a custom tool call from your code, being sent back to the model. + - `class AgentMessage: …` - - `id: str` + - `class MultiAgentCall: …` - The unique ID of the custom tool call output item. + - `class MultiAgentCallOutput: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `class BetaResponseFunctionWebSearch: …` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `"in_progress"` + - `class BetaResponseComputerToolCall: …` - - `"completed"` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `"incomplete"` + - `class BetaResponseComputerToolCallOutputItem: …` - - `created_by: Optional[str]` + - `class BetaResponseReasoningItem: …` - The identifier of the actor that created the item. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `output_index: int` + - `class Program: …` - The index of the output item that was added. + - `class ProgramOutput: …` - - `sequence_number: int` + - `class BetaResponseToolSearchCall: …` - The sequence number of this event. + - `class BetaResponseToolSearchOutputItem: …` - - `type: Literal["response.output_item.added"]` + - `class AdditionalTools: …` - The type of the event. Always `response.output_item.added`. + - `class BetaResponseCompactionItem: …` - - `"response.output_item.added"` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `agent: Optional[Agent]` + - `class ImageGenerationCall: …` - The agent that owns this multi-agent streaming event. + An image generation request made by the model. - - `agent_name: str` + - `class BetaResponseCodeInterpreterToolCall: …` - The canonical name of the agent that produced this item. + A tool call to run code. -### Beta Response Output Item Done Event + - `class LocalShellCall: …` -- `class BetaResponseOutputItemDoneEvent: …` + A tool call to run a command on the local shell. - Emitted when an output item is marked done. + - `class LocalShellCallOutput: …` - - `item: BetaResponseOutputItem` + The output of a local shell tool call. - The output item that was marked done. + - `class BetaResponseFunctionShellToolCall: …` - - `class BetaResponseOutputMessage: …` + A tool call that executes one or more shell commands in a managed environment. - An output message from the model. + - `class BetaResponseFunctionShellToolCallOutput: …` - - `id: str` + The output of a shell tool call that was emitted. - The unique ID of the output message. + - `class BetaResponseApplyPatchToolCall: …` - - `content: List[Content]` + A tool call that applies file diffs by creating, deleting, or updating files. - The content of the output message. + - `class BetaResponseApplyPatchToolCallOutput: …` - - `class BetaResponseOutputText: …` + The output emitted by an apply patch tool call. - A text output from the model. + - `class McpCall: …` - - `annotations: List[Annotation]` + An invocation of a tool on an MCP server. - The annotations of the text output. + - `class McpListTools: …` - - `class AnnotationFileCitation: …` + A list of tools available on an MCP server. - A citation to a file. + - `class McpApprovalRequest: …` - - `file_id: str` + A request for human approval of a tool invocation. - The ID of the file. + - `class McpApprovalResponse: …` - - `filename: str` + A response to an MCP approval request. - The filename of the file cited. + - `class BetaResponseCustomToolCall: …` - - `index: int` + A call to a custom tool created by the model. - The index of the file in the list of files. + - `class BetaResponseCustomToolCallOutputItem: …` - - `type: Literal["file_citation"]` + The output of a custom tool call from your code, being sent back to the model. - The type of the file citation. Always `file_citation`. + - `output_index: int` - - `"file_citation"` + The index of the output item that was added. - - `class AnnotationURLCitation: …` + - `sequence_number: int` - A citation for a web resource used to generate a model response. + The sequence number of this event. - - `end_index: int` + - `type: Literal["response.output_item.added"]` - The index of the last character of the URL citation in the message. + The type of the event. Always `response.output_item.added`. - - `start_index: int` + - `"response.output_item.added"` - The index of the first character of the URL citation in the message. + - `agent: Optional[Agent]` - - `title: str` + The agent that owns this multi-agent streaming event. - The title of the web resource. + - `agent_name: str` - - `type: Literal["url_citation"]` + The canonical name of the agent that produced this item. - The type of the URL citation. Always `url_citation`. + - `class BetaResponseOutputItemDoneEvent: …` - - `"url_citation"` + Emitted when an output item is marked done. - - `url: str` + - `item: BetaResponseOutputItem` - The URL of the web resource. + The output item that was marked done. - - `class AnnotationContainerFileCitation: …` + - `output_index: int` - A citation for a container file used to generate a model response. + The index of the output item that was marked done. - - `container_id: str` + - `sequence_number: int` - The ID of the container file. + The sequence number of this event. - - `end_index: int` + - `type: Literal["response.output_item.done"]` - The index of the last character of the container file citation in the message. + The type of the event. Always `response.output_item.done`. - - `file_id: str` + - `"response.output_item.done"` - The ID of the file. + - `agent: Optional[Agent]` - - `filename: str` + The agent that owns this multi-agent streaming event. - The filename of the container file cited. + - `agent_name: str` - - `start_index: int` + The canonical name of the agent that produced this item. - The index of the first character of the container file citation in the message. + - `class BetaResponseReasoningSummaryPartAddedEvent: …` - - `type: Literal["container_file_citation"]` + Emitted when a new reasoning summary part is added. - The type of the container file citation. Always `container_file_citation`. + - `item_id: str` - - `"container_file_citation"` + The ID of the item this summary part is associated with. - - `class AnnotationFilePath: …` + - `output_index: int` - A path to a file. + The index of the output item this summary part is associated with. - - `file_id: str` + - `part: Part` - The ID of the file. + The summary part that was added. - - `index: int` + - `text: str` - The index of the file in the list of files. + The text of the summary part. - - `type: Literal["file_path"]` + - `type: Literal["summary_text"]` - The type of the file path. Always `file_path`. + The type of the summary part. Always `summary_text`. - - `"file_path"` + - `"summary_text"` - - `text: str` + - `sequence_number: int` - The text output from the model. + The sequence number of this event. - - `type: Literal["output_text"]` + - `summary_index: int` - The type of the output text. Always `output_text`. + The index of the summary part within the reasoning summary. - - `"output_text"` + - `type: Literal["response.reasoning_summary_part.added"]` - - `logprobs: Optional[List[Logprob]]` + The type of the event. Always `response.reasoning_summary_part.added`. - - `token: str` + - `"response.reasoning_summary_part.added"` - - `bytes: List[int]` + - `agent: Optional[Agent]` - - `logprob: float` + The agent that owns this multi-agent streaming event. - - `top_logprobs: List[LogprobTopLogprob]` + - `agent_name: str` - - `token: str` + The canonical name of the agent that produced this item. - - `bytes: List[int]` + - `class BetaResponseReasoningSummaryPartDoneEvent: …` - - `logprob: float` + Emitted when a reasoning summary part is completed. - - `class BetaResponseOutputRefusal: …` + - `item_id: str` - A refusal from the model. + The ID of the item this summary part is associated with. - - `refusal: str` + - `output_index: int` - The refusal explanation from the model. + The index of the output item this summary part is associated with. - - `type: Literal["refusal"]` + - `part: Part` - The type of the refusal. Always `refusal`. + The completed summary part. - - `"refusal"` + - `text: str` - - `role: Literal["assistant"]` + The text of the summary part. - The role of the output message. Always `assistant`. + - `type: Literal["summary_text"]` - - `"assistant"` + The type of the summary part. Always `summary_text`. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"summary_text"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `sequence_number: int` - - `"in_progress"` + The sequence number of this event. - - `"completed"` + - `summary_index: int` - - `"incomplete"` + The index of the summary part within the reasoning summary. - - `type: Literal["message"]` + - `type: Literal["response.reasoning_summary_part.done"]` - The type of the output message. Always `message`. + The type of the event. Always `response.reasoning_summary_part.done`. - - `"message"` + - `"response.reasoning_summary_part.done"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `phase: Optional[Literal["commentary"]]` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `status: Optional[Literal["incomplete"]]` - - `"commentary"` + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - - `class BetaResponseFileSearchToolCall: …` + - `"incomplete"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `class BetaResponseReasoningSummaryTextDeltaEvent: …` - - `id: str` + Emitted when a delta is added to a reasoning summary text. - The unique ID of the file search tool call. + - `delta: str` - - `queries: List[str]` + The text delta that was added to the summary. - The queries used to search for files. + - `item_id: str` - - `status: Literal["in_progress", "searching", "completed", 2 more]` + The ID of the item this summary text delta is associated with. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `output_index: int` - - `"in_progress"` + The index of the output item this summary text delta is associated with. - - `"searching"` + - `sequence_number: int` - - `"completed"` + The sequence number of this event. - - `"incomplete"` + - `summary_index: int` - - `"failed"` + The index of the summary part within the reasoning summary. - - `type: Literal["file_search_call"]` + - `type: Literal["response.reasoning_summary_text.delta"]` - The type of the file search tool call. Always `file_search_call`. + The type of the event. Always `response.reasoning_summary_text.delta`. - - `"file_search_call"` + - `"response.reasoning_summary_text.delta"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `results: Optional[List[Result]]` - - The results of the file search tool call. + - `class BetaResponseReasoningSummaryTextDoneEvent: …` - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + Emitted when a reasoning summary text is completed. - 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, booleans, or numbers. + - `item_id: str` - - `str` + The ID of the item this summary text is associated with. - - `float` + - `output_index: int` - - `bool` + The index of the output item this summary text is associated with. - - `file_id: Optional[str]` + - `sequence_number: int` - The unique ID of the file. + The sequence number of this event. - - `filename: Optional[str]` + - `summary_index: int` - The name of the file. + The index of the summary part within the reasoning summary. - - `score: Optional[float]` + - `text: str` - The relevance score of the file - a value between 0 and 1. + The full text of the completed reasoning summary. - - `text: Optional[str]` + - `type: Literal["response.reasoning_summary_text.done"]` - The text that was retrieved from the file. + The type of the event. Always `response.reasoning_summary_text.done`. - - `class BetaResponseFunctionToolCall: …` + - `"response.reasoning_summary_text.done"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `agent: Optional[Agent]` - - `arguments: str` + The agent that owns this multi-agent streaming event. - A JSON string of the arguments to pass to the function. + - `agent_name: str` - - `call_id: str` + The canonical name of the agent that produced this item. - The unique ID of the function tool call generated by the model. + - `class BetaResponseReasoningTextDeltaEvent: …` - - `name: str` + Emitted when a delta is added to a reasoning text. - The name of the function to run. + - `content_index: int` - - `type: Literal["function_call"]` + The index of the reasoning content part this delta is associated with. - The type of the function tool call. Always `function_call`. + - `delta: str` - - `"function_call"` + The text delta that was added to the reasoning content. - - `id: Optional[str]` + - `item_id: str` - The unique ID of the function tool call. + The ID of the item this reasoning text delta is associated with. - - `agent: Optional[Agent]` + - `output_index: int` - The agent that produced this item. + The index of the output item this reasoning text delta is associated with. - - `agent_name: str` + - `sequence_number: int` - The canonical name of the agent that produced this item. + The sequence number of this event. - - `caller: Optional[Caller]` + - `type: Literal["response.reasoning_text.delta"]` - The execution context that produced this tool call. + The type of the event. Always `response.reasoning_text.delta`. - - `class CallerDirect: …` + - `"response.reasoning_text.delta"` - - `type: Literal["direct"]` + - `agent: Optional[Agent]` - - `"direct"` + The agent that owns this multi-agent streaming event. - - `class CallerProgram: …` + - `agent_name: str` - - `caller_id: str` + The canonical name of the agent that produced this item. - The call ID of the program item that produced this tool call. + - `class BetaResponseReasoningTextDoneEvent: …` - - `type: Literal["program"]` + Emitted when a reasoning text is completed. - - `"program"` + - `content_index: int` - - `namespace: Optional[str]` + The index of the reasoning content part. - The namespace of the function to run. + - `item_id: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The ID of the item this reasoning text is associated with. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `output_index: int` - - `"in_progress"` + The index of the output item this reasoning text is associated with. - - `"completed"` + - `sequence_number: int` - - `"incomplete"` + The sequence number of this event. - - `class BetaResponseFunctionToolCallOutputItem: …` + - `text: str` - - `id: str` + The full text of the completed reasoning content. - The unique ID of the function call tool output. + - `type: Literal["response.reasoning_text.done"]` - - `call_id: str` + The type of the event. Always `response.reasoning_text.done`. - The unique ID of the function tool call generated by the model. + - `"response.reasoning_text.done"` - - `output: Union[str, List[OutputOutputContentList]]` + - `agent: Optional[Agent]` - The output from the function call generated by your code. - Can be a string or an list of output content. + The agent that owns this multi-agent streaming event. - - `str` + - `agent_name: str` - A string of the output of the function call. + The canonical name of the agent that produced this item. - - `List[OutputOutputContentList]` + - `class BetaResponseRefusalDeltaEvent: …` - Text, image, or file output of the function call. + Emitted when there is a partial refusal text. - - `class BetaResponseInputText: …` + - `content_index: int` - A text input to the model. + The index of the content part that the refusal text is added to. - - `text: str` + - `delta: str` - The text input to the model. + The refusal text that is added. - - `type: Literal["input_text"]` + - `item_id: str` - The type of the input item. Always `input_text`. + The ID of the output item that the refusal text is added to. - - `"input_text"` + - `output_index: int` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The index of the output item that the refusal text is added to. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `sequence_number: int` - - `mode: Literal["explicit"]` + The sequence number of this event. - The breakpoint mode. Always `explicit`. + - `type: Literal["response.refusal.delta"]` - - `"explicit"` + The type of the event. Always `response.refusal.delta`. - - `class BetaResponseInputImage: …` + - `"response.refusal.delta"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `agent: Optional[Agent]` - - `detail: Literal["low", "high", "auto", "original"]` + The agent that owns this multi-agent streaming event. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `agent_name: str` - - `"low"` + The canonical name of the agent that produced this item. - - `"high"` + - `class BetaResponseRefusalDoneEvent: …` - - `"auto"` + Emitted when refusal text is finalized. - - `"original"` + - `content_index: int` - - `type: Literal["input_image"]` + The index of the content part that the refusal text is finalized. - The type of the input item. Always `input_image`. + - `item_id: str` - - `"input_image"` + The ID of the output item that the refusal text is finalized. - - `file_id: Optional[str]` + - `output_index: int` - The ID of the file to be sent to the model. + The index of the output item that the refusal text is finalized. - - `image_url: Optional[str]` + - `refusal: str` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The refusal text that is finalized. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `sequence_number: int` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The sequence number of this event. - - `mode: Literal["explicit"]` + - `type: Literal["response.refusal.done"]` - The breakpoint mode. Always `explicit`. + The type of the event. Always `response.refusal.done`. - - `"explicit"` + - `"response.refusal.done"` - - `class BetaResponseInputFile: …` + - `agent: Optional[Agent]` - A file input to the model. + The agent that owns this multi-agent streaming event. - - `type: Literal["input_file"]` + - `agent_name: str` - The type of the input item. Always `input_file`. + The canonical name of the agent that produced this item. - - `"input_file"` + - `class BetaResponseTextDeltaEvent: …` - - `detail: Optional[Literal["auto", "low", "high"]]` + Emitted when there is an additional text delta. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `content_index: int` - - `"auto"` + The index of the content part that the text delta was added to. - - `"low"` + - `delta: str` - - `"high"` + The text delta that was added. - - `file_data: Optional[str]` + - `item_id: str` - The content of the file to be sent to the model. + The ID of the output item that the text delta was added to. - - `file_id: Optional[str]` + - `logprobs: List[Logprob]` - The ID of the file to be sent to the model. + The log probabilities of the tokens in the delta. - - `file_url: Optional[str]` + - `token: str` - The URL of the file to be sent to the model. + A possible text token. - - `filename: Optional[str]` + - `logprob: float` - The name of the file to be sent to the model. + The log probability of this token. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `top_logprobs: Optional[List[LogprobTopLogprob]]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The log probabilities of up to 20 of the most likely tokens. - - `mode: Literal["explicit"]` + - `token: Optional[str]` - The breakpoint mode. Always `explicit`. + A possible text token. - - `"explicit"` + - `logprob: Optional[float]` - - `status: Literal["in_progress", "completed", "incomplete"]` + The log probability of this token. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `output_index: int` - - `"in_progress"` + The index of the output item that the text delta was added to. - - `"completed"` + - `sequence_number: int` - - `"incomplete"` + The sequence number for this event. - - `type: Literal["function_call_output"]` + - `type: Literal["response.output_text.delta"]` - The type of the function tool call output. Always `function_call_output`. + The type of the event. Always `response.output_text.delta`. - - `"function_call_output"` + - `"response.output_text.delta"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` + - `class BetaResponseTextDoneEvent: …` - - `type: Literal["direct"]` + Emitted when text content is finalized. - The caller type. Always `direct`. + - `content_index: int` - - `"direct"` + The index of the content part that the text content is finalized. - - `class CallerProgram: …` + - `item_id: str` - - `caller_id: str` + The ID of the output item that the text content is finalized. - The call ID of the program item that produced this tool call. + - `logprobs: List[Logprob]` - - `type: Literal["program"]` + The log probabilities of the tokens in the delta. - The caller type. Always `program`. + - `token: str` - - `"program"` + A possible text token. - - `created_by: Optional[str]` + - `logprob: float` - The identifier of the actor that created the item. + The log probability of this token. - - `class AgentMessage: …` + - `top_logprobs: Optional[List[LogprobTopLogprob]]` - - `id: str` + The log probabilities of up to 20 of the most likely tokens. - The unique ID of the agent message. + - `token: Optional[str]` - - `author: str` + A possible text token. - The sending agent identity. + - `logprob: Optional[float]` - - `content: List[AgentMessageContent]` + The log probability of this token. - Encrypted content sent between agents. + - `output_index: int` - - `class BetaResponseInputText: …` + The index of the output item that the text content is finalized. - A text input to the model. + - `sequence_number: int` - - `class BetaResponseOutputText: …` + The sequence number for this event. - A text output from the model. + - `text: str` - - `class AgentMessageContentText: …` + The text content that is finalized. - A text content. + - `type: Literal["response.output_text.done"]` - - `text: str` + The type of the event. Always `response.output_text.done`. - - `type: Literal["text"]` + - `"response.output_text.done"` - - `"text"` + - `agent: Optional[Agent]` - - `class AgentMessageContentSummaryText: …` + The agent that owns this multi-agent streaming event. - A summary text from the model. + - `agent_name: str` - - `text: str` + The canonical name of the agent that produced this item. - A summary of the reasoning output from the model so far. + - `class BetaResponseWebSearchCallCompletedEvent: …` - - `type: Literal["summary_text"]` + Emitted when a web search call is completed. - The type of the object. Always `summary_text`. + - `item_id: str` - - `"summary_text"` + Unique ID for the output item associated with the web search call. - - `class AgentMessageContentReasoningText: …` + - `output_index: int` - Reasoning text from the model. + The index of the output item that the web search call is associated with. - - `text: str` + - `sequence_number: int` - The reasoning text from the model. + The sequence number of the web search call being processed. - - `type: Literal["reasoning_text"]` + - `type: Literal["response.web_search_call.completed"]` - The type of the reasoning text. Always `reasoning_text`. + The type of the event. Always `response.web_search_call.completed`. - - `"reasoning_text"` + - `"response.web_search_call.completed"` - - `class BetaResponseOutputRefusal: …` + - `agent: Optional[Agent]` - A refusal from the model. + The agent that owns this multi-agent streaming event. - - `class BetaResponseInputImage: …` + - `agent_name: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The canonical name of the agent that produced this item. - - `class AgentMessageContentComputerScreenshot: …` + - `class BetaResponseWebSearchCallInProgressEvent: …` - A screenshot of a computer. + Emitted when a web search call is initiated. - - `detail: Literal["low", "high", "auto", "original"]` + - `item_id: str` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Unique ID for the output item associated with the web search call. - - `"low"` + - `output_index: int` - - `"high"` + The index of the output item that the web search call is associated with. - - `"auto"` + - `sequence_number: int` - - `"original"` + The sequence number of the web search call being processed. - - `file_id: Optional[str]` + - `type: Literal["response.web_search_call.in_progress"]` - The identifier of an uploaded file that contains the screenshot. + The type of the event. Always `response.web_search_call.in_progress`. - - `image_url: Optional[str]` + - `"response.web_search_call.in_progress"` - The URL of the screenshot image. + - `agent: Optional[Agent]` - - `type: Literal["computer_screenshot"]` + The agent that owns this multi-agent streaming event. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `agent_name: str` - - `"computer_screenshot"` + The canonical name of the agent that produced this item. - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `class BetaResponseWebSearchCallSearchingEvent: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Emitted when a web search call is executing. - - `mode: Literal["explicit"]` + - `item_id: str` - The breakpoint mode. Always `explicit`. + Unique ID for the output item associated with the web search call. - - `"explicit"` + - `output_index: int` - - `class BetaResponseInputFile: …` + The index of the output item that the web search call is associated with. - A file input to the model. + - `sequence_number: int` - - `class AgentMessageContentEncryptedContent: …` + The sequence number of the web search call being processed. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `type: Literal["response.web_search_call.searching"]` - - `encrypted_content: str` + The type of the event. Always `response.web_search_call.searching`. - Opaque encrypted content. + - `"response.web_search_call.searching"` - - `type: Literal["encrypted_content"]` + - `agent: Optional[Agent]` - The type of the input item. Always `encrypted_content`. + The agent that owns this multi-agent streaming event. - - `"encrypted_content"` + - `agent_name: str` - - `recipient: str` + The canonical name of the agent that produced this item. - The destination agent identity. + - `class BetaResponseImageGenCallCompletedEvent: …` - - `type: Literal["agent_message"]` + Emitted when an image generation tool call has completed and the final image is available. - The type of the item. Always `agent_message`. + - `item_id: str` - - `"agent_message"` + The unique identifier of the image generation item being processed. - - `agent: Optional[AgentMessageAgent]` + - `output_index: int` - The agent that produced this item. + The index of the output item in the response's output array. - - `agent_name: str` + - `sequence_number: int` - The canonical name of the agent that produced this item. + The sequence number of this event. - - `class MultiAgentCall: …` + - `type: Literal["response.image_generation_call.completed"]` - - `id: str` + The type of the event. Always 'response.image_generation_call.completed'. - The unique ID of the multi-agent call item. + - `"response.image_generation_call.completed"` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `agent: Optional[Agent]` - The multi-agent action to execute. + The agent that owns this multi-agent streaming event. - - `"spawn_agent"` + - `agent_name: str` - - `"interrupt_agent"` + The canonical name of the agent that produced this item. - - `"list_agents"` + - `class BetaResponseImageGenCallGeneratingEvent: …` - - `"send_message"` + Emitted when an image generation tool call is actively generating an image (intermediate state). - - `"followup_task"` + - `item_id: str` - - `"wait_agent"` + The unique identifier of the image generation item being processed. - - `arguments: str` + - `output_index: int` - The JSON string of arguments generated for the action. + The index of the output item in the response's output array. - - `call_id: str` + - `sequence_number: int` - The unique ID linking this call to its output. + The sequence number of the image generation item being processed. - - `type: Literal["multi_agent_call"]` + - `type: Literal["response.image_generation_call.generating"]` - The type of the multi-agent call. Always `multi_agent_call`. + The type of the event. Always 'response.image_generation_call.generating'. - - `"multi_agent_call"` + - `"response.image_generation_call.generating"` - - `agent: Optional[MultiAgentCallAgent]` + - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput: …` + - `class BetaResponseImageGenCallInProgressEvent: …` - - `id: str` + Emitted when an image generation tool call is in progress. - The unique ID of the multi-agent call output item. + - `item_id: str` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The unique identifier of the image generation item being processed. - The multi-agent action that produced this result. + - `output_index: int` - - `"spawn_agent"` + The index of the output item in the response's output array. - - `"interrupt_agent"` + - `sequence_number: int` - - `"list_agents"` + The sequence number of the image generation item being processed. - - `"send_message"` + - `type: Literal["response.image_generation_call.in_progress"]` - - `"followup_task"` + The type of the event. Always 'response.image_generation_call.in_progress'. - - `"wait_agent"` + - `"response.image_generation_call.in_progress"` - - `call_id: str` + - `agent: Optional[Agent]` - The unique ID of the multi-agent call. + The agent that owns this multi-agent streaming event. - - `output: List[BetaResponseOutputText]` + - `agent_name: str` - Text output returned by the multi-agent action. + The canonical name of the agent that produced this item. - - `annotations: List[Annotation]` + - `class BetaResponseImageGenCallPartialImageEvent: …` - The annotations of the text output. + Emitted when a partial image is available during image generation streaming. - - `text: str` + - `item_id: str` - The text output from the model. + The unique identifier of the image generation item being processed. - - `type: Literal["output_text"]` + - `output_index: int` - The type of the output text. Always `output_text`. + The index of the output item in the response's output array. - - `logprobs: Optional[List[Logprob]]` + - `partial_image_b64: str` - - `type: Literal["multi_agent_call_output"]` + Base64-encoded partial image data, suitable for rendering as an image. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `partial_image_index: int` - - `"multi_agent_call_output"` + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - - `agent: Optional[MultiAgentCallOutputAgent]` + - `sequence_number: int` - The agent that produced this item. + The sequence number of the image generation item being processed. - - `agent_name: str` + - `type: Literal["response.image_generation_call.partial_image"]` - The canonical name of the agent that produced this item. + The type of the event. Always 'response.image_generation_call.partial_image'. - - `class BetaResponseFunctionWebSearch: …` + - `"response.image_generation_call.partial_image"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `agent: Optional[Agent]` - - `id: str` + The agent that owns this multi-agent streaming event. - The unique ID of the web search tool call. + - `agent_name: str` - - `action: Action` + The canonical name of the agent that produced this item. - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `class BetaResponseMcpCallArgumentsDeltaEvent: …` - - `class ActionSearch: …` + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - Action type "search" - Performs a web search query. + - `delta: str` - - `type: Literal["search"]` + A JSON string containing the partial update to the arguments for the MCP tool call. - The action type. + - `item_id: str` - - `"search"` + The unique identifier of the MCP tool call item being processed. - - `queries: Optional[List[str]]` + - `output_index: int` - The search queries. + The index of the output item in the response's output array. - - `query: Optional[str]` + - `sequence_number: int` - The search query. + The sequence number of this event. - - `sources: Optional[List[ActionSearchSource]]` + - `type: Literal["response.mcp_call_arguments.delta"]` - The sources used in the search. + The type of the event. Always 'response.mcp_call_arguments.delta'. - - `type: Literal["url"]` + - `"response.mcp_call_arguments.delta"` - The type of source. Always `url`. + - `agent: Optional[Agent]` - - `"url"` + The agent that owns this multi-agent streaming event. - - `url: str` + - `agent_name: str` - The URL of the source. + The canonical name of the agent that produced this item. - - `class ActionOpenPage: …` + - `class BetaResponseMcpCallArgumentsDoneEvent: …` - Action type "open_page" - Opens a specific URL from search results. + Emitted when the arguments for an MCP tool call are finalized. - - `type: Literal["open_page"]` + - `arguments: str` - The action type. + A JSON string containing the finalized arguments for the MCP tool call. - - `"open_page"` + - `item_id: str` - - `url: Optional[str]` + The unique identifier of the MCP tool call item being processed. - The URL opened by the model. + - `output_index: int` - - `class ActionFindInPage: …` + The index of the output item in the response's output array. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `sequence_number: int` - - `pattern: str` + The sequence number of this event. - The pattern or text to search for within the page. + - `type: Literal["response.mcp_call_arguments.done"]` - - `type: Literal["find_in_page"]` + The type of the event. Always 'response.mcp_call_arguments.done'. - The action type. + - `"response.mcp_call_arguments.done"` - - `"find_in_page"` + - `agent: Optional[Agent]` - - `url: str` + The agent that owns this multi-agent streaming event. - The URL of the page searched for the pattern. + - `agent_name: str` - - `status: Literal["in_progress", "searching", "completed", "failed"]` + The canonical name of the agent that produced this item. - The status of the web search tool call. + - `class BetaResponseMcpCallCompletedEvent: …` - - `"in_progress"` + Emitted when an MCP tool call has completed successfully. - - `"searching"` + - `item_id: str` - - `"completed"` + The ID of the MCP tool call item that completed. - - `"failed"` + - `output_index: int` - - `type: Literal["web_search_call"]` + The index of the output item that completed. - The type of the web search tool call. Always `web_search_call`. + - `sequence_number: int` - - `"web_search_call"` + The sequence number of this event. + + - `type: Literal["response.mcp_call.completed"]` + + The type of the event. Always 'response.mcp_call.completed'. + + - `"response.mcp_call.completed"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCall: …` + - `class BetaResponseMcpCallFailedEvent: …` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Emitted when an MCP tool call has failed. - - `id: str` + - `item_id: str` - The unique ID of the computer call. + The ID of the MCP tool call item that failed. - - `call_id: str` + - `output_index: int` - An identifier used when responding to the tool call with output. + The index of the output item that failed. - - `pending_safety_checks: List[PendingSafetyCheck]` + - `sequence_number: int` - The pending safety checks for the computer call. + The sequence number of this event. - - `id: str` + - `type: Literal["response.mcp_call.failed"]` - The ID of the pending safety check. + The type of the event. Always 'response.mcp_call.failed'. - - `code: Optional[str]` + - `"response.mcp_call.failed"` - The type of the pending safety check. + - `agent: Optional[Agent]` - - `message: Optional[str]` + The agent that owns this multi-agent streaming event. - Details about the pending safety check. + - `agent_name: str` - - `status: Literal["in_progress", "completed", "incomplete"]` + The canonical name of the agent that produced this item. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class BetaResponseMcpCallInProgressEvent: …` - - `"in_progress"` + Emitted when an MCP tool call is in progress. - - `"completed"` + - `item_id: str` - - `"incomplete"` + The unique identifier of the MCP tool call item being processed. - - `type: Literal["computer_call"]` + - `output_index: int` - The type of the computer call. Always `computer_call`. + The index of the output item in the response's output array. - - `"computer_call"` + - `sequence_number: int` - - `action: Optional[BetaComputerAction]` + The sequence number of this event. - A click action. + - `type: Literal["response.mcp_call.in_progress"]` - - `class Click: …` + The type of the event. Always 'response.mcp_call.in_progress'. - A click action. + - `"response.mcp_call.in_progress"` - - `button: Literal["left", "right", "wheel", 2 more]` + - `agent: Optional[Agent]` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The agent that owns this multi-agent streaming event. - - `"left"` + - `agent_name: str` - - `"right"` + The canonical name of the agent that produced this item. - - `"wheel"` + - `class BetaResponseMcpListToolsCompletedEvent: …` - - `"back"` + Emitted when the list of available MCP tools has been successfully retrieved. - - `"forward"` + - `item_id: str` - - `type: Literal["click"]` + The ID of the MCP tool call item that produced this output. - Specifies the event type. For a click action, this property is always `click`. + - `output_index: int` - - `"click"` + The index of the output item that was processed. - - `x: int` + - `sequence_number: int` - The x-coordinate where the click occurred. + The sequence number of this event. - - `y: int` + - `type: Literal["response.mcp_list_tools.completed"]` - The y-coordinate where the click occurred. + The type of the event. Always 'response.mcp_list_tools.completed'. - - `keys: Optional[List[str]]` + - `"response.mcp_list_tools.completed"` - The keys being held while clicking. + - `agent: Optional[Agent]` - - `class DoubleClick: …` + The agent that owns this multi-agent streaming event. - A double click action. + - `agent_name: str` - - `keys: Optional[List[str]]` + The canonical name of the agent that produced this item. - The keys being held while double-clicking. + - `class BetaResponseMcpListToolsFailedEvent: …` - - `type: Literal["double_click"]` + Emitted when the attempt to list available MCP tools has failed. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `item_id: str` - - `"double_click"` + The ID of the MCP tool call item that failed. - - `x: int` + - `output_index: int` - The x-coordinate where the double click occurred. + The index of the output item that failed. - - `y: int` + - `sequence_number: int` - The y-coordinate where the double click occurred. + The sequence number of this event. - - `class Drag: …` + - `type: Literal["response.mcp_list_tools.failed"]` - A drag action. + The type of the event. Always 'response.mcp_list_tools.failed'. - - `path: List[DragPath]` + - `"response.mcp_list_tools.failed"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `agent: Optional[Agent]` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The agent that owns this multi-agent streaming event. - - `x: int` + - `agent_name: str` - The x-coordinate. + The canonical name of the agent that produced this item. - - `y: int` + - `class BetaResponseMcpListToolsInProgressEvent: …` - The y-coordinate. + Emitted when the system is in the process of retrieving the list of available MCP tools. - - `type: Literal["drag"]` + - `item_id: str` - Specifies the event type. For a drag action, this property is always set to `drag`. + The ID of the MCP tool call item that is being processed. - - `"drag"` + - `output_index: int` - - `keys: Optional[List[str]]` + The index of the output item that is being processed. - The keys being held while dragging the mouse. + - `sequence_number: int` - - `class Keypress: …` + The sequence number of this event. - A collection of keypresses the model would like to perform. + - `type: Literal["response.mcp_list_tools.in_progress"]` - - `keys: List[str]` + The type of the event. Always 'response.mcp_list_tools.in_progress'. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"response.mcp_list_tools.in_progress"` - - `type: Literal["keypress"]` + - `agent: Optional[Agent]` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The agent that owns this multi-agent streaming event. - - `"keypress"` + - `agent_name: str` - - `class Move: …` + The canonical name of the agent that produced this item. - A mouse move action. + - `class BetaResponseOutputTextAnnotationAddedEvent: …` - - `type: Literal["move"]` + Emitted when an annotation is added to output text content. - Specifies the event type. For a move action, this property is always set to `move`. + - `annotation: object` - - `"move"` + The annotation object being added. (See annotation schema for details.) - - `x: int` + - `annotation_index: int` - The x-coordinate to move to. + The index of the annotation within the content part. - - `y: int` + - `content_index: int` - The y-coordinate to move to. + The index of the content part within the output item. - - `keys: Optional[List[str]]` + - `item_id: str` - The keys being held while moving the mouse. + The unique identifier of the item to which the annotation is being added. - - `class Screenshot: …` + - `output_index: int` - A screenshot action. + The index of the output item in the response's output array. - - `type: Literal["screenshot"]` + - `sequence_number: int` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The sequence number of this event. - - `"screenshot"` + - `type: Literal["response.output_text.annotation.added"]` - - `class Scroll: …` + The type of the event. Always 'response.output_text.annotation.added'. - A scroll action. + - `"response.output_text.annotation.added"` - - `scroll_x: int` + - `agent: Optional[Agent]` - The horizontal scroll distance. + The agent that owns this multi-agent streaming event. - - `scroll_y: int` + - `agent_name: str` - The vertical scroll distance. + The canonical name of the agent that produced this item. - - `type: Literal["scroll"]` + - `class BetaResponseQueuedEvent: …` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + Emitted when a response is queued and waiting to be processed. - - `"scroll"` + - `response: BetaResponse` - - `x: int` + The full response object that is queued. - The x-coordinate where the scroll occurred. + - `sequence_number: int` - - `y: int` + The sequence number for this event. - The y-coordinate where the scroll occurred. + - `type: Literal["response.queued"]` - - `keys: Optional[List[str]]` + The type of the event. Always 'response.queued'. - The keys being held while scrolling. + - `"response.queued"` - - `class Type: …` + - `agent: Optional[Agent]` - An action to type in text. + The agent that owns this multi-agent streaming event. - - `text: str` + - `agent_name: str` - The text to type. + The canonical name of the agent that produced this item. - - `type: Literal["type"]` + - `class BetaResponseCustomToolCallInputDeltaEvent: …` - Specifies the event type. For a type action, this property is always set to `type`. + Event representing a delta (partial update) to the input of a custom tool call. - - `"type"` + - `delta: str` - - `class Wait: …` + The incremental input data (delta) for the custom tool call. - A wait action. + - `item_id: str` - - `type: Literal["wait"]` + Unique identifier for the API item associated with this event. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `output_index: int` - - `"wait"` + The index of the output this delta applies to. - - `actions: Optional[BetaComputerActionList]` + - `sequence_number: int` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The sequence number of this event. - - `class Click: …` + - `type: Literal["response.custom_tool_call_input.delta"]` - A click action. + The event type identifier. - - `class DoubleClick: …` + - `"response.custom_tool_call_input.delta"` - A double click action. + - `agent: Optional[Agent]` - - `class Drag: …` + The agent that owns this multi-agent streaming event. - A drag action. + - `agent_name: str` - - `class Keypress: …` + The canonical name of the agent that produced this item. - A collection of keypresses the model would like to perform. + - `class BetaResponseCustomToolCallInputDoneEvent: …` - - `class Move: …` + Event indicating that input for a custom tool call is complete. - A mouse move action. + - `input: str` - - `class Screenshot: …` + The complete input data for the custom tool call. - A screenshot action. + - `item_id: str` - - `class Scroll: …` + Unique identifier for the API item associated with this event. - A scroll action. + - `output_index: int` - - `class Type: …` + The index of the output this event applies to. - An action to type in text. + - `sequence_number: int` - - `class Wait: …` + The sequence number of this event. - A wait action. + - `type: Literal["response.custom_tool_call_input.done"]` + + The event type identifier. + + - `"response.custom_tool_call_input.done"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem: …` - - - `id: str` +### Beta Response Text Config - The unique ID of the computer call tool output. +- `class BetaResponseTextConfig: …` - - `call_id: str` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The ID of the computer tool call that produced the output. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `format: Optional[BetaResponseFormatTextConfig]` - A computer screenshot image used with the computer use tool. + An object specifying the format that the model must output. - - `type: Literal["computer_screenshot"]` + Configuring `{ "type": "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). - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The default format is `{ "type": "text" }` with no additional options. - - `"computer_screenshot"` + **Not recommended for gpt-4o and newer models:** - - `file_id: Optional[str]` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - The identifier of an uploaded file that contains the screenshot. + - `class Text: …` - - `image_url: Optional[str]` + Default response format. Used to generate text responses. - The URL of the screenshot image. + - `type: Literal["text"]` - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + The type of response format being defined. Always `text`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"text"` - - `"completed"` + - `class BetaResponseFormatTextJSONSchemaConfig: …` - - `"incomplete"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `"failed"` + - `name: str` - - `"in_progress"` + 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. - - `type: Literal["computer_call_output"]` + - `schema: Dict[str, object]` - The type of the computer tool call output. Always `computer_call_output`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"computer_call_output"` + - `type: Literal["json_schema"]` - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + The type of response format being defined. Always `json_schema`. - The safety checks reported by the API that have been acknowledged by the - developer. + - `"json_schema"` - - `id: str` + - `description: Optional[str]` - The ID of the pending safety check. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `code: Optional[str]` + - `strict: Optional[bool]` - The type of the pending safety check. + 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). - - `message: Optional[str]` + - `class JSONObject: …` - Details about the pending safety check. + 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. - - `agent: Optional[Agent]` + - `type: Literal["json_object"]` - The agent that produced this item. + The type of response format being defined. Always `json_object`. - - `agent_name: str` + - `"json_object"` - The canonical name of the agent that produced this item. + - `verbosity: Optional[Literal["low", "medium", "high"]]` - - `created_by: Optional[str]` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - The identifier of the actor that created the item. + - `"low"` - - `class BetaResponseReasoningItem: …` + - `"medium"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `"high"` - - `id: str` +### Beta Response Text Delta Event - The unique identifier of the reasoning content. +- `class BetaResponseTextDeltaEvent: …` - - `summary: List[Summary]` + Emitted when there is an additional text delta. - Reasoning summary content. + - `content_index: int` - - `text: str` + The index of the content part that the text delta was added to. - A summary of the reasoning output from the model so far. + - `delta: str` - - `type: Literal["summary_text"]` + The text delta that was added. - The type of the object. Always `summary_text`. + - `item_id: str` - - `"summary_text"` + The ID of the output item that the text delta was added to. - - `type: Literal["reasoning"]` + - `logprobs: List[Logprob]` - The type of the object. Always `reasoning`. + The log probabilities of the tokens in the delta. - - `"reasoning"` + - `token: str` - - `agent: Optional[Agent]` + A possible text token. - The agent that produced this item. + - `logprob: float` - - `agent_name: str` + The log probability of this token. - The canonical name of the agent that produced this item. + - `top_logprobs: Optional[List[LogprobTopLogprob]]` - - `content: Optional[List[Content]]` + The log probabilities of up to 20 of the most likely tokens. - Reasoning text content. + - `token: Optional[str]` - - `text: str` + A possible text token. - The reasoning text from the model. + - `logprob: Optional[float]` - - `type: Literal["reasoning_text"]` + The log probability of this token. - The type of the reasoning text. Always `reasoning_text`. + - `output_index: int` - - `"reasoning_text"` + The index of the output item that the text delta was added to. - - `encrypted_content: Optional[str]` + - `sequence_number: int` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The sequence number for this event. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `type: Literal["response.output_text.delta"]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the event. Always `response.output_text.delta`. - - `"in_progress"` + - `"response.output_text.delta"` - - `"completed"` + - `agent: Optional[Agent]` - - `"incomplete"` + The agent that owns this multi-agent streaming event. - - `class Program: …` + - `agent_name: str` - - `id: str` + The canonical name of the agent that produced this item. - The unique ID of the program item. +### Beta Response Text Done Event - - `call_id: str` +- `class BetaResponseTextDoneEvent: …` - The stable call ID of the program item. + Emitted when text content is finalized. - - `code: str` + - `content_index: int` - The JavaScript source executed by programmatic tool calling. + The index of the content part that the text content is finalized. - - `fingerprint: str` + - `item_id: str` - Opaque program replay fingerprint that must be round-tripped. + The ID of the output item that the text content is finalized. - - `type: Literal["program"]` + - `logprobs: List[Logprob]` - The type of the item. Always `program`. + The log probabilities of the tokens in the delta. - - `"program"` + - `token: str` - - `agent: Optional[ProgramAgent]` + A possible text token. - The agent that produced this item. + - `logprob: float` - - `agent_name: str` + The log probability of this token. - The canonical name of the agent that produced this item. + - `top_logprobs: Optional[List[LogprobTopLogprob]]` - - `class ProgramOutput: …` + The log probabilities of up to 20 of the most likely tokens. - - `id: str` + - `token: Optional[str]` - The unique ID of the program output item. + A possible text token. - - `call_id: str` + - `logprob: Optional[float]` - The call ID of the program item. + The log probability of this token. - - `result: str` + - `output_index: int` - The result produced by the program item. + The index of the output item that the text content is finalized. - - `status: Literal["completed", "incomplete"]` + - `sequence_number: int` - The terminal status of the program output item. + The sequence number for this event. - - `"completed"` + - `text: str` - - `"incomplete"` + The text content that is finalized. - - `type: Literal["program_output"]` + - `type: Literal["response.output_text.done"]` - The type of the item. Always `program_output`. + The type of the event. Always `response.output_text.done`. - - `"program_output"` + - `"response.output_text.done"` - - `agent: Optional[ProgramOutputAgent]` + - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall: …` +### Beta Response Tool Search Call + +- `class BetaResponseToolSearchCall: …` - `id: str` @@ -117175,7 +127702,9 @@ print(compacted_response) The identifier of the actor that created the item. - - `class BetaResponseToolSearchOutputItem: …` +### Beta Response Tool Search Output Item + +- `class BetaResponseToolSearchOutputItem: …` - `id: str` @@ -117304,7 +127833,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -117314,7 +127843,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `class FiltersCompoundFilter: …` @@ -117361,7 +127894,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -117371,7 +127904,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `object` @@ -118311,1645 +128848,1387 @@ print(compacted_response) The identifier of the actor that created the item. - - `class AdditionalTools: …` - - - `id: str` - - The unique ID of the additional tools item. - - - `role: Literal["unknown", "user", "assistant", 5 more]` - - The role that provided the additional tools. - - - `"unknown"` - - - `"user"` - - - `"assistant"` - - - `"system"` - - - `"critic"` - - - `"discriminator"` - - - `"developer"` +### Beta Response Tool Search Output Item Param - - `"tool"` +- `class BetaResponseToolSearchOutputItemParam: …` - `tools: List[BetaTool]` - The additional tool definitions made available at this item. + The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool: …` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `class BetaFileSearchTool: …` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - - `class BetaComputerTool: …` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaComputerUsePreviewTool: …` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaWebSearchTool: …` - - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `class Mcp: …` - - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - - `class CodeInterpreter: …` - - A tool that runs Python code to help generate a response to a prompt. - - - `class ProgrammaticToolCalling: …` - - - `class ImageGeneration: …` - - A tool that generates images using the GPT image models. - - - `class LocalShell: …` - - A tool that allows the model to execute shell commands in a local environment. - - - `class BetaFunctionShellTool: …` - - A tool that allows the model to execute shell commands. - - - `class BetaCustomTool: …` - - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - - `class BetaNamespaceTool: …` - - Groups function/custom tools under a shared namespace. - - - `class BetaToolSearchTool: …` - - Hosted or BYOT tool search configuration for deferred tools. - - - `class BetaWebSearchPreviewTool: …` - - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `class BetaApplyPatchTool: …` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `type: Literal["additional_tools"]` - - The type of the item. Always `additional_tools`. - - - `"additional_tools"` - - - `agent: Optional[AdditionalToolsAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `class BetaResponseCompactionItem: …` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - - `id: str` - - The unique ID of the compaction item. - - - `encrypted_content: str` - - The encrypted content that was produced by compaction. - - - `type: Literal["compaction"]` - - The type of the item. Always `compaction`. - - - `"compaction"` - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `class ImageGenerationCall: …` - - An image generation request made by the model. - - - `id: str` - - The unique ID of the image generation call. - - - `result: Optional[str]` - - The generated image encoded in base64. - - - `status: Literal["in_progress", "completed", "generating", "failed"]` - - The status of the image generation call. - - - `"in_progress"` - - - `"completed"` - - - `"generating"` - - - `"failed"` - - - `type: Literal["image_generation_call"]` - - The type of the image generation call. Always `image_generation_call`. - - - `"image_generation_call"` - - - `agent: Optional[ImageGenerationCallAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `class BetaResponseCodeInterpreterToolCall: …` - - A tool call to run code. - - - `id: str` - - The unique ID of the code interpreter tool call. - - - `code: Optional[str]` - - The code to run, or null if not available. - - - `container_id: str` - - The ID of the container used to run the code. - - - `outputs: Optional[List[Output]]` - - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. - - - `class OutputLogs: …` - - The logs output from the code interpreter. - - - `logs: str` - - The logs output from the code interpreter. - - - `type: Literal["logs"]` - - The type of the output. Always `logs`. - - - `"logs"` - - - `class OutputImage: …` - - The image output from the code interpreter. - - - `type: Literal["image"]` - - The type of the output. Always `image`. - - - `"image"` - - - `url: str` - - The URL of the image output from the code interpreter. - - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - - `"in_progress"` - - - `"completed"` + - `name: str` - - `"incomplete"` + The name of the function to call. - - `"interpreting"` + - `parameters: Optional[Dict[str, object]]` - - `"failed"` + A JSON schema object describing the parameters of the function. - - `type: Literal["code_interpreter_call"]` + - `strict: Optional[bool]` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Whether strict parameter validation is enforced for this function tool. - - `"code_interpreter_call"` + - `type: Literal["function"]` - - `agent: Optional[Agent]` + The type of the function tool. Always `function`. - The agent that produced this item. + - `"function"` - - `agent_name: str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The canonical name of the agent that produced this item. + The tool invocation context(s). - - `class LocalShellCall: …` + - `"direct"` - A tool call to run a command on the local shell. + - `"programmatic"` - - `id: str` + - `defer_loading: Optional[bool]` - The unique ID of the local shell call. + Whether this function is deferred and loaded via tool search. - - `action: LocalShellCallAction` + - `description: Optional[str]` - Execute a shell command on the server. + A description of the function. Used by the model to determine whether or not to call the function. - - `command: List[str]` + - `output_schema: Optional[Dict[str, object]]` - The command to run. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `env: Dict[str, str]` + - `class BetaFileSearchTool: …` - Environment variables to set for the command. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: Literal["exec"]` + - `type: Literal["file_search"]` - The type of the local shell action. Always `exec`. + The type of the file search tool. Always `file_search`. - - `"exec"` + - `"file_search"` - - `timeout_ms: Optional[int]` + - `vector_store_ids: List[str]` - Optional timeout in milliseconds for the command. + The IDs of the vector stores to search. - - `user: Optional[str]` + - `filters: Optional[Filters]` - Optional user to run the command as. + A filter to apply. - - `working_directory: Optional[str]` + - `class FiltersComparisonFilter: …` - Optional working directory to run the command in. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `call_id: str` + - `key: str` - The unique ID of the local shell tool call generated by the model. + The key to compare against the value. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `type: Literal["eq", "ne", "gt", 5 more]` - The status of the local shell call. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"in_progress"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `"completed"` + - `"eq"` - - `"incomplete"` + - `"ne"` - - `type: Literal["local_shell_call"]` + - `"gt"` - The type of the local shell call. Always `local_shell_call`. + - `"gte"` - - `"local_shell_call"` + - `"lt"` - - `agent: Optional[LocalShellCallAgent]` + - `"lte"` - The agent that produced this item. + - `"in"` - - `agent_name: str` + - `"nin"` - The canonical name of the agent that produced this item. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `class LocalShellCallOutput: …` + The value to compare against the attribute key; supports string, number, or boolean types. - The output of a local shell tool call. + - `str` - - `id: str` + - `float` - The unique ID of the local shell tool call generated by the model. + - `bool` - - `output: str` + - `List[Union[str, float]]` - A JSON string of the output of the local shell tool call. + - `str` - - `type: Literal["local_shell_call_output"]` + - `float` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `class FiltersCompoundFilter: …` - - `"local_shell_call_output"` + Combine multiple filters using `and` or `or`. - - `agent: Optional[LocalShellCallOutputAgent]` + - `filters: List[FiltersCompoundFilterFilter]` - The agent that produced this item. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `agent_name: str` + - `class FiltersCompoundFilterFilterComparisonFilter: …` - The canonical name of the agent that produced this item. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `key: str` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The key to compare against the value. - - `"in_progress"` + - `type: Literal["eq", "ne", "gt", 5 more]` - - `"completed"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"incomplete"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `class BetaResponseFunctionShellToolCall: …` + - `"eq"` - A tool call that executes one or more shell commands in a managed environment. + - `"ne"` - - `id: str` + - `"gt"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"gte"` - - `action: Action` + - `"lt"` - The shell commands and limits that describe how to run the tool call. + - `"lte"` - - `commands: List[str]` + - `"in"` - - `max_output_length: Optional[int]` + - `"nin"` - Optional maximum number of characters to return from each command. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `timeout_ms: Optional[int]` + The value to compare against the attribute key; supports string, number, or boolean types. - Optional timeout in milliseconds for the commands. + - `str` - - `call_id: str` + - `float` - The unique ID of the shell tool call generated by the model. + - `bool` - - `environment: Optional[Environment]` + - `List[Union[str, float]]` - Represents the use of a local environment to perform shell actions. + - `str` - - `class BetaResponseLocalEnvironment: …` + - `float` - Represents the use of a local environment to perform shell actions. + - `object` - - `type: Literal["local"]` + - `type: Literal["and", "or"]` - The environment type. Always `local`. + Type of operation: `and` or `or`. - - `"local"` + - `"and"` - - `class BetaResponseContainerReference: …` + - `"or"` - Represents a container created with /v1/containers. + - `max_num_results: Optional[int]` - - `container_id: str` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `type: Literal["container_reference"]` + - `ranking_options: Optional[RankingOptions]` - The environment type. Always `container_reference`. + Ranking options for search. - - `"container_reference"` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - `status: Literal["in_progress", "completed", "incomplete"]` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `embedding_weight: float` - - `"in_progress"` + The weight of the embedding in the reciprocal ranking fusion. - - `"completed"` + - `text_weight: float` - - `"incomplete"` + The weight of the text in the reciprocal ranking fusion. - - `type: Literal["shell_call"]` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - The type of the item. Always `shell_call`. + The ranker to use for the file search. - - `"shell_call"` + - `"auto"` - - `agent: Optional[Agent]` + - `"default-2024-11-15"` - The agent that produced this item. + - `score_threshold: Optional[float]` - - `agent_name: str` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The canonical name of the agent that produced this item. + - `class BetaComputerTool: …` - - `caller: Optional[Caller]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The execution context that produced this tool call. + - `type: Literal["computer"]` - - `class CallerDirect: …` + The type of the computer tool. Always `computer`. - - `type: Literal["direct"]` + - `"computer"` - - `"direct"` + - `class BetaComputerUsePreviewTool: …` - - `class CallerProgram: …` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `caller_id: str` + - `display_height: int` - The call ID of the program item that produced this tool call. + The height of the computer display. - - `type: Literal["program"]` + - `display_width: int` - - `"program"` + The width of the computer display. - - `created_by: Optional[str]` + - `environment: Literal["windows", "mac", "linux", 2 more]` - The ID of the entity that created this tool call. + The type of computer environment to control. - - `class BetaResponseFunctionShellToolCallOutput: …` + - `"windows"` - The output of a shell tool call that was emitted. + - `"mac"` - - `id: str` + - `"linux"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `"ubuntu"` - - `call_id: str` + - `"browser"` - The unique ID of the shell tool call generated by the model. + - `type: Literal["computer_use_preview"]` - - `max_output_length: Optional[int]` + The type of the computer use tool. Always `computer_use_preview`. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `"computer_use_preview"` - - `output: List[Output]` + - `class BetaWebSearchTool: …` - An array of shell call output contents + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `outcome: OutputOutcome` + - `type: Literal["web_search", "web_search_2025_08_26"]` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `class OutputOutcomeTimeout: …` + - `"web_search"` - Indicates that the shell call exceeded its configured time limit. + - `"web_search_2025_08_26"` - - `type: Literal["timeout"]` + - `filters: Optional[Filters]` - The outcome type. Always `timeout`. + Filters for the search. - - `"timeout"` + - `allowed_domains: Optional[List[str]]` - - `class OutputOutcomeExit: …` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Indicates that the shell commands finished and returned an exit code. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `exit_code: int` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - Exit code from the shell process. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `type: Literal["exit"]` + - `"low"` - The outcome type. Always `exit`. + - `"medium"` - - `"exit"` + - `"high"` - - `stderr: str` + - `user_location: Optional[UserLocation]` - The standard error output that was captured. + The approximate location of the user. - - `stdout: str` + - `city: Optional[str]` - The standard output that was captured. + Free text input for the city of the user, e.g. `San Francisco`. - - `created_by: Optional[str]` + - `country: Optional[str]` - The identifier of the actor that created the item. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `region: Optional[str]` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + Free text input for the region of the user, e.g. `California`. - - `"in_progress"` + - `timezone: Optional[str]` - - `"completed"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"incomplete"` + - `type: Optional[Literal["approximate"]]` - - `type: Literal["shell_call_output"]` + The type of location approximation. Always `approximate`. - The type of the shell call output. Always `shell_call_output`. + - `"approximate"` - - `"shell_call_output"` + - `class Mcp: …` - - `agent: Optional[Agent]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The agent that produced this item. + - `server_label: str` - - `agent_name: str` + A label for this MCP server, used to identify it in tool calls. - The canonical name of the agent that produced this item. + - `type: Literal["mcp"]` - - `caller: Optional[Caller]` + The type of the MCP tool. Always `mcp`. - The execution context that produced this tool call. + - `"mcp"` - - `class CallerDirect: …` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `type: Literal["direct"]` + The tool invocation context(s). - `"direct"` - - `class CallerProgram: …` - - - `caller_id: str` - - The call ID of the program item that produced this tool call. - - - `type: Literal["program"]` - - - `"program"` - - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `class BetaResponseApplyPatchToolCall: …` - - A tool call that applies file diffs by creating, deleting, or updating files. - - - `id: str` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `call_id: str` - - The unique ID of the apply patch tool call generated by the model. - - - `operation: Operation` - - One of the create_file, delete_file, or update_file operations applied via apply_patch. - - - `class OperationCreateFile: …` - - Instruction describing how to create a file via the apply_patch tool. - - - `diff: str` - - Diff to apply. - - - `path: str` - - Path of the file to create. - - - `type: Literal["create_file"]` - - Create a new file with the provided diff. - - - `"create_file"` - - - `class OperationDeleteFile: …` - - Instruction describing how to delete a file via the apply_patch tool. - - - `path: str` - - Path of the file to delete. - - - `type: Literal["delete_file"]` - - Delete the specified file. - - - `"delete_file"` - - - `class OperationUpdateFile: …` - - Instruction describing how to update a file via the apply_patch tool. - - - `diff: str` - - Diff to apply. - - - `path: str` - - Path of the file to update. - - - `type: Literal["update_file"]` - - Update an existing file with the provided diff. - - - `"update_file"` - - - `status: Literal["in_progress", "completed"]` - - The status of the apply patch tool call. One of `in_progress` or `completed`. - - - `"in_progress"` - - - `"completed"` - - - `type: Literal["apply_patch_call"]` - - The type of the item. Always `apply_patch_call`. - - - `"apply_patch_call"` - - - `agent: Optional[Agent]` - - The agent that produced this item. + - `"programmatic"` - - `agent_name: str` + - `allowed_tools: Optional[McpAllowedTools]` - The canonical name of the agent that produced this item. + List of allowed tool names or a filter object. - - `caller: Optional[Caller]` + - `List[str]` - The execution context that produced this tool call. + A string array of allowed tool names - - `class CallerDirect: …` + - `class McpAllowedToolsMcpToolFilter: …` - - `type: Literal["direct"]` + A filter object to specify which tools are allowed. - - `"direct"` + - `read_only: Optional[bool]` - - `class CallerProgram: …` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `caller_id: str` + - `tool_names: Optional[List[str]]` - The call ID of the program item that produced this tool call. + List of allowed tool names. - - `type: Literal["program"]` + - `authorization: Optional[str]` - - `"program"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `created_by: Optional[str]` + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - The ID of the entity that created this tool call. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `class BetaResponseApplyPatchToolCallOutput: …` + Currently supported `connector_id` values are: - The output emitted by an apply patch tool call. + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `id: str` + - `"connector_dropbox"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"connector_gmail"` - - `call_id: str` + - `"connector_googlecalendar"` - The unique ID of the apply patch tool call generated by the model. + - `"connector_googledrive"` - - `status: Literal["completed", "failed"]` + - `"connector_microsoftteams"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"connector_outlookcalendar"` - - `"completed"` + - `"connector_outlookemail"` - - `"failed"` + - `"connector_sharepoint"` - - `type: Literal["apply_patch_call_output"]` + - `defer_loading: Optional[bool]` - The type of the item. Always `apply_patch_call_output`. + Whether this MCP tool is deferred and discovered via tool search. - - `"apply_patch_call_output"` + - `headers: Optional[Dict[str, str]]` - - `agent: Optional[Agent]` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The agent that produced this item. + - `require_approval: Optional[McpRequireApproval]` - - `agent_name: str` + Specify which of the MCP server's tools require approval. - The canonical name of the agent that produced this item. + - `class McpRequireApprovalMcpToolApprovalFilter: …` - - `caller: Optional[Caller]` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The execution context that produced this tool call. + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `class CallerDirect: …` + A filter object to specify which tools are allowed. - - `type: Literal["direct"]` + - `read_only: Optional[bool]` - - `"direct"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `class CallerProgram: …` + - `tool_names: Optional[List[str]]` - - `caller_id: str` + List of allowed tool names. - The call ID of the program item that produced this tool call. + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - - `type: Literal["program"]` + A filter object to specify which tools are allowed. - - `"program"` + - `read_only: Optional[bool]` - - `created_by: Optional[str]` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The ID of the entity that created this tool call output. + - `tool_names: Optional[List[str]]` - - `output: Optional[str]` + List of allowed tool names. - Optional textual output returned by the apply patch tool. + - `Literal["always", "never"]` - - `class McpCall: …` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - An invocation of a tool on an MCP server. + - `"always"` - - `id: str` + - `"never"` - The unique ID of the tool call. + - `server_description: Optional[str]` - - `arguments: str` + Optional description of the MCP server, used to provide more context. - A JSON string of the arguments passed to the tool. + - `server_url: Optional[str]` - - `name: str` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The name of the tool that was run. + - `tunnel_id: Optional[str]` - - `server_label: str` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The label of the MCP server running the tool. + - `class CodeInterpreter: …` - - `type: Literal["mcp_call"]` + A tool that runs Python code to help generate a response to a prompt. - The type of the item. Always `mcp_call`. + - `container: CodeInterpreterContainer` - - `"mcp_call"` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `agent: Optional[McpCallAgent]` + - `str` - The agent that produced this item. + The container ID. - - `agent_name: str` + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - The canonical name of the agent that produced this item. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `approval_request_id: Optional[str]` + - `type: Literal["auto"]` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + Always `auto`. - - `error: Optional[str]` + - `"auto"` - The error from the tool call, if any. + - `file_ids: Optional[List[str]]` - - `output: Optional[str]` + An optional list of uploaded files to make available to your code. - The output from the tool call. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + The memory limit for the code interpreter container. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"1g"` - - `"in_progress"` + - `"4g"` - - `"completed"` + - `"16g"` - - `"incomplete"` + - `"64g"` - - `"calling"` + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - - `"failed"` + Network access policy for the container. - - `class McpListTools: …` + - `class BetaContainerNetworkPolicyDisabled: …` - A list of tools available on an MCP server. + - `type: Literal["disabled"]` - - `id: str` + Disable outbound network access. Always `disabled`. - The unique ID of the list. + - `"disabled"` - - `server_label: str` + - `class BetaContainerNetworkPolicyAllowlist: …` - The label of the MCP server. + - `allowed_domains: List[str]` - - `tools: List[McpListToolsTool]` + A list of allowed domains when type is `allowlist`. - The tools available on the server. + - `type: Literal["allowlist"]` - - `input_schema: object` + Allow outbound network access only to specified domains. Always `allowlist`. - The JSON schema describing the tool's input. + - `"allowlist"` - - `name: str` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - The name of the tool. + Optional domain-scoped secrets for allowlisted domains. - - `annotations: Optional[object]` + - `domain: str` - Additional annotations about the tool. + The domain associated with the secret. - - `description: Optional[str]` + - `name: str` - The description of the tool. + The name of the secret to inject for the domain. - - `type: Literal["mcp_list_tools"]` + - `value: str` - The type of the item. Always `mcp_list_tools`. + The secret value to inject for the domain. - - `"mcp_list_tools"` + - `type: Literal["code_interpreter"]` - - `agent: Optional[McpListToolsAgent]` + The type of the code interpreter tool. Always `code_interpreter`. - The agent that produced this item. + - `"code_interpreter"` - - `agent_name: str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The canonical name of the agent that produced this item. + The tool invocation context(s). - - `error: Optional[str]` + - `"direct"` - Error message if the server could not list tools. + - `"programmatic"` - - `class McpApprovalRequest: …` + - `class ProgrammaticToolCalling: …` - A request for human approval of a tool invocation. + - `type: Literal["programmatic_tool_calling"]` - - `id: str` + The type of the tool. Always `programmatic_tool_calling`. - The unique ID of the approval request. + - `"programmatic_tool_calling"` - - `arguments: str` + - `class ImageGeneration: …` - A JSON string of arguments for the tool. + A tool that generates images using the GPT image models. - - `name: str` + - `type: Literal["image_generation"]` - The name of the tool to run. + The type of the image generation tool. Always `image_generation`. - - `server_label: str` + - `"image_generation"` - The label of the MCP server making the request. + - `action: Optional[Literal["generate", "edit", "auto"]]` - - `type: Literal["mcp_approval_request"]` + Whether to generate a new image or edit an existing image. Default: `auto`. - The type of the item. Always `mcp_approval_request`. + - `"generate"` - - `"mcp_approval_request"` + - `"edit"` - - `agent: Optional[McpApprovalRequestAgent]` + - `"auto"` - The agent that produced this item. + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `agent_name: str` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - The canonical name of the agent that produced this item. + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `class McpApprovalResponse: …` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - A response to an MCP approval request. + - `"transparent"` - - `id: str` + - `"opaque"` - The unique ID of the approval response + - `"auto"` - - `approval_request_id: str` + - `input_fidelity: Optional[Literal["high", "low"]]` - The ID of the approval request being answered. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `approve: bool` + - `"high"` - Whether the request was approved. + - `"low"` - - `type: Literal["mcp_approval_response"]` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - The type of the item. Always `mcp_approval_response`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"mcp_approval_response"` + - `file_id: Optional[str]` - - `agent: Optional[McpApprovalResponseAgent]` + File ID for the mask image. - The agent that produced this item. + - `image_url: Optional[str]` - - `agent_name: str` + Base64-encoded mask image. - The canonical name of the agent that produced this item. + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - - `reason: Optional[str]` + The image generation model to use. Default: `gpt-image-1`. - Optional reason for the decision. + - `str` - - `class BetaResponseCustomToolCall: …` + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - A call to a custom tool created by the model. + The image generation model to use. Default: `gpt-image-1`. - - `call_id: str` + - `"gpt-image-1"` - An identifier used to map this custom tool call to a tool call output. + - `"gpt-image-1-mini"` - - `input: str` + - `"gpt-image-2"` - The input for the custom tool call generated by the model. + - `"gpt-image-2-2026-04-21"` - - `name: str` + - `"gpt-image-1.5"` - The name of the custom tool being called. + - `"chatgpt-image-latest"` - - `type: Literal["custom_tool_call"]` + - `moderation: Optional[Literal["auto", "low"]]` - The type of the custom tool call. Always `custom_tool_call`. + Moderation level for the generated image. Default: `auto`. - - `"custom_tool_call"` + - `"auto"` - - `id: Optional[str]` + - `"low"` - The unique ID of the custom tool call in the OpenAI platform. + - `output_compression: Optional[int]` - - `agent: Optional[Agent]` + Compression level for the output image. Default: 100. - The agent that produced this item. + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `agent_name: str` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The canonical name of the agent that produced this item. + - `"png"` - - `caller: Optional[Caller]` + - `"webp"` - The execution context that produced this tool call. + - `"jpeg"` - - `class CallerDirect: …` + - `partial_images: Optional[int]` - - `type: Literal["direct"]` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"direct"` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - - `class CallerProgram: …` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `caller_id: str` + - `"low"` - The call ID of the program item that produced this tool call. + - `"medium"` - - `type: Literal["program"]` + - `"high"` - - `"program"` + - `"auto"` - - `namespace: Optional[str]` + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - The namespace of the custom tool being called. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `class BetaResponseCustomToolCallOutputItem: …` + - `str` - The output of a custom tool call from your code, being sent back to the model. + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `id: str` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The unique ID of the custom tool call output item. + - `"1024x1024"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"1024x1536"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"1536x1024"` - - `"in_progress"` + - `"auto"` - - `"completed"` + - `class LocalShell: …` - - `"incomplete"` + A tool that allows the model to execute shell commands in a local environment. - - `created_by: Optional[str]` + - `type: Literal["local_shell"]` - The identifier of the actor that created the item. + The type of the local shell tool. Always `local_shell`. - - `output_index: int` + - `"local_shell"` - The index of the output item that was marked done. + - `class BetaFunctionShellTool: …` - - `sequence_number: int` + A tool that allows the model to execute shell commands. - The sequence number of this event. + - `type: Literal["shell"]` - - `type: Literal["response.output_item.done"]` + The type of the shell tool. Always `shell`. - The type of the event. Always `response.output_item.done`. + - `"shell"` - - `"response.output_item.done"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `agent: Optional[Agent]` + The tool invocation context(s). - The agent that owns this multi-agent streaming event. + - `"direct"` - - `agent_name: str` + - `"programmatic"` - The canonical name of the agent that produced this item. + - `environment: Optional[Environment]` -### Beta Response Output Message + - `class BetaContainerAuto: …` -- `class BetaResponseOutputMessage: …` + - `type: Literal["container_auto"]` - An output message from the model. + Automatically creates a container for this request - - `id: str` + - `"container_auto"` - The unique ID of the output message. + - `file_ids: Optional[List[str]]` - - `content: List[Content]` + An optional list of uploaded files to make available to your code. - The content of the output message. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `class BetaResponseOutputText: …` + The memory limit for the container. - A text output from the model. + - `"1g"` - - `annotations: List[Annotation]` + - `"4g"` - The annotations of the text output. + - `"16g"` - - `class AnnotationFileCitation: …` + - `"64g"` - A citation to a file. + - `network_policy: Optional[NetworkPolicy]` - - `file_id: str` + Network access policy for the container. - The ID of the file. + - `class BetaContainerNetworkPolicyDisabled: …` - - `filename: str` + - `class BetaContainerNetworkPolicyAllowlist: …` - The filename of the file cited. + - `skills: Optional[List[Skill]]` - - `index: int` + An optional list of skills referenced by id or inline data. - The index of the file in the list of files. + - `class BetaSkillReference: …` - - `type: Literal["file_citation"]` + - `skill_id: str` - The type of the file citation. Always `file_citation`. + The ID of the referenced skill. - - `"file_citation"` + - `type: Literal["skill_reference"]` - - `class AnnotationURLCitation: …` + References a skill created with the /v1/skills endpoint. - A citation for a web resource used to generate a model response. + - `"skill_reference"` - - `end_index: int` + - `version: Optional[str]` - The index of the last character of the URL citation in the message. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `start_index: int` + - `class BetaInlineSkill: …` - The index of the first character of the URL citation in the message. + - `description: str` - - `title: str` + The description of the skill. - The title of the web resource. + - `name: str` - - `type: Literal["url_citation"]` + The name of the skill. - The type of the URL citation. Always `url_citation`. + - `source: BetaInlineSkillSource` - - `"url_citation"` + Inline skill payload - - `url: str` + - `data: str` - The URL of the web resource. + Base64-encoded skill zip bundle. - - `class AnnotationContainerFileCitation: …` + - `media_type: Literal["application/zip"]` - A citation for a container file used to generate a model response. + The media type of the inline skill payload. Must be `application/zip`. - - `container_id: str` + - `"application/zip"` - The ID of the container file. + - `type: Literal["base64"]` - - `end_index: int` + The type of the inline skill source. Must be `base64`. - The index of the last character of the container file citation in the message. + - `"base64"` - - `file_id: str` + - `type: Literal["inline"]` - The ID of the file. + Defines an inline skill for this request. - - `filename: str` + - `"inline"` - The filename of the container file cited. + - `class BetaLocalEnvironment: …` - - `start_index: int` + - `type: Literal["local"]` - The index of the first character of the container file citation in the message. + Use a local computer environment. - - `type: Literal["container_file_citation"]` + - `"local"` - The type of the container file citation. Always `container_file_citation`. + - `skills: Optional[List[BetaLocalSkill]]` - - `"container_file_citation"` + An optional list of skills. - - `class AnnotationFilePath: …` + - `description: str` - A path to a file. + The description of the skill. - - `file_id: str` + - `name: str` - The ID of the file. + The name of the skill. - - `index: int` + - `path: str` - The index of the file in the list of files. + The path to the directory containing the skill. - - `type: Literal["file_path"]` + - `class BetaContainerReference: …` - The type of the file path. Always `file_path`. + - `container_id: str` - - `"file_path"` + The ID of the referenced container. - - `text: str` + - `type: Literal["container_reference"]` - The text output from the model. + References a container created with the /v1/containers endpoint - - `type: Literal["output_text"]` + - `"container_reference"` - The type of the output text. Always `output_text`. + - `class BetaCustomTool: …` - - `"output_text"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `logprobs: Optional[List[Logprob]]` + - `name: str` - - `token: str` + The name of the custom tool, used to identify it in tool calls. - - `bytes: List[int]` + - `type: Literal["custom"]` - - `logprob: float` + The type of the custom tool. Always `custom`. - - `top_logprobs: List[LogprobTopLogprob]` + - `"custom"` - - `token: str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `bytes: List[int]` + The tool invocation context(s). - - `logprob: float` + - `"direct"` - - `class BetaResponseOutputRefusal: …` + - `"programmatic"` - A refusal from the model. + - `defer_loading: Optional[bool]` - - `refusal: str` + Whether this tool should be deferred and discovered via tool search. - The refusal explanation from the model. + - `description: Optional[str]` - - `type: Literal["refusal"]` + Optional description of the custom tool, used to provide more context. - The type of the refusal. Always `refusal`. + - `format: Optional[Format]` - - `"refusal"` + The input format for the custom tool. Default is unconstrained text. - - `role: Literal["assistant"]` + - `class FormatText: …` - The role of the output message. Always `assistant`. + Unconstrained free-form text. - - `"assistant"` + - `type: Literal["text"]` - - `status: Literal["in_progress", "completed", "incomplete"]` + Unconstrained text format. Always `text`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"text"` - - `"in_progress"` + - `class FormatGrammar: …` - - `"completed"` + A grammar defined by the user. - - `"incomplete"` + - `definition: str` - - `type: Literal["message"]` + The grammar definition. - The type of the output message. Always `message`. + - `syntax: Literal["lark", "regex"]` - - `"message"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `agent: Optional[Agent]` + - `"lark"` - The agent that produced this item. + - `"regex"` - - `agent_name: str` + - `type: Literal["grammar"]` - The canonical name of the agent that produced this item. + Grammar format. Always `grammar`. - - `phase: Optional[Literal["commentary"]]` + - `"grammar"` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `class BetaNamespaceTool: …` - - `"commentary"` + Groups function/custom tools under a shared namespace. -### Beta Response Output Refusal + - `description: str` -- `class BetaResponseOutputRefusal: …` + A description of the namespace shown to the model. - A refusal from the model. + - `name: str` - - `refusal: str` + The namespace name used in tool calls (for example, `crm`). - The refusal explanation from the model. + - `tools: List[Tool]` - - `type: Literal["refusal"]` + The function/custom tools available inside this namespace. - The type of the refusal. Always `refusal`. + - `class ToolFunction: …` - - `"refusal"` + - `name: str` -### Beta Response Output Text + - `type: Literal["function"]` -- `class BetaResponseOutputText: …` + - `"function"` - A text output from the model. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `annotations: List[Annotation]` + The tool invocation context(s). - The annotations of the text output. + - `"direct"` - - `class AnnotationFileCitation: …` + - `"programmatic"` - A citation to a file. + - `defer_loading: Optional[bool]` - - `file_id: str` + Whether this function should be deferred and discovered via tool search. - The ID of the file. + - `description: Optional[str]` - - `filename: str` + - `output_schema: Optional[Dict[str, object]]` - The filename of the file cited. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `index: int` + - `parameters: Optional[object]` - The index of the file in the list of files. + - `strict: Optional[bool]` - - `type: Literal["file_citation"]` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - The type of the file citation. Always `file_citation`. + - `class BetaCustomTool: …` - - `"file_citation"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `class AnnotationURLCitation: …` + - `type: Literal["namespace"]` - A citation for a web resource used to generate a model response. + The type of the tool. Always `namespace`. - - `end_index: int` + - `"namespace"` - The index of the last character of the URL citation in the message. + - `class BetaToolSearchTool: …` - - `start_index: int` + Hosted or BYOT tool search configuration for deferred tools. - The index of the first character of the URL citation in the message. + - `type: Literal["tool_search"]` - - `title: str` + The type of the tool. Always `tool_search`. - The title of the web resource. + - `"tool_search"` - - `type: Literal["url_citation"]` + - `description: Optional[str]` - The type of the URL citation. Always `url_citation`. + Description shown to the model for a client-executed tool search tool. - - `"url_citation"` + - `execution: Optional[Literal["server", "client"]]` - - `url: str` + Whether tool search is executed by the server or by the client. - The URL of the web resource. + - `"server"` - - `class AnnotationContainerFileCitation: …` + - `"client"` - A citation for a container file used to generate a model response. + - `parameters: Optional[object]` - - `container_id: str` + Parameter schema for a client-executed tool search tool. - The ID of the container file. + - `class BetaWebSearchPreviewTool: …` - - `end_index: int` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The index of the last character of the container file citation in the message. + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - - `file_id: str` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The ID of the file. + - `"web_search_preview"` - - `filename: str` + - `"web_search_preview_2025_03_11"` - The filename of the container file cited. + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `start_index: int` + - `"text"` - The index of the first character of the container file citation in the message. + - `"image"` - - `type: Literal["container_file_citation"]` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The type of the container file citation. Always `container_file_citation`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `"container_file_citation"` + - `"low"` - - `class AnnotationFilePath: …` + - `"medium"` - A path to a file. + - `"high"` - - `file_id: str` + - `user_location: Optional[UserLocation]` - The ID of the file. + The user's location. - - `index: int` + - `type: Literal["approximate"]` - The index of the file in the list of files. + The type of location approximation. Always `approximate`. - - `type: Literal["file_path"]` + - `"approximate"` - The type of the file path. Always `file_path`. + - `city: Optional[str]` - - `"file_path"` + Free text input for the city of the user, e.g. `San Francisco`. - - `text: str` + - `country: Optional[str]` - The text output from the model. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `type: Literal["output_text"]` + - `region: Optional[str]` - The type of the output text. Always `output_text`. + Free text input for the region of the user, e.g. `California`. - - `"output_text"` + - `timezone: Optional[str]` - - `logprobs: Optional[List[Logprob]]` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `token: str` + - `class BetaApplyPatchTool: …` - - `bytes: List[int]` + Allows the assistant to create, delete, or update files using unified diffs. - - `logprob: float` + - `type: Literal["apply_patch"]` - - `top_logprobs: List[LogprobTopLogprob]` + The type of the tool. Always `apply_patch`. - - `token: str` + - `"apply_patch"` - - `bytes: List[int]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `logprob: float` + The tool invocation context(s). -### Beta Response Output Text Annotation Added Event + - `"direct"` -- `class BetaResponseOutputTextAnnotationAddedEvent: …` + - `"programmatic"` - Emitted when an annotation is added to output text content. + - `type: Literal["tool_search_output"]` - - `annotation: object` + The item type. Always `tool_search_output`. - The annotation object being added. (See annotation schema for details.) + - `"tool_search_output"` - - `annotation_index: int` + - `id: Optional[str]` - The index of the annotation within the content part. + The unique ID of this tool search output. - - `content_index: int` + - `agent: Optional[Agent]` - The index of the content part within the output item. + The agent that produced this item. - - `item_id: str` + - `agent_name: str` - The unique identifier of the item to which the annotation is being added. + The canonical name of the agent that produced this item. - - `output_index: int` + - `call_id: Optional[str]` - The index of the output item in the response's output array. + The unique ID of the tool search call generated by the model. - - `sequence_number: int` + - `execution: Optional[Literal["server", "client"]]` - The sequence number of this event. + Whether tool search was executed by the server or by the client. - - `type: Literal["response.output_text.annotation.added"]` + - `"server"` - The type of the event. Always 'response.output_text.annotation.added'. + - `"client"` - - `"response.output_text.annotation.added"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `agent: Optional[Agent]` + The status of the tool search output. - The agent that owns this multi-agent streaming event. + - `"in_progress"` - - `agent_name: str` + - `"completed"` - The canonical name of the agent that produced this item. + - `"incomplete"` -### Beta Response Prompt +### Beta Response Usage -- `class BetaResponsePrompt: …` +- `class BetaResponseUsage: …` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `id: str` + - `input_tokens: int` - The unique identifier of the prompt template to use. + The number of input tokens. - - `variables: Optional[Dict[str, Variables]]` + - `input_tokens_details: InputTokensDetails` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + A detailed breakdown of the input tokens. - - `str` + - `cache_write_tokens: int` - - `class BetaResponseInputText: …` + The number of input tokens that were written to the cache. - A text input to the model. + - `cached_tokens: int` - - `text: str` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - The text input to the model. + - `output_tokens: int` - - `type: Literal["input_text"]` + The number of output tokens. - The type of the input item. Always `input_text`. + - `output_tokens_details: OutputTokensDetails` - - `"input_text"` + A detailed breakdown of the output tokens. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `reasoning_tokens: int` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The number of reasoning tokens. - - `mode: Literal["explicit"]` + - `total_tokens: int` - The breakpoint mode. Always `explicit`. + The total number of tokens used. - - `"explicit"` +### Beta Response Web Search Call Completed Event - - `class BetaResponseInputImage: …` +- `class BetaResponseWebSearchCallCompletedEvent: …` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Emitted when a web search call is completed. - - `detail: Literal["low", "high", "auto", "original"]` + - `item_id: str` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Unique ID for the output item associated with the web search call. - - `"low"` + - `output_index: int` - - `"high"` + The index of the output item that the web search call is associated with. - - `"auto"` + - `sequence_number: int` - - `"original"` + The sequence number of the web search call being processed. - - `type: Literal["input_image"]` + - `type: Literal["response.web_search_call.completed"]` - The type of the input item. Always `input_image`. + The type of the event. Always `response.web_search_call.completed`. - - `"input_image"` + - `"response.web_search_call.completed"` - - `file_id: Optional[str]` + - `agent: Optional[Agent]` - The ID of the file to be sent to the model. + The agent that owns this multi-agent streaming event. - - `image_url: Optional[str]` + - `agent_name: str` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The canonical name of the agent that produced this item. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` +### Beta Response Web Search Call In Progress Event - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. +- `class BetaResponseWebSearchCallInProgressEvent: …` - - `mode: Literal["explicit"]` + Emitted when a web search call is initiated. - The breakpoint mode. Always `explicit`. + - `item_id: str` - - `"explicit"` + Unique ID for the output item associated with the web search call. - - `class BetaResponseInputFile: …` + - `output_index: int` - A file input to the model. + The index of the output item that the web search call is associated with. - - `type: Literal["input_file"]` + - `sequence_number: int` - The type of the input item. Always `input_file`. + The sequence number of the web search call being processed. - - `"input_file"` + - `type: Literal["response.web_search_call.in_progress"]` - - `detail: Optional[Literal["auto", "low", "high"]]` + The type of the event. Always `response.web_search_call.in_progress`. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"response.web_search_call.in_progress"` - - `"auto"` + - `agent: Optional[Agent]` - - `"low"` + The agent that owns this multi-agent streaming event. - - `"high"` + - `agent_name: str` - - `file_data: Optional[str]` + The canonical name of the agent that produced this item. - The content of the file to be sent to the model. +### Beta Response Web Search Call Searching Event - - `file_id: Optional[str]` +- `class BetaResponseWebSearchCallSearchingEvent: …` - The ID of the file to be sent to the model. + Emitted when a web search call is executing. - - `file_url: Optional[str]` + - `item_id: str` - The URL of the file to be sent to the model. + Unique ID for the output item associated with the web search call. - - `filename: Optional[str]` + - `output_index: int` - The name of the file to be sent to the model. + The index of the output item that the web search call is associated with. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `sequence_number: int` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The sequence number of the web search call being processed. - - `mode: Literal["explicit"]` + - `type: Literal["response.web_search_call.searching"]` - The breakpoint mode. Always `explicit`. + The type of the event. Always `response.web_search_call.searching`. - - `"explicit"` + - `"response.web_search_call.searching"` - - `version: Optional[str]` + - `agent: Optional[Agent]` - Optional version of the prompt template. + The agent that owns this multi-agent streaming event. -### Beta Response Queued Event + - `agent_name: str` -- `class BetaResponseQueuedEvent: …` + The canonical name of the agent that produced this item. - Emitted when a response is queued and waiting to be processed. +### Beta Responses Client Event - - `response: BetaResponse` +- `BetaResponsesClientEvent` - The full response object that is queued. + Client events accepted by the Responses WebSocket server. - - `id: str` + - `class ResponseCreate: …` - Unique identifier for this Response. + Client event for creating a response over a persistent WebSocket connection. + This payload uses the same top-level fields as `POST /v1/responses`. - - `created_at: float` + Notes: - Unix timestamp (in seconds) of when this Response was created. + - `stream` is implicit over WebSocket and should not be sent. + - `background` is not supported over WebSocket. - - `error: Optional[BetaResponseError]` + - `type: Literal["response.create"]` - An error object returned when the model fails to generate a Response. + The type of the client event. Always `response.create`. - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + - `"response.create"` - The error code for the response. + - `background: Optional[bool]` - - `"server_error"` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `"rate_limit_exceeded"` + - `context_management: Optional[List[ResponseCreateContextManagement]]` - - `"invalid_prompt"` + Context management configuration for this request. - - `"bio_policy"` + - `type: str` - - `"vector_store_timeout"` + The context management entry type. Currently only 'compaction' is supported. - - `"invalid_image"` + - `compact_threshold: Optional[int]` - - `"invalid_image_format"` + Token threshold at which compaction should be triggered for this entry. - - `"invalid_base64_image"` + - `conversation: Optional[ResponseCreateConversation]` - - `"invalid_image_url"` + The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. - - `"image_too_large"` + - `str` - - `"image_too_small"` + The unique ID of the conversation. - - `"image_parse_error"` + - `class BetaResponseConversationParam: …` - - `"image_content_policy_violation"` + The conversation that this response belongs to. - - `"invalid_image_mode"` + - `id: str` - - `"image_file_too_large"` + The unique ID of the conversation. - - `"unsupported_image_media_type"` + - `include: Optional[List[BetaResponseIncludable]]` - - `"empty_image_file"` + Specify additional output data to include in the model response. Currently supported values are: - - `"failed_to_download_image"` + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - - `"image_file_not_found"` + - `"file_search_call.results"` - - `message: str` + - `"web_search_call.results"` - A human-readable description of the error. + - `"web_search_call.action.sources"` - - `incomplete_details: Optional[IncompleteDetails]` + - `"message.input_image.image_url"` - Details about why the response is incomplete. + - `"computer_call_output.output.image_url"` - - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` + - `"code_interpreter_call.outputs"` - The reason why the response is incomplete. + - `"reasoning.encrypted_content"` - - `"max_output_tokens"` + - `"message.output_text.logprobs"` - - `"content_filter"` + - `input: Optional[Union[str, BetaResponseInput, null]]` - - `instructions: Union[str, List[BetaResponseInputItem], null]` + Text, image, or file inputs to the model, used to generate a response. - A system (or developer) message inserted into the model's context. + Learn more: - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Image inputs](https://platform.openai.com/docs/guides/images) + - [File inputs](https://platform.openai.com/docs/guides/pdf-files) + - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) + - [Function calling](https://platform.openai.com/docs/guides/function-calling) - `str` A text input to the model, equivalent to a text input with the - `developer` role. + `user` role. - `List[BetaResponseInputItem]` - A list of one or many input items to the model, containing - different content types. - - `class BetaEasyInputMessage: …` A message input to the model with a role indicating instruction following @@ -120092,7 +130371,7 @@ print(compacted_response) - `"developer"` - - `phase: Optional[Literal["commentary"]]` + - `phase: Optional[Literal["commentary", "final_answer"]]` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -120100,6 +130379,8 @@ print(compacted_response) - `"commentary"` + - `"final_answer"` + - `type: Optional[Literal["message"]]` The type of the message input. Always `message`. @@ -120351,7 +130632,7 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `phase: Optional[Literal["commentary"]]` + - `phase: Optional[Literal["commentary", "final_answer"]]` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -120359,6 +130640,8 @@ print(compacted_response) - `"commentary"` + - `"final_answer"` + - `class BetaResponseFileSearchToolCall: …` The results of a file search tool call. See the @@ -121529,7 +131812,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -121539,7 +131822,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `class FiltersCompoundFilter: …` @@ -121586,7 +131873,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -121596,7 +131883,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `object` @@ -123746,6 +134037,22 @@ print(compacted_response) The canonical name of the agent that produced this item. + - `instructions: Optional[str]` + + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + + - `max_output_tokens: Optional[int]` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + + - `max_tool_calls: Optional[int]` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `metadata: Optional[Dict[str, str]]` Set of 16 key-value pairs that can be attached to an object. This can be @@ -123755,7 +134062,7 @@ print(compacted_response) Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` + - `model: Optional[Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str, null]]` Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance @@ -123961,59 +134268,77 @@ print(compacted_response) - `str` - - `object: Literal["response"]` + - `moderation: Optional[ResponseCreateModeration]` - The object type of this resource - always set to `response`. + Configuration for running moderation on the input and output of this response. - - `"response"` + - `model: str` - - `output: List[BetaResponseOutputItem]` + The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - An array of content items generated by the model. + - `policy: Optional[ResponseCreateModerationPolicy]` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + The policy to apply to moderated response input and output. - - `class BetaResponseOutputMessage: …` + - `input: Optional[ResponseCreateModerationPolicyInput]` - An output message from the model. + The moderation policy for the response input. - - `class BetaResponseFileSearchToolCall: …` + - `mode: Literal["score", "block"]` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"score"` - - `class BetaResponseFunctionToolCall: …` + - `"block"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `output: Optional[ResponseCreateModerationPolicyOutput]` - - `class BetaResponseFunctionToolCallOutputItem: …` + The moderation policy for the response output. - - `id: str` + - `mode: Literal["score", "block"]` - The unique ID of the function call tool output. + - `"score"` - - `call_id: str` + - `"block"` - The unique ID of the function tool call generated by the model. + - `multi_agent: Optional[ResponseCreateMultiAgent]` - - `output: Union[str, List[OutputOutputContentList]]` + Configuration for server-hosted multi-agent execution. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `enabled: bool` - - `str` + Whether to enable server-hosted multi-agent execution for this response. - A string of the output of the function call. + - `max_concurrent_subagents: Optional[int]` - - `List[OutputOutputContentList]` + `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. + The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. - Text, image, or file output of the function call. + - `parallel_tool_calls: Optional[bool]` + + Whether to allow the model to run tool calls in parallel. + + - `previous_response_id: Optional[str]` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `prompt: Optional[BetaResponsePrompt]` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `id: str` + + The unique identifier of the prompt template to use. + + - `variables: Optional[Dict[str, Variables]]` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `str` - `class BetaResponseInputText: …` @@ -124027,841 +134352,1468 @@ print(compacted_response) A file input to the model. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `version: Optional[str]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Optional version of the prompt template. - - `"in_progress"` + - `prompt_cache_key: Optional[str]` - - `"completed"` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `"incomplete"` + - `prompt_cache_options: Optional[ResponseCreatePromptCacheOptions]` - - `type: Literal["function_call_output"]` + Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. - The type of the function tool call output. Always `function_call_output`. + - `mode: Optional[Literal["implicit", "explicit"]]` - - `"function_call_output"` + Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - - `agent: Optional[Agent]` + - `"implicit"` - The agent that produced this item. + - `"explicit"` - - `agent_name: str` + - `ttl: Optional[Literal["30m"]]` - The canonical name of the agent that produced this item. + The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. - - `caller: Optional[Caller]` + - `"30m"` - The execution context that produced this tool call. + - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` - - `class CallerDirect: …` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `type: Literal["direct"]` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - The caller type. Always `direct`. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `"direct"` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `class CallerProgram: …` + - `"in_memory"` - - `caller_id: str` + - `"24h"` - The call ID of the program item that produced this tool call. + - `reasoning: Optional[ResponseCreateReasoning]` - - `type: Literal["program"]` + **gpt-5 and o-series models only** - The caller type. Always `program`. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `"program"` + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` - - `created_by: Optional[str]` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - The identifier of the actor that created the item. + - `"auto"` - - `class AgentMessage: …` + - `"current_turn"` - - `id: str` + - `"all_turns"` - The unique ID of the agent message. + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` - - `author: str` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - The sending agent identity. + - `"none"` - - `content: List[AgentMessageContent]` + - `"minimal"` - Encrypted content sent between agents. + - `"low"` - - `class BetaResponseInputText: …` + - `"medium"` - A text input to the model. + - `"high"` - - `class BetaResponseOutputText: …` + - `"xhigh"` - A text output from the model. + - `"max"` - - `class AgentMessageContentText: …` + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` - A text content. + **Deprecated:** use `summary` instead. - - `text: str` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `type: Literal["text"]` + - `"auto"` - - `"text"` + - `"concise"` - - `class AgentMessageContentSummaryText: …` + - `"detailed"` - A summary text from the model. + - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` - - `text: str` + Controls the reasoning execution mode for the request. - A summary of the reasoning output from the model so far. + When returned on a response, this is the effective execution mode. - - `type: Literal["summary_text"]` + - `str` - The type of the object. Always `summary_text`. + - `Literal["standard", "pro"]` - - `"summary_text"` + Controls the reasoning execution mode for the request. - - `class AgentMessageContentReasoningText: …` + When returned on a response, this is the effective execution mode. - Reasoning text from the model. + - `"standard"` - - `text: str` + - `"pro"` - The reasoning text from the model. + - `summary: Optional[Literal["auto", "concise", "detailed"]]` - - `type: Literal["reasoning_text"]` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The type of the reasoning text. Always `reasoning_text`. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `"reasoning_text"` + - `"auto"` - - `class BetaResponseOutputRefusal: …` + - `"concise"` - A refusal from the model. + - `"detailed"` - - `class BetaResponseInputImage: …` + - `safety_identifier: Optional[str]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `class AgentMessageContentComputerScreenshot: …` + - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` - A screenshot of a computer. + Specifies the processing type used for serving the request. - - `detail: Literal["low", "high", "auto", "original"]` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"scale"` + + - `"priority"` + + - `store: Optional[bool]` + + Whether to store the generated model response for later retrieval via + API. + + - `stream: Optional[bool]` + + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) + for more information. + + - `stream_options: Optional[ResponseCreateStreamOptions]` + + Options for streaming responses. Only set this when you set `stream: true`. + + - `include_obfuscation: Optional[bool]` + + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events to + normalize payload sizes as a mitigation to certain side-channel attacks. + These obfuscation fields are included by default, but add a small amount + of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between + your application and the OpenAI API. + + - `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. + We generally recommend altering this or `top_p` but not both. + + - `text: Optional[BetaResponseTextConfig]` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + + - `format: Optional[BetaResponseFormatTextConfig]` + + An object specifying the format that the model must output. + + Configuring `{ "type": "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). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `class Text: …` + + Default response format. Used to generate text responses. + + - `type: Literal["text"]` + + The type of response format being defined. Always `text`. + + - `"text"` + + - `class BetaResponseFormatTextJSONSchemaConfig: …` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + + - `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. + + - `schema: 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/). + + - `type: Literal["json_schema"]` + + The type of response format being defined. Always `json_schema`. + + - `"json_schema"` + + - `description: Optional[str]` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `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). + + - `class JSONObject: …` + + 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"` + + - `verbosity: Optional[Literal["low", "medium", "high"]]` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - `"low"` + - `"medium"` + - `"high"` + - `tool_choice: Optional[ResponseCreateToolChoice]` + + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. + + - `Literal["none", "auto", "required"]` + + - `"none"` + - `"auto"` - - `"original"` + - `"required"` - - `file_id: Optional[str]` + - `class BetaToolChoiceAllowed: …` - The identifier of an uploaded file that contains the screenshot. + Constrains the tools available to the model to a pre-defined set. - - `image_url: Optional[str]` + - `mode: Literal["auto", "required"]` - The URL of the screenshot image. + Constrains the tools available to the model to a pre-defined set. - - `type: Literal["computer_screenshot"]` + `auto` allows the model to pick from among the allowed tools and generate a + message. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + `required` requires the model to call one or more of the allowed tools. - - `"computer_screenshot"` + - `"auto"` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `"required"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `tools: List[Dict[str, object]]` - - `mode: Literal["explicit"]` + A list of tool definitions that the model should be allowed to call. - The breakpoint mode. Always `explicit`. + For the Responses API, the list of tool definitions might look like: - - `"explicit"` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `class BetaResponseInputFile: …` + - `type: Literal["allowed_tools"]` - A file input to the model. + Allowed tool configuration type. Always `allowed_tools`. - - `class AgentMessageContentEncryptedContent: …` + - `"allowed_tools"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `class BetaToolChoiceTypes: …` - - `encrypted_content: str` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - Opaque encrypted content. + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` - - `type: Literal["encrypted_content"]` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - The type of the input item. Always `encrypted_content`. + Allowed values are: - - `"encrypted_content"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `recipient: str` + - `"file_search"` - The destination agent identity. + - `"web_search_preview"` - - `type: Literal["agent_message"]` + - `"computer"` - The type of the item. Always `agent_message`. + - `"computer_use_preview"` - - `"agent_message"` + - `"computer_use"` - - `agent: Optional[AgentMessageAgent]` + - `"web_search_preview_2025_03_11"` - The agent that produced this item. + - `"image_generation"` + + - `"code_interpreter"` + + - `class BetaToolChoiceFunction: …` + + Use this option to force the model to call a specific function. + + - `name: str` + + The name of the function to call. + + - `type: Literal["function"]` + + For function calling, the type is always `function`. + + - `"function"` + + - `class BetaToolChoiceMcp: …` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `server_label: str` + + The label of the MCP server to use. + + - `type: Literal["mcp"]` + + For MCP tools, the type is always `mcp`. + + - `"mcp"` + + - `name: Optional[str]` + + The name of the tool to call on the server. + + - `class BetaToolChoiceCustom: …` + + Use this option to force the model to call a specific custom tool. + + - `name: str` + + The name of the custom tool to call. + + - `type: Literal["custom"]` + + For custom tool calling, the type is always `custom`. + + - `"custom"` + + - `class ResponseCreateToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + + - `type: Literal["programmatic_tool_calling"]` + + The tool to call. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + + - `class BetaToolChoiceApplyPatch: …` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `type: Literal["apply_patch"]` + + The tool to call. Always `apply_patch`. + + - `"apply_patch"` + + - `class BetaToolChoiceShell: …` + + Forces the model to call the shell tool when a tool call is required. + + - `type: Literal["shell"]` + + The tool to call. Always `shell`. + + - `"shell"` + + - `tools: Optional[List[BetaTool]]` + + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. + + - `class BetaFunctionTool: …` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool: …` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool: …` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool: …` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class Mcp: …` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `class CodeInterpreter: …` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling: …` + + - `class ImageGeneration: …` + + A tool that generates images using the GPT image models. + + - `class LocalShell: …` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool: …` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool: …` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool: …` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool: …` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool: …` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool: …` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `top_logprobs: Optional[int]` + + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + + - `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. + + - `truncation: Optional[Literal["auto", "disabled"]]` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `"auto"` + + - `"disabled"` + + - `user: Optional[str]` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `class BetaResponseInjectEvent: …` + + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. + + - `input: List[BetaResponseInputItem]` + + Input items to inject into the active response. + + - `class BetaEasyInputMessage: …` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `class Message: …` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `class BetaResponseOutputMessage: …` + + An output message from the model. + + - `class BetaResponseFileSearchToolCall: …` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `class BetaResponseComputerToolCall: …` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `class ComputerCallOutput: …` + + The output of a computer tool call. + + - `class BetaResponseFunctionWebSearch: …` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `class BetaResponseFunctionToolCall: …` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `class FunctionCallOutput: …` + + The output of a function tool call. + + - `class AgentMessage: …` + + A message routed between agents. + + - `class MultiAgentCall: …` + + - `class MultiAgentCallOutput: …` + + - `class ToolSearchCall: …` + + - `class BetaResponseToolSearchOutputItemParam: …` + + - `class AdditionalTools: …` + + - `class BetaResponseReasoningItem: …` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `class BetaResponseCompactionItemParam: …` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `class ImageGenerationCall: …` + + An image generation request made by the model. + + - `class BetaResponseCodeInterpreterToolCall: …` + + A tool call to run code. + + - `class LocalShellCall: …` + + A tool call to run a command on the local shell. + + - `class LocalShellCallOutput: …` + + The output of a local shell tool call. + + - `class ShellCall: …` + + A tool representing a request to execute one or more shell commands. + + - `class ShellCallOutput: …` + + The streamed output items emitted by a shell tool call. + + - `class ApplyPatchCall: …` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `class ApplyPatchCallOutput: …` + + The streamed output emitted by an apply patch tool call. + + - `class McpListTools: …` + + A list of tools available on an MCP server. + + - `class McpApprovalRequest: …` + + A request for human approval of a tool invocation. + + - `class McpApprovalResponse: …` + + A response to an MCP approval request. + + - `class McpCall: …` + + An invocation of a tool on an MCP server. + + - `class BetaResponseCustomToolCallOutput: …` + + The output of a custom tool call from your code, being sent back to the model. + + - `class BetaResponseCustomToolCall: …` + + A call to a custom tool created by the model. + + - `class CompactionTrigger: …` + + Compacts the current context. Must be the final input item. + + - `class ItemReference: …` + + An internal identifier for an item to reference. + + - `class Program: …` + + - `class ProgramOutput: …` + + - `response_id: str` + + The ID of the active response that should receive the input. + + - `type: Literal["response.inject"]` + + The event discriminator. Always `response.inject`. + + - `"response.inject"` + +### Beta Responses Server Event + +- `BetaResponsesServerEvent` + + Server events emitted by the Responses WebSocket server. + + - `class BetaResponseAudioDeltaEvent: …` + + Emitted when there is a partial audio response. + + - `delta: str` + + A chunk of Base64 encoded response audio bytes. + + - `sequence_number: int` + + A sequence number for this chunk of the stream response. + + - `type: Literal["response.audio.delta"]` + + The type of the event. Always `response.audio.delta`. + + - `"response.audio.delta"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class MultiAgentCall: …` + - `class BetaResponseAudioDoneEvent: …` - - `id: str` + Emitted when the audio response is complete. - The unique ID of the multi-agent call item. + - `sequence_number: int` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The sequence number of the delta. - The multi-agent action to execute. + - `type: Literal["response.audio.done"]` - - `"spawn_agent"` + The type of the event. Always `response.audio.done`. - - `"interrupt_agent"` + - `"response.audio.done"` - - `"list_agents"` + - `agent: Optional[Agent]` - - `"send_message"` + The agent that owns this multi-agent streaming event. - - `"followup_task"` + - `agent_name: str` - - `"wait_agent"` + The canonical name of the agent that produced this item. - - `arguments: str` + - `class BetaResponseAudioTranscriptDeltaEvent: …` - The JSON string of arguments generated for the action. + Emitted when there is a partial transcript of audio. - - `call_id: str` + - `delta: str` - The unique ID linking this call to its output. + The partial transcript of the audio response. - - `type: Literal["multi_agent_call"]` + - `sequence_number: int` - The type of the multi-agent call. Always `multi_agent_call`. + The sequence number of this event. - - `"multi_agent_call"` + - `type: Literal["response.audio.transcript.delta"]` - - `agent: Optional[MultiAgentCallAgent]` + The type of the event. Always `response.audio.transcript.delta`. - The agent that produced this item. + - `"response.audio.transcript.delta"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput: …` + - `class BetaResponseAudioTranscriptDoneEvent: …` - - `id: str` + Emitted when the full audio transcript is completed. - The unique ID of the multi-agent call output item. + - `sequence_number: int` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The sequence number of this event. - The multi-agent action that produced this result. + - `type: Literal["response.audio.transcript.done"]` - - `"spawn_agent"` + The type of the event. Always `response.audio.transcript.done`. - - `"interrupt_agent"` + - `"response.audio.transcript.done"` - - `"list_agents"` + - `agent: Optional[Agent]` - - `"send_message"` + The agent that owns this multi-agent streaming event. - - `"followup_task"` + - `agent_name: str` - - `"wait_agent"` + The canonical name of the agent that produced this item. - - `call_id: str` + - `class BetaResponseCodeInterpreterCallCodeDeltaEvent: …` - The unique ID of the multi-agent call. + Emitted when a partial code snippet is streamed by the code interpreter. - - `output: List[BetaResponseOutputText]` + - `delta: str` - Text output returned by the multi-agent action. + The partial code snippet being streamed by the code interpreter. - - `annotations: List[Annotation]` + - `item_id: str` - The annotations of the text output. + The unique identifier of the code interpreter tool call item. - - `text: str` + - `output_index: int` - The text output from the model. + The index of the output item in the response for which the code is being streamed. - - `type: Literal["output_text"]` + - `sequence_number: int` - The type of the output text. Always `output_text`. + The sequence number of this event, used to order streaming events. - - `logprobs: Optional[List[Logprob]]` + - `type: Literal["response.code_interpreter_call_code.delta"]` - - `type: Literal["multi_agent_call_output"]` + The type of the event. Always `response.code_interpreter_call_code.delta`. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"response.code_interpreter_call_code.delta"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterCallCodeDoneEvent: …` + + Emitted when the code snippet is finalized by the code interpreter. + + - `code: str` + + The final code snippet output by the code interpreter. + + - `item_id: str` + + The unique identifier of the code interpreter tool call item. + + - `output_index: int` + + The index of the output item in the response for which the code is finalized. + + - `sequence_number: int` + + The sequence number of this event, used to order streaming events. + + - `type: Literal["response.code_interpreter_call_code.done"]` + + The type of the event. Always `response.code_interpreter_call_code.done`. + + - `"response.code_interpreter_call_code.done"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterCallCompletedEvent: …` + + Emitted when the code interpreter call is completed. + + - `item_id: str` + + The unique identifier of the code interpreter tool call item. + + - `output_index: int` + + The index of the output item in the response for which the code interpreter call is completed. + + - `sequence_number: int` + + The sequence number of this event, used to order streaming events. + + - `type: Literal["response.code_interpreter_call.completed"]` + + The type of the event. Always `response.code_interpreter_call.completed`. - - `"multi_agent_call_output"` + - `"response.code_interpreter_call.completed"` - - `agent: Optional[MultiAgentCallOutputAgent]` + - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class BetaResponseFunctionWebSearch: …` - - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - - `class BetaResponseComputerToolCall: …` + - `class BetaResponseCodeInterpreterCallInProgressEvent: …` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Emitted when a code interpreter call is in progress. - - `class BetaResponseComputerToolCallOutputItem: …` + - `item_id: str` - - `id: str` + The unique identifier of the code interpreter tool call item. - The unique ID of the computer call tool output. + - `output_index: int` - - `call_id: str` + The index of the output item in the response for which the code interpreter call is in progress. - The ID of the computer tool call that produced the output. + - `sequence_number: int` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The sequence number of this event, used to order streaming events. - A computer screenshot image used with the computer use tool. + - `type: Literal["response.code_interpreter_call.in_progress"]` - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + The type of the event. Always `response.code_interpreter_call.in_progress`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"response.code_interpreter_call.in_progress"` - - `"completed"` + - `agent: Optional[Agent]` - - `"incomplete"` + The agent that owns this multi-agent streaming event. - - `"failed"` + - `agent_name: str` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `type: Literal["computer_call_output"]` + - `class BetaResponseCodeInterpreterCallInterpretingEvent: …` - The type of the computer tool call output. Always `computer_call_output`. + Emitted when the code interpreter is actively interpreting the code snippet. - - `"computer_call_output"` + - `item_id: str` - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + The unique identifier of the code interpreter tool call item. - The safety checks reported by the API that have been acknowledged by the - developer. + - `output_index: int` - - `id: str` + The index of the output item in the response for which the code interpreter is interpreting code. - The ID of the pending safety check. + - `sequence_number: int` - - `code: Optional[str]` + The sequence number of this event, used to order streaming events. - The type of the pending safety check. + - `type: Literal["response.code_interpreter_call.interpreting"]` - - `message: Optional[str]` + The type of the event. Always `response.code_interpreter_call.interpreting`. - Details about the pending safety check. + - `"response.code_interpreter_call.interpreting"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. + - `class BetaResponseCompletedEvent: …` - - `class BetaResponseReasoningItem: …` + Emitted when the model response is complete. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `response: BetaResponse` - - `class Program: …` + Properties of the completed response. - `id: str` - The unique ID of the program item. + Unique identifier for this Response. - - `call_id: str` + - `created_at: float` - The stable call ID of the program item. + Unix timestamp (in seconds) of when this Response was created. - - `code: str` + - `error: Optional[BetaResponseError]` - The JavaScript source executed by programmatic tool calling. + An error object returned when the model fails to generate a Response. - - `fingerprint: str` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` - Opaque program replay fingerprint that must be round-tripped. + The error code for the response. - - `type: Literal["program"]` + - `"server_error"` - The type of the item. Always `program`. + - `"rate_limit_exceeded"` - - `"program"` + - `"invalid_prompt"` - - `agent: Optional[ProgramAgent]` + - `"bio_policy"` - The agent that produced this item. + - `"vector_store_timeout"` - - `agent_name: str` + - `"invalid_image"` - The canonical name of the agent that produced this item. + - `"invalid_image_format"` - - `class ProgramOutput: …` + - `"invalid_base64_image"` - - `id: str` + - `"invalid_image_url"` - The unique ID of the program output item. + - `"image_too_large"` - - `call_id: str` + - `"image_too_small"` - The call ID of the program item. + - `"image_parse_error"` - - `result: str` + - `"image_content_policy_violation"` - The result produced by the program item. + - `"invalid_image_mode"` - - `status: Literal["completed", "incomplete"]` + - `"image_file_too_large"` - The terminal status of the program output item. + - `"unsupported_image_media_type"` - - `"completed"` + - `"empty_image_file"` - - `"incomplete"` + - `"failed_to_download_image"` - - `type: Literal["program_output"]` + - `"image_file_not_found"` - The type of the item. Always `program_output`. + - `message: str` - - `"program_output"` + A human-readable description of the error. - - `agent: Optional[ProgramOutputAgent]` + - `incomplete_details: Optional[IncompleteDetails]` - The agent that produced this item. + Details about why the response is incomplete. - - `agent_name: str` + - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` - The canonical name of the agent that produced this item. + The reason why the response is incomplete. - - `class BetaResponseToolSearchCall: …` + - `"max_output_tokens"` - - `id: str` + - `"content_filter"` - The unique ID of the tool search call item. + - `instructions: Union[str, List[BetaResponseInputItem], null]` - - `arguments: object` + A system (or developer) message inserted into the model's context. - Arguments used for the tool search call. + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `call_id: Optional[str]` + - `str` - The unique ID of the tool search call generated by the model. + A text input to the model, equivalent to a text input with the + `developer` role. - - `execution: Literal["server", "client"]` + - `List[BetaResponseInputItem]` - Whether tool search was executed by the server or by the client. + A list of one or many input items to the model, containing + different content types. - - `"server"` + - `class BetaEasyInputMessage: …` - - `"client"` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `content: Union[str, BetaResponseInputMessageContentList]` - The status of the tool search call item that was recorded. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"in_progress"` + - `str` - - `"completed"` + A text input to the model. - - `"incomplete"` + - `List[BetaResponseInputContent]` - - `type: Literal["tool_search_call"]` + - `class BetaResponseInputText: …` - The type of the item. Always `tool_search_call`. + A text input to the model. - - `"tool_search_call"` + - `text: str` - - `agent: Optional[Agent]` + The text input to the model. - The agent that produced this item. + - `type: Literal["input_text"]` - - `agent_name: str` + The type of the input item. Always `input_text`. - The canonical name of the agent that produced this item. + - `"input_text"` - - `created_by: Optional[str]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The identifier of the actor that created the item. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaResponseToolSearchOutputItem: …` + - `mode: Literal["explicit"]` - - `id: str` + The breakpoint mode. Always `explicit`. - The unique ID of the tool search output item. + - `"explicit"` - - `call_id: Optional[str]` + - `class BetaResponseInputImage: …` - The unique ID of the tool search call generated by the model. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `execution: Literal["server", "client"]` + - `detail: Literal["low", "high", "auto", "original"]` - Whether tool search was executed by the server or by the client. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"server"` + - `"low"` - - `"client"` + - `"high"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"auto"` - The status of the tool search output item that was recorded. + - `"original"` - - `"in_progress"` + - `type: Literal["input_image"]` - - `"completed"` + The type of the input item. Always `input_image`. - - `"incomplete"` + - `"input_image"` - - `tools: List[BetaTool]` + - `file_id: Optional[str]` - The loaded tool definitions returned by tool search. + The ID of the file to be sent to the model. - - `class BetaFunctionTool: …` + - `image_url: Optional[str]` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `class BetaFileSearchTool: …` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaComputerTool: …` + - `mode: Literal["explicit"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The breakpoint mode. Always `explicit`. - - `class BetaComputerUsePreviewTool: …` + - `"explicit"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class BetaResponseInputFile: …` - - `class BetaWebSearchTool: …` + A file input to the model. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `type: Literal["input_file"]` - - `class Mcp: …` + The type of the input item. Always `input_file`. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"input_file"` - - `class CodeInterpreter: …` + - `detail: Optional[Literal["auto", "low", "high"]]` - A tool that runs Python code to help generate a response to a prompt. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `class ProgrammaticToolCalling: …` + - `"auto"` - - `class ImageGeneration: …` + - `"low"` - A tool that generates images using the GPT image models. + - `"high"` - - `class LocalShell: …` + - `file_data: Optional[str]` - A tool that allows the model to execute shell commands in a local environment. + The content of the file to be sent to the model. - - `class BetaFunctionShellTool: …` + - `file_id: Optional[str]` - A tool that allows the model to execute shell commands. + The ID of the file to be sent to the model. - - `class BetaCustomTool: …` + - `file_url: Optional[str]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The URL of the file to be sent to the model. - - `class BetaNamespaceTool: …` + - `filename: Optional[str]` - Groups function/custom tools under a shared namespace. + The name of the file to be sent to the model. - - `class BetaToolSearchTool: …` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - Hosted or BYOT tool search configuration for deferred tools. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaWebSearchPreviewTool: …` + - `mode: Literal["explicit"]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The breakpoint mode. Always `explicit`. - - `class BetaApplyPatchTool: …` + - `"explicit"` - Allows the assistant to create, delete, or update files using unified diffs. + - `role: Literal["user", "assistant", "system", "developer"]` - - `type: Literal["tool_search_output"]` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The type of the item. Always `tool_search_output`. + - `"user"` - - `"tool_search_output"` + - `"assistant"` - - `agent: Optional[Agent]` + - `"system"` - The agent that produced this item. + - `"developer"` - - `agent_name: str` + - `phase: Optional[Literal["commentary", "final_answer"]]` - The canonical name of the agent that produced this item. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `created_by: Optional[str]` + - `"commentary"` - The identifier of the actor that created the item. + - `"final_answer"` - - `class AdditionalTools: …` + - `type: Optional[Literal["message"]]` - - `id: str` + The type of the message input. Always `message`. - The unique ID of the additional tools item. + - `"message"` - - `role: Literal["unknown", "user", "assistant", 5 more]` + - `class Message: …` - The role that provided the additional tools. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `"unknown"` + - `content: BetaResponseInputMessageContentList` - - `"user"` + A list of one or many input items to the model, containing different content + types. - - `"assistant"` + - `class BetaResponseInputText: …` - - `"system"` + A text input to the model. - - `"critic"` + - `class BetaResponseInputImage: …` - - `"discriminator"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"developer"` + - `class BetaResponseInputFile: …` - - `"tool"` + A file input to the model. - - `tools: List[BetaTool]` + - `role: Literal["user", "system", "developer"]` - The additional tool definitions made available at this item. + The role of the message input. One of `user`, `system`, or `developer`. - - `class BetaFunctionTool: …` + - `"user"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `"system"` - - `class BetaFileSearchTool: …` + - `"developer"` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `agent: Optional[MessageAgent]` - - `class BetaComputerTool: …` + The agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent_name: str` - - `class BetaComputerUsePreviewTool: …` + The canonical name of the agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `class BetaWebSearchTool: …` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"in_progress"` - - `class Mcp: …` + - `"completed"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"incomplete"` - - `class CodeInterpreter: …` + - `type: Optional[Literal["message"]]` - A tool that runs Python code to help generate a response to a prompt. + The type of the message input. Always set to `message`. - - `class ProgrammaticToolCalling: …` + - `"message"` - - `class ImageGeneration: …` + - `class BetaResponseOutputMessage: …` - A tool that generates images using the GPT image models. + An output message from the model. - - `class LocalShell: …` + - `id: str` - A tool that allows the model to execute shell commands in a local environment. + The unique ID of the output message. - - `class BetaFunctionShellTool: …` + - `content: List[Content]` - A tool that allows the model to execute shell commands. + The content of the output message. - - `class BetaCustomTool: …` + - `class BetaResponseOutputText: …` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A text output from the model. - - `class BetaNamespaceTool: …` + - `annotations: List[Annotation]` - Groups function/custom tools under a shared namespace. + The annotations of the text output. - - `class BetaToolSearchTool: …` + - `class AnnotationFileCitation: …` - Hosted or BYOT tool search configuration for deferred tools. + A citation to a file. - - `class BetaWebSearchPreviewTool: …` + - `file_id: str` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The ID of the file. - - `class BetaApplyPatchTool: …` + - `filename: str` - Allows the assistant to create, delete, or update files using unified diffs. + The filename of the file cited. - - `type: Literal["additional_tools"]` + - `index: int` - The type of the item. Always `additional_tools`. + The index of the file in the list of files. - - `"additional_tools"` + - `type: Literal["file_citation"]` - - `agent: Optional[AdditionalToolsAgent]` + The type of the file citation. Always `file_citation`. - The agent that produced this item. + - `"file_citation"` - - `agent_name: str` + - `class AnnotationURLCitation: …` - The canonical name of the agent that produced this item. + A citation for a web resource used to generate a model response. - - `class BetaResponseCompactionItem: …` + - `end_index: int` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The index of the last character of the URL citation in the message. - - `id: str` + - `start_index: int` - The unique ID of the compaction item. + The index of the first character of the URL citation in the message. - - `encrypted_content: str` + - `title: str` - The encrypted content that was produced by compaction. + The title of the web resource. - - `type: Literal["compaction"]` + - `type: Literal["url_citation"]` - The type of the item. Always `compaction`. + The type of the URL citation. Always `url_citation`. - - `"compaction"` + - `"url_citation"` - - `agent: Optional[Agent]` + - `url: str` - The agent that produced this item. + The URL of the web resource. - - `agent_name: str` + - `class AnnotationContainerFileCitation: …` - The canonical name of the agent that produced this item. + A citation for a container file used to generate a model response. - - `created_by: Optional[str]` + - `container_id: str` - The identifier of the actor that created the item. + The ID of the container file. - - `class ImageGenerationCall: …` + - `end_index: int` - An image generation request made by the model. + The index of the last character of the container file citation in the message. - - `id: str` + - `file_id: str` - The unique ID of the image generation call. + The ID of the file. - - `result: Optional[str]` + - `filename: str` - The generated image encoded in base64. + The filename of the container file cited. - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `start_index: int` - The status of the image generation call. + The index of the first character of the container file citation in the message. - - `"in_progress"` + - `type: Literal["container_file_citation"]` - - `"completed"` + The type of the container file citation. Always `container_file_citation`. - - `"generating"` + - `"container_file_citation"` - - `"failed"` + - `class AnnotationFilePath: …` - - `type: Literal["image_generation_call"]` + A path to a file. - The type of the image generation call. Always `image_generation_call`. + - `file_id: str` - - `"image_generation_call"` + The ID of the file. - - `agent: Optional[ImageGenerationCallAgent]` + - `index: int` - The agent that produced this item. + The index of the file in the list of files. - - `agent_name: str` + - `type: Literal["file_path"]` - The canonical name of the agent that produced this item. + The type of the file path. Always `file_path`. - - `class BetaResponseCodeInterpreterToolCall: …` + - `"file_path"` - A tool call to run code. + - `text: str` - - `class LocalShellCall: …` + The text output from the model. - A tool call to run a command on the local shell. + - `type: Literal["output_text"]` - - `id: str` + The type of the output text. Always `output_text`. - The unique ID of the local shell call. + - `"output_text"` - - `action: LocalShellCallAction` + - `logprobs: Optional[List[Logprob]]` - Execute a shell command on the server. + - `token: str` - - `command: List[str]` + - `bytes: List[int]` - The command to run. + - `logprob: float` - - `env: Dict[str, str]` + - `top_logprobs: List[LogprobTopLogprob]` - Environment variables to set for the command. + - `token: str` - - `type: Literal["exec"]` + - `bytes: List[int]` - The type of the local shell action. Always `exec`. + - `logprob: float` - - `"exec"` + - `class BetaResponseOutputRefusal: …` - - `timeout_ms: Optional[int]` + A refusal from the model. - Optional timeout in milliseconds for the command. + - `refusal: str` - - `user: Optional[str]` + The refusal explanation from the model. - Optional user to run the command as. + - `type: Literal["refusal"]` - - `working_directory: Optional[str]` + The type of the refusal. Always `refusal`. - Optional working directory to run the command in. + - `"refusal"` - - `call_id: str` + - `role: Literal["assistant"]` - The unique ID of the local shell tool call generated by the model. + The role of the output message. Always `assistant`. + + - `"assistant"` - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the local shell call. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"in_progress"` @@ -124869,13 +135821,13 @@ print(compacted_response) - `"incomplete"` - - `type: Literal["local_shell_call"]` + - `type: Literal["message"]` - The type of the local shell call. Always `local_shell_call`. + The type of the output message. Always `message`. - - `"local_shell_call"` + - `"message"` - - `agent: Optional[LocalShellCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -124883,25 +135835,51 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCallOutput: …` + - `phase: Optional[Literal["commentary", "final_answer"]]` - The output of a local shell tool call. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `class BetaResponseFileSearchToolCall: …` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: str` - The unique ID of the local shell tool call generated by the model. + The unique ID of the file search tool call. - - `output: str` + - `queries: List[str]` - A JSON string of the output of the local shell tool call. + The queries used to search for files. - - `type: Literal["local_shell_call_output"]` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - The type of the local shell tool call output. Always `local_shell_call_output`. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"local_shell_call_output"` + - `"in_progress"` - - `agent: Optional[LocalShellCallOutputAgent]` + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: Literal["file_search_call"]` + + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` + + - `agent: Optional[Agent]` The agent that produced this item. @@ -124909,71 +135887,73 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` + - `results: Optional[List[Result]]` - - `"completed"` + The results of the file search tool call. - - `"incomplete"` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - - `class BetaResponseFunctionShellToolCall: …` + 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, booleans, or numbers. - A tool call that executes one or more shell commands in a managed environment. + - `str` - - `id: str` + - `float` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `bool` - - `action: Action` + - `file_id: Optional[str]` - The shell commands and limits that describe how to run the tool call. + The unique ID of the file. - - `commands: List[str]` + - `filename: Optional[str]` - - `max_output_length: Optional[int]` + The name of the file. - Optional maximum number of characters to return from each command. + - `score: Optional[float]` - - `timeout_ms: Optional[int]` + The relevance score of the file - a value between 0 and 1. - Optional timeout in milliseconds for the commands. + - `text: Optional[str]` - - `call_id: str` + The text that was retrieved from the file. - The unique ID of the shell tool call generated by the model. + - `class BetaResponseComputerToolCall: …` - - `environment: Optional[Environment]` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - Represents the use of a local environment to perform shell actions. + - `id: str` - - `class BetaResponseLocalEnvironment: …` + The unique ID of the computer call. - Represents the use of a local environment to perform shell actions. + - `call_id: str` - - `type: Literal["local"]` + An identifier used when responding to the tool call with output. - The environment type. Always `local`. + - `pending_safety_checks: List[PendingSafetyCheck]` - - `"local"` + The pending safety checks for the computer call. - - `class BetaResponseContainerReference: …` + - `id: str` - Represents a container created with /v1/containers. + The ID of the pending safety check. - - `container_id: str` + - `code: Optional[str]` - - `type: Literal["container_reference"]` + The type of the pending safety check. - The environment type. Always `container_reference`. + - `message: Optional[str]` - - `"container_reference"` + Details about the pending safety check. - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -124981,231 +135961,247 @@ print(compacted_response) - `"incomplete"` - - `type: Literal["shell_call"]` + - `type: Literal["computer_call"]` - The type of the item. Always `shell_call`. + The type of the computer call. Always `computer_call`. - - `"shell_call"` + - `"computer_call"` - - `agent: Optional[Agent]` + - `action: Optional[BetaComputerAction]` - The agent that produced this item. + A click action. - - `agent_name: str` + - `class Click: …` - The canonical name of the agent that produced this item. + A click action. - - `caller: Optional[Caller]` + - `button: Literal["left", "right", "wheel", 2 more]` - The execution context that produced this tool call. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `class CallerDirect: …` + - `"left"` - - `type: Literal["direct"]` + - `"right"` - - `"direct"` + - `"wheel"` - - `class CallerProgram: …` + - `"back"` - - `caller_id: str` + - `"forward"` - The call ID of the program item that produced this tool call. + - `type: Literal["click"]` - - `type: Literal["program"]` + Specifies the event type. For a click action, this property is always `click`. - - `"program"` + - `"click"` - - `created_by: Optional[str]` + - `x: int` - The ID of the entity that created this tool call. + The x-coordinate where the click occurred. - - `class BetaResponseFunctionShellToolCallOutput: …` + - `y: int` - The output of a shell tool call that was emitted. + The y-coordinate where the click occurred. - - `id: str` + - `keys: Optional[List[str]]` - The unique ID of the shell call output. Populated when this item is returned via API. + The keys being held while clicking. - - `call_id: str` + - `class DoubleClick: …` - The unique ID of the shell tool call generated by the model. + A double click action. - - `max_output_length: Optional[int]` + - `keys: Optional[List[str]]` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The keys being held while double-clicking. - - `output: List[Output]` + - `type: Literal["double_click"]` - An array of shell call output contents + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `outcome: OutputOutcome` + - `"double_click"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `x: int` - - `class OutputOutcomeTimeout: …` + The x-coordinate where the double click occurred. - Indicates that the shell call exceeded its configured time limit. + - `y: int` - - `type: Literal["timeout"]` + The y-coordinate where the double click occurred. - The outcome type. Always `timeout`. + - `class Drag: …` - - `"timeout"` + A drag action. - - `class OutputOutcomeExit: …` + - `path: List[DragPath]` - Indicates that the shell commands finished and returned an exit code. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `exit_code: int` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - Exit code from the shell process. + - `x: int` - - `type: Literal["exit"]` + The x-coordinate. - The outcome type. Always `exit`. + - `y: int` - - `"exit"` + The y-coordinate. - - `stderr: str` + - `type: Literal["drag"]` - The standard error output that was captured. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `stdout: str` + - `"drag"` - The standard output that was captured. + - `keys: Optional[List[str]]` - - `created_by: Optional[str]` + The keys being held while dragging the mouse. - The identifier of the actor that created the item. + - `class Keypress: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + A collection of keypresses the model would like to perform. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `keys: List[str]` - - `"in_progress"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"completed"` + - `type: Literal["keypress"]` - - `"incomplete"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `type: Literal["shell_call_output"]` + - `"keypress"` - The type of the shell call output. Always `shell_call_output`. + - `class Move: …` - - `"shell_call_output"` + A mouse move action. - - `agent: Optional[Agent]` + - `type: Literal["move"]` - The agent that produced this item. + Specifies the event type. For a move action, this property is always set to `move`. - - `agent_name: str` + - `"move"` - The canonical name of the agent that produced this item. + - `x: int` - - `caller: Optional[Caller]` + The x-coordinate to move to. - The execution context that produced this tool call. + - `y: int` - - `class CallerDirect: …` + The y-coordinate to move to. - - `type: Literal["direct"]` + - `keys: Optional[List[str]]` - - `"direct"` + The keys being held while moving the mouse. - - `class CallerProgram: …` + - `class Screenshot: …` - - `caller_id: str` + A screenshot action. - The call ID of the program item that produced this tool call. + - `type: Literal["screenshot"]` - - `type: Literal["program"]` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"program"` + - `"screenshot"` - - `created_by: Optional[str]` + - `class Scroll: …` - The identifier of the actor that created the item. + A scroll action. - - `class BetaResponseApplyPatchToolCall: …` + - `scroll_x: int` - A tool call that applies file diffs by creating, deleting, or updating files. + The horizontal scroll distance. - - `id: str` + - `scroll_y: int` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The vertical scroll distance. - - `call_id: str` + - `type: Literal["scroll"]` - The unique ID of the apply patch tool call generated by the model. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `operation: Operation` + - `"scroll"` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `x: int` - - `class OperationCreateFile: …` + The x-coordinate where the scroll occurred. - Instruction describing how to create a file via the apply_patch tool. + - `y: int` - - `diff: str` + The y-coordinate where the scroll occurred. - Diff to apply. + - `keys: Optional[List[str]]` - - `path: str` + The keys being held while scrolling. - Path of the file to create. + - `class Type: …` - - `type: Literal["create_file"]` + An action to type in text. - Create a new file with the provided diff. + - `text: str` - - `"create_file"` + The text to type. - - `class OperationDeleteFile: …` + - `type: Literal["type"]` - Instruction describing how to delete a file via the apply_patch tool. + Specifies the event type. For a type action, this property is always set to `type`. - - `path: str` + - `"type"` - Path of the file to delete. + - `class Wait: …` - - `type: Literal["delete_file"]` + A wait action. - Delete the specified file. + - `type: Literal["wait"]` - - `"delete_file"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `class OperationUpdateFile: …` + - `"wait"` - Instruction describing how to update a file via the apply_patch tool. + - `actions: Optional[BetaComputerActionList]` - - `diff: str` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - Diff to apply. + - `class Click: …` - - `path: str` + A click action. - Path of the file to update. + - `class DoubleClick: …` - - `type: Literal["update_file"]` + A double click action. - Update an existing file with the provided diff. + - `class Drag: …` - - `"update_file"` + A drag action. - - `status: Literal["in_progress", "completed"]` + - `class Keypress: …` - The status of the apply patch tool call. One of `in_progress` or `completed`. + A collection of keypresses the model would like to perform. - - `"in_progress"` + - `class Move: …` - - `"completed"` + A mouse move action. - - `type: Literal["apply_patch_call"]` + - `class Screenshot: …` - The type of the item. Always `apply_patch_call`. + A screenshot action. - - `"apply_patch_call"` + - `class Scroll: …` + + A scroll action. + + - `class Type: …` + + An action to type in text. + + - `class Wait: …` + + A wait action. - `agent: Optional[Agent]` @@ -125215,57 +136211,60 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `class ComputerCallOutput: …` - The execution context that produced this tool call. + The output of a computer tool call. - - `class CallerDirect: …` + - `call_id: str` - - `type: Literal["direct"]` + The ID of the computer tool call that produced the output. - - `"direct"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `class CallerProgram: …` + A computer screenshot image used with the computer use tool. - - `caller_id: str` + - `type: Literal["computer_screenshot"]` - The call ID of the program item that produced this tool call. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `type: Literal["program"]` + - `"computer_screenshot"` - - `"program"` + - `file_id: Optional[str]` - - `created_by: Optional[str]` + The identifier of an uploaded file that contains the screenshot. - The ID of the entity that created this tool call. + - `image_url: Optional[str]` - - `class BetaResponseApplyPatchToolCallOutput: …` + The URL of the screenshot image. - The output emitted by an apply patch tool call. + - `type: Literal["computer_call_output"]` - - `id: str` + The type of the computer tool call output. Always `computer_call_output`. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"computer_call_output"` - - `call_id: str` + - `id: Optional[str]` - The unique ID of the apply patch tool call generated by the model. + The ID of the computer tool call output. - - `status: Literal["completed", "failed"]` + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - The status of the apply patch tool call output. One of `completed` or `failed`. + The safety checks reported by the API that have been acknowledged by the developer. - - `"completed"` + - `id: str` - - `"failed"` + The ID of the pending safety check. - - `type: Literal["apply_patch_call_output"]` + - `code: Optional[str]` - The type of the item. Always `apply_patch_call_output`. + The type of the pending safety check. - - `"apply_patch_call_output"` + - `message: Optional[str]` - - `agent: Optional[Agent]` + Details about the pending safety check. + + - `agent: Optional[ComputerCallOutputAgent]` The agent that produced this item. @@ -125273,134 +136272,113 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` - - - `type: Literal["direct"]` - - - `"direct"` - - - `class CallerProgram: …` - - - `caller_id: str` - - The call ID of the program item that produced this tool call. - - - `type: Literal["program"]` - - - `"program"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `created_by: Optional[str]` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The ID of the entity that created this tool call output. + - `"in_progress"` - - `output: Optional[str]` + - `"completed"` - Optional textual output returned by the apply patch tool. + - `"incomplete"` - - `class McpCall: …` + - `class BetaResponseFunctionWebSearch: …` - An invocation of a tool on an MCP server. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: str` - The unique ID of the tool call. - - - `arguments: str` - - A JSON string of the arguments passed to the tool. + The unique ID of the web search tool call. - - `name: str` + - `action: Action` - The name of the tool that was run. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `server_label: str` + - `class ActionSearch: …` - The label of the MCP server running the tool. + Action type "search" - Performs a web search query. - - `type: Literal["mcp_call"]` + - `type: Literal["search"]` - The type of the item. Always `mcp_call`. + The action type. - - `"mcp_call"` + - `"search"` - - `agent: Optional[McpCallAgent]` + - `queries: Optional[List[str]]` - The agent that produced this item. + The search queries. - - `agent_name: str` + - `query: Optional[str]` - The canonical name of the agent that produced this item. + The search query. - - `approval_request_id: Optional[str]` + - `sources: Optional[List[ActionSearchSource]]` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + The sources used in the search. - - `error: Optional[str]` + - `type: Literal["url"]` - The error from the tool call, if any. + The type of source. Always `url`. - - `output: Optional[str]` + - `"url"` - The output from the tool call. + - `url: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + The URL of the source. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `class ActionOpenPage: …` - - `"in_progress"` + Action type "open_page" - Opens a specific URL from search results. - - `"completed"` + - `type: Literal["open_page"]` - - `"incomplete"` + The action type. - - `"calling"` + - `"open_page"` - - `"failed"` + - `url: Optional[str]` - - `class McpListTools: …` + The URL opened by the model. - A list of tools available on an MCP server. + - `class ActionFindInPage: …` - - `id: str` + Action type "find_in_page": Searches for a pattern within a loaded page. - The unique ID of the list. + - `pattern: str` - - `server_label: str` + The pattern or text to search for within the page. - The label of the MCP server. + - `type: Literal["find_in_page"]` - - `tools: List[McpListToolsTool]` + The action type. - The tools available on the server. + - `"find_in_page"` - - `input_schema: object` + - `url: str` - The JSON schema describing the tool's input. + The URL of the page searched for the pattern. - - `name: str` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - The name of the tool. + The status of the web search tool call. - - `annotations: Optional[object]` + - `"in_progress"` - Additional annotations about the tool. + - `"searching"` - - `description: Optional[str]` + - `"completed"` - The description of the tool. + - `"failed"` - - `type: Literal["mcp_list_tools"]` + - `type: Literal["web_search_call"]` - The type of the item. Always `mcp_list_tools`. + The type of the web search tool call. Always `web_search_call`. - - `"mcp_list_tools"` + - `"web_search_call"` - - `agent: Optional[McpListToolsAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -125408,37 +136386,34 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `error: Optional[str]` - - Error message if the server could not list tools. - - - `class McpApprovalRequest: …` + - `class BetaResponseFunctionToolCall: …` - A request for human approval of a tool invocation. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `id: str` + - `arguments: str` - The unique ID of the approval request. + A JSON string of the arguments to pass to the function. - - `arguments: str` + - `call_id: str` - A JSON string of arguments for the tool. + The unique ID of the function tool call generated by the model. - `name: str` - The name of the tool to run. + The name of the function to run. - - `server_label: str` + - `type: Literal["function_call"]` - The label of the MCP server making the request. + The type of the function tool call. Always `function_call`. - - `type: Literal["mcp_approval_request"]` + - `"function_call"` - The type of the item. Always `mcp_approval_request`. + - `id: Optional[str]` - - `"mcp_approval_request"` + The unique ID of the function tool call. - - `agent: Optional[McpApprovalRequestAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -125446,1853 +136421,1792 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class McpApprovalResponse: …` - - A response to an MCP approval request. - - - `id: str` - - The unique ID of the approval response + - `caller: Optional[Caller]` - - `approval_request_id: str` + The execution context that produced this tool call. - The ID of the approval request being answered. + - `class CallerDirect: …` - - `approve: bool` + - `type: Literal["direct"]` - Whether the request was approved. + - `"direct"` - - `type: Literal["mcp_approval_response"]` + - `class CallerProgram: …` - The type of the item. Always `mcp_approval_response`. + - `caller_id: str` - - `"mcp_approval_response"` + The call ID of the program item that produced this tool call. - - `agent: Optional[McpApprovalResponseAgent]` + - `type: Literal["program"]` - The agent that produced this item. + - `"program"` - - `agent_name: str` + - `namespace: Optional[str]` - The canonical name of the agent that produced this item. + The namespace of the function to run. - - `reason: Optional[str]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Optional reason for the decision. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class BetaResponseCustomToolCall: …` + - `"in_progress"` - A call to a custom tool created by the model. + - `"completed"` - - `class BetaResponseCustomToolCallOutputItem: …` + - `"incomplete"` - The output of a custom tool call from your code, being sent back to the model. + - `class FunctionCallOutput: …` - - `id: str` + The output of a function tool call. - The unique ID of the custom tool call output item. + - `call_id: str` - - `status: Literal["in_progress", "completed", "incomplete"]` + The unique ID of the function tool call generated by the model. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - - `"in_progress"` + Text, image, or file output of the function tool call. - - `"completed"` + - `str` - - `"incomplete"` + A JSON string of the output of the function tool call. - - `created_by: Optional[str]` + - `List[BetaResponseFunctionCallOutputItem]` - The identifier of the actor that created the item. + - `class BetaResponseInputTextContent: …` - - `parallel_tool_calls: bool` + A text input to the model. - Whether to allow the model to run tool calls in parallel. + - `text: str` - - `temperature: Optional[float]` + The text input to the model. - 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. - We generally recommend altering this or `top_p` but not both. + - `type: Literal["input_text"]` - - `tool_choice: ToolChoice` + The type of the input item. Always `input_text`. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `"input_text"` - - `Literal["none", "auto", "required"]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"none"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"auto"` + - `mode: Literal["explicit"]` - - `"required"` + The breakpoint mode. Always `explicit`. - - `class BetaToolChoiceAllowed: …` + - `"explicit"` - Constrains the tools available to the model to a pre-defined set. + - `class BetaResponseInputImageContent: …` - - `mode: Literal["auto", "required"]` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - Constrains the tools available to the model to a pre-defined set. + - `type: Literal["input_image"]` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The type of the input item. Always `input_image`. - `required` requires the model to call one or more of the allowed tools. + - `"input_image"` - - `"auto"` + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - - `"required"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `tools: List[Dict[str, object]]` + - `"low"` - A list of tool definitions that the model should be allowed to call. + - `"high"` - For the Responses API, the list of tool definitions might look like: + - `"auto"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `"original"` - - `type: Literal["allowed_tools"]` + - `file_id: Optional[str]` - Allowed tool configuration type. Always `allowed_tools`. + The ID of the file to be sent to the model. - - `"allowed_tools"` + - `image_url: Optional[str]` - - `class BetaToolChoiceTypes: …` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `mode: Literal["explicit"]` - Allowed values are: + The breakpoint mode. Always `explicit`. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"explicit"` - - `"file_search"` + - `class BetaResponseInputFileContent: …` - - `"web_search_preview"` + A file input to the model. - - `"computer"` + - `type: Literal["input_file"]` - - `"computer_use_preview"` + The type of the input item. Always `input_file`. - - `"computer_use"` + - `"input_file"` - - `"web_search_preview_2025_03_11"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"image_generation"` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `"code_interpreter"` + - `"auto"` - - `class BetaToolChoiceFunction: …` + - `"low"` - Use this option to force the model to call a specific function. + - `"high"` - - `name: str` + - `file_data: Optional[str]` - The name of the function to call. + The base64-encoded data of the file to be sent to the model. - - `type: Literal["function"]` + - `file_id: Optional[str]` - For function calling, the type is always `function`. + The ID of the file to be sent to the model. - - `"function"` + - `file_url: Optional[str]` - - `class BetaToolChoiceMcp: …` + The URL of the file to be sent to the model. - Use this option to force the model to call a specific tool on a remote MCP server. + - `filename: Optional[str]` - - `server_label: str` + The name of the file to be sent to the model. - The label of the MCP server to use. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `type: Literal["mcp"]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - For MCP tools, the type is always `mcp`. + - `mode: Literal["explicit"]` - - `"mcp"` + The breakpoint mode. Always `explicit`. - - `name: Optional[str]` + - `"explicit"` - The name of the tool to call on the server. + - `type: Literal["function_call_output"]` - - `class BetaToolChoiceCustom: …` + The type of the function tool call output. Always `function_call_output`. - Use this option to force the model to call a specific custom tool. + - `"function_call_output"` - - `name: str` + - `id: Optional[str]` - The name of the custom tool to call. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `type: Literal["custom"]` + - `agent: Optional[FunctionCallOutputAgent]` - For custom tool calling, the type is always `custom`. + The agent that produced this item. - - `"custom"` + - `agent_name: str` - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + The canonical name of the agent that produced this item. - - `type: Literal["programmatic_tool_calling"]` + - `caller: Optional[FunctionCallOutputCaller]` - The tool to call. Always `programmatic_tool_calling`. + The execution context that produced this tool call. - - `"programmatic_tool_calling"` + - `class FunctionCallOutputCallerDirect: …` - - `class BetaToolChoiceApplyPatch: …` + - `type: Literal["direct"]` - Forces the model to call the apply_patch tool when executing a tool call. + The caller type. Always `direct`. - - `type: Literal["apply_patch"]` + - `"direct"` - The tool to call. Always `apply_patch`. + - `class FunctionCallOutputCallerProgram: …` - - `"apply_patch"` + - `caller_id: str` - - `class BetaToolChoiceShell: …` + The call ID of the program item that produced this tool call. - Forces the model to call the shell tool when a tool call is required. + - `type: Literal["program"]` - - `type: Literal["shell"]` + The caller type. Always `program`. - The tool to call. Always `shell`. + - `"program"` - - `"shell"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `tools: List[BetaTool]` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `"in_progress"` - We support the following categories of tools: + - `"completed"` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `"incomplete"` - - `class BetaFunctionTool: …` + - `class AgentMessage: …` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + A message routed between agents. - - `class BetaFileSearchTool: …` + - `author: str` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The sending agent identity. - - `class BetaComputerTool: …` + - `content: List[AgentMessageContent]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Plaintext, image, or encrypted content sent between agents. - - `class BetaComputerUsePreviewTool: …` + - `class BetaResponseInputTextContent: …` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A text input to the model. - - `class BetaWebSearchTool: …` + - `class BetaResponseInputImageContent: …` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `class Mcp: …` + - `class AgentMessageContentEncryptedContent: …` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `class CodeInterpreter: …` + - `encrypted_content: str` - A tool that runs Python code to help generate a response to a prompt. + Opaque encrypted content. - - `class ProgrammaticToolCalling: …` + - `type: Literal["encrypted_content"]` - - `class ImageGeneration: …` + The type of the input item. Always `encrypted_content`. - A tool that generates images using the GPT image models. + - `"encrypted_content"` - - `class LocalShell: …` + - `recipient: str` - A tool that allows the model to execute shell commands in a local environment. + The destination agent identity. - - `class BetaFunctionShellTool: …` + - `type: Literal["agent_message"]` - A tool that allows the model to execute shell commands. + The item type. Always `agent_message`. - - `class BetaCustomTool: …` + - `"agent_message"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `id: Optional[str]` - - `class BetaNamespaceTool: …` + The unique ID of this agent message item. - Groups function/custom tools under a shared namespace. + - `agent: Optional[AgentMessageAgent]` - - `class BetaToolSearchTool: …` + The agent that produced this item. - Hosted or BYOT tool search configuration for deferred tools. + - `agent_name: str` - - `class BetaWebSearchPreviewTool: …` + The canonical name of the agent that produced this item. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class MultiAgentCall: …` - - `class BetaApplyPatchTool: …` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - Allows the assistant to create, delete, or update files using unified diffs. + The multi-agent action that was executed. - - `top_p: Optional[float]` + - `"spawn_agent"` - 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. + - `"interrupt_agent"` - We generally recommend altering this or `temperature` but not both. + - `"list_agents"` - - `background: Optional[bool]` + - `"send_message"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `"followup_task"` - - `completed_at: Optional[float]` + - `"wait_agent"` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `arguments: str` - - `conversation: Optional[Conversation]` + The action arguments as a JSON string. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `call_id: str` - - `id: str` + The unique ID linking this call to its output. - The unique ID of the conversation that this response was associated with. + - `type: Literal["multi_agent_call"]` - - `max_output_tokens: Optional[int]` + The item type. Always `multi_agent_call`. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `"multi_agent_call"` - - `max_tool_calls: Optional[int]` + - `id: Optional[str]` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + The unique ID of this multi-agent call. - - `moderation: Optional[Moderation]` + - `agent: Optional[MultiAgentCallAgent]` - Moderation results for the response input and output, if moderated completions were requested. + The agent that produced this item. - - `input: ModerationInput` + - `agent_name: str` - Moderation for the response input. + The canonical name of the agent that produced this item. - - `class ModerationInputModerationResult: …` + - `class MultiAgentCallOutput: …` - A moderation result produced for the response input or output. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `categories: Dict[str, bool]` + The multi-agent action that produced this result. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"spawn_agent"` - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `"interrupt_agent"` - Which modalities of input are reflected by the score for each category. + - `"list_agents"` - - `"text"` + - `"send_message"` - - `"image"` + - `"followup_task"` - - `category_scores: Dict[str, float]` + - `"wait_agent"` - A dictionary of moderation categories to scores. + - `call_id: str` - - `flagged: bool` + The unique ID of the multi-agent call. - A boolean indicating whether the content was flagged by any category. + - `output: List[MultiAgentCallOutputOutput]` - - `model: str` + Text output returned by the multi-agent action. - The moderation model that produced this result. + - `text: str` - - `type: Literal["moderation_result"]` + The text content. - The object type, which was always `moderation_result` for successful moderation results. + - `type: Literal["output_text"]` - - `"moderation_result"` + The content type. Always `output_text`. - - `class ModerationInputError: …` + - `"output_text"` - An error produced while attempting moderation for the response input or output. + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - - `code: str` + Citations associated with the text content. - The error code. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - - `message: str` + - `file_id: str` - The error message. + The ID of the file. - - `type: Literal["error"]` + - `filename: str` - The object type, which was always `error` for moderation failures. + The filename of the file cited. - - `"error"` + - `index: int` - - `output: ModerationOutput` + The index of the file in the list of files. - Moderation for the response output. + - `type: Literal["file_citation"]` - - `class ModerationOutputModerationResult: …` + The citation type. Always `file_citation`. - A moderation result produced for the response input or output. + - `"file_citation"` - - `categories: Dict[str, bool]` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `end_index: int` - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + The index of the last character of the citation in the message. - Which modalities of input are reflected by the score for each category. + - `start_index: int` - - `"text"` + The index of the first character of the citation in the message. - - `"image"` + - `title: str` - - `category_scores: Dict[str, float]` + The title of the cited resource. - A dictionary of moderation categories to scores. + - `type: Literal["url_citation"]` - - `flagged: bool` + The citation type. Always `url_citation`. - A boolean indicating whether the content was flagged by any category. + - `"url_citation"` - - `model: str` + - `url: str` - The moderation model that produced this result. + The URL of the cited resource. - - `type: Literal["moderation_result"]` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` - The object type, which was always `moderation_result` for successful moderation results. + - `container_id: str` - - `"moderation_result"` + The ID of the container. - - `class ModerationOutputError: …` + - `end_index: int` - An error produced while attempting moderation for the response input or output. + The index of the last character of the citation in the message. - - `code: str` + - `file_id: str` - The error code. + The ID of the container file. - - `message: str` + - `filename: str` - The error message. + The filename of the container file cited. - - `type: Literal["error"]` + - `start_index: int` - The object type, which was always `error` for moderation failures. + The index of the first character of the citation in the message. - - `"error"` + - `type: Literal["container_file_citation"]` - - `previous_response_id: Optional[str]` + The citation type. Always `container_file_citation`. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `"container_file_citation"` - - `prompt: Optional[BetaResponsePrompt]` + - `type: Literal["multi_agent_call_output"]` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The item type. Always `multi_agent_call_output`. - - `id: str` + - `"multi_agent_call_output"` - The unique identifier of the prompt template to use. + - `id: Optional[str]` - - `variables: Optional[Dict[str, Variables]]` + The unique ID of this multi-agent call output. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `agent: Optional[MultiAgentCallOutputAgent]` - - `str` + The agent that produced this item. - - `class BetaResponseInputText: …` + - `agent_name: str` - A text input to the model. + The canonical name of the agent that produced this item. - - `class BetaResponseInputImage: …` + - `class ToolSearchCall: …` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `arguments: object` - - `class BetaResponseInputFile: …` + The arguments supplied to the tool search call. - A file input to the model. + - `type: Literal["tool_search_call"]` - - `version: Optional[str]` + The item type. Always `tool_search_call`. - Optional version of the prompt template. + - `"tool_search_call"` - - `prompt_cache_key: Optional[str]` + - `id: Optional[str]` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + The unique ID of this tool search call. - - `prompt_cache_options: Optional[PromptCacheOptions]` + - `agent: Optional[ToolSearchCallAgent]` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The agent that produced this item. - - `mode: Literal["implicit", "explicit"]` + - `agent_name: str` - Whether implicit prompt-cache breakpoints were enabled. + The canonical name of the agent that produced this item. - - `"implicit"` + - `call_id: Optional[str]` - - `"explicit"` + The unique ID of the tool search call generated by the model. - - `ttl: Literal["30m"]` + - `execution: Optional[Literal["server", "client"]]` - The minimum lifetime applied to each cache breakpoint. + Whether tool search was executed by the server or by the client. - - `"30m"` + - `"server"` - - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + - `"client"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + The status of the tool search call. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `"in_progress"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `"completed"` - - `"in_memory"` + - `"incomplete"` - - `"24h"` + - `class BetaResponseToolSearchOutputItemParam: …` - - `reasoning: Optional[Reasoning]` + - `tools: List[BetaTool]` - **gpt-5 and o-series models only** + The loaded tool definitions returned by the tool search output. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `class BetaFunctionTool: …` - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `name: str` - - `"auto"` + The name of the function to call. - - `"current_turn"` + - `parameters: Optional[Dict[str, object]]` - - `"all_turns"` + A JSON schema object describing the parameters of the function. - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + - `strict: Optional[bool]` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + Whether strict parameter validation is enforced for this function tool. - - `"none"` + - `type: Literal["function"]` - - `"minimal"` + The type of the function tool. Always `function`. - - `"low"` + - `"function"` - - `"medium"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"high"` + The tool invocation context(s). - - `"xhigh"` + - `"direct"` - - `"max"` + - `"programmatic"` - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + - `defer_loading: Optional[bool]` - **Deprecated:** use `summary` instead. + Whether this function is deferred and loaded via tool search. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `description: Optional[str]` - - `"auto"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"concise"` + - `output_schema: Optional[Dict[str, object]]` - - `"detailed"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + - `class BetaFileSearchTool: …` - Controls the reasoning execution mode for the request. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - When returned on a response, this is the effective execution mode. + - `type: Literal["file_search"]` - - `str` + The type of the file search tool. Always `file_search`. - - `Literal["standard", "pro"]` + - `"file_search"` - Controls the reasoning execution mode for the request. + - `vector_store_ids: List[str]` - When returned on a response, this is the effective execution mode. + The IDs of the vector stores to search. - - `"standard"` + - `filters: Optional[Filters]` - - `"pro"` + A filter to apply. - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + - `class FiltersComparisonFilter: …` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `key: str` - - `"auto"` + The key to compare against the value. - - `"concise"` + - `type: Literal["eq", "ne", "gt", 5 more]` - - `"detailed"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `safety_identifier: Optional[str]` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"eq"` - - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + - `"ne"` - Specifies the processing type used for serving the request. + - `"gt"` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `"gte"` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `"lt"` - - `"auto"` + - `"lte"` - - `"default"` + - `"in"` - - `"flex"` + - `"nin"` - - `"scale"` + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `"priority"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `status: Optional[BetaResponseStatus]` + - `str` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `float` - - `"completed"` + - `bool` - - `"failed"` + - `List[Union[str, float]]` - - `"in_progress"` + - `str` - - `"cancelled"` + - `float` - - `"queued"` + - `class FiltersCompoundFilter: …` - - `"incomplete"` + Combine multiple filters using `and` or `or`. - - `text: Optional[BetaResponseTextConfig]` + - `filters: List[FiltersCompoundFilterFilter]` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `class FiltersCompoundFilterFilterComparisonFilter: …` - - `format: Optional[BetaResponseFormatTextConfig]` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - An object specifying the format that the model must output. + - `key: str` - Configuring `{ "type": "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). + The key to compare against the value. - The default format is `{ "type": "text" }` with no additional options. + - `type: Literal["eq", "ne", "gt", 5 more]` - **Not recommended for gpt-4o and newer models:** + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `class Text: …` + - `"eq"` - Default response format. Used to generate text responses. + - `"ne"` - - `type: Literal["text"]` + - `"gt"` - The type of response format being defined. Always `text`. + - `"gte"` - - `"text"` + - `"lt"` - - `class BetaResponseFormatTextJSONSchemaConfig: …` + - `"lte"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"in"` - - `name: str` + - `"nin"` - 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. + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `schema: Dict[str, object]` + The value to compare against the attribute key; supports string, number, or boolean types. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `str` - - `type: Literal["json_schema"]` + - `float` - The type of response format being defined. Always `json_schema`. + - `bool` - - `"json_schema"` + - `List[Union[str, float]]` - - `description: Optional[str]` + - `str` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `float` - - `strict: Optional[bool]` + - `object` - 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["and", "or"]` - - `class JSONObject: …` + Type of operation: `and` or `or`. - 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. + - `"and"` - - `type: Literal["json_object"]` + - `"or"` - The type of response format being defined. Always `json_object`. + - `max_num_results: Optional[int]` - - `"json_object"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `verbosity: Optional[Literal["low", "medium", "high"]]` + - `ranking_options: Optional[RankingOptions]` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + Ranking options for search. - - `"low"` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - `"medium"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"high"` + - `embedding_weight: float` - - `top_logprobs: Optional[int]` + The weight of the embedding in the reciprocal ranking fusion. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `text_weight: float` - - `truncation: Optional[Literal["auto", "disabled"]]` + The weight of the text in the reciprocal ranking fusion. - The truncation strategy to use for the model response. + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + The ranker to use for the file search. - `"auto"` - - `"disabled"` + - `"default-2024-11-15"` - - `usage: Optional[BetaResponseUsage]` + - `score_threshold: Optional[float]` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `input_tokens: int` + - `class BetaComputerTool: …` - The number of input tokens. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `input_tokens_details: InputTokensDetails` + - `type: Literal["computer"]` - A detailed breakdown of the input tokens. + The type of the computer tool. Always `computer`. - - `cache_write_tokens: int` + - `"computer"` - The number of input tokens that were written to the cache. + - `class BetaComputerUsePreviewTool: …` - - `cached_tokens: int` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `display_height: int` - - `output_tokens: int` + The height of the computer display. - The number of output tokens. + - `display_width: int` - - `output_tokens_details: OutputTokensDetails` + The width of the computer display. - A detailed breakdown of the output tokens. + - `environment: Literal["windows", "mac", "linux", 2 more]` - - `reasoning_tokens: int` + The type of computer environment to control. - The number of reasoning tokens. + - `"windows"` - - `total_tokens: int` + - `"mac"` - The total number of tokens used. + - `"linux"` - - `user: Optional[str]` + - `"ubuntu"` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"browser"` - - `sequence_number: int` + - `type: Literal["computer_use_preview"]` - The sequence number for this event. + The type of the computer use tool. Always `computer_use_preview`. - - `type: Literal["response.queued"]` + - `"computer_use_preview"` - The type of the event. Always 'response.queued'. + - `class BetaWebSearchTool: …` - - `"response.queued"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `agent: Optional[Agent]` + - `type: Literal["web_search", "web_search_2025_08_26"]` - The agent that owns this multi-agent streaming event. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `agent_name: str` + - `"web_search"` - The canonical name of the agent that produced this item. + - `"web_search_2025_08_26"` -### Beta Response Reasoning Item + - `filters: Optional[Filters]` -- `class BetaResponseReasoningItem: …` + Filters for the search. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `allowed_domains: Optional[List[str]]` - - `id: str` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The unique identifier of the reasoning content. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `summary: List[Summary]` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - Reasoning summary content. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `text: str` + - `"low"` - A summary of the reasoning output from the model so far. + - `"medium"` - - `type: Literal["summary_text"]` + - `"high"` - The type of the object. Always `summary_text`. + - `user_location: Optional[UserLocation]` - - `"summary_text"` + The approximate location of the user. - - `type: Literal["reasoning"]` + - `city: Optional[str]` - The type of the object. Always `reasoning`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"reasoning"` + - `country: Optional[str]` - - `agent: Optional[Agent]` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The agent that produced this item. + - `region: Optional[str]` - - `agent_name: str` + Free text input for the region of the user, e.g. `California`. - The canonical name of the agent that produced this item. + - `timezone: Optional[str]` - - `content: Optional[List[Content]]` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Reasoning text content. + - `type: Optional[Literal["approximate"]]` - - `text: str` + The type of location approximation. Always `approximate`. - The reasoning text from the model. + - `"approximate"` - - `type: Literal["reasoning_text"]` + - `class Mcp: …` - The type of the reasoning text. Always `reasoning_text`. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `server_label: str` - - `"reasoning_text"` + A label for this MCP server, used to identify it in tool calls. - - `encrypted_content: Optional[str]` + - `type: Literal["mcp"]` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The type of the MCP tool. Always `mcp`. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"mcp"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"in_progress"` + The tool invocation context(s). - - `"completed"` + - `"direct"` - - `"incomplete"` + - `"programmatic"` -### Beta Response Reasoning Summary Part Added Event + - `allowed_tools: Optional[McpAllowedTools]` -- `class BetaResponseReasoningSummaryPartAddedEvent: …` + List of allowed tool names or a filter object. - Emitted when a new reasoning summary part is added. + - `List[str]` - - `item_id: str` + A string array of allowed tool names - The ID of the item this summary part is associated with. + - `class McpAllowedToolsMcpToolFilter: …` - - `output_index: int` + A filter object to specify which tools are allowed. - The index of the output item this summary part is associated with. + - `read_only: Optional[bool]` - - `part: Part` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The summary part that was added. + - `tool_names: Optional[List[str]]` - - `text: str` + List of allowed tool names. - The text of the summary part. + - `authorization: Optional[str]` - - `type: Literal["summary_text"]` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The type of the summary part. Always `summary_text`. + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `"summary_text"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `sequence_number: int` + Currently supported `connector_id` values are: - The sequence number of this event. + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `summary_index: int` + - `"connector_dropbox"` - The index of the summary part within the reasoning summary. + - `"connector_gmail"` - - `type: Literal["response.reasoning_summary_part.added"]` + - `"connector_googlecalendar"` - The type of the event. Always `response.reasoning_summary_part.added`. + - `"connector_googledrive"` - - `"response.reasoning_summary_part.added"` + - `"connector_microsoftteams"` - - `agent: Optional[Agent]` + - `"connector_outlookcalendar"` - The agent that owns this multi-agent streaming event. + - `"connector_outlookemail"` - - `agent_name: str` + - `"connector_sharepoint"` - The canonical name of the agent that produced this item. + - `defer_loading: Optional[bool]` -### Beta Response Reasoning Summary Part Done Event + Whether this MCP tool is deferred and discovered via tool search. -- `class BetaResponseReasoningSummaryPartDoneEvent: …` + - `headers: Optional[Dict[str, str]]` - Emitted when a reasoning summary part is completed. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `item_id: str` + - `require_approval: Optional[McpRequireApproval]` - The ID of the item this summary part is associated with. + Specify which of the MCP server's tools require approval. - - `output_index: int` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - The index of the output item this summary part is associated with. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `part: Part` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - The completed summary part. + A filter object to specify which tools are allowed. - - `text: str` + - `read_only: Optional[bool]` - The text of the summary part. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `type: Literal["summary_text"]` + - `tool_names: Optional[List[str]]` - The type of the summary part. Always `summary_text`. + List of allowed tool names. - - `"summary_text"` + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - - `sequence_number: int` + A filter object to specify which tools are allowed. - The sequence number of this event. + - `read_only: Optional[bool]` - - `summary_index: int` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The index of the summary part within the reasoning summary. + - `tool_names: Optional[List[str]]` - - `type: Literal["response.reasoning_summary_part.done"]` + List of allowed tool names. - The type of the event. Always `response.reasoning_summary_part.done`. + - `Literal["always", "never"]` - - `"response.reasoning_summary_part.done"` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `agent: Optional[Agent]` + - `"always"` - The agent that owns this multi-agent streaming event. + - `"never"` - - `agent_name: str` + - `server_description: Optional[str]` - The canonical name of the agent that produced this item. + Optional description of the MCP server, used to provide more context. - - `status: Optional[Literal["incomplete"]]` + - `server_url: Optional[str]` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"incomplete"` + - `tunnel_id: Optional[str]` -### Beta Response Reasoning Summary Text Delta Event + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. -- `class BetaResponseReasoningSummaryTextDeltaEvent: …` + - `class CodeInterpreter: …` - Emitted when a delta is added to a reasoning summary text. + A tool that runs Python code to help generate a response to a prompt. - - `delta: str` + - `container: CodeInterpreterContainer` - The text delta that was added to the summary. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `item_id: str` + - `str` - The ID of the item this summary text delta is associated with. + The container ID. - - `output_index: int` + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - The index of the output item this summary text delta is associated with. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `sequence_number: int` + - `type: Literal["auto"]` - The sequence number of this event. + Always `auto`. - - `summary_index: int` + - `"auto"` - The index of the summary part within the reasoning summary. + - `file_ids: Optional[List[str]]` - - `type: Literal["response.reasoning_summary_text.delta"]` + An optional list of uploaded files to make available to your code. - The type of the event. Always `response.reasoning_summary_text.delta`. + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `"response.reasoning_summary_text.delta"` + The memory limit for the code interpreter container. - - `agent: Optional[Agent]` + - `"1g"` - The agent that owns this multi-agent streaming event. + - `"4g"` - - `agent_name: str` + - `"16g"` - The canonical name of the agent that produced this item. + - `"64g"` -### Beta Response Reasoning Summary Text Done Event + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` -- `class BetaResponseReasoningSummaryTextDoneEvent: …` + Network access policy for the container. - Emitted when a reasoning summary text is completed. + - `class BetaContainerNetworkPolicyDisabled: …` - - `item_id: str` + - `type: Literal["disabled"]` - The ID of the item this summary text is associated with. + Disable outbound network access. Always `disabled`. - - `output_index: int` + - `"disabled"` - The index of the output item this summary text is associated with. + - `class BetaContainerNetworkPolicyAllowlist: …` - - `sequence_number: int` + - `allowed_domains: List[str]` - The sequence number of this event. + A list of allowed domains when type is `allowlist`. - - `summary_index: int` + - `type: Literal["allowlist"]` - The index of the summary part within the reasoning summary. + Allow outbound network access only to specified domains. Always `allowlist`. - - `text: str` + - `"allowlist"` - The full text of the completed reasoning summary. + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `type: Literal["response.reasoning_summary_text.done"]` + Optional domain-scoped secrets for allowlisted domains. - The type of the event. Always `response.reasoning_summary_text.done`. + - `domain: str` - - `"response.reasoning_summary_text.done"` + The domain associated with the secret. - - `agent: Optional[Agent]` + - `name: str` - The agent that owns this multi-agent streaming event. + The name of the secret to inject for the domain. - - `agent_name: str` + - `value: str` - The canonical name of the agent that produced this item. + The secret value to inject for the domain. -### Beta Response Reasoning Text Delta Event + - `type: Literal["code_interpreter"]` -- `class BetaResponseReasoningTextDeltaEvent: …` + The type of the code interpreter tool. Always `code_interpreter`. - Emitted when a delta is added to a reasoning text. + - `"code_interpreter"` - - `content_index: int` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The index of the reasoning content part this delta is associated with. + The tool invocation context(s). - - `delta: str` + - `"direct"` - The text delta that was added to the reasoning content. + - `"programmatic"` - - `item_id: str` + - `class ProgrammaticToolCalling: …` - The ID of the item this reasoning text delta is associated with. + - `type: Literal["programmatic_tool_calling"]` - - `output_index: int` + The type of the tool. Always `programmatic_tool_calling`. - The index of the output item this reasoning text delta is associated with. + - `"programmatic_tool_calling"` - - `sequence_number: int` + - `class ImageGeneration: …` - The sequence number of this event. + A tool that generates images using the GPT image models. - - `type: Literal["response.reasoning_text.delta"]` + - `type: Literal["image_generation"]` - The type of the event. Always `response.reasoning_text.delta`. + The type of the image generation tool. Always `image_generation`. - - `"response.reasoning_text.delta"` + - `"image_generation"` - - `agent: Optional[Agent]` + - `action: Optional[Literal["generate", "edit", "auto"]]` - The agent that owns this multi-agent streaming event. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `agent_name: str` + - `"generate"` - The canonical name of the agent that produced this item. + - `"edit"` -### Beta Response Reasoning Text Done Event + - `"auto"` -- `class BetaResponseReasoningTextDoneEvent: …` + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - Emitted when a reasoning text is completed. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `content_index: int` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - The index of the reasoning content part. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `item_id: str` + - `"transparent"` - The ID of the item this reasoning text is associated with. + - `"opaque"` - - `output_index: int` + - `"auto"` - The index of the output item this reasoning text is associated with. + - `input_fidelity: Optional[Literal["high", "low"]]` - - `sequence_number: int` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The sequence number of this event. + - `"high"` - - `text: str` + - `"low"` - The full text of the completed reasoning content. + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - - `type: Literal["response.reasoning_text.done"]` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The type of the event. Always `response.reasoning_text.done`. + - `file_id: Optional[str]` - - `"response.reasoning_text.done"` + File ID for the mask image. - - `agent: Optional[Agent]` + - `image_url: Optional[str]` - The agent that owns this multi-agent streaming event. + Base64-encoded mask image. - - `agent_name: str` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - The canonical name of the agent that produced this item. + The image generation model to use. Default: `gpt-image-1`. -### Beta Response Refusal Delta Event + - `str` -- `class BetaResponseRefusalDeltaEvent: …` + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - Emitted when there is a partial refusal text. + The image generation model to use. Default: `gpt-image-1`. - - `content_index: int` + - `"gpt-image-1"` - The index of the content part that the refusal text is added to. + - `"gpt-image-1-mini"` - - `delta: str` + - `"gpt-image-2"` - The refusal text that is added. + - `"gpt-image-2-2026-04-21"` - - `item_id: str` + - `"gpt-image-1.5"` - The ID of the output item that the refusal text is added to. + - `"chatgpt-image-latest"` - - `output_index: int` + - `moderation: Optional[Literal["auto", "low"]]` - The index of the output item that the refusal text is added to. + Moderation level for the generated image. Default: `auto`. - - `sequence_number: int` + - `"auto"` - The sequence number of this event. + - `"low"` - - `type: Literal["response.refusal.delta"]` + - `output_compression: Optional[int]` - The type of the event. Always `response.refusal.delta`. + Compression level for the output image. Default: 100. - - `"response.refusal.delta"` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `agent: Optional[Agent]` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The agent that owns this multi-agent streaming event. + - `"png"` - - `agent_name: str` + - `"webp"` - The canonical name of the agent that produced this item. + - `"jpeg"` -### Beta Response Refusal Done Event + - `partial_images: Optional[int]` -- `class BetaResponseRefusalDoneEvent: …` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - Emitted when refusal text is finalized. + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - - `content_index: int` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The index of the content part that the refusal text is finalized. + - `"low"` - - `item_id: str` + - `"medium"` - The ID of the output item that the refusal text is finalized. + - `"high"` - - `output_index: int` + - `"auto"` - The index of the output item that the refusal text is finalized. + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - - `refusal: str` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The refusal text that is finalized. + - `str` - - `sequence_number: int` + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - The sequence number of this event. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `type: Literal["response.refusal.done"]` + - `"1024x1024"` - The type of the event. Always `response.refusal.done`. + - `"1024x1536"` - - `"response.refusal.done"` + - `"1536x1024"` - - `agent: Optional[Agent]` + - `"auto"` - The agent that owns this multi-agent streaming event. + - `class LocalShell: …` - - `agent_name: str` + A tool that allows the model to execute shell commands in a local environment. - The canonical name of the agent that produced this item. + - `type: Literal["local_shell"]` -### Beta Response Status + The type of the local shell tool. Always `local_shell`. -- `Literal["completed", "failed", "in_progress", 3 more]` + - `"local_shell"` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `class BetaFunctionShellTool: …` - - `"completed"` + A tool that allows the model to execute shell commands. - - `"failed"` + - `type: Literal["shell"]` - - `"in_progress"` + The type of the shell tool. Always `shell`. - - `"cancelled"` + - `"shell"` - - `"queued"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"incomplete"` + The tool invocation context(s). -### Beta Response Stream Event + - `"direct"` -- `BetaResponseStreamEvent` + - `"programmatic"` - Emitted when there is a partial audio response. + - `environment: Optional[Environment]` - - `class BetaResponseAudioDeltaEvent: …` + - `class BetaContainerAuto: …` - Emitted when there is a partial audio response. + - `type: Literal["container_auto"]` - - `delta: str` + Automatically creates a container for this request - A chunk of Base64 encoded response audio bytes. + - `"container_auto"` - - `sequence_number: int` + - `file_ids: Optional[List[str]]` - A sequence number for this chunk of the stream response. + An optional list of uploaded files to make available to your code. - - `type: Literal["response.audio.delta"]` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The type of the event. Always `response.audio.delta`. + The memory limit for the container. - - `"response.audio.delta"` + - `"1g"` - - `agent: Optional[Agent]` + - `"4g"` - The agent that owns this multi-agent streaming event. + - `"16g"` - - `agent_name: str` + - `"64g"` - The canonical name of the agent that produced this item. + - `network_policy: Optional[NetworkPolicy]` - - `class BetaResponseAudioDoneEvent: …` + Network access policy for the container. - Emitted when the audio response is complete. + - `class BetaContainerNetworkPolicyDisabled: …` - - `sequence_number: int` + - `class BetaContainerNetworkPolicyAllowlist: …` - The sequence number of the delta. + - `skills: Optional[List[Skill]]` - - `type: Literal["response.audio.done"]` + An optional list of skills referenced by id or inline data. - The type of the event. Always `response.audio.done`. + - `class BetaSkillReference: …` - - `"response.audio.done"` + - `skill_id: str` - - `agent: Optional[Agent]` + The ID of the referenced skill. - The agent that owns this multi-agent streaming event. + - `type: Literal["skill_reference"]` - - `agent_name: str` + References a skill created with the /v1/skills endpoint. - The canonical name of the agent that produced this item. + - `"skill_reference"` - - `class BetaResponseAudioTranscriptDeltaEvent: …` + - `version: Optional[str]` - Emitted when there is a partial transcript of audio. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `delta: str` + - `class BetaInlineSkill: …` - The partial transcript of the audio response. + - `description: str` - - `sequence_number: int` + The description of the skill. - The sequence number of this event. + - `name: str` - - `type: Literal["response.audio.transcript.delta"]` + The name of the skill. - The type of the event. Always `response.audio.transcript.delta`. + - `source: BetaInlineSkillSource` - - `"response.audio.transcript.delta"` + Inline skill payload - - `agent: Optional[Agent]` + - `data: str` - The agent that owns this multi-agent streaming event. + Base64-encoded skill zip bundle. - - `agent_name: str` + - `media_type: Literal["application/zip"]` - The canonical name of the agent that produced this item. + The media type of the inline skill payload. Must be `application/zip`. - - `class BetaResponseAudioTranscriptDoneEvent: …` + - `"application/zip"` - Emitted when the full audio transcript is completed. + - `type: Literal["base64"]` - - `sequence_number: int` + The type of the inline skill source. Must be `base64`. - The sequence number of this event. + - `"base64"` - - `type: Literal["response.audio.transcript.done"]` + - `type: Literal["inline"]` - The type of the event. Always `response.audio.transcript.done`. + Defines an inline skill for this request. - - `"response.audio.transcript.done"` + - `"inline"` - - `agent: Optional[Agent]` + - `class BetaLocalEnvironment: …` - The agent that owns this multi-agent streaming event. + - `type: Literal["local"]` - - `agent_name: str` + Use a local computer environment. - The canonical name of the agent that produced this item. + - `"local"` - - `class BetaResponseCodeInterpreterCallCodeDeltaEvent: …` + - `skills: Optional[List[BetaLocalSkill]]` - Emitted when a partial code snippet is streamed by the code interpreter. + An optional list of skills. - - `delta: str` + - `description: str` - The partial code snippet being streamed by the code interpreter. + The description of the skill. - - `item_id: str` + - `name: str` - The unique identifier of the code interpreter tool call item. + The name of the skill. - - `output_index: int` + - `path: str` - The index of the output item in the response for which the code is being streamed. + The path to the directory containing the skill. - - `sequence_number: int` + - `class BetaContainerReference: …` - The sequence number of this event, used to order streaming events. + - `container_id: str` - - `type: Literal["response.code_interpreter_call_code.delta"]` + The ID of the referenced container. - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `type: Literal["container_reference"]` - - `"response.code_interpreter_call_code.delta"` + References a container created with the /v1/containers endpoint - - `agent: Optional[Agent]` + - `"container_reference"` - The agent that owns this multi-agent streaming event. + - `class BetaCustomTool: …` - - `agent_name: str` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The canonical name of the agent that produced this item. + - `name: str` - - `class BetaResponseCodeInterpreterCallCodeDoneEvent: …` + The name of the custom tool, used to identify it in tool calls. - Emitted when the code snippet is finalized by the code interpreter. + - `type: Literal["custom"]` - - `code: str` + The type of the custom tool. Always `custom`. - The final code snippet output by the code interpreter. + - `"custom"` - - `item_id: str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The unique identifier of the code interpreter tool call item. + The tool invocation context(s). - - `output_index: int` + - `"direct"` - The index of the output item in the response for which the code is finalized. + - `"programmatic"` - - `sequence_number: int` + - `defer_loading: Optional[bool]` - The sequence number of this event, used to order streaming events. + Whether this tool should be deferred and discovered via tool search. - - `type: Literal["response.code_interpreter_call_code.done"]` + - `description: Optional[str]` - The type of the event. Always `response.code_interpreter_call_code.done`. + Optional description of the custom tool, used to provide more context. - - `"response.code_interpreter_call_code.done"` + - `format: Optional[Format]` - - `agent: Optional[Agent]` + The input format for the custom tool. Default is unconstrained text. - The agent that owns this multi-agent streaming event. + - `class FormatText: …` - - `agent_name: str` + Unconstrained free-form text. - The canonical name of the agent that produced this item. + - `type: Literal["text"]` - - `class BetaResponseCodeInterpreterCallCompletedEvent: …` + Unconstrained text format. Always `text`. - Emitted when the code interpreter call is completed. + - `"text"` - - `item_id: str` + - `class FormatGrammar: …` - The unique identifier of the code interpreter tool call item. + A grammar defined by the user. - - `output_index: int` + - `definition: str` - The index of the output item in the response for which the code interpreter call is completed. + The grammar definition. - - `sequence_number: int` + - `syntax: Literal["lark", "regex"]` - The sequence number of this event, used to order streaming events. + The syntax of the grammar definition. One of `lark` or `regex`. - - `type: Literal["response.code_interpreter_call.completed"]` + - `"lark"` - The type of the event. Always `response.code_interpreter_call.completed`. + - `"regex"` - - `"response.code_interpreter_call.completed"` + - `type: Literal["grammar"]` - - `agent: Optional[Agent]` + Grammar format. Always `grammar`. - The agent that owns this multi-agent streaming event. + - `"grammar"` - - `agent_name: str` + - `class BetaNamespaceTool: …` - The canonical name of the agent that produced this item. + Groups function/custom tools under a shared namespace. - - `class BetaResponseCodeInterpreterCallInProgressEvent: …` + - `description: str` - Emitted when a code interpreter call is in progress. + A description of the namespace shown to the model. - - `item_id: str` + - `name: str` - The unique identifier of the code interpreter tool call item. + The namespace name used in tool calls (for example, `crm`). - - `output_index: int` + - `tools: List[Tool]` - The index of the output item in the response for which the code interpreter call is in progress. + The function/custom tools available inside this namespace. - - `sequence_number: int` + - `class ToolFunction: …` - The sequence number of this event, used to order streaming events. + - `name: str` - - `type: Literal["response.code_interpreter_call.in_progress"]` + - `type: Literal["function"]` - The type of the event. Always `response.code_interpreter_call.in_progress`. + - `"function"` - - `"response.code_interpreter_call.in_progress"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `agent: Optional[Agent]` + The tool invocation context(s). - The agent that owns this multi-agent streaming event. + - `"direct"` - - `agent_name: str` + - `"programmatic"` - The canonical name of the agent that produced this item. + - `defer_loading: Optional[bool]` - - `class BetaResponseCodeInterpreterCallInterpretingEvent: …` + Whether this function should be deferred and discovered via tool search. - Emitted when the code interpreter is actively interpreting the code snippet. + - `description: Optional[str]` - - `item_id: str` + - `output_schema: Optional[Dict[str, object]]` - The unique identifier of the code interpreter tool call item. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `output_index: int` + - `parameters: Optional[object]` - The index of the output item in the response for which the code interpreter is interpreting code. + - `strict: Optional[bool]` - - `sequence_number: int` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - The sequence number of this event, used to order streaming events. + - `class BetaCustomTool: …` - - `type: Literal["response.code_interpreter_call.interpreting"]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `type: Literal["namespace"]` - - `"response.code_interpreter_call.interpreting"` + The type of the tool. Always `namespace`. - - `agent: Optional[Agent]` + - `"namespace"` - The agent that owns this multi-agent streaming event. + - `class BetaToolSearchTool: …` - - `agent_name: str` + Hosted or BYOT tool search configuration for deferred tools. - The canonical name of the agent that produced this item. + - `type: Literal["tool_search"]` - - `class BetaResponseCompletedEvent: …` + The type of the tool. Always `tool_search`. - Emitted when the model response is complete. + - `"tool_search"` - - `response: BetaResponse` + - `description: Optional[str]` - Properties of the completed response. + Description shown to the model for a client-executed tool search tool. - - `id: str` + - `execution: Optional[Literal["server", "client"]]` - Unique identifier for this Response. + Whether tool search is executed by the server or by the client. - - `created_at: float` + - `"server"` - Unix timestamp (in seconds) of when this Response was created. + - `"client"` - - `error: Optional[BetaResponseError]` + - `parameters: Optional[object]` - An error object returned when the model fails to generate a Response. + Parameter schema for a client-executed tool search tool. - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + - `class BetaWebSearchPreviewTool: …` - The error code for the response. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"server_error"` + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - - `"rate_limit_exceeded"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"invalid_prompt"` + - `"web_search_preview"` - - `"bio_policy"` + - `"web_search_preview_2025_03_11"` - - `"vector_store_timeout"` + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `"invalid_image"` + - `"text"` - - `"invalid_image_format"` + - `"image"` - - `"invalid_base64_image"` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `"invalid_image_url"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `"image_too_large"` + - `"low"` - - `"image_too_small"` + - `"medium"` - - `"image_parse_error"` + - `"high"` - - `"image_content_policy_violation"` + - `user_location: Optional[UserLocation]` - - `"invalid_image_mode"` + The user's location. - - `"image_file_too_large"` + - `type: Literal["approximate"]` - - `"unsupported_image_media_type"` + The type of location approximation. Always `approximate`. - - `"empty_image_file"` + - `"approximate"` - - `"failed_to_download_image"` + - `city: Optional[str]` - - `"image_file_not_found"` + Free text input for the city of the user, e.g. `San Francisco`. - - `message: str` + - `country: Optional[str]` - A human-readable description of the error. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `incomplete_details: Optional[IncompleteDetails]` + - `region: Optional[str]` - Details about why the response is incomplete. + Free text input for the region of the user, e.g. `California`. - - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` + - `timezone: Optional[str]` - The reason why the response is incomplete. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"max_output_tokens"` + - `class BetaApplyPatchTool: …` - - `"content_filter"` + Allows the assistant to create, delete, or update files using unified diffs. - - `instructions: Union[str, List[BetaResponseInputItem], null]` + - `type: Literal["apply_patch"]` - A system (or developer) message inserted into the model's context. + The type of the tool. Always `apply_patch`. - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `"apply_patch"` - - `str` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - A text input to the model, equivalent to a text input with the - `developer` role. + The tool invocation context(s). - - `List[BetaResponseInputItem]` + - `"direct"` - A list of one or many input items to the model, containing - different content types. + - `"programmatic"` - - `class BetaEasyInputMessage: …` + - `type: Literal["tool_search_output"]` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The item type. Always `tool_search_output`. - - `content: Union[str, BetaResponseInputMessageContentList]` + - `"tool_search_output"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `id: Optional[str]` - - `str` + The unique ID of this tool search output. - A text input to the model. + - `agent: Optional[Agent]` - - `List[BetaResponseInputContent]` + The agent that produced this item. - - `class BetaResponseInputText: …` + - `agent_name: str` - A text input to the model. + The canonical name of the agent that produced this item. - - `text: str` + - `call_id: Optional[str]` - The text input to the model. + The unique ID of the tool search call generated by the model. - - `type: Literal["input_text"]` + - `execution: Optional[Literal["server", "client"]]` - The type of the input item. Always `input_text`. + Whether tool search was executed by the server or by the client. - - `"input_text"` + - `"server"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"client"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `mode: Literal["explicit"]` + The status of the tool search output. - The breakpoint mode. Always `explicit`. + - `"in_progress"` - - `"explicit"` + - `"completed"` - - `class BetaResponseInputImage: …` + - `"incomplete"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class AdditionalTools: …` - - `detail: Literal["low", "high", "auto", "original"]` + - `role: Literal["developer"]` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The role that provided the additional tools. Only `developer` is supported. - - `"low"` + - `"developer"` - - `"high"` + - `tools: List[BetaTool]` - - `"auto"` + A list of additional tools made available at this item. - - `"original"` + - `class BetaFunctionTool: …` - - `type: Literal["input_image"]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The type of the input item. Always `input_image`. + - `class BetaFileSearchTool: …` - - `"input_image"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `file_id: Optional[str]` + - `class BetaComputerTool: …` - The ID of the file to be sent to the model. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `image_url: Optional[str]` + - `class BetaComputerUsePreviewTool: …` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `class BetaWebSearchTool: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `mode: Literal["explicit"]` + - `class Mcp: …` - The breakpoint mode. Always `explicit`. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"explicit"` + - `class CodeInterpreter: …` - - `class BetaResponseInputFile: …` + A tool that runs Python code to help generate a response to a prompt. - A file input to the model. + - `class ProgrammaticToolCalling: …` - - `type: Literal["input_file"]` + - `class ImageGeneration: …` - The type of the input item. Always `input_file`. + A tool that generates images using the GPT image models. - - `"input_file"` + - `class LocalShell: …` - - `detail: Optional[Literal["auto", "low", "high"]]` + A tool that allows the model to execute shell commands in a local environment. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `class BetaFunctionShellTool: …` - - `"auto"` + A tool that allows the model to execute shell commands. - - `"low"` + - `class BetaCustomTool: …` - - `"high"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `file_data: Optional[str]` + - `class BetaNamespaceTool: …` - The content of the file to be sent to the model. + Groups function/custom tools under a shared namespace. - - `file_id: Optional[str]` + - `class BetaToolSearchTool: …` - The ID of the file to be sent to the model. + Hosted or BYOT tool search configuration for deferred tools. - - `file_url: Optional[str]` + - `class BetaWebSearchPreviewTool: …` - The URL of the file to be sent to the model. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `filename: Optional[str]` + - `class BetaApplyPatchTool: …` - The name of the file to be sent to the model. + Allows the assistant to create, delete, or update files using unified diffs. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["additional_tools"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The item type. Always `additional_tools`. - - `mode: Literal["explicit"]` + - `"additional_tools"` - The breakpoint mode. Always `explicit`. + - `id: Optional[str]` - - `"explicit"` + The unique ID of this additional tools item. - - `role: Literal["user", "assistant", "system", "developer"]` + - `agent: Optional[AdditionalToolsAgent]` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The agent that produced this item. - - `"user"` + - `agent_name: str` - - `"assistant"` + The canonical name of the agent that produced this item. - - `"system"` + - `class BetaResponseReasoningItem: …` - - `"developer"` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `phase: Optional[Literal["commentary"]]` + - `id: str` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The unique identifier of the reasoning content. - - `"commentary"` + - `summary: List[Summary]` - - `type: Optional[Literal["message"]]` + Reasoning summary content. - The type of the message input. Always `message`. + - `text: str` - - `"message"` + A summary of the reasoning output from the model so far. - - `class Message: …` + - `type: Literal["summary_text"]` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + The type of the object. Always `summary_text`. - - `content: BetaResponseInputMessageContentList` + - `"summary_text"` - A list of one or many input items to the model, containing different content - types. + - `type: Literal["reasoning"]` - - `class BetaResponseInputText: …` + The type of the object. Always `reasoning`. - A text input to the model. + - `"reasoning"` - - `class BetaResponseInputImage: …` + - `agent: Optional[Agent]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The agent that produced this item. - - `class BetaResponseInputFile: …` + - `agent_name: str` - A file input to the model. + The canonical name of the agent that produced this item. - - `role: Literal["user", "system", "developer"]` + - `content: Optional[List[Content]]` - The role of the message input. One of `user`, `system`, or `developer`. + Reasoning text content. - - `"user"` + - `text: str` - - `"system"` + The reasoning text from the model. - - `"developer"` + - `type: Literal["reasoning_text"]` - - `agent: Optional[MessageAgent]` + The type of the reasoning text. Always `reasoning_text`. - The agent that produced this item. + - `"reasoning_text"` - - `agent_name: str` + - `encrypted_content: Optional[str]` - The canonical name of the agent that produced this item. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of item. One of `in_progress`, `completed`, or + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -127301,178 +138215,192 @@ print(compacted_response) - `"incomplete"` - - `type: Optional[Literal["message"]]` + - `class BetaResponseCompactionItemParam: …` - The type of the message input. Always set to `message`. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `"message"` + - `encrypted_content: str` - - `class BetaResponseOutputMessage: …` + The encrypted content of the compaction summary. - An output message from the model. + - `type: Literal["compaction"]` - - `id: str` + The type of the item. Always `compaction`. - The unique ID of the output message. + - `"compaction"` - - `content: List[Content]` + - `id: Optional[str]` - The content of the output message. + The ID of the compaction item. - - `class BetaResponseOutputText: …` + - `agent: Optional[Agent]` - A text output from the model. + The agent that produced this item. - - `annotations: List[Annotation]` + - `agent_name: str` - The annotations of the text output. + The canonical name of the agent that produced this item. - - `class AnnotationFileCitation: …` + - `class ImageGenerationCall: …` + + An image generation request made by the model. + + - `id: str` + + The unique ID of the image generation call. + + - `result: Optional[str]` + + The generated image encoded in base64. + + - `status: Literal["in_progress", "completed", "generating", "failed"]` + + The status of the image generation call. - A citation to a file. + - `"in_progress"` - - `file_id: str` + - `"completed"` - The ID of the file. + - `"generating"` - - `filename: str` + - `"failed"` - The filename of the file cited. + - `type: Literal["image_generation_call"]` - - `index: int` + The type of the image generation call. Always `image_generation_call`. - The index of the file in the list of files. + - `"image_generation_call"` - - `type: Literal["file_citation"]` + - `agent: Optional[ImageGenerationCallAgent]` - The type of the file citation. Always `file_citation`. + The agent that produced this item. - - `"file_citation"` + - `agent_name: str` - - `class AnnotationURLCitation: …` + The canonical name of the agent that produced this item. - A citation for a web resource used to generate a model response. + - `class BetaResponseCodeInterpreterToolCall: …` - - `end_index: int` + A tool call to run code. - The index of the last character of the URL citation in the message. + - `id: str` - - `start_index: int` + The unique ID of the code interpreter tool call. - The index of the first character of the URL citation in the message. + - `code: Optional[str]` - - `title: str` + The code to run, or null if not available. - The title of the web resource. + - `container_id: str` - - `type: Literal["url_citation"]` + The ID of the container used to run the code. - The type of the URL citation. Always `url_citation`. + - `outputs: Optional[List[Output]]` - - `"url_citation"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `url: str` + - `class OutputLogs: …` - The URL of the web resource. + The logs output from the code interpreter. - - `class AnnotationContainerFileCitation: …` + - `logs: str` - A citation for a container file used to generate a model response. + The logs output from the code interpreter. - - `container_id: str` + - `type: Literal["logs"]` - The ID of the container file. + The type of the output. Always `logs`. - - `end_index: int` + - `"logs"` - The index of the last character of the container file citation in the message. + - `class OutputImage: …` - - `file_id: str` + The image output from the code interpreter. - The ID of the file. + - `type: Literal["image"]` - - `filename: str` + The type of the output. Always `image`. - The filename of the container file cited. + - `"image"` - - `start_index: int` + - `url: str` - The index of the first character of the container file citation in the message. + The URL of the image output from the code interpreter. - - `type: Literal["container_file_citation"]` + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - The type of the container file citation. Always `container_file_citation`. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"container_file_citation"` + - `"in_progress"` - - `class AnnotationFilePath: …` + - `"completed"` - A path to a file. + - `"incomplete"` - - `file_id: str` + - `"interpreting"` - The ID of the file. + - `"failed"` - - `index: int` + - `type: Literal["code_interpreter_call"]` - The index of the file in the list of files. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `type: Literal["file_path"]` + - `"code_interpreter_call"` - The type of the file path. Always `file_path`. + - `agent: Optional[Agent]` - - `"file_path"` + The agent that produced this item. - - `text: str` + - `agent_name: str` - The text output from the model. + The canonical name of the agent that produced this item. - - `type: Literal["output_text"]` + - `class LocalShellCall: …` - The type of the output text. Always `output_text`. + A tool call to run a command on the local shell. - - `"output_text"` + - `id: str` - - `logprobs: Optional[List[Logprob]]` + The unique ID of the local shell call. - - `token: str` + - `action: LocalShellCallAction` - - `bytes: List[int]` + Execute a shell command on the server. - - `logprob: float` + - `command: List[str]` - - `top_logprobs: List[LogprobTopLogprob]` + The command to run. - - `token: str` + - `env: Dict[str, str]` - - `bytes: List[int]` + Environment variables to set for the command. - - `logprob: float` + - `type: Literal["exec"]` - - `class BetaResponseOutputRefusal: …` + The type of the local shell action. Always `exec`. - A refusal from the model. + - `"exec"` - - `refusal: str` + - `timeout_ms: Optional[int]` - The refusal explanation from the model. + Optional timeout in milliseconds for the command. - - `type: Literal["refusal"]` + - `user: Optional[str]` - The type of the refusal. Always `refusal`. + Optional user to run the command as. - - `"refusal"` + - `working_directory: Optional[str]` - - `role: Literal["assistant"]` + Optional working directory to run the command in. - The role of the output message. Always `assistant`. + - `call_id: str` - - `"assistant"` + The unique ID of the local shell tool call generated by the model. - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The status of the local shell call. - `"in_progress"` @@ -127480,13 +138408,13 @@ print(compacted_response) - `"incomplete"` - - `type: Literal["message"]` + - `type: Literal["local_shell_call"]` - The type of the output message. Always `message`. + The type of the local shell call. Always `local_shell_call`. - - `"message"` + - `"local_shell_call"` - - `agent: Optional[Agent]` + - `agent: Optional[LocalShellCallAgent]` The agent that produced this item. @@ -127494,123 +138422,119 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `phase: Optional[Literal["commentary"]]` + - `class LocalShellCallOutput: …` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The output of a local shell tool call. - - `"commentary"` + - `id: str` - - `class BetaResponseFileSearchToolCall: …` + The unique ID of the local shell tool call generated by the model. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `output: str` - - `id: str` + A JSON string of the output of the local shell tool call. - The unique ID of the file search tool call. + - `type: Literal["local_shell_call_output"]` - - `queries: List[str]` + The type of the local shell tool call output. Always `local_shell_call_output`. - The queries used to search for files. + - `"local_shell_call_output"` - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `agent: Optional[LocalShellCallOutputAgent]` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The agent that produced this item. - - `"in_progress"` + - `agent_name: str` - - `"searching"` + The canonical name of the agent that produced this item. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` - `"completed"` - `"incomplete"` - - `"failed"` + - `class ShellCall: …` - - `type: Literal["file_search_call"]` + A tool representing a request to execute one or more shell commands. - The type of the file search tool call. Always `file_search_call`. + - `action: ShellCallAction` - - `"file_search_call"` + The shell commands and limits that describe how to run the tool call. - - `agent: Optional[Agent]` + - `commands: List[str]` - The agent that produced this item. + Ordered shell commands for the execution environment to run. - - `agent_name: str` + - `max_output_length: Optional[int]` - The canonical name of the agent that produced this item. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `results: Optional[List[Result]]` + - `timeout_ms: Optional[int]` - The results of the file search tool call. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + - `call_id: str` - 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, booleans, or numbers. + The unique ID of the shell tool call generated by the model. - - `str` + - `type: Literal["shell_call"]` - - `float` + The type of the item. Always `shell_call`. - - `bool` + - `"shell_call"` - - `file_id: Optional[str]` + - `id: Optional[str]` - The unique ID of the file. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `filename: Optional[str]` + - `agent: Optional[ShellCallAgent]` - The name of the file. + The agent that produced this item. - - `score: Optional[float]` + - `agent_name: str` - The relevance score of the file - a value between 0 and 1. + The canonical name of the agent that produced this item. - - `text: Optional[str]` + - `caller: Optional[ShellCallCaller]` - The text that was retrieved from the file. + The execution context that produced this tool call. - - `class BetaResponseComputerToolCall: …` + - `class ShellCallCallerDirect: …` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `type: Literal["direct"]` - - `id: str` + The caller type. Always `direct`. - The unique ID of the computer call. + - `"direct"` - - `call_id: str` + - `class ShellCallCallerProgram: …` - An identifier used when responding to the tool call with output. + - `caller_id: str` - - `pending_safety_checks: List[PendingSafetyCheck]` + The call ID of the program item that produced this tool call. - The pending safety checks for the computer call. + - `type: Literal["program"]` - - `id: str` + The caller type. Always `program`. - The ID of the pending safety check. + - `"program"` - - `code: Optional[str]` + - `environment: Optional[ShellCallEnvironment]` - The type of the pending safety check. + The environment to execute the shell commands in. - - `message: Optional[str]` + - `class BetaLocalEnvironment: …` - Details about the pending safety check. + - `class BetaContainerReference: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -127618,249 +138542,249 @@ print(compacted_response) - `"incomplete"` - - `type: Literal["computer_call"]` + - `class ShellCallOutput: …` - The type of the computer call. Always `computer_call`. + The streamed output items emitted by a shell tool call. - - `"computer_call"` + - `call_id: str` - - `action: Optional[BetaComputerAction]` + The unique ID of the shell tool call generated by the model. - A click action. + - `output: List[BetaResponseFunctionShellCallOutputContent]` - - `class Click: …` + Captured chunks of stdout and stderr output, along with their associated outcomes. - A click action. + - `outcome: Outcome` - - `button: Literal["left", "right", "wheel", 2 more]` + The exit or timeout outcome associated with this shell call. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `class OutcomeTimeout: …` - - `"left"` + Indicates that the shell call exceeded its configured time limit. - - `"right"` + - `type: Literal["timeout"]` - - `"wheel"` + The outcome type. Always `timeout`. - - `"back"` + - `"timeout"` - - `"forward"` + - `class OutcomeExit: …` - - `type: Literal["click"]` + Indicates that the shell commands finished and returned an exit code. - Specifies the event type. For a click action, this property is always `click`. + - `exit_code: int` - - `"click"` + The exit code returned by the shell process. - - `x: int` + - `type: Literal["exit"]` - The x-coordinate where the click occurred. + The outcome type. Always `exit`. - - `y: int` + - `"exit"` - The y-coordinate where the click occurred. + - `stderr: str` - - `keys: Optional[List[str]]` + Captured stderr output for the shell call. - The keys being held while clicking. + - `stdout: str` - - `class DoubleClick: …` + Captured stdout output for the shell call. - A double click action. + - `type: Literal["shell_call_output"]` - - `keys: Optional[List[str]]` + The type of the item. Always `shell_call_output`. - The keys being held while double-clicking. + - `"shell_call_output"` - - `type: Literal["double_click"]` + - `id: Optional[str]` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `"double_click"` + - `agent: Optional[ShellCallOutputAgent]` - - `x: int` + The agent that produced this item. - The x-coordinate where the double click occurred. + - `agent_name: str` - - `y: int` + The canonical name of the agent that produced this item. - The y-coordinate where the double click occurred. + - `caller: Optional[ShellCallOutputCaller]` - - `class Drag: …` + The execution context that produced this tool call. - A drag action. + - `class ShellCallOutputCallerDirect: …` - - `path: List[DragPath]` + - `type: Literal["direct"]` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The caller type. Always `direct`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"direct"` - - `x: int` + - `class ShellCallOutputCallerProgram: …` - The x-coordinate. + - `caller_id: str` - - `y: int` + The call ID of the program item that produced this tool call. - The y-coordinate. + - `type: Literal["program"]` - - `type: Literal["drag"]` + The caller type. Always `program`. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `"program"` - - `"drag"` + - `max_output_length: Optional[int]` - - `keys: Optional[List[str]]` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The keys being held while dragging the mouse. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `class Keypress: …` + The status of the shell call output. - A collection of keypresses the model would like to perform. + - `"in_progress"` - - `keys: List[str]` + - `"completed"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"incomplete"` - - `type: Literal["keypress"]` + - `class ApplyPatchCall: …` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + A tool call representing a request to create, delete, or update files using diff patches. - - `"keypress"` + - `call_id: str` - - `class Move: …` + The unique ID of the apply patch tool call generated by the model. - A mouse move action. + - `operation: ApplyPatchCallOperation` - - `type: Literal["move"]` + The specific create, delete, or update instruction for the apply_patch tool call. - Specifies the event type. For a move action, this property is always set to `move`. + - `class ApplyPatchCallOperationCreateFile: …` - - `"move"` + Instruction for creating a new file via the apply_patch tool. - - `x: int` + - `diff: str` - The x-coordinate to move to. + Unified diff content to apply when creating the file. - - `y: int` + - `path: str` - The y-coordinate to move to. + Path of the file to create relative to the workspace root. - - `keys: Optional[List[str]]` + - `type: Literal["create_file"]` - The keys being held while moving the mouse. + The operation type. Always `create_file`. - - `class Screenshot: …` + - `"create_file"` - A screenshot action. + - `class ApplyPatchCallOperationDeleteFile: …` - - `type: Literal["screenshot"]` + Instruction for deleting an existing file via the apply_patch tool. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `path: str` - - `"screenshot"` + Path of the file to delete relative to the workspace root. - - `class Scroll: …` + - `type: Literal["delete_file"]` - A scroll action. + The operation type. Always `delete_file`. - - `scroll_x: int` + - `"delete_file"` - The horizontal scroll distance. + - `class ApplyPatchCallOperationUpdateFile: …` - - `scroll_y: int` + Instruction for updating an existing file via the apply_patch tool. - The vertical scroll distance. + - `diff: str` - - `type: Literal["scroll"]` + Unified diff content to apply to the existing file. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `path: str` - - `"scroll"` + Path of the file to update relative to the workspace root. - - `x: int` + - `type: Literal["update_file"]` - The x-coordinate where the scroll occurred. + The operation type. Always `update_file`. - - `y: int` + - `"update_file"` - The y-coordinate where the scroll occurred. + - `status: Literal["in_progress", "completed"]` - - `keys: Optional[List[str]]` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The keys being held while scrolling. + - `"in_progress"` - - `class Type: …` + - `"completed"` - An action to type in text. + - `type: Literal["apply_patch_call"]` - - `text: str` + The type of the item. Always `apply_patch_call`. - The text to type. + - `"apply_patch_call"` - - `type: Literal["type"]` + - `id: Optional[str]` - Specifies the event type. For a type action, this property is always set to `type`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"type"` + - `agent: Optional[ApplyPatchCallAgent]` - - `class Wait: …` + The agent that produced this item. - A wait action. + - `agent_name: str` - - `type: Literal["wait"]` + The canonical name of the agent that produced this item. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `caller: Optional[ApplyPatchCallCaller]` - - `"wait"` + The execution context that produced this tool call. - - `actions: Optional[BetaComputerActionList]` + - `class ApplyPatchCallCallerDirect: …` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `type: Literal["direct"]` - - `class Click: …` + The caller type. Always `direct`. - A click action. + - `"direct"` - - `class DoubleClick: …` + - `class ApplyPatchCallCallerProgram: …` - A double click action. + - `caller_id: str` - - `class Drag: …` + The call ID of the program item that produced this tool call. - A drag action. + - `type: Literal["program"]` - - `class Keypress: …` + The caller type. Always `program`. - A collection of keypresses the model would like to perform. + - `"program"` - - `class Move: …` + - `class ApplyPatchCallOutput: …` - A mouse move action. + The streamed output emitted by an apply patch tool call. - - `class Screenshot: …` + - `call_id: str` - A screenshot action. + The unique ID of the apply patch tool call generated by the model. - - `class Scroll: …` + - `status: Literal["completed", "failed"]` - A scroll action. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `class Type: …` + - `"completed"` - An action to type in text. + - `"failed"` - - `class Wait: …` + - `type: Literal["apply_patch_call_output"]` - A wait action. + The type of the item. Always `apply_patch_call_output`. - - `agent: Optional[Agent]` + - `"apply_patch_call_output"` + + - `id: Optional[str]` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: Optional[ApplyPatchCallOutputAgent]` The agent that produced this item. @@ -127868,174 +138792,179 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ComputerCallOutput: …` + - `caller: Optional[ApplyPatchCallOutputCaller]` - The output of a computer tool call. + The execution context that produced this tool call. - - `call_id: str` + - `class ApplyPatchCallOutputCallerDirect: …` - The ID of the computer tool call that produced the output. + - `type: Literal["direct"]` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The caller type. Always `direct`. - A computer screenshot image used with the computer use tool. + - `"direct"` - - `type: Literal["computer_screenshot"]` + - `class ApplyPatchCallOutputCallerProgram: …` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `caller_id: str` - - `"computer_screenshot"` + The call ID of the program item that produced this tool call. - - `file_id: Optional[str]` + - `type: Literal["program"]` - The identifier of an uploaded file that contains the screenshot. + The caller type. Always `program`. - - `image_url: Optional[str]` + - `"program"` - The URL of the screenshot image. + - `output: Optional[str]` - - `type: Literal["computer_call_output"]` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - The type of the computer tool call output. Always `computer_call_output`. + - `class McpListTools: …` - - `"computer_call_output"` + A list of tools available on an MCP server. - - `id: Optional[str]` + - `id: str` - The ID of the computer tool call output. + The unique ID of the list. - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + - `server_label: str` - The safety checks reported by the API that have been acknowledged by the developer. + The label of the MCP server. - - `id: str` + - `tools: List[McpListToolsTool]` - The ID of the pending safety check. + The tools available on the server. - - `code: Optional[str]` + - `input_schema: object` - The type of the pending safety check. + The JSON schema describing the tool's input. - - `message: Optional[str]` + - `name: str` - Details about the pending safety check. + The name of the tool. - - `agent: Optional[ComputerCallOutputAgent]` + - `annotations: Optional[object]` - The agent that produced this item. + Additional annotations about the tool. - - `agent_name: str` + - `description: Optional[str]` - The canonical name of the agent that produced this item. + The description of the tool. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `type: Literal["mcp_list_tools"]` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The type of the item. Always `mcp_list_tools`. - - `"in_progress"` + - `"mcp_list_tools"` - - `"completed"` + - `agent: Optional[McpListToolsAgent]` - - `"incomplete"` + The agent that produced this item. - - `class BetaResponseFunctionWebSearch: …` + - `agent_name: str` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The canonical name of the agent that produced this item. + + - `error: Optional[str]` + + Error message if the server could not list tools. + + - `class McpApprovalRequest: …` + + A request for human approval of a tool invocation. - `id: str` - The unique ID of the web search tool call. + The unique ID of the approval request. - - `action: Action` + - `arguments: str` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + A JSON string of arguments for the tool. - - `class ActionSearch: …` + - `name: str` - Action type "search" - Performs a web search query. + The name of the tool to run. - - `type: Literal["search"]` + - `server_label: str` - The action type. + The label of the MCP server making the request. - - `"search"` + - `type: Literal["mcp_approval_request"]` - - `queries: Optional[List[str]]` + The type of the item. Always `mcp_approval_request`. - The search queries. + - `"mcp_approval_request"` - - `query: Optional[str]` + - `agent: Optional[McpApprovalRequestAgent]` - The search query. + The agent that produced this item. - - `sources: Optional[List[ActionSearchSource]]` + - `agent_name: str` - The sources used in the search. + The canonical name of the agent that produced this item. - - `type: Literal["url"]` + - `class McpApprovalResponse: …` - The type of source. Always `url`. + A response to an MCP approval request. - - `"url"` + - `approval_request_id: str` - - `url: str` + The ID of the approval request being answered. - The URL of the source. + - `approve: bool` - - `class ActionOpenPage: …` + Whether the request was approved. - Action type "open_page" - Opens a specific URL from search results. + - `type: Literal["mcp_approval_response"]` - - `type: Literal["open_page"]` + The type of the item. Always `mcp_approval_response`. - The action type. + - `"mcp_approval_response"` - - `"open_page"` + - `id: Optional[str]` - - `url: Optional[str]` + The unique ID of the approval response - The URL opened by the model. + - `agent: Optional[McpApprovalResponseAgent]` - - `class ActionFindInPage: …` + The agent that produced this item. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `agent_name: str` - - `pattern: str` + The canonical name of the agent that produced this item. - The pattern or text to search for within the page. + - `reason: Optional[str]` - - `type: Literal["find_in_page"]` + Optional reason for the decision. - The action type. + - `class McpCall: …` - - `"find_in_page"` + An invocation of a tool on an MCP server. - - `url: str` + - `id: str` - The URL of the page searched for the pattern. + The unique ID of the tool call. - - `status: Literal["in_progress", "searching", "completed", "failed"]` + - `arguments: str` - The status of the web search tool call. + A JSON string of the arguments passed to the tool. - - `"in_progress"` + - `name: str` - - `"searching"` + The name of the tool that was run. - - `"completed"` + - `server_label: str` - - `"failed"` + The label of the MCP server running the tool. - - `type: Literal["web_search_call"]` + - `type: Literal["mcp_call"]` - The type of the web search tool call. Always `web_search_call`. + The type of the item. Always `mcp_call`. - - `"web_search_call"` + - `"mcp_call"` - - `agent: Optional[Agent]` + - `agent: Optional[McpCallAgent]` The agent that produced this item. @@ -128043,32 +138972,75 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall: …` + - `approval_request_id: Optional[str]` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `arguments: str` + - `error: Optional[str]` - A JSON string of the arguments to pass to the function. + The error from the tool call, if any. + + - `output: Optional[str]` + + The output from the tool call. + + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `class BetaResponseCustomToolCallOutput: …` + + The output of a custom tool call from your code, being sent back to the model. - `call_id: str` - The unique ID of the function tool call generated by the model. + The call ID, used to map this custom tool call output to a custom tool call. - - `name: str` + - `output: Union[str, List[OutputOutputContentList]]` - The name of the function to run. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `type: Literal["function_call"]` + - `str` - The type of the function tool call. Always `function_call`. + A string of the output of the custom tool call. - - `"function_call"` + - `List[OutputOutputContentList]` + + Text, image, or file output of the custom tool call. + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `type: Literal["custom_tool_call_output"]` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `"custom_tool_call_output"` - `id: Optional[str]` - The unique ID of the function tool call. + The unique ID of the custom tool call output in the OpenAI platform. - `agent: Optional[Agent]` @@ -128086,6 +139058,8 @@ print(compacted_response) - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - `class CallerProgram: …` @@ -128096,162 +139070,133 @@ print(compacted_response) - `type: Literal["program"]` - - `"program"` - - - `namespace: Optional[str]` - - The namespace of the function to run. - - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` + The caller type. Always `program`. - - `"incomplete"` + - `"program"` - - `class FunctionCallOutput: …` + - `class BetaResponseCustomToolCall: …` - The output of a function tool call. + A call to a custom tool created by the model. - `call_id: str` - The unique ID of the function tool call generated by the model. - - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - - Text, image, or file output of the function tool call. - - - `str` - - A JSON string of the output of the function tool call. - - - `List[BetaResponseFunctionCallOutputItem]` - - - `class BetaResponseInputTextContent: …` - - A text input to the model. - - - `text: str` + An identifier used to map this custom tool call to a tool call output. - The text input to the model. + - `input: str` - - `type: Literal["input_text"]` + The input for the custom tool call generated by the model. - The type of the input item. Always `input_text`. + - `name: str` - - `"input_text"` + The name of the custom tool being called. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["custom_tool_call"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The type of the custom tool call. Always `custom_tool_call`. - - `mode: Literal["explicit"]` + - `"custom_tool_call"` - The breakpoint mode. Always `explicit`. + - `id: Optional[str]` - - `"explicit"` + The unique ID of the custom tool call in the OpenAI platform. - - `class BetaResponseInputImageContent: …` + - `agent: Optional[Agent]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The agent that produced this item. - - `type: Literal["input_image"]` + - `agent_name: str` - The type of the input item. Always `input_image`. + The canonical name of the agent that produced this item. - - `"input_image"` + - `caller: Optional[Caller]` - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + The execution context that produced this tool call. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `class CallerDirect: …` - - `"low"` + - `type: Literal["direct"]` - - `"high"` + - `"direct"` - - `"auto"` + - `class CallerProgram: …` - - `"original"` + - `caller_id: str` - - `file_id: Optional[str]` + The call ID of the program item that produced this tool call. - The ID of the file to be sent to the model. + - `type: Literal["program"]` - - `image_url: Optional[str]` + - `"program"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `namespace: Optional[str]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The namespace of the custom tool being called. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class CompactionTrigger: …` - - `mode: Literal["explicit"]` + Compacts the current context. Must be the final input item. - The breakpoint mode. Always `explicit`. + - `type: Literal["compaction_trigger"]` - - `"explicit"` + The type of the item. Always `compaction_trigger`. - - `class BetaResponseInputFileContent: …` + - `"compaction_trigger"` - A file input to the model. + - `agent: Optional[CompactionTriggerAgent]` - - `type: Literal["input_file"]` + The agent that produced this item. - The type of the input item. Always `input_file`. + - `agent_name: str` - - `"input_file"` + The canonical name of the agent that produced this item. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `class ItemReference: …` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + An internal identifier for an item to reference. - - `"auto"` + - `id: str` - - `"low"` + The ID of the item to reference. - - `"high"` + - `agent: Optional[ItemReferenceAgent]` - - `file_data: Optional[str]` + The agent that produced this item. - The base64-encoded data of the file to be sent to the model. + - `agent_name: str` - - `file_id: Optional[str]` + The canonical name of the agent that produced this item. - The ID of the file to be sent to the model. + - `type: Optional[Literal["item_reference"]]` - - `file_url: Optional[str]` + The type of item to reference. Always `item_reference`. - The URL of the file to be sent to the model. + - `"item_reference"` - - `filename: Optional[str]` + - `class Program: …` - The name of the file to be sent to the model. + - `id: str` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The unique ID of this program item. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `call_id: str` - - `mode: Literal["explicit"]` + The stable call ID of the program item. - The breakpoint mode. Always `explicit`. + - `code: str` - - `"explicit"` + The JavaScript source executed by programmatic tool calling. - - `type: Literal["function_call_output"]` + - `fingerprint: str` - The type of the function tool call output. Always `function_call_output`. + Opaque program replay fingerprint that must be round-tripped. - - `"function_call_output"` + - `type: Literal["program"]` - - `id: Optional[str]` + The item type. Always `program`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"program"` - - `agent: Optional[FunctionCallOutputAgent]` + - `agent: Optional[ProgramAgent]` The agent that produced this item. @@ -128259,309 +139204,327 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[FunctionCallOutputCaller]` + - `class ProgramOutput: …` - The execution context that produced this tool call. + - `id: str` - - `class FunctionCallOutputCallerDirect: …` + The unique ID of this program output item. - - `type: Literal["direct"]` + - `call_id: str` - The caller type. Always `direct`. + The call ID of the program item. - - `"direct"` + - `result: str` - - `class FunctionCallOutputCallerProgram: …` + The result produced by the program item. - - `caller_id: str` + - `status: Literal["completed", "incomplete"]` - The call ID of the program item that produced this tool call. + The terminal status of the program output. - - `type: Literal["program"]` + - `"completed"` - The caller type. Always `program`. + - `"incomplete"` - - `"program"` + - `type: Literal["program_output"]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The item type. Always `program_output`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `"program_output"` - - `"in_progress"` + - `agent: Optional[ProgramOutputAgent]` - - `"completed"` + The agent that produced this item. - - `"incomplete"` + - `agent_name: str` - - `class AgentMessage: …` + The canonical name of the agent that produced this item. - A message routed between agents. + - `metadata: Optional[Dict[str, str]]` - - `author: str` + 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. - The sending agent identity. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `content: List[AgentMessageContent]` + - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` - Plaintext, image, or encrypted content sent between agents. + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `class BetaResponseInputTextContent: …` + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` - A text input to the model. + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `class BetaResponseInputImageContent: …` + - `"gpt-5.6-sol"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"gpt-5.6-terra"` - - `class AgentMessageContentEncryptedContent: …` + - `"gpt-5.6-luna"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"gpt-5.4"` - - `encrypted_content: str` + - `"gpt-5.4-mini"` - Opaque encrypted content. + - `"gpt-5.4-nano"` - - `type: Literal["encrypted_content"]` + - `"gpt-5.4-mini-2026-03-17"` - The type of the input item. Always `encrypted_content`. + - `"gpt-5.4-nano-2026-03-17"` - - `"encrypted_content"` + - `"gpt-5.3-chat-latest"` - - `recipient: str` + - `"gpt-5.2"` - The destination agent identity. + - `"gpt-5.2-2025-12-11"` - - `type: Literal["agent_message"]` + - `"gpt-5.2-chat-latest"` - The item type. Always `agent_message`. + - `"gpt-5.2-pro"` - - `"agent_message"` + - `"gpt-5.2-pro-2025-12-11"` - - `id: Optional[str]` + - `"gpt-5.1"` - The unique ID of this agent message item. + - `"gpt-5.1-2025-11-13"` - - `agent: Optional[AgentMessageAgent]` + - `"gpt-5.1-codex"` - The agent that produced this item. + - `"gpt-5.1-mini"` - - `agent_name: str` + - `"gpt-5.1-chat-latest"` - The canonical name of the agent that produced this item. + - `"gpt-5"` - - `class MultiAgentCall: …` + - `"gpt-5-mini"` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `"gpt-5-nano"` - The multi-agent action that was executed. + - `"gpt-5-2025-08-07"` - - `"spawn_agent"` + - `"gpt-5-mini-2025-08-07"` - - `"interrupt_agent"` + - `"gpt-5-nano-2025-08-07"` - - `"list_agents"` + - `"gpt-5-chat-latest"` - - `"send_message"` + - `"gpt-4.1"` - - `"followup_task"` + - `"gpt-4.1-mini"` - - `"wait_agent"` + - `"gpt-4.1-nano"` - - `arguments: str` + - `"gpt-4.1-2025-04-14"` - The action arguments as a JSON string. + - `"gpt-4.1-mini-2025-04-14"` - - `call_id: str` + - `"gpt-4.1-nano-2025-04-14"` - The unique ID linking this call to its output. + - `"o4-mini"` - - `type: Literal["multi_agent_call"]` + - `"o4-mini-2025-04-16"` - The item type. Always `multi_agent_call`. + - `"o3"` - - `"multi_agent_call"` + - `"o3-2025-04-16"` - - `id: Optional[str]` + - `"o3-mini"` - The unique ID of this multi-agent call. + - `"o3-mini-2025-01-31"` - - `agent: Optional[MultiAgentCallAgent]` + - `"o1"` - The agent that produced this item. + - `"o1-2024-12-17"` - - `agent_name: str` + - `"o1-preview"` - The canonical name of the agent that produced this item. + - `"o1-preview-2024-09-12"` - - `class MultiAgentCallOutput: …` + - `"o1-mini"` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `"o1-mini-2024-09-12"` - The multi-agent action that produced this result. + - `"gpt-4o"` - - `"spawn_agent"` + - `"gpt-4o-2024-11-20"` - - `"interrupt_agent"` + - `"gpt-4o-2024-08-06"` - - `"list_agents"` + - `"gpt-4o-2024-05-13"` - - `"send_message"` + - `"gpt-4o-audio-preview"` - - `"followup_task"` + - `"gpt-4o-audio-preview-2024-10-01"` - - `"wait_agent"` + - `"gpt-4o-audio-preview-2024-12-17"` - - `call_id: str` + - `"gpt-4o-audio-preview-2025-06-03"` - The unique ID of the multi-agent call. + - `"gpt-4o-mini-audio-preview"` - - `output: List[MultiAgentCallOutputOutput]` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - Text output returned by the multi-agent action. + - `"gpt-4o-search-preview"` - - `text: str` + - `"gpt-4o-mini-search-preview"` - The text content. + - `"gpt-4o-search-preview-2025-03-11"` - - `type: Literal["output_text"]` + - `"gpt-4o-mini-search-preview-2025-03-11"` - The content type. Always `output_text`. + - `"chatgpt-4o-latest"` - - `"output_text"` + - `"codex-mini-latest"` - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + - `"gpt-4o-mini"` - Citations associated with the text content. + - `"gpt-4o-mini-2024-07-18"` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + - `"gpt-4-turbo"` - - `file_id: str` + - `"gpt-4-turbo-2024-04-09"` - The ID of the file. + - `"gpt-4-0125-preview"` - - `filename: str` + - `"gpt-4-turbo-preview"` - The filename of the file cited. + - `"gpt-4-1106-preview"` - - `index: int` + - `"gpt-4-vision-preview"` - The index of the file in the list of files. + - `"gpt-4"` - - `type: Literal["file_citation"]` + - `"gpt-4-0314"` - The citation type. Always `file_citation`. + - `"gpt-4-0613"` - - `"file_citation"` + - `"gpt-4-32k"` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + - `"gpt-4-32k-0314"` - - `end_index: int` + - `"gpt-4-32k-0613"` - The index of the last character of the citation in the message. + - `"gpt-3.5-turbo"` - - `start_index: int` + - `"gpt-3.5-turbo-16k"` - The index of the first character of the citation in the message. + - `"gpt-3.5-turbo-0301"` - - `title: str` + - `"gpt-3.5-turbo-0613"` - The title of the cited resource. + - `"gpt-3.5-turbo-1106"` - - `type: Literal["url_citation"]` + - `"gpt-3.5-turbo-0125"` - The citation type. Always `url_citation`. + - `"gpt-3.5-turbo-16k-0613"` - - `"url_citation"` + - `"o1-pro"` - - `url: str` + - `"o1-pro-2025-03-19"` - The URL of the cited resource. + - `"o3-pro"` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `"o3-pro-2025-06-10"` - - `container_id: str` + - `"o3-deep-research"` - The ID of the container. + - `"o3-deep-research-2025-06-26"` - - `end_index: int` + - `"o4-mini-deep-research"` - The index of the last character of the citation in the message. + - `"o4-mini-deep-research-2025-06-26"` - - `file_id: str` + - `"computer-use-preview"` - The ID of the container file. + - `"computer-use-preview-2025-03-11"` - - `filename: str` + - `"gpt-5-codex"` - The filename of the container file cited. + - `"gpt-5-pro"` - - `start_index: int` + - `"gpt-5-pro-2025-10-06"` - The index of the first character of the citation in the message. + - `"gpt-5.1-codex-max"` - - `type: Literal["container_file_citation"]` + - `str` - The citation type. Always `container_file_citation`. + - `object: Literal["response"]` - - `"container_file_citation"` + The object type of this resource - always set to `response`. - - `type: Literal["multi_agent_call_output"]` + - `"response"` - The item type. Always `multi_agent_call_output`. + - `output: List[BetaResponseOutputItem]` - - `"multi_agent_call_output"` + An array of content items generated by the model. - - `id: Optional[str]` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - The unique ID of this multi-agent call output. + - `class BetaResponseOutputMessage: …` - - `agent: Optional[MultiAgentCallOutputAgent]` + An output message from the model. - The agent that produced this item. + - `class BetaResponseFileSearchToolCall: …` - - `agent_name: str` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The canonical name of the agent that produced this item. + - `class BetaResponseFunctionToolCall: …` - - `class ToolSearchCall: …` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `arguments: object` + - `class BetaResponseFunctionToolCallOutputItem: …` - The arguments supplied to the tool search call. + - `id: str` - - `type: Literal["tool_search_call"]` + The unique ID of the function call tool output. - The item type. Always `tool_search_call`. + - `call_id: str` - - `"tool_search_call"` + The unique ID of the function tool call generated by the model. - - `id: Optional[str]` + - `output: Union[str, List[OutputOutputContentList]]` - The unique ID of this tool search call. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `agent: Optional[ToolSearchCallAgent]` + - `str` - The agent that produced this item. + A string of the output of the function call. - - `agent_name: str` + - `List[OutputOutputContentList]` - The canonical name of the agent that produced this item. + Text, image, or file output of the function call. - - `call_id: Optional[str]` + - `class BetaResponseInputText: …` - The unique ID of the tool search call generated by the model. + A text input to the model. - - `execution: Optional[Literal["server", "client"]]` + - `class BetaResponseInputImage: …` - Whether tool search was executed by the server or by the client. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"server"` + - `class BetaResponseInputFile: …` - - `"client"` + A file input to the model. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the tool search call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -128569,1107 +139532,1062 @@ print(compacted_response) - `"incomplete"` - - `class BetaResponseToolSearchOutputItemParam: …` - - - `tools: List[BetaTool]` - - The loaded tool definitions returned by the tool search output. - - - `class BetaFunctionTool: …` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `type: Literal["function_call_output"]` - - `name: str` + The type of the function tool call output. Always `function_call_output`. - The name of the function to call. + - `"function_call_output"` - - `parameters: Optional[Dict[str, object]]` + - `agent: Optional[Agent]` - A JSON schema object describing the parameters of the function. + The agent that produced this item. - - `strict: Optional[bool]` + - `agent_name: str` - Whether strict parameter validation is enforced for this function tool. + The canonical name of the agent that produced this item. - - `type: Literal["function"]` + - `caller: Optional[Caller]` - The type of the function tool. Always `function`. + The execution context that produced this tool call. - - `"function"` + - `class CallerDirect: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["direct"]` - The tool invocation context(s). + The caller type. Always `direct`. - `"direct"` - - `"programmatic"` + - `class CallerProgram: …` - - `defer_loading: Optional[bool]` + - `caller_id: str` - Whether this function is deferred and loaded via tool search. + The call ID of the program item that produced this tool call. - - `description: Optional[str]` + - `type: Literal["program"]` - A description of the function. Used by the model to determine whether or not to call the function. + The caller type. Always `program`. - - `output_schema: Optional[Dict[str, object]]` + - `"program"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `created_by: Optional[str]` - - `class BetaFileSearchTool: …` + The identifier of the actor that created the item. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `class AgentMessage: …` - - `type: Literal["file_search"]` + - `id: str` - The type of the file search tool. Always `file_search`. + The unique ID of the agent message. - - `"file_search"` + - `author: str` - - `vector_store_ids: List[str]` + The sending agent identity. - The IDs of the vector stores to search. + - `content: List[AgentMessageContent]` - - `filters: Optional[Filters]` + Encrypted content sent between agents. - A filter to apply. + - `class BetaResponseInputText: …` - - `class FiltersComparisonFilter: …` + A text input to the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `class BetaResponseOutputText: …` - - `key: str` + A text output from the model. - The key to compare against the value. + - `class AgentMessageContentText: …` - - `type: Literal["eq", "ne", "gt", 5 more]` + A text content. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `text: str` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `type: Literal["text"]` - - `"eq"` + - `"text"` - - `"ne"` + - `class AgentMessageContentSummaryText: …` - - `"gt"` + A summary text from the model. - - `"gte"` + - `text: str` - - `"lt"` + A summary of the reasoning output from the model so far. - - `"lte"` + - `type: Literal["summary_text"]` - - `"in"` + The type of the object. Always `summary_text`. - - `"nin"` + - `"summary_text"` - - `value: Union[str, float, bool, List[object]]` + - `class AgentMessageContentReasoningText: …` - The value to compare against the attribute key; supports string, number, or boolean types. + Reasoning text from the model. - - `str` + - `text: str` - - `float` + The reasoning text from the model. - - `bool` + - `type: Literal["reasoning_text"]` - - `List[object]` + The type of the reasoning text. Always `reasoning_text`. - - `class FiltersCompoundFilter: …` + - `"reasoning_text"` - Combine multiple filters using `and` or `or`. + - `class BetaResponseOutputRefusal: …` - - `filters: List[FiltersCompoundFilterFilter]` + A refusal from the model. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `class BetaResponseInputImage: …` - - `class FiltersCompoundFilterFilterComparisonFilter: …` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `class AgentMessageContentComputerScreenshot: …` - - `key: str` + A screenshot of a computer. - The key to compare against the value. + - `detail: Literal["low", "high", "auto", "original"]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"low"` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `"high"` - - `"eq"` + - `"auto"` - - `"ne"` + - `"original"` - - `"gt"` + - `file_id: Optional[str]` - - `"gte"` + The identifier of an uploaded file that contains the screenshot. - - `"lt"` + - `image_url: Optional[str]` - - `"lte"` + The URL of the screenshot image. - - `"in"` + - `type: Literal["computer_screenshot"]` - - `"nin"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `value: Union[str, float, bool, List[object]]` + - `"computer_screenshot"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - - `str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `float` + - `mode: Literal["explicit"]` - - `bool` + The breakpoint mode. Always `explicit`. - - `List[object]` + - `"explicit"` - - `object` + - `class BetaResponseInputFile: …` - - `type: Literal["and", "or"]` + A file input to the model. - Type of operation: `and` or `or`. + - `class AgentMessageContentEncryptedContent: …` - - `"and"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"or"` + - `encrypted_content: str` - - `max_num_results: Optional[int]` + Opaque encrypted content. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `type: Literal["encrypted_content"]` - - `ranking_options: Optional[RankingOptions]` + The type of the input item. Always `encrypted_content`. - Ranking options for search. + - `"encrypted_content"` - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + - `recipient: str` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The destination agent identity. - - `embedding_weight: float` + - `type: Literal["agent_message"]` - The weight of the embedding in the reciprocal ranking fusion. + The type of the item. Always `agent_message`. - - `text_weight: float` + - `"agent_message"` - The weight of the text in the reciprocal ranking fusion. + - `agent: Optional[AgentMessageAgent]` - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + The agent that produced this item. - The ranker to use for the file search. + - `agent_name: str` - - `"auto"` + The canonical name of the agent that produced this item. - - `"default-2024-11-15"` + - `class MultiAgentCall: …` - - `score_threshold: Optional[float]` + - `id: str` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The unique ID of the multi-agent call item. - - `class BetaComputerTool: …` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The multi-agent action to execute. - - `type: Literal["computer"]` + - `"spawn_agent"` - The type of the computer tool. Always `computer`. + - `"interrupt_agent"` - - `"computer"` + - `"list_agents"` - - `class BetaComputerUsePreviewTool: …` + - `"send_message"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"followup_task"` - - `display_height: int` + - `"wait_agent"` - The height of the computer display. + - `arguments: str` - - `display_width: int` + The JSON string of arguments generated for the action. - The width of the computer display. + - `call_id: str` - - `environment: Literal["windows", "mac", "linux", 2 more]` + The unique ID linking this call to its output. - The type of computer environment to control. + - `type: Literal["multi_agent_call"]` - - `"windows"` + The type of the multi-agent call. Always `multi_agent_call`. - - `"mac"` + - `"multi_agent_call"` - - `"linux"` + - `agent: Optional[MultiAgentCallAgent]` - - `"ubuntu"` + The agent that produced this item. - - `"browser"` + - `agent_name: str` - - `type: Literal["computer_use_preview"]` + The canonical name of the agent that produced this item. - The type of the computer use tool. Always `computer_use_preview`. + - `class MultiAgentCallOutput: …` - - `"computer_use_preview"` + - `id: str` - - `class BetaWebSearchTool: …` + The unique ID of the multi-agent call output item. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `type: Literal["web_search", "web_search_2025_08_26"]` + The multi-agent action that produced this result. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"spawn_agent"` - - `"web_search"` + - `"interrupt_agent"` - - `"web_search_2025_08_26"` + - `"list_agents"` - - `filters: Optional[Filters]` + - `"send_message"` - Filters for the search. + - `"followup_task"` - - `allowed_domains: Optional[List[str]]` + - `"wait_agent"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `call_id: str` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The unique ID of the multi-agent call. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `output: List[BetaResponseOutputText]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + Text output returned by the multi-agent action. - - `"low"` + - `annotations: List[Annotation]` - - `"medium"` + The annotations of the text output. - - `"high"` + - `text: str` - - `user_location: Optional[UserLocation]` + The text output from the model. - The approximate location of the user. + - `type: Literal["output_text"]` - - `city: Optional[str]` + The type of the output text. Always `output_text`. - Free text input for the city of the user, e.g. `San Francisco`. + - `logprobs: Optional[List[Logprob]]` - - `country: Optional[str]` + - `type: Literal["multi_agent_call_output"]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `region: Optional[str]` + - `"multi_agent_call_output"` - Free text input for the region of the user, e.g. `California`. + - `agent: Optional[MultiAgentCallOutputAgent]` - - `timezone: Optional[str]` + The agent that produced this item. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `agent_name: str` - - `type: Optional[Literal["approximate"]]` + The canonical name of the agent that produced this item. - The type of location approximation. Always `approximate`. + - `class BetaResponseFunctionWebSearch: …` - - `"approximate"` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `class Mcp: …` + - `class BetaResponseComputerToolCall: …` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `server_label: str` + - `class BetaResponseComputerToolCallOutputItem: …` - A label for this MCP server, used to identify it in tool calls. + - `id: str` - - `type: Literal["mcp"]` + The unique ID of the computer call tool output. - The type of the MCP tool. Always `mcp`. + - `call_id: str` - - `"mcp"` + The ID of the computer tool call that produced the output. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The tool invocation context(s). + A computer screenshot image used with the computer use tool. - - `"direct"` + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - `"programmatic"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `allowed_tools: Optional[McpAllowedTools]` + - `"completed"` - List of allowed tool names or a filter object. + - `"incomplete"` - - `List[str]` + - `"failed"` - A string array of allowed tool names + - `"in_progress"` - - `class McpAllowedToolsMcpToolFilter: …` + - `type: Literal["computer_call_output"]` - A filter object to specify which tools are allowed. + The type of the computer tool call output. Always `computer_call_output`. - - `read_only: Optional[bool]` + - `"computer_call_output"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - - `tool_names: Optional[List[str]]` + The safety checks reported by the API that have been acknowledged by the + developer. - List of allowed tool names. + - `id: str` - - `authorization: Optional[str]` + The ID of the pending safety check. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `code: Optional[str]` - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + The type of the pending safety check. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `message: Optional[str]` - Currently supported `connector_id` values are: + Details about the pending safety check. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `agent: Optional[Agent]` - - `"connector_dropbox"` + The agent that produced this item. - - `"connector_gmail"` + - `agent_name: str` - - `"connector_googlecalendar"` + The canonical name of the agent that produced this item. - - `"connector_googledrive"` + - `created_by: Optional[str]` - - `"connector_microsoftteams"` + The identifier of the actor that created the item. - - `"connector_outlookcalendar"` + - `class BetaResponseReasoningItem: …` - - `"connector_outlookemail"` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `"connector_sharepoint"` + - `class Program: …` - - `defer_loading: Optional[bool]` + - `id: str` - Whether this MCP tool is deferred and discovered via tool search. + The unique ID of the program item. - - `headers: Optional[Dict[str, str]]` + - `call_id: str` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The stable call ID of the program item. - - `require_approval: Optional[McpRequireApproval]` + - `code: str` - Specify which of the MCP server's tools require approval. + The JavaScript source executed by programmatic tool calling. - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `fingerprint: str` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + Opaque program replay fingerprint that must be round-tripped. - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `type: Literal["program"]` - A filter object to specify which tools are allowed. + The type of the item. Always `program`. - - `read_only: Optional[bool]` + - `"program"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `agent: Optional[ProgramAgent]` - - `tool_names: Optional[List[str]]` + The agent that produced this item. - List of allowed tool names. + - `agent_name: str` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + The canonical name of the agent that produced this item. - A filter object to specify which tools are allowed. + - `class ProgramOutput: …` - - `read_only: Optional[bool]` + - `id: str` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The unique ID of the program output item. - - `tool_names: Optional[List[str]]` + - `call_id: str` - List of allowed tool names. + The call ID of the program item. - - `Literal["always", "never"]` + - `result: str` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The result produced by the program item. - - `"always"` + - `status: Literal["completed", "incomplete"]` - - `"never"` + The terminal status of the program output item. - - `server_description: Optional[str]` + - `"completed"` - Optional description of the MCP server, used to provide more context. + - `"incomplete"` - - `server_url: Optional[str]` + - `type: Literal["program_output"]` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The type of the item. Always `program_output`. - - `tunnel_id: Optional[str]` + - `"program_output"` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `agent: Optional[ProgramOutputAgent]` - - `class CodeInterpreter: …` + The agent that produced this item. - A tool that runs Python code to help generate a response to a prompt. + - `agent_name: str` - - `container: CodeInterpreterContainer` + The canonical name of the agent that produced this item. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `class BetaResponseToolSearchCall: …` - - `str` + - `id: str` - The container ID. + The unique ID of the tool search call item. - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `arguments: object` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Arguments used for the tool search call. - - `type: Literal["auto"]` + - `call_id: Optional[str]` - Always `auto`. + The unique ID of the tool search call generated by the model. - - `"auto"` + - `execution: Literal["server", "client"]` - - `file_ids: Optional[List[str]]` + Whether tool search was executed by the server or by the client. - An optional list of uploaded files to make available to your code. + - `"server"` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `"client"` - The memory limit for the code interpreter container. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"1g"` + The status of the tool search call item that was recorded. - - `"4g"` + - `"in_progress"` - - `"16g"` + - `"completed"` - - `"64g"` + - `"incomplete"` - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `type: Literal["tool_search_call"]` - Network access policy for the container. + The type of the item. Always `tool_search_call`. - - `class BetaContainerNetworkPolicyDisabled: …` + - `"tool_search_call"` - - `type: Literal["disabled"]` + - `agent: Optional[Agent]` - Disable outbound network access. Always `disabled`. + The agent that produced this item. - - `"disabled"` + - `agent_name: str` - - `class BetaContainerNetworkPolicyAllowlist: …` + The canonical name of the agent that produced this item. - - `allowed_domains: List[str]` + - `created_by: Optional[str]` - A list of allowed domains when type is `allowlist`. + The identifier of the actor that created the item. - - `type: Literal["allowlist"]` + - `class BetaResponseToolSearchOutputItem: …` - Allow outbound network access only to specified domains. Always `allowlist`. + - `id: str` - - `"allowlist"` + The unique ID of the tool search output item. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `call_id: Optional[str]` - Optional domain-scoped secrets for allowlisted domains. + The unique ID of the tool search call generated by the model. - - `domain: str` + - `execution: Literal["server", "client"]` - The domain associated with the secret. + Whether tool search was executed by the server or by the client. - - `name: str` + - `"server"` - The name of the secret to inject for the domain. + - `"client"` - - `value: str` + - `status: Literal["in_progress", "completed", "incomplete"]` - The secret value to inject for the domain. + The status of the tool search output item that was recorded. - - `type: Literal["code_interpreter"]` + - `"in_progress"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"completed"` - - `"code_interpreter"` + - `"incomplete"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `tools: List[BetaTool]` - The tool invocation context(s). + The loaded tool definitions returned by tool search. - - `"direct"` + - `class BetaFunctionTool: …` - - `"programmatic"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `class ProgrammaticToolCalling: …` + - `class BetaFileSearchTool: …` - - `type: Literal["programmatic_tool_calling"]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The type of the tool. Always `programmatic_tool_calling`. + - `class BetaComputerTool: …` - - `"programmatic_tool_calling"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class ImageGeneration: …` + - `class BetaComputerUsePreviewTool: …` - A tool that generates images using the GPT image models. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: Literal["image_generation"]` + - `class BetaWebSearchTool: …` - The type of the image generation tool. Always `image_generation`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"image_generation"` + - `class Mcp: …` - - `action: Optional[Literal["generate", "edit", "auto"]]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - Whether to generate a new image or edit an existing image. Default: `auto`. + - `class CodeInterpreter: …` - - `"generate"` + A tool that runs Python code to help generate a response to a prompt. - - `"edit"` + - `class ProgrammaticToolCalling: …` - - `"auto"` + - `class ImageGeneration: …` - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + A tool that generates images using the GPT image models. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `class LocalShell: …` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + A tool that allows the model to execute shell commands in a local environment. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `class BetaFunctionShellTool: …` - - `"transparent"` + A tool that allows the model to execute shell commands. - - `"opaque"` + - `class BetaCustomTool: …` - - `"auto"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `input_fidelity: Optional[Literal["high", "low"]]` + - `class BetaNamespaceTool: …` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + Groups function/custom tools under a shared namespace. - - `"high"` + - `class BetaToolSearchTool: …` - - `"low"` + Hosted or BYOT tool search configuration for deferred tools. - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + - `class BetaWebSearchPreviewTool: …` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `file_id: Optional[str]` + - `class BetaApplyPatchTool: …` - File ID for the mask image. + Allows the assistant to create, delete, or update files using unified diffs. - - `image_url: Optional[str]` + - `type: Literal["tool_search_output"]` - Base64-encoded mask image. + The type of the item. Always `tool_search_output`. - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + - `"tool_search_output"` - The image generation model to use. Default: `gpt-image-1`. + - `agent: Optional[Agent]` - - `str` + The agent that produced this item. - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `agent_name: str` - The image generation model to use. Default: `gpt-image-1`. + The canonical name of the agent that produced this item. - - `"gpt-image-1"` + - `created_by: Optional[str]` - - `"gpt-image-1-mini"` + The identifier of the actor that created the item. - - `"gpt-image-2"` + - `class AdditionalTools: …` - - `"gpt-image-2-2026-04-21"` + - `id: str` - - `"gpt-image-1.5"` + The unique ID of the additional tools item. - - `"chatgpt-image-latest"` + - `role: Literal["unknown", "user", "assistant", 5 more]` - - `moderation: Optional[Literal["auto", "low"]]` + The role that provided the additional tools. - Moderation level for the generated image. Default: `auto`. + - `"unknown"` - - `"auto"` + - `"user"` - - `"low"` + - `"assistant"` - - `output_compression: Optional[int]` + - `"system"` - Compression level for the output image. Default: 100. + - `"critic"` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + - `"discriminator"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"developer"` - - `"png"` + - `"tool"` - - `"webp"` + - `tools: List[BetaTool]` - - `"jpeg"` + The additional tool definitions made available at this item. - - `partial_images: Optional[int]` + - `class BetaFunctionTool: …` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + - `class BetaFileSearchTool: …` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `"low"` + - `class BetaComputerTool: …` - - `"medium"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"high"` + - `class BetaComputerUsePreviewTool: …` - - `"auto"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + - `class BetaWebSearchTool: …` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `str` + - `class Mcp: …` - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `class CodeInterpreter: …` - - `"1024x1024"` + A tool that runs Python code to help generate a response to a prompt. - - `"1024x1536"` + - `class ProgrammaticToolCalling: …` - - `"1536x1024"` + - `class ImageGeneration: …` - - `"auto"` + A tool that generates images using the GPT image models. - `class LocalShell: …` A tool that allows the model to execute shell commands in a local environment. - - `type: Literal["local_shell"]` + - `class BetaFunctionShellTool: …` - The type of the local shell tool. Always `local_shell`. + A tool that allows the model to execute shell commands. - - `"local_shell"` + - `class BetaCustomTool: …` - - `class BetaFunctionShellTool: …` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - A tool that allows the model to execute shell commands. + - `class BetaNamespaceTool: …` - - `type: Literal["shell"]` + Groups function/custom tools under a shared namespace. - The type of the shell tool. Always `shell`. + - `class BetaToolSearchTool: …` - - `"shell"` + Hosted or BYOT tool search configuration for deferred tools. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `class BetaWebSearchPreviewTool: …` - The tool invocation context(s). + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"direct"` + - `class BetaApplyPatchTool: …` - - `"programmatic"` + Allows the assistant to create, delete, or update files using unified diffs. - - `environment: Optional[Environment]` + - `type: Literal["additional_tools"]` - - `class BetaContainerAuto: …` + The type of the item. Always `additional_tools`. - - `type: Literal["container_auto"]` + - `"additional_tools"` - Automatically creates a container for this request + - `agent: Optional[AdditionalToolsAgent]` - - `"container_auto"` + The agent that produced this item. - - `file_ids: Optional[List[str]]` + - `agent_name: str` - An optional list of uploaded files to make available to your code. + The canonical name of the agent that produced this item. - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `class BetaResponseCompactionItem: …` - The memory limit for the container. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `"1g"` + - `id: str` - - `"4g"` + The unique ID of the compaction item. - - `"16g"` + - `encrypted_content: str` - - `"64g"` + The encrypted content that was produced by compaction. - - `network_policy: Optional[NetworkPolicy]` + - `type: Literal["compaction"]` - Network access policy for the container. + The type of the item. Always `compaction`. - - `class BetaContainerNetworkPolicyDisabled: …` + - `"compaction"` - - `class BetaContainerNetworkPolicyAllowlist: …` + - `agent: Optional[Agent]` - - `skills: Optional[List[Skill]]` + The agent that produced this item. - An optional list of skills referenced by id or inline data. + - `agent_name: str` - - `class BetaSkillReference: …` + The canonical name of the agent that produced this item. - - `skill_id: str` + - `created_by: Optional[str]` - The ID of the referenced skill. + The identifier of the actor that created the item. - - `type: Literal["skill_reference"]` + - `class ImageGenerationCall: …` - References a skill created with the /v1/skills endpoint. + An image generation request made by the model. - - `"skill_reference"` + - `id: str` - - `version: Optional[str]` + The unique ID of the image generation call. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `result: Optional[str]` - - `class BetaInlineSkill: …` + The generated image encoded in base64. + + - `status: Literal["in_progress", "completed", "generating", "failed"]` + + The status of the image generation call. + + - `"in_progress"` - - `description: str` + - `"completed"` - The description of the skill. + - `"generating"` - - `name: str` + - `"failed"` - The name of the skill. + - `type: Literal["image_generation_call"]` - - `source: BetaInlineSkillSource` + The type of the image generation call. Always `image_generation_call`. - Inline skill payload + - `"image_generation_call"` - - `data: str` + - `agent: Optional[ImageGenerationCallAgent]` - Base64-encoded skill zip bundle. + The agent that produced this item. - - `media_type: Literal["application/zip"]` + - `agent_name: str` - The media type of the inline skill payload. Must be `application/zip`. + The canonical name of the agent that produced this item. - - `"application/zip"` + - `class BetaResponseCodeInterpreterToolCall: …` - - `type: Literal["base64"]` + A tool call to run code. - The type of the inline skill source. Must be `base64`. + - `class LocalShellCall: …` - - `"base64"` + A tool call to run a command on the local shell. - - `type: Literal["inline"]` + - `id: str` - Defines an inline skill for this request. + The unique ID of the local shell call. - - `"inline"` + - `action: LocalShellCallAction` - - `class BetaLocalEnvironment: …` + Execute a shell command on the server. - - `type: Literal["local"]` + - `command: List[str]` - Use a local computer environment. + The command to run. - - `"local"` + - `env: Dict[str, str]` - - `skills: Optional[List[BetaLocalSkill]]` + Environment variables to set for the command. - An optional list of skills. + - `type: Literal["exec"]` - - `description: str` + The type of the local shell action. Always `exec`. - The description of the skill. + - `"exec"` - - `name: str` + - `timeout_ms: Optional[int]` - The name of the skill. + Optional timeout in milliseconds for the command. - - `path: str` + - `user: Optional[str]` - The path to the directory containing the skill. + Optional user to run the command as. - - `class BetaContainerReference: …` + - `working_directory: Optional[str]` - - `container_id: str` + Optional working directory to run the command in. - The ID of the referenced container. + - `call_id: str` - - `type: Literal["container_reference"]` + The unique ID of the local shell tool call generated by the model. - References a container created with the /v1/containers endpoint + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"container_reference"` + The status of the local shell call. - - `class BetaCustomTool: …` + - `"in_progress"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"completed"` - - `name: str` + - `"incomplete"` - The name of the custom tool, used to identify it in tool calls. + - `type: Literal["local_shell_call"]` - - `type: Literal["custom"]` + The type of the local shell call. Always `local_shell_call`. - The type of the custom tool. Always `custom`. + - `"local_shell_call"` - - `"custom"` + - `agent: Optional[LocalShellCallAgent]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The agent that produced this item. - The tool invocation context(s). + - `agent_name: str` - - `"direct"` + The canonical name of the agent that produced this item. - - `"programmatic"` + - `class LocalShellCallOutput: …` - - `defer_loading: Optional[bool]` + The output of a local shell tool call. - Whether this tool should be deferred and discovered via tool search. + - `id: str` - - `description: Optional[str]` + The unique ID of the local shell tool call generated by the model. - Optional description of the custom tool, used to provide more context. + - `output: str` - - `format: Optional[Format]` + A JSON string of the output of the local shell tool call. - The input format for the custom tool. Default is unconstrained text. + - `type: Literal["local_shell_call_output"]` - - `class FormatText: …` + The type of the local shell tool call output. Always `local_shell_call_output`. - Unconstrained free-form text. + - `"local_shell_call_output"` - - `type: Literal["text"]` + - `agent: Optional[LocalShellCallOutputAgent]` - Unconstrained text format. Always `text`. + The agent that produced this item. - - `"text"` + - `agent_name: str` - - `class FormatGrammar: …` + The canonical name of the agent that produced this item. - A grammar defined by the user. + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `definition: str` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The grammar definition. + - `"in_progress"` - - `syntax: Literal["lark", "regex"]` + - `"completed"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"incomplete"` - - `"lark"` + - `class BetaResponseFunctionShellToolCall: …` - - `"regex"` + A tool call that executes one or more shell commands in a managed environment. - - `type: Literal["grammar"]` + - `id: str` - Grammar format. Always `grammar`. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"grammar"` + - `action: Action` - - `class BetaNamespaceTool: …` + The shell commands and limits that describe how to run the tool call. - Groups function/custom tools under a shared namespace. + - `commands: List[str]` - - `description: str` + - `max_output_length: Optional[int]` - A description of the namespace shown to the model. + Optional maximum number of characters to return from each command. - - `name: str` + - `timeout_ms: Optional[int]` - The namespace name used in tool calls (for example, `crm`). + Optional timeout in milliseconds for the commands. - - `tools: List[Tool]` + - `call_id: str` - The function/custom tools available inside this namespace. + The unique ID of the shell tool call generated by the model. - - `class ToolFunction: …` + - `environment: Optional[Environment]` - - `name: str` + Represents the use of a local environment to perform shell actions. - - `type: Literal["function"]` + - `class BetaResponseLocalEnvironment: …` - - `"function"` + Represents the use of a local environment to perform shell actions. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["local"]` - The tool invocation context(s). + The environment type. Always `local`. - - `"direct"` + - `"local"` - - `"programmatic"` + - `class BetaResponseContainerReference: …` - - `defer_loading: Optional[bool]` + Represents a container created with /v1/containers. - Whether this function should be deferred and discovered via tool search. + - `container_id: str` - - `description: Optional[str]` + - `type: Literal["container_reference"]` - - `output_schema: Optional[Dict[str, object]]` + The environment type. Always `container_reference`. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `"container_reference"` - - `parameters: Optional[object]` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `strict: Optional[bool]` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `"in_progress"` - - `class BetaCustomTool: …` + - `"completed"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"incomplete"` - - `type: Literal["namespace"]` + - `type: Literal["shell_call"]` - The type of the tool. Always `namespace`. + The type of the item. Always `shell_call`. - - `"namespace"` + - `"shell_call"` - - `class BetaToolSearchTool: …` + - `agent: Optional[Agent]` - Hosted or BYOT tool search configuration for deferred tools. + The agent that produced this item. - - `type: Literal["tool_search"]` + - `agent_name: str` - The type of the tool. Always `tool_search`. + The canonical name of the agent that produced this item. - - `"tool_search"` + - `caller: Optional[Caller]` - - `description: Optional[str]` + The execution context that produced this tool call. - Description shown to the model for a client-executed tool search tool. + - `class CallerDirect: …` - - `execution: Optional[Literal["server", "client"]]` + - `type: Literal["direct"]` - Whether tool search is executed by the server or by the client. + - `"direct"` - - `"server"` + - `class CallerProgram: …` - - `"client"` + - `caller_id: str` - - `parameters: Optional[object]` + The call ID of the program item that produced this tool call. - Parameter schema for a client-executed tool search tool. + - `type: Literal["program"]` - - `class BetaWebSearchPreviewTool: …` + - `"program"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `created_by: Optional[str]` - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + The ID of the entity that created this tool call. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `class BetaResponseFunctionShellToolCallOutput: …` - - `"web_search_preview"` + The output of a shell tool call that was emitted. - - `"web_search_preview_2025_03_11"` + - `id: str` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + The unique ID of the shell call output. Populated when this item is returned via API. - - `"text"` + - `call_id: str` - - `"image"` + The unique ID of the shell tool call generated by the model. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `max_output_length: Optional[int]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `"low"` + - `output: List[Output]` - - `"medium"` + An array of shell call output contents - - `"high"` + - `outcome: OutputOutcome` - - `user_location: Optional[UserLocation]` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The user's location. + - `class OutputOutcomeTimeout: …` - - `type: Literal["approximate"]` + Indicates that the shell call exceeded its configured time limit. - The type of location approximation. Always `approximate`. + - `type: Literal["timeout"]` - - `"approximate"` + The outcome type. Always `timeout`. - - `city: Optional[str]` + - `"timeout"` - Free text input for the city of the user, e.g. `San Francisco`. + - `class OutputOutcomeExit: …` - - `country: Optional[str]` + Indicates that the shell commands finished and returned an exit code. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `exit_code: int` - - `region: Optional[str]` + Exit code from the shell process. - Free text input for the region of the user, e.g. `California`. + - `type: Literal["exit"]` - - `timezone: Optional[str]` + The outcome type. Always `exit`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"exit"` - - `class BetaApplyPatchTool: …` + - `stderr: str` - Allows the assistant to create, delete, or update files using unified diffs. + The standard error output that was captured. - - `type: Literal["apply_patch"]` + - `stdout: str` - The type of the tool. Always `apply_patch`. + The standard output that was captured. - - `"apply_patch"` + - `created_by: Optional[str]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The identifier of the actor that created the item. - The tool invocation context(s). + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"direct"` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `"programmatic"` + - `"in_progress"` - - `type: Literal["tool_search_output"]` + - `"completed"` - The item type. Always `tool_search_output`. + - `"incomplete"` - - `"tool_search_output"` + - `type: Literal["shell_call_output"]` - - `id: Optional[str]` + The type of the shell call output. Always `shell_call_output`. - The unique ID of this tool search output. + - `"shell_call_output"` - `agent: Optional[Agent]` @@ -129679,115 +140597,111 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `call_id: Optional[str]` - - The unique ID of the tool search call generated by the model. + - `caller: Optional[Caller]` - - `execution: Optional[Literal["server", "client"]]` + The execution context that produced this tool call. - Whether tool search was executed by the server or by the client. + - `class CallerDirect: …` - - `"server"` + - `type: Literal["direct"]` - - `"client"` + - `"direct"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `class CallerProgram: …` - The status of the tool search output. + - `caller_id: str` - - `"in_progress"` + The call ID of the program item that produced this tool call. - - `"completed"` + - `type: Literal["program"]` - - `"incomplete"` + - `"program"` - - `class AdditionalTools: …` + - `created_by: Optional[str]` - - `role: Literal["developer"]` + The identifier of the actor that created the item. - The role that provided the additional tools. Only `developer` is supported. + - `class BetaResponseApplyPatchToolCall: …` - - `"developer"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `tools: List[BetaTool]` + - `id: str` - A list of additional tools made available at this item. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `class BetaFunctionTool: …` + - `call_id: str` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The unique ID of the apply patch tool call generated by the model. - - `class BetaFileSearchTool: …` + - `operation: Operation` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `class BetaComputerTool: …` + - `class OperationCreateFile: …` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Instruction describing how to create a file via the apply_patch tool. - - `class BetaComputerUsePreviewTool: …` + - `diff: str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Diff to apply. - - `class BetaWebSearchTool: …` + - `path: str` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Path of the file to create. - - `class Mcp: …` + - `type: Literal["create_file"]` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + Create a new file with the provided diff. - - `class CodeInterpreter: …` + - `"create_file"` - A tool that runs Python code to help generate a response to a prompt. + - `class OperationDeleteFile: …` - - `class ProgrammaticToolCalling: …` + Instruction describing how to delete a file via the apply_patch tool. - - `class ImageGeneration: …` + - `path: str` - A tool that generates images using the GPT image models. + Path of the file to delete. - - `class LocalShell: …` + - `type: Literal["delete_file"]` - A tool that allows the model to execute shell commands in a local environment. + Delete the specified file. - - `class BetaFunctionShellTool: …` + - `"delete_file"` - A tool that allows the model to execute shell commands. + - `class OperationUpdateFile: …` - - `class BetaCustomTool: …` + Instruction describing how to update a file via the apply_patch tool. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `diff: str` - - `class BetaNamespaceTool: …` + Diff to apply. - Groups function/custom tools under a shared namespace. + - `path: str` - - `class BetaToolSearchTool: …` + Path of the file to update. - Hosted or BYOT tool search configuration for deferred tools. + - `type: Literal["update_file"]` - - `class BetaWebSearchPreviewTool: …` + Update an existing file with the provided diff. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"update_file"` - - `class BetaApplyPatchTool: …` + - `status: Literal["in_progress", "completed"]` - Allows the assistant to create, delete, or update files using unified diffs. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `type: Literal["additional_tools"]` + - `"in_progress"` - The item type. Always `additional_tools`. + - `"completed"` - - `"additional_tools"` + - `type: Literal["apply_patch_call"]` - - `id: Optional[str]` + The type of the item. Always `apply_patch_call`. - The unique ID of this additional tools item. + - `"apply_patch_call"` - - `agent: Optional[AdditionalToolsAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -129795,36 +140709,55 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseReasoningItem: …` + - `caller: Optional[Caller]` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The execution context that produced this tool call. - - `id: str` + - `class CallerDirect: …` - The unique identifier of the reasoning content. + - `type: Literal["direct"]` - - `summary: List[Summary]` + - `"direct"` - Reasoning summary content. + - `class CallerProgram: …` - - `text: str` + - `caller_id: str` - A summary of the reasoning output from the model so far. + The call ID of the program item that produced this tool call. - - `type: Literal["summary_text"]` + - `type: Literal["program"]` - The type of the object. Always `summary_text`. + - `"program"` - - `"summary_text"` + - `created_by: Optional[str]` - - `type: Literal["reasoning"]` + The ID of the entity that created this tool call. - The type of the object. Always `reasoning`. + - `class BetaResponseApplyPatchToolCallOutput: …` - - `"reasoning"` + The output emitted by an apply patch tool call. + + - `id: str` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `call_id: str` + + The unique ID of the apply patch tool call generated by the model. + + - `status: Literal["completed", "failed"]` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: Literal["apply_patch_call_output"]` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` - `agent: Optional[Agent]` @@ -129834,55 +140767,61 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `content: Optional[List[Content]]` + - `caller: Optional[Caller]` - Reasoning text content. + The execution context that produced this tool call. - - `text: str` + - `class CallerDirect: …` - The reasoning text from the model. + - `type: Literal["direct"]` - - `type: Literal["reasoning_text"]` + - `"direct"` - The type of the reasoning text. Always `reasoning_text`. + - `class CallerProgram: …` - - `"reasoning_text"` + - `caller_id: str` - - `encrypted_content: Optional[str]` + The call ID of the program item that produced this tool call. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `type: Literal["program"]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"program"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `created_by: Optional[str]` - - `"in_progress"` + The ID of the entity that created this tool call output. - - `"completed"` + - `output: Optional[str]` - - `"incomplete"` + Optional textual output returned by the apply patch tool. - - `class BetaResponseCompactionItemParam: …` + - `class McpCall: …` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + An invocation of a tool on an MCP server. - - `encrypted_content: str` + - `id: str` - The encrypted content of the compaction summary. + The unique ID of the tool call. - - `type: Literal["compaction"]` + - `arguments: str` - The type of the item. Always `compaction`. + A JSON string of the arguments passed to the tool. - - `"compaction"` + - `name: str` - - `id: Optional[str]` + The name of the tool that was run. - The ID of the compaction item. + - `server_label: str` - - `agent: Optional[Agent]` + The label of the MCP server running the tool. + + - `type: Literal["mcp_call"]` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `agent: Optional[McpCallAgent]` The agent that produced this item. @@ -129890,114 +140829,110 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ImageGenerationCall: …` + - `approval_request_id: Optional[str]` - An image generation request made by the model. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `id: str` + - `error: Optional[str]` - The unique ID of the image generation call. + The error from the tool call, if any. - - `result: Optional[str]` + - `output: Optional[str]` - The generated image encoded in base64. + The output from the tool call. - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - The status of the image generation call. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `"in_progress"` - `"completed"` - - `"generating"` - - - `"failed"` - - - `type: Literal["image_generation_call"]` + - `"incomplete"` - The type of the image generation call. Always `image_generation_call`. + - `"calling"` - - `"image_generation_call"` + - `"failed"` - - `agent: Optional[ImageGenerationCallAgent]` + - `class McpListTools: …` - The agent that produced this item. + A list of tools available on an MCP server. - - `agent_name: str` + - `id: str` - The canonical name of the agent that produced this item. + The unique ID of the list. - - `class BetaResponseCodeInterpreterToolCall: …` + - `server_label: str` - A tool call to run code. + The label of the MCP server. - - `id: str` + - `tools: List[McpListToolsTool]` - The unique ID of the code interpreter tool call. + The tools available on the server. - - `code: Optional[str]` + - `input_schema: object` - The code to run, or null if not available. + The JSON schema describing the tool's input. - - `container_id: str` + - `name: str` - The ID of the container used to run the code. + The name of the tool. - - `outputs: Optional[List[Output]]` + - `annotations: Optional[object]` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Additional annotations about the tool. - - `class OutputLogs: …` + - `description: Optional[str]` - The logs output from the code interpreter. + The description of the tool. - - `logs: str` + - `type: Literal["mcp_list_tools"]` - The logs output from the code interpreter. + The type of the item. Always `mcp_list_tools`. - - `type: Literal["logs"]` + - `"mcp_list_tools"` - The type of the output. Always `logs`. + - `agent: Optional[McpListToolsAgent]` - - `"logs"` + The agent that produced this item. - - `class OutputImage: …` + - `agent_name: str` - The image output from the code interpreter. + The canonical name of the agent that produced this item. - - `type: Literal["image"]` + - `error: Optional[str]` - The type of the output. Always `image`. + Error message if the server could not list tools. - - `"image"` + - `class McpApprovalRequest: …` - - `url: str` + A request for human approval of a tool invocation. - The URL of the image output from the code interpreter. + - `id: str` - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + The unique ID of the approval request. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `arguments: str` - - `"in_progress"` + A JSON string of arguments for the tool. - - `"completed"` + - `name: str` - - `"incomplete"` + The name of the tool to run. - - `"interpreting"` + - `server_label: str` - - `"failed"` + The label of the MCP server making the request. - - `type: Literal["code_interpreter_call"]` + - `type: Literal["mcp_approval_request"]` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the item. Always `mcp_approval_request`. - - `"code_interpreter_call"` + - `"mcp_approval_request"` - - `agent: Optional[Agent]` + - `agent: Optional[McpApprovalRequestAgent]` The agent that produced this item. @@ -130005,51 +140940,56 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class LocalShellCall: …` + - `class McpApprovalResponse: …` - A tool call to run a command on the local shell. + A response to an MCP approval request. - `id: str` - The unique ID of the local shell call. + The unique ID of the approval response - - `action: LocalShellCallAction` + - `approval_request_id: str` - Execute a shell command on the server. + The ID of the approval request being answered. - - `command: List[str]` + - `approve: bool` - The command to run. + Whether the request was approved. - - `env: Dict[str, str]` + - `type: Literal["mcp_approval_response"]` - Environment variables to set for the command. + The type of the item. Always `mcp_approval_response`. - - `type: Literal["exec"]` + - `"mcp_approval_response"` - The type of the local shell action. Always `exec`. + - `agent: Optional[McpApprovalResponseAgent]` - - `"exec"` + The agent that produced this item. - - `timeout_ms: Optional[int]` + - `agent_name: str` - Optional timeout in milliseconds for the command. + The canonical name of the agent that produced this item. - - `user: Optional[str]` + - `reason: Optional[str]` - Optional user to run the command as. + Optional reason for the decision. - - `working_directory: Optional[str]` + - `class BetaResponseCustomToolCall: …` - Optional working directory to run the command in. + A call to a custom tool created by the model. - - `call_id: str` + - `class BetaResponseCustomToolCallOutputItem: …` - The unique ID of the local shell tool call generated by the model. + The output of a custom tool call from your code, being sent back to the model. + + - `id: str` + + The unique ID of the custom tool call output item. - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the local shell call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -130057,5264 +140997,5417 @@ print(compacted_response) - `"incomplete"` - - `type: Literal["local_shell_call"]` + - `created_by: Optional[str]` - The type of the local shell call. Always `local_shell_call`. + The identifier of the actor that created the item. - - `"local_shell_call"` + - `parallel_tool_calls: bool` - - `agent: Optional[LocalShellCallAgent]` + Whether to allow the model to run tool calls in parallel. - The agent that produced this item. + - `temperature: Optional[float]` - - `agent_name: str` + 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. + We generally recommend altering this or `top_p` but not both. - The canonical name of the agent that produced this item. + - `tool_choice: ToolChoice` - - `class LocalShellCallOutput: …` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - The output of a local shell tool call. + - `Literal["none", "auto", "required"]` - - `id: str` + - `"none"` - The unique ID of the local shell tool call generated by the model. + - `"auto"` - - `output: str` + - `"required"` - A JSON string of the output of the local shell tool call. + - `class BetaToolChoiceAllowed: …` - - `type: Literal["local_shell_call_output"]` + Constrains the tools available to the model to a pre-defined set. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `mode: Literal["auto", "required"]` - - `"local_shell_call_output"` + Constrains the tools available to the model to a pre-defined set. - - `agent: Optional[LocalShellCallOutputAgent]` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The agent that produced this item. + `required` requires the model to call one or more of the allowed tools. - - `agent_name: str` + - `"auto"` - The canonical name of the agent that produced this item. + - `"required"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `tools: List[Dict[str, object]]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + A list of tool definitions that the model should be allowed to call. - - `"in_progress"` + For the Responses API, the list of tool definitions might look like: - - `"completed"` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `"incomplete"` + - `type: Literal["allowed_tools"]` - - `class ShellCall: …` + Allowed tool configuration type. Always `allowed_tools`. - A tool representing a request to execute one or more shell commands. + - `"allowed_tools"` - - `action: ShellCallAction` + - `class BetaToolChoiceTypes: …` - The shell commands and limits that describe how to run the tool call. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `commands: List[str]` + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` - Ordered shell commands for the execution environment to run. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `max_output_length: Optional[int]` + Allowed values are: - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `timeout_ms: Optional[int]` + - `"file_search"` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `"web_search_preview"` - - `call_id: str` + - `"computer"` - The unique ID of the shell tool call generated by the model. + - `"computer_use_preview"` - - `type: Literal["shell_call"]` + - `"computer_use"` - The type of the item. Always `shell_call`. + - `"web_search_preview_2025_03_11"` - - `"shell_call"` + - `"image_generation"` - - `id: Optional[str]` + - `"code_interpreter"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `class BetaToolChoiceFunction: …` - - `agent: Optional[ShellCallAgent]` + Use this option to force the model to call a specific function. - The agent that produced this item. + - `name: str` - - `agent_name: str` + The name of the function to call. - The canonical name of the agent that produced this item. + - `type: Literal["function"]` - - `caller: Optional[ShellCallCaller]` + For function calling, the type is always `function`. - The execution context that produced this tool call. + - `"function"` - - `class ShellCallCallerDirect: …` + - `class BetaToolChoiceMcp: …` - - `type: Literal["direct"]` + Use this option to force the model to call a specific tool on a remote MCP server. - The caller type. Always `direct`. + - `server_label: str` - - `"direct"` + The label of the MCP server to use. - - `class ShellCallCallerProgram: …` + - `type: Literal["mcp"]` - - `caller_id: str` + For MCP tools, the type is always `mcp`. - The call ID of the program item that produced this tool call. + - `"mcp"` - - `type: Literal["program"]` + - `name: Optional[str]` - The caller type. Always `program`. + The name of the tool to call on the server. - - `"program"` + - `class BetaToolChoiceCustom: …` - - `environment: Optional[ShellCallEnvironment]` + Use this option to force the model to call a specific custom tool. - The environment to execute the shell commands in. + - `name: str` - - `class BetaLocalEnvironment: …` + The name of the custom tool to call. - - `class BetaContainerReference: …` + - `type: Literal["custom"]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + For custom tool calling, the type is always `custom`. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"custom"` - - `"in_progress"` + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` - - `"completed"` + - `type: Literal["programmatic_tool_calling"]` - - `"incomplete"` + The tool to call. Always `programmatic_tool_calling`. - - `class ShellCallOutput: …` + - `"programmatic_tool_calling"` - The streamed output items emitted by a shell tool call. + - `class BetaToolChoiceApplyPatch: …` - - `call_id: str` + Forces the model to call the apply_patch tool when executing a tool call. - The unique ID of the shell tool call generated by the model. + - `type: Literal["apply_patch"]` - - `output: List[BetaResponseFunctionShellCallOutputContent]` + The tool to call. Always `apply_patch`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"apply_patch"` - - `outcome: Outcome` + - `class BetaToolChoiceShell: …` - The exit or timeout outcome associated with this shell call. + Forces the model to call the shell tool when a tool call is required. - - `class OutcomeTimeout: …` + - `type: Literal["shell"]` - Indicates that the shell call exceeded its configured time limit. + The tool to call. Always `shell`. - - `type: Literal["timeout"]` + - `"shell"` - The outcome type. Always `timeout`. + - `tools: List[BetaTool]` - - `"timeout"` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `class OutcomeExit: …` + We support the following categories of tools: - Indicates that the shell commands finished and returned an exit code. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `exit_code: int` + - `class BetaFunctionTool: …` - The exit code returned by the shell process. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `type: Literal["exit"]` + - `class BetaFileSearchTool: …` - The outcome type. Always `exit`. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `"exit"` + - `class BetaComputerTool: …` - - `stderr: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Captured stderr output for the shell call. + - `class BetaComputerUsePreviewTool: …` - - `stdout: str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Captured stdout output for the shell call. + - `class BetaWebSearchTool: …` - - `type: Literal["shell_call_output"]` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The type of the item. Always `shell_call_output`. + - `class Mcp: …` - - `"shell_call_output"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `id: Optional[str]` + - `class CodeInterpreter: …` - The unique ID of the shell tool call output. Populated when this item is returned via API. + A tool that runs Python code to help generate a response to a prompt. - - `agent: Optional[ShellCallOutputAgent]` + - `class ProgrammaticToolCalling: …` - The agent that produced this item. + - `class ImageGeneration: …` - - `agent_name: str` + A tool that generates images using the GPT image models. - The canonical name of the agent that produced this item. + - `class LocalShell: …` - - `caller: Optional[ShellCallOutputCaller]` + A tool that allows the model to execute shell commands in a local environment. - The execution context that produced this tool call. + - `class BetaFunctionShellTool: …` - - `class ShellCallOutputCallerDirect: …` + A tool that allows the model to execute shell commands. - - `type: Literal["direct"]` + - `class BetaCustomTool: …` - The caller type. Always `direct`. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `"direct"` + - `class BetaNamespaceTool: …` - - `class ShellCallOutputCallerProgram: …` + Groups function/custom tools under a shared namespace. - - `caller_id: str` + - `class BetaToolSearchTool: …` - The call ID of the program item that produced this tool call. + Hosted or BYOT tool search configuration for deferred tools. - - `type: Literal["program"]` + - `class BetaWebSearchPreviewTool: …` - The caller type. Always `program`. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"program"` + - `class BetaApplyPatchTool: …` - - `max_output_length: Optional[int]` + Allows the assistant to create, delete, or update files using unified diffs. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `top_p: Optional[float]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + 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. - The status of the shell call output. + We generally recommend altering this or `temperature` but not both. - - `"in_progress"` + - `background: Optional[bool]` - - `"completed"` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `"incomplete"` + - `completed_at: Optional[float]` - - `class ApplyPatchCall: …` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - A tool call representing a request to create, delete, or update files using diff patches. + - `conversation: Optional[Conversation]` - - `call_id: str` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The unique ID of the apply patch tool call generated by the model. + - `id: str` - - `operation: ApplyPatchCallOperation` + The unique ID of the conversation that this response was associated with. - The specific create, delete, or update instruction for the apply_patch tool call. + - `max_output_tokens: Optional[int]` - - `class ApplyPatchCallOperationCreateFile: …` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - Instruction for creating a new file via the apply_patch tool. + - `max_tool_calls: Optional[int]` - - `diff: str` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - Unified diff content to apply when creating the file. + - `moderation: Optional[Moderation]` - - `path: str` + Moderation results for the response input and output, if moderated completions were requested. - Path of the file to create relative to the workspace root. + - `input: ModerationInput` - - `type: Literal["create_file"]` + Moderation for the response input. - The operation type. Always `create_file`. + - `class ModerationInputModerationResult: …` - - `"create_file"` + A moderation result produced for the response input or output. - - `class ApplyPatchCallOperationDeleteFile: …` + - `categories: Dict[str, bool]` - Instruction for deleting an existing file via the apply_patch tool. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `path: str` + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - Path of the file to delete relative to the workspace root. + Which modalities of input are reflected by the score for each category. - - `type: Literal["delete_file"]` + - `"text"` - The operation type. Always `delete_file`. + - `"image"` - - `"delete_file"` + - `category_scores: Dict[str, float]` - - `class ApplyPatchCallOperationUpdateFile: …` + A dictionary of moderation categories to scores. - Instruction for updating an existing file via the apply_patch tool. + - `flagged: bool` - - `diff: str` + A boolean indicating whether the content was flagged by any category. - Unified diff content to apply to the existing file. + - `model: str` - - `path: str` + The moderation model that produced this result. - Path of the file to update relative to the workspace root. + - `type: Literal["moderation_result"]` - - `type: Literal["update_file"]` + The object type, which was always `moderation_result` for successful moderation results. - The operation type. Always `update_file`. + - `"moderation_result"` - - `"update_file"` + - `class ModerationInputError: …` - - `status: Literal["in_progress", "completed"]` + An error produced while attempting moderation for the response input or output. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `code: str` - - `"in_progress"` + The error code. + + - `message: str` + + The error message. - - `"completed"` + - `type: Literal["error"]` - - `type: Literal["apply_patch_call"]` + The object type, which was always `error` for moderation failures. - The type of the item. Always `apply_patch_call`. + - `"error"` - - `"apply_patch_call"` + - `output: ModerationOutput` - - `id: Optional[str]` + Moderation for the response output. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `class ModerationOutputModerationResult: …` - - `agent: Optional[ApplyPatchCallAgent]` + A moderation result produced for the response input or output. - The agent that produced this item. + - `categories: Dict[str, bool]` - - `agent_name: str` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The canonical name of the agent that produced this item. + - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` - - `caller: Optional[ApplyPatchCallCaller]` + Which modalities of input are reflected by the score for each category. - The execution context that produced this tool call. + - `"text"` - - `class ApplyPatchCallCallerDirect: …` + - `"image"` - - `type: Literal["direct"]` + - `category_scores: Dict[str, float]` - The caller type. Always `direct`. + A dictionary of moderation categories to scores. - - `"direct"` + - `flagged: bool` - - `class ApplyPatchCallCallerProgram: …` + A boolean indicating whether the content was flagged by any category. - - `caller_id: str` + - `model: str` - The call ID of the program item that produced this tool call. + The moderation model that produced this result. - - `type: Literal["program"]` + - `type: Literal["moderation_result"]` - The caller type. Always `program`. + The object type, which was always `moderation_result` for successful moderation results. - - `"program"` + - `"moderation_result"` - - `class ApplyPatchCallOutput: …` + - `class ModerationOutputError: …` - The streamed output emitted by an apply patch tool call. + An error produced while attempting moderation for the response input or output. - - `call_id: str` + - `code: str` - The unique ID of the apply patch tool call generated by the model. + The error code. - - `status: Literal["completed", "failed"]` + - `message: str` - The status of the apply patch tool call output. One of `completed` or `failed`. + The error message. - - `"completed"` + - `type: Literal["error"]` - - `"failed"` + The object type, which was always `error` for moderation failures. - - `type: Literal["apply_patch_call_output"]` + - `"error"` - The type of the item. Always `apply_patch_call_output`. + - `previous_response_id: Optional[str]` - - `"apply_patch_call_output"` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `id: Optional[str]` + - `prompt: Optional[BetaResponsePrompt]` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `agent: Optional[ApplyPatchCallOutputAgent]` + - `id: str` - The agent that produced this item. + The unique identifier of the prompt template to use. - - `agent_name: str` + - `variables: Optional[Dict[str, Variables]]` - The canonical name of the agent that produced this item. + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `caller: Optional[ApplyPatchCallOutputCaller]` + - `str` - The execution context that produced this tool call. + - `class BetaResponseInputText: …` - - `class ApplyPatchCallOutputCallerDirect: …` + A text input to the model. - - `type: Literal["direct"]` + - `class BetaResponseInputImage: …` - The caller type. Always `direct`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"direct"` + - `class BetaResponseInputFile: …` - - `class ApplyPatchCallOutputCallerProgram: …` + A file input to the model. - - `caller_id: str` + - `version: Optional[str]` - The call ID of the program item that produced this tool call. + Optional version of the prompt template. - - `type: Literal["program"]` + - `prompt_cache_key: Optional[str]` - The caller type. Always `program`. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `"program"` + - `prompt_cache_options: Optional[PromptCacheOptions]` - - `output: Optional[str]` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `mode: Literal["implicit", "explicit"]` - - `class McpListTools: …` + Whether implicit prompt-cache breakpoints were enabled. - A list of tools available on an MCP server. + - `"implicit"` - - `id: str` + - `"explicit"` - The unique ID of the list. + - `ttl: Literal["30m"]` - - `server_label: str` + The minimum lifetime applied to each cache breakpoint. - The label of the MCP server. + - `"30m"` - - `tools: List[McpListToolsTool]` + - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` - The tools available on the server. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `input_schema: object` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - The JSON schema describing the tool's input. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `name: str` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The name of the tool. + - `"in_memory"` - - `annotations: Optional[object]` + - `"24h"` - Additional annotations about the tool. + - `reasoning: Optional[Reasoning]` - - `description: Optional[str]` + **gpt-5 and o-series models only** - The description of the tool. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `type: Literal["mcp_list_tools"]` + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` - The type of the item. Always `mcp_list_tools`. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `"mcp_list_tools"` + - `"auto"` - - `agent: Optional[McpListToolsAgent]` + - `"current_turn"` - The agent that produced this item. + - `"all_turns"` - - `agent_name: str` + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` - The canonical name of the agent that produced this item. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `error: Optional[str]` + - `"none"` - Error message if the server could not list tools. + - `"minimal"` - - `class McpApprovalRequest: …` + - `"low"` - A request for human approval of a tool invocation. + - `"medium"` - - `id: str` + - `"high"` - The unique ID of the approval request. + - `"xhigh"` - - `arguments: str` + - `"max"` - A JSON string of arguments for the tool. + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` - - `name: str` + **Deprecated:** use `summary` instead. - The name of the tool to run. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `server_label: str` + - `"auto"` - The label of the MCP server making the request. + - `"concise"` - - `type: Literal["mcp_approval_request"]` + - `"detailed"` - The type of the item. Always `mcp_approval_request`. + - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` - - `"mcp_approval_request"` + Controls the reasoning execution mode for the request. - - `agent: Optional[McpApprovalRequestAgent]` + When returned on a response, this is the effective execution mode. - The agent that produced this item. + - `str` - - `agent_name: str` + - `Literal["standard", "pro"]` - The canonical name of the agent that produced this item. + Controls the reasoning execution mode for the request. - - `class McpApprovalResponse: …` + When returned on a response, this is the effective execution mode. - A response to an MCP approval request. + - `"standard"` - - `approval_request_id: str` + - `"pro"` - The ID of the approval request being answered. + - `summary: Optional[Literal["auto", "concise", "detailed"]]` - - `approve: bool` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - Whether the request was approved. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `type: Literal["mcp_approval_response"]` + - `"auto"` - The type of the item. Always `mcp_approval_response`. + - `"concise"` - - `"mcp_approval_response"` + - `"detailed"` - - `id: Optional[str]` + - `safety_identifier: Optional[str]` - The unique ID of the approval response + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `agent: Optional[McpApprovalResponseAgent]` + - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` - The agent that produced this item. + Specifies the processing type used for serving the request. - - `agent_name: str` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - The canonical name of the agent that produced this item. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `reason: Optional[str]` + - `"auto"` - Optional reason for the decision. + - `"default"` - - `class McpCall: …` + - `"flex"` - An invocation of a tool on an MCP server. + - `"scale"` - - `id: str` + - `"priority"` - The unique ID of the tool call. + - `status: Optional[BetaResponseStatus]` - - `arguments: str` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - A JSON string of the arguments passed to the tool. + - `"completed"` - - `name: str` + - `"failed"` - The name of the tool that was run. + - `"in_progress"` - - `server_label: str` + - `"cancelled"` - The label of the MCP server running the tool. + - `"queued"` - - `type: Literal["mcp_call"]` + - `"incomplete"` - The type of the item. Always `mcp_call`. + - `text: Optional[BetaResponseTextConfig]` - - `"mcp_call"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `agent: Optional[McpCallAgent]` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - The agent that produced this item. + - `format: Optional[BetaResponseFormatTextConfig]` - - `agent_name: str` + An object specifying the format that the model must output. - The canonical name of the agent that produced this item. + Configuring `{ "type": "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). - - `approval_request_id: Optional[str]` + The default format is `{ "type": "text" }` with no additional options. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + **Not recommended for gpt-4o and newer models:** - - `error: Optional[str]` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - The error from the tool call, if any. + - `class Text: …` - - `output: Optional[str]` + Default response format. Used to generate text responses. - The output from the tool call. + - `type: Literal["text"]` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + The type of response format being defined. Always `text`. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"text"` - - `"in_progress"` + - `class BetaResponseFormatTextJSONSchemaConfig: …` - - `"completed"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `"incomplete"` + - `name: str` - - `"calling"` + 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. - - `"failed"` + - `schema: Dict[str, object]` - - `class BetaResponseCustomToolCallOutput: …` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The output of a custom tool call from your code, being sent back to the model. + - `type: Literal["json_schema"]` - - `call_id: str` + The type of response format being defined. Always `json_schema`. - The call ID, used to map this custom tool call output to a custom tool call. + - `"json_schema"` - - `output: Union[str, List[OutputOutputContentList]]` + - `description: Optional[str]` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `str` + - `strict: Optional[bool]` - A string of the output of the custom tool call. + 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). - - `List[OutputOutputContentList]` + - `class JSONObject: …` - Text, image, or file output of the custom tool call. + 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. - - `class BetaResponseInputText: …` + - `type: Literal["json_object"]` - A text input to the model. + The type of response format being defined. Always `json_object`. - - `class BetaResponseInputImage: …` + - `"json_object"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `verbosity: Optional[Literal["low", "medium", "high"]]` - - `class BetaResponseInputFile: …` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - A file input to the model. + - `"low"` - - `type: Literal["custom_tool_call_output"]` + - `"medium"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"high"` - - `"custom_tool_call_output"` + - `top_logprobs: Optional[int]` - - `id: Optional[str]` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - The unique ID of the custom tool call output in the OpenAI platform. + - `truncation: Optional[Literal["auto", "disabled"]]` - - `agent: Optional[Agent]` + The truncation strategy to use for the model response. - The agent that produced this item. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `agent_name: str` + - `"auto"` - The canonical name of the agent that produced this item. + - `"disabled"` - - `caller: Optional[Caller]` + - `usage: Optional[BetaResponseUsage]` - The execution context that produced this tool call. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `class CallerDirect: …` + - `input_tokens: int` - - `type: Literal["direct"]` + The number of input tokens. - The caller type. Always `direct`. + - `input_tokens_details: InputTokensDetails` - - `"direct"` + A detailed breakdown of the input tokens. - - `class CallerProgram: …` + - `cache_write_tokens: int` - - `caller_id: str` + The number of input tokens that were written to the cache. - The call ID of the program item that produced this tool call. + - `cached_tokens: int` - - `type: Literal["program"]` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - The caller type. Always `program`. + - `output_tokens: int` - - `"program"` + The number of output tokens. - - `class BetaResponseCustomToolCall: …` + - `output_tokens_details: OutputTokensDetails` - A call to a custom tool created by the model. + A detailed breakdown of the output tokens. - - `call_id: str` + - `reasoning_tokens: int` - An identifier used to map this custom tool call to a tool call output. + The number of reasoning tokens. - - `input: str` + - `total_tokens: int` - The input for the custom tool call generated by the model. + The total number of tokens used. - - `name: str` + - `user: Optional[str]` - The name of the custom tool being called. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `type: Literal["custom_tool_call"]` + - `sequence_number: int` - The type of the custom tool call. Always `custom_tool_call`. + The sequence number for this event. - - `"custom_tool_call"` + - `type: Literal["response.completed"]` - - `id: Optional[str]` + The type of the event. Always `response.completed`. - The unique ID of the custom tool call in the OpenAI platform. + - `"response.completed"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `class BetaResponseContentPartAddedEvent: …` - The execution context that produced this tool call. + Emitted when a new content part is added. - - `class CallerDirect: …` + - `content_index: int` - - `type: Literal["direct"]` + The index of the content part that was added. - - `"direct"` + - `item_id: str` - - `class CallerProgram: …` + The ID of the output item that the content part was added to. - - `caller_id: str` + - `output_index: int` - The call ID of the program item that produced this tool call. + The index of the output item that the content part was added to. - - `type: Literal["program"]` + - `part: Part` - - `"program"` + The content part that was added. - - `namespace: Optional[str]` + - `class BetaResponseOutputText: …` - The namespace of the custom tool being called. + A text output from the model. - - `class CompactionTrigger: …` + - `class BetaResponseOutputRefusal: …` - Compacts the current context. Must be the final input item. + A refusal from the model. - - `type: Literal["compaction_trigger"]` + - `class PartReasoningText: …` - The type of the item. Always `compaction_trigger`. + Reasoning text from the model. - - `"compaction_trigger"` + - `text: str` - - `agent: Optional[CompactionTriggerAgent]` + The reasoning text from the model. - The agent that produced this item. + - `type: Literal["reasoning_text"]` - - `agent_name: str` + The type of the reasoning text. Always `reasoning_text`. - The canonical name of the agent that produced this item. + - `"reasoning_text"` - - `class ItemReference: …` + - `sequence_number: int` - An internal identifier for an item to reference. + The sequence number of this event. - - `id: str` + - `type: Literal["response.content_part.added"]` - The ID of the item to reference. + The type of the event. Always `response.content_part.added`. - - `agent: Optional[ItemReferenceAgent]` + - `"response.content_part.added"` - The agent that produced this item. + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `type: Optional[Literal["item_reference"]]` - - The type of item to reference. Always `item_reference`. - - - `"item_reference"` + - `class BetaResponseContentPartDoneEvent: …` - - `class Program: …` + Emitted when a content part is done. - - `id: str` + - `content_index: int` - The unique ID of this program item. + The index of the content part that is done. - - `call_id: str` + - `item_id: str` - The stable call ID of the program item. + The ID of the output item that the content part was added to. - - `code: str` + - `output_index: int` - The JavaScript source executed by programmatic tool calling. + The index of the output item that the content part was added to. - - `fingerprint: str` + - `part: Part` - Opaque program replay fingerprint that must be round-tripped. + The content part that is done. - - `type: Literal["program"]` + - `class BetaResponseOutputText: …` - The item type. Always `program`. + A text output from the model. - - `"program"` + - `class BetaResponseOutputRefusal: …` - - `agent: Optional[ProgramAgent]` + A refusal from the model. - The agent that produced this item. + - `class PartReasoningText: …` - - `agent_name: str` + Reasoning text from the model. - The canonical name of the agent that produced this item. + - `text: str` - - `class ProgramOutput: …` + The reasoning text from the model. - - `id: str` + - `type: Literal["reasoning_text"]` - The unique ID of this program output item. + The type of the reasoning text. Always `reasoning_text`. - - `call_id: str` + - `"reasoning_text"` - The call ID of the program item. + - `sequence_number: int` - - `result: str` + The sequence number of this event. - The result produced by the program item. + - `type: Literal["response.content_part.done"]` - - `status: Literal["completed", "incomplete"]` + The type of the event. Always `response.content_part.done`. - The terminal status of the program output. + - `"response.content_part.done"` - - `"completed"` + - `agent: Optional[Agent]` - - `"incomplete"` + The agent that owns this multi-agent streaming event. - - `type: Literal["program_output"]` + - `agent_name: str` - The item type. Always `program_output`. + The canonical name of the agent that produced this item. - - `"program_output"` + - `class BetaResponseCreatedEvent: …` - - `agent: Optional[ProgramOutputAgent]` + An event that is emitted when a response is created. - The agent that produced this item. + - `response: BetaResponse` - - `agent_name: str` + The response that was created. - The canonical name of the agent that produced this item. + - `sequence_number: int` - - `metadata: Optional[Dict[str, str]]` + The sequence number for this event. - 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. + - `type: Literal["response.created"]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The type of the event. Always `response.created`. - - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` + - `"response.created"` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `agent: Optional[Agent]` - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` + The agent that owns this multi-agent streaming event. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `agent_name: str` - - `"gpt-5.6-sol"` + The canonical name of the agent that produced this item. - - `"gpt-5.6-terra"` + - `class BetaResponseErrorEvent: …` - - `"gpt-5.6-luna"` + Emitted when an error occurs. - - `"gpt-5.4"` + - `code: Optional[str]` - - `"gpt-5.4-mini"` + The error code. - - `"gpt-5.4-nano"` + - `message: str` - - `"gpt-5.4-mini-2026-03-17"` + The error message. - - `"gpt-5.4-nano-2026-03-17"` + - `param: Optional[str]` - - `"gpt-5.3-chat-latest"` + The error parameter. - - `"gpt-5.2"` + - `sequence_number: int` - - `"gpt-5.2-2025-12-11"` + The sequence number of this event. - - `"gpt-5.2-chat-latest"` + - `type: Literal["error"]` - - `"gpt-5.2-pro"` + The type of the event. Always `error`. - - `"gpt-5.2-pro-2025-12-11"` + - `"error"` - - `"gpt-5.1"` + - `agent: Optional[Agent]` - - `"gpt-5.1-2025-11-13"` + The agent that owns this multi-agent streaming event. - - `"gpt-5.1-codex"` + - `agent_name: str` - - `"gpt-5.1-mini"` + The canonical name of the agent that produced this item. - - `"gpt-5.1-chat-latest"` + - `class BetaResponseFileSearchCallCompletedEvent: …` - - `"gpt-5"` + Emitted when a file search call is completed (results found). - - `"gpt-5-mini"` + - `item_id: str` - - `"gpt-5-nano"` + The ID of the output item that the file search call is initiated. - - `"gpt-5-2025-08-07"` + - `output_index: int` - - `"gpt-5-mini-2025-08-07"` + The index of the output item that the file search call is initiated. - - `"gpt-5-nano-2025-08-07"` + - `sequence_number: int` - - `"gpt-5-chat-latest"` + The sequence number of this event. - - `"gpt-4.1"` + - `type: Literal["response.file_search_call.completed"]` - - `"gpt-4.1-mini"` + The type of the event. Always `response.file_search_call.completed`. - - `"gpt-4.1-nano"` + - `"response.file_search_call.completed"` - - `"gpt-4.1-2025-04-14"` + - `agent: Optional[Agent]` - - `"gpt-4.1-mini-2025-04-14"` + The agent that owns this multi-agent streaming event. - - `"gpt-4.1-nano-2025-04-14"` + - `agent_name: str` - - `"o4-mini"` + The canonical name of the agent that produced this item. - - `"o4-mini-2025-04-16"` + - `class BetaResponseFileSearchCallInProgressEvent: …` - - `"o3"` + Emitted when a file search call is initiated. - - `"o3-2025-04-16"` + - `item_id: str` - - `"o3-mini"` + The ID of the output item that the file search call is initiated. - - `"o3-mini-2025-01-31"` + - `output_index: int` - - `"o1"` + The index of the output item that the file search call is initiated. - - `"o1-2024-12-17"` + - `sequence_number: int` - - `"o1-preview"` + The sequence number of this event. - - `"o1-preview-2024-09-12"` + - `type: Literal["response.file_search_call.in_progress"]` - - `"o1-mini"` + The type of the event. Always `response.file_search_call.in_progress`. - - `"o1-mini-2024-09-12"` + - `"response.file_search_call.in_progress"` - - `"gpt-4o"` + - `agent: Optional[Agent]` - - `"gpt-4o-2024-11-20"` + The agent that owns this multi-agent streaming event. - - `"gpt-4o-2024-08-06"` + - `agent_name: str` - - `"gpt-4o-2024-05-13"` + The canonical name of the agent that produced this item. - - `"gpt-4o-audio-preview"` + - `class BetaResponseFileSearchCallSearchingEvent: …` - - `"gpt-4o-audio-preview-2024-10-01"` + Emitted when a file search is currently searching. - - `"gpt-4o-audio-preview-2024-12-17"` + - `item_id: str` - - `"gpt-4o-audio-preview-2025-06-03"` + The ID of the output item that the file search call is initiated. - - `"gpt-4o-mini-audio-preview"` + - `output_index: int` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The index of the output item that the file search call is searching. - - `"gpt-4o-search-preview"` + - `sequence_number: int` - - `"gpt-4o-mini-search-preview"` + The sequence number of this event. - - `"gpt-4o-search-preview-2025-03-11"` + - `type: Literal["response.file_search_call.searching"]` - - `"gpt-4o-mini-search-preview-2025-03-11"` + The type of the event. Always `response.file_search_call.searching`. - - `"chatgpt-4o-latest"` + - `"response.file_search_call.searching"` - - `"codex-mini-latest"` + - `agent: Optional[Agent]` - - `"gpt-4o-mini"` + The agent that owns this multi-agent streaming event. - - `"gpt-4o-mini-2024-07-18"` + - `agent_name: str` - - `"gpt-4-turbo"` + The canonical name of the agent that produced this item. - - `"gpt-4-turbo-2024-04-09"` + - `class BetaResponseFunctionCallArgumentsDeltaEvent: …` - - `"gpt-4-0125-preview"` + Emitted when there is a partial function-call arguments delta. - - `"gpt-4-turbo-preview"` + - `delta: str` - - `"gpt-4-1106-preview"` + The function-call arguments delta that is added. - - `"gpt-4-vision-preview"` + - `item_id: str` - - `"gpt-4"` + The ID of the output item that the function-call arguments delta is added to. - - `"gpt-4-0314"` + - `output_index: int` - - `"gpt-4-0613"` + The index of the output item that the function-call arguments delta is added to. - - `"gpt-4-32k"` + - `sequence_number: int` - - `"gpt-4-32k-0314"` + The sequence number of this event. - - `"gpt-4-32k-0613"` + - `type: Literal["response.function_call_arguments.delta"]` - - `"gpt-3.5-turbo"` + The type of the event. Always `response.function_call_arguments.delta`. - - `"gpt-3.5-turbo-16k"` + - `"response.function_call_arguments.delta"` - - `"gpt-3.5-turbo-0301"` + - `agent: Optional[Agent]` - - `"gpt-3.5-turbo-0613"` + The agent that owns this multi-agent streaming event. - - `"gpt-3.5-turbo-1106"` + - `agent_name: str` - - `"gpt-3.5-turbo-0125"` + The canonical name of the agent that produced this item. - - `"gpt-3.5-turbo-16k-0613"` + - `class BetaResponseFunctionCallArgumentsDoneEvent: …` - - `"o1-pro"` + Emitted when function-call arguments are finalized. - - `"o1-pro-2025-03-19"` + - `arguments: str` - - `"o3-pro"` + The function-call arguments. - - `"o3-pro-2025-06-10"` + - `item_id: str` - - `"o3-deep-research"` + The ID of the item. - - `"o3-deep-research-2025-06-26"` + - `name: str` - - `"o4-mini-deep-research"` + The name of the function that was called. - - `"o4-mini-deep-research-2025-06-26"` + - `output_index: int` - - `"computer-use-preview"` + The index of the output item. - - `"computer-use-preview-2025-03-11"` + - `sequence_number: int` - - `"gpt-5-codex"` + The sequence number of this event. - - `"gpt-5-pro"` + - `type: Literal["response.function_call_arguments.done"]` - - `"gpt-5-pro-2025-10-06"` + - `"response.function_call_arguments.done"` - - `"gpt-5.1-codex-max"` + - `agent: Optional[Agent]` - - `str` + The agent that owns this multi-agent streaming event. - - `object: Literal["response"]` + - `agent_name: str` - The object type of this resource - always set to `response`. + The canonical name of the agent that produced this item. - - `"response"` + - `class BetaResponseInProgressEvent: …` - - `output: List[BetaResponseOutputItem]` + Emitted when the response is in progress. - An array of content items generated by the model. + - `response: BetaResponse` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + The response that is in progress. - - `class BetaResponseOutputMessage: …` + - `sequence_number: int` - An output message from the model. + The sequence number of this event. - - `class BetaResponseFileSearchToolCall: …` + - `type: Literal["response.in_progress"]` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + The type of the event. Always `response.in_progress`. - - `class BetaResponseFunctionToolCall: …` + - `"response.in_progress"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `agent: Optional[Agent]` - - `class BetaResponseFunctionToolCallOutputItem: …` + The agent that owns this multi-agent streaming event. - - `id: str` + - `agent_name: str` - The unique ID of the function call tool output. + The canonical name of the agent that produced this item. - - `call_id: str` + - `class BetaResponseFailedEvent: …` - The unique ID of the function tool call generated by the model. + An event that is emitted when a response fails. - - `output: Union[str, List[OutputOutputContentList]]` + - `response: BetaResponse` - The output from the function call generated by your code. - Can be a string or an list of output content. + The response that failed. - - `str` + - `sequence_number: int` - A string of the output of the function call. + The sequence number of this event. - - `List[OutputOutputContentList]` + - `type: Literal["response.failed"]` - Text, image, or file output of the function call. + The type of the event. Always `response.failed`. - - `class BetaResponseInputText: …` + - `"response.failed"` - A text input to the model. + - `agent: Optional[Agent]` - - `class BetaResponseInputImage: …` + The agent that owns this multi-agent streaming event. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `agent_name: str` - - `class BetaResponseInputFile: …` + The canonical name of the agent that produced this item. - A file input to the model. + - `class BetaResponseIncompleteEvent: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + An event that is emitted when a response finishes as incomplete. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `response: BetaResponse` - - `"in_progress"` + The response that was incomplete. - - `"completed"` + - `sequence_number: int` - - `"incomplete"` + The sequence number of this event. - - `type: Literal["function_call_output"]` + - `type: Literal["response.incomplete"]` - The type of the function tool call output. Always `function_call_output`. + The type of the event. Always `response.incomplete`. - - `"function_call_output"` + - `"response.incomplete"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` - - - `type: Literal["direct"]` + - `class BetaResponseOutputItemAddedEvent: …` - The caller type. Always `direct`. + Emitted when a new output item is added. - - `"direct"` + - `item: BetaResponseOutputItem` - - `class CallerProgram: …` + The output item that was added. - - `caller_id: str` + - `class BetaResponseOutputMessage: …` - The call ID of the program item that produced this tool call. + An output message from the model. - - `type: Literal["program"]` + - `class BetaResponseFileSearchToolCall: …` - The caller type. Always `program`. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `"program"` + - `class BetaResponseFunctionToolCall: …` - - `created_by: Optional[str]` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The identifier of the actor that created the item. + - `class BetaResponseFunctionToolCallOutputItem: …` - `class AgentMessage: …` - - `id: str` - - The unique ID of the agent message. + - `class MultiAgentCall: …` - - `author: str` + - `class MultiAgentCallOutput: …` - The sending agent identity. + - `class BetaResponseFunctionWebSearch: …` - - `content: List[AgentMessageContent]` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - Encrypted content sent between agents. + - `class BetaResponseComputerToolCall: …` - - `class BetaResponseInputText: …` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - A text input to the model. + - `class BetaResponseComputerToolCallOutputItem: …` - - `class BetaResponseOutputText: …` + - `class BetaResponseReasoningItem: …` - A text output from the model. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `class AgentMessageContentText: …` + - `class Program: …` - A text content. + - `class ProgramOutput: …` - - `text: str` + - `class BetaResponseToolSearchCall: …` - - `type: Literal["text"]` + - `class BetaResponseToolSearchOutputItem: …` - - `"text"` + - `class AdditionalTools: …` - - `class AgentMessageContentSummaryText: …` + - `class BetaResponseCompactionItem: …` - A summary text from the model. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `text: str` + - `class ImageGenerationCall: …` - A summary of the reasoning output from the model so far. + An image generation request made by the model. - - `type: Literal["summary_text"]` + - `class BetaResponseCodeInterpreterToolCall: …` - The type of the object. Always `summary_text`. + A tool call to run code. - - `"summary_text"` + - `class LocalShellCall: …` - - `class AgentMessageContentReasoningText: …` + A tool call to run a command on the local shell. - Reasoning text from the model. + - `class LocalShellCallOutput: …` - - `text: str` + The output of a local shell tool call. - The reasoning text from the model. + - `class BetaResponseFunctionShellToolCall: …` - - `type: Literal["reasoning_text"]` + A tool call that executes one or more shell commands in a managed environment. - The type of the reasoning text. Always `reasoning_text`. + - `class BetaResponseFunctionShellToolCallOutput: …` - - `"reasoning_text"` + The output of a shell tool call that was emitted. - - `class BetaResponseOutputRefusal: …` + - `class BetaResponseApplyPatchToolCall: …` - A refusal from the model. + A tool call that applies file diffs by creating, deleting, or updating files. - - `class BetaResponseInputImage: …` + - `class BetaResponseApplyPatchToolCallOutput: …` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The output emitted by an apply patch tool call. - - `class AgentMessageContentComputerScreenshot: …` + - `class McpCall: …` - A screenshot of a computer. + An invocation of a tool on an MCP server. - - `detail: Literal["low", "high", "auto", "original"]` + - `class McpListTools: …` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + A list of tools available on an MCP server. - - `"low"` + - `class McpApprovalRequest: …` - - `"high"` + A request for human approval of a tool invocation. - - `"auto"` + - `class McpApprovalResponse: …` - - `"original"` + A response to an MCP approval request. - - `file_id: Optional[str]` + - `class BetaResponseCustomToolCall: …` - The identifier of an uploaded file that contains the screenshot. + A call to a custom tool created by the model. - - `image_url: Optional[str]` + - `class BetaResponseCustomToolCallOutputItem: …` - The URL of the screenshot image. + The output of a custom tool call from your code, being sent back to the model. - - `type: Literal["computer_screenshot"]` + - `output_index: int` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The index of the output item that was added. - - `"computer_screenshot"` + - `sequence_number: int` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + The sequence number of this event. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: Literal["response.output_item.added"]` - - `mode: Literal["explicit"]` + The type of the event. Always `response.output_item.added`. - The breakpoint mode. Always `explicit`. + - `"response.output_item.added"` - - `"explicit"` + - `agent: Optional[Agent]` - - `class BetaResponseInputFile: …` + The agent that owns this multi-agent streaming event. - A file input to the model. + - `agent_name: str` - - `class AgentMessageContentEncryptedContent: …` + The canonical name of the agent that produced this item. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `class BetaResponseOutputItemDoneEvent: …` - - `encrypted_content: str` + Emitted when an output item is marked done. - Opaque encrypted content. + - `item: BetaResponseOutputItem` - - `type: Literal["encrypted_content"]` + The output item that was marked done. - The type of the input item. Always `encrypted_content`. + - `output_index: int` - - `"encrypted_content"` + The index of the output item that was marked done. - - `recipient: str` + - `sequence_number: int` - The destination agent identity. + The sequence number of this event. - - `type: Literal["agent_message"]` + - `type: Literal["response.output_item.done"]` - The type of the item. Always `agent_message`. + The type of the event. Always `response.output_item.done`. - - `"agent_message"` + - `"response.output_item.done"` - - `agent: Optional[AgentMessageAgent]` + - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class MultiAgentCall: …` + - `class BetaResponseReasoningSummaryPartAddedEvent: …` - - `id: str` + Emitted when a new reasoning summary part is added. - The unique ID of the multi-agent call item. + - `item_id: str` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The ID of the item this summary part is associated with. - The multi-agent action to execute. + - `output_index: int` - - `"spawn_agent"` + The index of the output item this summary part is associated with. - - `"interrupt_agent"` + - `part: Part` - - `"list_agents"` + The summary part that was added. - - `"send_message"` + - `text: str` - - `"followup_task"` + The text of the summary part. - - `"wait_agent"` + - `type: Literal["summary_text"]` - - `arguments: str` + The type of the summary part. Always `summary_text`. - The JSON string of arguments generated for the action. + - `"summary_text"` - - `call_id: str` + - `sequence_number: int` - The unique ID linking this call to its output. + The sequence number of this event. - - `type: Literal["multi_agent_call"]` + - `summary_index: int` - The type of the multi-agent call. Always `multi_agent_call`. + The index of the summary part within the reasoning summary. - - `"multi_agent_call"` + - `type: Literal["response.reasoning_summary_part.added"]` - - `agent: Optional[MultiAgentCallAgent]` + The type of the event. Always `response.reasoning_summary_part.added`. - The agent that produced this item. + - `"response.reasoning_summary_part.added"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class MultiAgentCallOutput: …` + - `class BetaResponseReasoningSummaryPartDoneEvent: …` - - `id: str` + Emitted when a reasoning summary part is completed. - The unique ID of the multi-agent call output item. + - `item_id: str` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The ID of the item this summary part is associated with. - The multi-agent action that produced this result. + - `output_index: int` - - `"spawn_agent"` + The index of the output item this summary part is associated with. - - `"interrupt_agent"` + - `part: Part` - - `"list_agents"` + The completed summary part. - - `"send_message"` + - `text: str` - - `"followup_task"` + The text of the summary part. - - `"wait_agent"` + - `type: Literal["summary_text"]` - - `call_id: str` + The type of the summary part. Always `summary_text`. - The unique ID of the multi-agent call. + - `"summary_text"` - - `output: List[BetaResponseOutputText]` + - `sequence_number: int` - Text output returned by the multi-agent action. + The sequence number of this event. - - `annotations: List[Annotation]` + - `summary_index: int` - The annotations of the text output. + The index of the summary part within the reasoning summary. - - `text: str` + - `type: Literal["response.reasoning_summary_part.done"]` - The text output from the model. + The type of the event. Always `response.reasoning_summary_part.done`. - - `type: Literal["output_text"]` + - `"response.reasoning_summary_part.done"` - The type of the output text. Always `output_text`. + - `agent: Optional[Agent]` - - `logprobs: Optional[List[Logprob]]` + The agent that owns this multi-agent streaming event. - - `type: Literal["multi_agent_call_output"]` + - `agent_name: str` - The type of the multi-agent result. Always `multi_agent_call_output`. + The canonical name of the agent that produced this item. - - `"multi_agent_call_output"` + - `status: Optional[Literal["incomplete"]]` - - `agent: Optional[MultiAgentCallOutputAgent]` + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - The agent that produced this item. + - `"incomplete"` - - `agent_name: str` + - `class BetaResponseReasoningSummaryTextDeltaEvent: …` - The canonical name of the agent that produced this item. + Emitted when a delta is added to a reasoning summary text. - - `class BetaResponseFunctionWebSearch: …` + - `delta: str` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The text delta that was added to the summary. - - `class BetaResponseComputerToolCall: …` + - `item_id: str` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The ID of the item this summary text delta is associated with. - - `class BetaResponseComputerToolCallOutputItem: …` + - `output_index: int` - - `id: str` + The index of the output item this summary text delta is associated with. - The unique ID of the computer call tool output. + - `sequence_number: int` - - `call_id: str` + The sequence number of this event. - The ID of the computer tool call that produced the output. + - `summary_index: int` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The index of the summary part within the reasoning summary. - A computer screenshot image used with the computer use tool. + - `type: Literal["response.reasoning_summary_text.delta"]` - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + The type of the event. Always `response.reasoning_summary_text.delta`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"response.reasoning_summary_text.delta"` - - `"completed"` + - `agent: Optional[Agent]` - - `"incomplete"` + The agent that owns this multi-agent streaming event. - - `"failed"` + - `agent_name: str` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `type: Literal["computer_call_output"]` + - `class BetaResponseReasoningSummaryTextDoneEvent: …` - The type of the computer tool call output. Always `computer_call_output`. + Emitted when a reasoning summary text is completed. - - `"computer_call_output"` + - `item_id: str` - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + The ID of the item this summary text is associated with. - The safety checks reported by the API that have been acknowledged by the - developer. + - `output_index: int` - - `id: str` + The index of the output item this summary text is associated with. - The ID of the pending safety check. + - `sequence_number: int` - - `code: Optional[str]` + The sequence number of this event. - The type of the pending safety check. + - `summary_index: int` - - `message: Optional[str]` + The index of the summary part within the reasoning summary. - Details about the pending safety check. + - `text: str` + + The full text of the completed reasoning summary. + + - `type: Literal["response.reasoning_summary_text.done"]` + + The type of the event. Always `response.reasoning_summary_text.done`. + + - `"response.reasoning_summary_text.done"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `created_by: Optional[str]` - - The identifier of the actor that created the item. + - `class BetaResponseReasoningTextDeltaEvent: …` - - `class BetaResponseReasoningItem: …` + Emitted when a delta is added to a reasoning text. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `content_index: int` - - `class Program: …` + The index of the reasoning content part this delta is associated with. - - `id: str` + - `delta: str` - The unique ID of the program item. + The text delta that was added to the reasoning content. - - `call_id: str` + - `item_id: str` - The stable call ID of the program item. + The ID of the item this reasoning text delta is associated with. - - `code: str` + - `output_index: int` - The JavaScript source executed by programmatic tool calling. + The index of the output item this reasoning text delta is associated with. - - `fingerprint: str` + - `sequence_number: int` - Opaque program replay fingerprint that must be round-tripped. + The sequence number of this event. - - `type: Literal["program"]` + - `type: Literal["response.reasoning_text.delta"]` - The type of the item. Always `program`. + The type of the event. Always `response.reasoning_text.delta`. - - `"program"` + - `"response.reasoning_text.delta"` - - `agent: Optional[ProgramAgent]` + - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class ProgramOutput: …` + - `class BetaResponseReasoningTextDoneEvent: …` - - `id: str` + Emitted when a reasoning text is completed. - The unique ID of the program output item. + - `content_index: int` - - `call_id: str` + The index of the reasoning content part. - The call ID of the program item. + - `item_id: str` - - `result: str` + The ID of the item this reasoning text is associated with. - The result produced by the program item. + - `output_index: int` - - `status: Literal["completed", "incomplete"]` + The index of the output item this reasoning text is associated with. - The terminal status of the program output item. + - `sequence_number: int` - - `"completed"` + The sequence number of this event. - - `"incomplete"` + - `text: str` - - `type: Literal["program_output"]` + The full text of the completed reasoning content. - The type of the item. Always `program_output`. + - `type: Literal["response.reasoning_text.done"]` - - `"program_output"` + The type of the event. Always `response.reasoning_text.done`. - - `agent: Optional[ProgramOutputAgent]` + - `"response.reasoning_text.done"` - The agent that produced this item. + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall: …` - - - `id: str` - - The unique ID of the tool search call item. - - - `arguments: object` - - Arguments used for the tool search call. + - `class BetaResponseRefusalDeltaEvent: …` - - `call_id: Optional[str]` + Emitted when there is a partial refusal text. - The unique ID of the tool search call generated by the model. + - `content_index: int` - - `execution: Literal["server", "client"]` + The index of the content part that the refusal text is added to. - Whether tool search was executed by the server or by the client. + - `delta: str` - - `"server"` + The refusal text that is added. - - `"client"` + - `item_id: str` - - `status: Literal["in_progress", "completed", "incomplete"]` + The ID of the output item that the refusal text is added to. - The status of the tool search call item that was recorded. + - `output_index: int` - - `"in_progress"` + The index of the output item that the refusal text is added to. - - `"completed"` + - `sequence_number: int` - - `"incomplete"` + The sequence number of this event. - - `type: Literal["tool_search_call"]` + - `type: Literal["response.refusal.delta"]` - The type of the item. Always `tool_search_call`. + The type of the event. Always `response.refusal.delta`. - - `"tool_search_call"` + - `"response.refusal.delta"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `created_by: Optional[str]` + - `class BetaResponseRefusalDoneEvent: …` - The identifier of the actor that created the item. + Emitted when refusal text is finalized. - - `class BetaResponseToolSearchOutputItem: …` + - `content_index: int` - - `id: str` + The index of the content part that the refusal text is finalized. - The unique ID of the tool search output item. + - `item_id: str` - - `call_id: Optional[str]` + The ID of the output item that the refusal text is finalized. - The unique ID of the tool search call generated by the model. + - `output_index: int` - - `execution: Literal["server", "client"]` + The index of the output item that the refusal text is finalized. - Whether tool search was executed by the server or by the client. + - `refusal: str` - - `"server"` + The refusal text that is finalized. - - `"client"` + - `sequence_number: int` - - `status: Literal["in_progress", "completed", "incomplete"]` + The sequence number of this event. - The status of the tool search output item that was recorded. + - `type: Literal["response.refusal.done"]` - - `"in_progress"` + The type of the event. Always `response.refusal.done`. - - `"completed"` + - `"response.refusal.done"` - - `"incomplete"` + - `agent: Optional[Agent]` - - `tools: List[BetaTool]` + The agent that owns this multi-agent streaming event. - The loaded tool definitions returned by tool search. + - `agent_name: str` - - `class BetaFunctionTool: …` + The canonical name of the agent that produced this item. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class BetaResponseTextDeltaEvent: …` - - `class BetaFileSearchTool: …` + Emitted when there is an additional text delta. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `content_index: int` - - `class BetaComputerTool: …` + The index of the content part that the text delta was added to. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `delta: str` - - `class BetaComputerUsePreviewTool: …` + The text delta that was added. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `item_id: str` - - `class BetaWebSearchTool: …` + The ID of the output item that the text delta was added to. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `logprobs: List[Logprob]` - - `class Mcp: …` + The log probabilities of the tokens in the delta. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `token: str` - - `class CodeInterpreter: …` + A possible text token. - A tool that runs Python code to help generate a response to a prompt. + - `logprob: float` - - `class ProgrammaticToolCalling: …` + The log probability of this token. - - `class ImageGeneration: …` + - `top_logprobs: Optional[List[LogprobTopLogprob]]` - A tool that generates images using the GPT image models. + The log probabilities of up to 20 of the most likely tokens. - - `class LocalShell: …` + - `token: Optional[str]` - A tool that allows the model to execute shell commands in a local environment. + A possible text token. - - `class BetaFunctionShellTool: …` + - `logprob: Optional[float]` - A tool that allows the model to execute shell commands. + The log probability of this token. - - `class BetaCustomTool: …` + - `output_index: int` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The index of the output item that the text delta was added to. - - `class BetaNamespaceTool: …` + - `sequence_number: int` - Groups function/custom tools under a shared namespace. + The sequence number for this event. - - `class BetaToolSearchTool: …` + - `type: Literal["response.output_text.delta"]` - Hosted or BYOT tool search configuration for deferred tools. + The type of the event. Always `response.output_text.delta`. - - `class BetaWebSearchPreviewTool: …` + - `"response.output_text.delta"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `agent: Optional[Agent]` - - `class BetaApplyPatchTool: …` + The agent that owns this multi-agent streaming event. - Allows the assistant to create, delete, or update files using unified diffs. + - `agent_name: str` - - `type: Literal["tool_search_output"]` + The canonical name of the agent that produced this item. - The type of the item. Always `tool_search_output`. + - `class BetaResponseTextDoneEvent: …` - - `"tool_search_output"` + Emitted when text content is finalized. - - `agent: Optional[Agent]` + - `content_index: int` - The agent that produced this item. + The index of the content part that the text content is finalized. - - `agent_name: str` + - `item_id: str` - The canonical name of the agent that produced this item. + The ID of the output item that the text content is finalized. - - `created_by: Optional[str]` + - `logprobs: List[Logprob]` - The identifier of the actor that created the item. + The log probabilities of the tokens in the delta. - - `class AdditionalTools: …` + - `token: str` - - `id: str` + A possible text token. - The unique ID of the additional tools item. + - `logprob: float` - - `role: Literal["unknown", "user", "assistant", 5 more]` + The log probability of this token. - The role that provided the additional tools. + - `top_logprobs: Optional[List[LogprobTopLogprob]]` - - `"unknown"` + The log probabilities of up to 20 of the most likely tokens. - - `"user"` + - `token: Optional[str]` - - `"assistant"` + A possible text token. - - `"system"` + - `logprob: Optional[float]` - - `"critic"` + The log probability of this token. - - `"discriminator"` + - `output_index: int` - - `"developer"` + The index of the output item that the text content is finalized. - - `"tool"` + - `sequence_number: int` - - `tools: List[BetaTool]` + The sequence number for this event. - The additional tool definitions made available at this item. + - `text: str` - - `class BetaFunctionTool: …` + The text content that is finalized. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `type: Literal["response.output_text.done"]` - - `class BetaFileSearchTool: …` + The type of the event. Always `response.output_text.done`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `"response.output_text.done"` - - `class BetaComputerTool: …` + - `agent: Optional[Agent]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The agent that owns this multi-agent streaming event. - - `class BetaComputerUsePreviewTool: …` + - `agent_name: str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The canonical name of the agent that produced this item. - - `class BetaWebSearchTool: …` + - `class BetaResponseWebSearchCallCompletedEvent: …` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Emitted when a web search call is completed. - - `class Mcp: …` + - `item_id: str` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + Unique ID for the output item associated with the web search call. - - `class CodeInterpreter: …` + - `output_index: int` - A tool that runs Python code to help generate a response to a prompt. + The index of the output item that the web search call is associated with. - - `class ProgrammaticToolCalling: …` + - `sequence_number: int` - - `class ImageGeneration: …` + The sequence number of the web search call being processed. - A tool that generates images using the GPT image models. + - `type: Literal["response.web_search_call.completed"]` - - `class LocalShell: …` + The type of the event. Always `response.web_search_call.completed`. - A tool that allows the model to execute shell commands in a local environment. + - `"response.web_search_call.completed"` - - `class BetaFunctionShellTool: …` + - `agent: Optional[Agent]` - A tool that allows the model to execute shell commands. + The agent that owns this multi-agent streaming event. - - `class BetaCustomTool: …` + - `agent_name: str` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The canonical name of the agent that produced this item. - - `class BetaNamespaceTool: …` + - `class BetaResponseWebSearchCallInProgressEvent: …` - Groups function/custom tools under a shared namespace. + Emitted when a web search call is initiated. - - `class BetaToolSearchTool: …` + - `item_id: str` - Hosted or BYOT tool search configuration for deferred tools. + Unique ID for the output item associated with the web search call. - - `class BetaWebSearchPreviewTool: …` + - `output_index: int` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The index of the output item that the web search call is associated with. - - `class BetaApplyPatchTool: …` + - `sequence_number: int` - Allows the assistant to create, delete, or update files using unified diffs. + The sequence number of the web search call being processed. - - `type: Literal["additional_tools"]` + - `type: Literal["response.web_search_call.in_progress"]` - The type of the item. Always `additional_tools`. + The type of the event. Always `response.web_search_call.in_progress`. - - `"additional_tools"` + - `"response.web_search_call.in_progress"` - - `agent: Optional[AdditionalToolsAgent]` + - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem: …` + - `class BetaResponseWebSearchCallSearchingEvent: …` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Emitted when a web search call is executing. - - `id: str` + - `item_id: str` - The unique ID of the compaction item. + Unique ID for the output item associated with the web search call. - - `encrypted_content: str` + - `output_index: int` - The encrypted content that was produced by compaction. + The index of the output item that the web search call is associated with. - - `type: Literal["compaction"]` + - `sequence_number: int` - The type of the item. Always `compaction`. + The sequence number of the web search call being processed. - - `"compaction"` + - `type: Literal["response.web_search_call.searching"]` + + The type of the event. Always `response.web_search_call.searching`. + + - `"response.web_search_call.searching"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `created_by: Optional[str]` + - `class BetaResponseImageGenCallCompletedEvent: …` - The identifier of the actor that created the item. + Emitted when an image generation tool call has completed and the final image is available. - - `class ImageGenerationCall: …` + - `item_id: str` - An image generation request made by the model. + The unique identifier of the image generation item being processed. - - `id: str` + - `output_index: int` - The unique ID of the image generation call. + The index of the output item in the response's output array. - - `result: Optional[str]` + - `sequence_number: int` - The generated image encoded in base64. + The sequence number of this event. - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `type: Literal["response.image_generation_call.completed"]` - The status of the image generation call. + The type of the event. Always 'response.image_generation_call.completed'. - - `"in_progress"` + - `"response.image_generation_call.completed"` - - `"completed"` + - `agent: Optional[Agent]` - - `"generating"` + The agent that owns this multi-agent streaming event. - - `"failed"` + - `agent_name: str` - - `type: Literal["image_generation_call"]` + The canonical name of the agent that produced this item. - The type of the image generation call. Always `image_generation_call`. + - `class BetaResponseImageGenCallGeneratingEvent: …` - - `"image_generation_call"` + Emitted when an image generation tool call is actively generating an image (intermediate state). - - `agent: Optional[ImageGenerationCallAgent]` + - `item_id: str` - The agent that produced this item. + The unique identifier of the image generation item being processed. - - `agent_name: str` + - `output_index: int` - The canonical name of the agent that produced this item. + The index of the output item in the response's output array. - - `class BetaResponseCodeInterpreterToolCall: …` + - `sequence_number: int` - A tool call to run code. + The sequence number of the image generation item being processed. - - `class LocalShellCall: …` + - `type: Literal["response.image_generation_call.generating"]` - A tool call to run a command on the local shell. + The type of the event. Always 'response.image_generation_call.generating'. - - `id: str` + - `"response.image_generation_call.generating"` - The unique ID of the local shell call. + - `agent: Optional[Agent]` - - `action: LocalShellCallAction` + The agent that owns this multi-agent streaming event. - Execute a shell command on the server. + - `agent_name: str` - - `command: List[str]` + The canonical name of the agent that produced this item. - The command to run. + - `class BetaResponseImageGenCallInProgressEvent: …` - - `env: Dict[str, str]` + Emitted when an image generation tool call is in progress. - Environment variables to set for the command. + - `item_id: str` - - `type: Literal["exec"]` + The unique identifier of the image generation item being processed. - The type of the local shell action. Always `exec`. + - `output_index: int` - - `"exec"` + The index of the output item in the response's output array. - - `timeout_ms: Optional[int]` + - `sequence_number: int` - Optional timeout in milliseconds for the command. + The sequence number of the image generation item being processed. - - `user: Optional[str]` + - `type: Literal["response.image_generation_call.in_progress"]` - Optional user to run the command as. + The type of the event. Always 'response.image_generation_call.in_progress'. - - `working_directory: Optional[str]` + - `"response.image_generation_call.in_progress"` - Optional working directory to run the command in. + - `agent: Optional[Agent]` - - `call_id: str` + The agent that owns this multi-agent streaming event. - The unique ID of the local shell tool call generated by the model. + - `agent_name: str` - - `status: Literal["in_progress", "completed", "incomplete"]` + The canonical name of the agent that produced this item. - The status of the local shell call. + - `class BetaResponseImageGenCallPartialImageEvent: …` - - `"in_progress"` + Emitted when a partial image is available during image generation streaming. - - `"completed"` + - `item_id: str` - - `"incomplete"` + The unique identifier of the image generation item being processed. - - `type: Literal["local_shell_call"]` + - `output_index: int` - The type of the local shell call. Always `local_shell_call`. + The index of the output item in the response's output array. - - `"local_shell_call"` + - `partial_image_b64: str` - - `agent: Optional[LocalShellCallAgent]` + Base64-encoded partial image data, suitable for rendering as an image. - The agent that produced this item. + - `partial_image_index: int` - - `agent_name: str` + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - The canonical name of the agent that produced this item. + - `sequence_number: int` - - `class LocalShellCallOutput: …` + The sequence number of the image generation item being processed. - The output of a local shell tool call. + - `type: Literal["response.image_generation_call.partial_image"]` - - `id: str` + The type of the event. Always 'response.image_generation_call.partial_image'. - The unique ID of the local shell tool call generated by the model. + - `"response.image_generation_call.partial_image"` - - `output: str` + - `agent: Optional[Agent]` - A JSON string of the output of the local shell tool call. + The agent that owns this multi-agent streaming event. - - `type: Literal["local_shell_call_output"]` + - `agent_name: str` - The type of the local shell tool call output. Always `local_shell_call_output`. + The canonical name of the agent that produced this item. - - `"local_shell_call_output"` + - `class BetaResponseMcpCallArgumentsDeltaEvent: …` - - `agent: Optional[LocalShellCallOutputAgent]` + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - The agent that produced this item. + - `delta: str` - - `agent_name: str` + A JSON string containing the partial update to the arguments for the MCP tool call. - The canonical name of the agent that produced this item. + - `item_id: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The unique identifier of the MCP tool call item being processed. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `output_index: int` - - `"in_progress"` + The index of the output item in the response's output array. - - `"completed"` + - `sequence_number: int` - - `"incomplete"` + The sequence number of this event. - - `class BetaResponseFunctionShellToolCall: …` + - `type: Literal["response.mcp_call_arguments.delta"]` - A tool call that executes one or more shell commands in a managed environment. + The type of the event. Always 'response.mcp_call_arguments.delta'. - - `id: str` + - `"response.mcp_call_arguments.delta"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `agent: Optional[Agent]` - - `action: Action` + The agent that owns this multi-agent streaming event. - The shell commands and limits that describe how to run the tool call. + - `agent_name: str` - - `commands: List[str]` + The canonical name of the agent that produced this item. - - `max_output_length: Optional[int]` + - `class BetaResponseMcpCallArgumentsDoneEvent: …` - Optional maximum number of characters to return from each command. + Emitted when the arguments for an MCP tool call are finalized. - - `timeout_ms: Optional[int]` + - `arguments: str` - Optional timeout in milliseconds for the commands. + A JSON string containing the finalized arguments for the MCP tool call. - - `call_id: str` + - `item_id: str` - The unique ID of the shell tool call generated by the model. + The unique identifier of the MCP tool call item being processed. - - `environment: Optional[Environment]` + - `output_index: int` - Represents the use of a local environment to perform shell actions. + The index of the output item in the response's output array. - - `class BetaResponseLocalEnvironment: …` + - `sequence_number: int` - Represents the use of a local environment to perform shell actions. + The sequence number of this event. - - `type: Literal["local"]` + - `type: Literal["response.mcp_call_arguments.done"]` - The environment type. Always `local`. + The type of the event. Always 'response.mcp_call_arguments.done'. - - `"local"` + - `"response.mcp_call_arguments.done"` - - `class BetaResponseContainerReference: …` + - `agent: Optional[Agent]` - Represents a container created with /v1/containers. + The agent that owns this multi-agent streaming event. - - `container_id: str` + - `agent_name: str` - - `type: Literal["container_reference"]` + The canonical name of the agent that produced this item. - The environment type. Always `container_reference`. + - `class BetaResponseMcpCallCompletedEvent: …` - - `"container_reference"` + Emitted when an MCP tool call has completed successfully. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `item_id: str` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The ID of the MCP tool call item that completed. - - `"in_progress"` + - `output_index: int` - - `"completed"` + The index of the output item that completed. - - `"incomplete"` + - `sequence_number: int` - - `type: Literal["shell_call"]` + The sequence number of this event. - The type of the item. Always `shell_call`. + - `type: Literal["response.mcp_call.completed"]` - - `"shell_call"` + The type of the event. Always 'response.mcp_call.completed'. + + - `"response.mcp_call.completed"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` - - The execution context that produced this tool call. + - `class BetaResponseMcpCallFailedEvent: …` - - `class CallerDirect: …` + Emitted when an MCP tool call has failed. - - `type: Literal["direct"]` + - `item_id: str` - - `"direct"` + The ID of the MCP tool call item that failed. - - `class CallerProgram: …` + - `output_index: int` - - `caller_id: str` + The index of the output item that failed. - The call ID of the program item that produced this tool call. + - `sequence_number: int` - - `type: Literal["program"]` + The sequence number of this event. - - `"program"` + - `type: Literal["response.mcp_call.failed"]` - - `created_by: Optional[str]` + The type of the event. Always 'response.mcp_call.failed'. - The ID of the entity that created this tool call. + - `"response.mcp_call.failed"` - - `class BetaResponseFunctionShellToolCallOutput: …` + - `agent: Optional[Agent]` - The output of a shell tool call that was emitted. + The agent that owns this multi-agent streaming event. - - `id: str` + - `agent_name: str` - The unique ID of the shell call output. Populated when this item is returned via API. + The canonical name of the agent that produced this item. - - `call_id: str` + - `class BetaResponseMcpCallInProgressEvent: …` - The unique ID of the shell tool call generated by the model. + Emitted when an MCP tool call is in progress. - - `max_output_length: Optional[int]` + - `item_id: str` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The unique identifier of the MCP tool call item being processed. - - `output: List[Output]` + - `output_index: int` - An array of shell call output contents + The index of the output item in the response's output array. - - `outcome: OutputOutcome` + - `sequence_number: int` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The sequence number of this event. - - `class OutputOutcomeTimeout: …` + - `type: Literal["response.mcp_call.in_progress"]` - Indicates that the shell call exceeded its configured time limit. + The type of the event. Always 'response.mcp_call.in_progress'. - - `type: Literal["timeout"]` + - `"response.mcp_call.in_progress"` - The outcome type. Always `timeout`. + - `agent: Optional[Agent]` - - `"timeout"` + The agent that owns this multi-agent streaming event. - - `class OutputOutcomeExit: …` + - `agent_name: str` - Indicates that the shell commands finished and returned an exit code. + The canonical name of the agent that produced this item. - - `exit_code: int` + - `class BetaResponseMcpListToolsCompletedEvent: …` - Exit code from the shell process. + Emitted when the list of available MCP tools has been successfully retrieved. - - `type: Literal["exit"]` + - `item_id: str` - The outcome type. Always `exit`. + The ID of the MCP tool call item that produced this output. - - `"exit"` + - `output_index: int` - - `stderr: str` + The index of the output item that was processed. - The standard error output that was captured. + - `sequence_number: int` - - `stdout: str` + The sequence number of this event. - The standard output that was captured. + - `type: Literal["response.mcp_list_tools.completed"]` - - `created_by: Optional[str]` + The type of the event. Always 'response.mcp_list_tools.completed'. - The identifier of the actor that created the item. + - `"response.mcp_list_tools.completed"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `agent: Optional[Agent]` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The agent that owns this multi-agent streaming event. - - `"in_progress"` + - `agent_name: str` - - `"completed"` + The canonical name of the agent that produced this item. - - `"incomplete"` + - `class BetaResponseMcpListToolsFailedEvent: …` - - `type: Literal["shell_call_output"]` + Emitted when the attempt to list available MCP tools has failed. - The type of the shell call output. Always `shell_call_output`. + - `item_id: str` - - `"shell_call_output"` + The ID of the MCP tool call item that failed. - - `agent: Optional[Agent]` + - `output_index: int` - The agent that produced this item. + The index of the output item that failed. - - `agent_name: str` + - `sequence_number: int` - The canonical name of the agent that produced this item. + The sequence number of this event. - - `caller: Optional[Caller]` + - `type: Literal["response.mcp_list_tools.failed"]` - The execution context that produced this tool call. + The type of the event. Always 'response.mcp_list_tools.failed'. - - `class CallerDirect: …` + - `"response.mcp_list_tools.failed"` - - `type: Literal["direct"]` + - `agent: Optional[Agent]` - - `"direct"` + The agent that owns this multi-agent streaming event. - - `class CallerProgram: …` + - `agent_name: str` - - `caller_id: str` + The canonical name of the agent that produced this item. - The call ID of the program item that produced this tool call. + - `class BetaResponseMcpListToolsInProgressEvent: …` - - `type: Literal["program"]` + Emitted when the system is in the process of retrieving the list of available MCP tools. - - `"program"` + - `item_id: str` - - `created_by: Optional[str]` + The ID of the MCP tool call item that is being processed. - The identifier of the actor that created the item. + - `output_index: int` - - `class BetaResponseApplyPatchToolCall: …` + The index of the output item that is being processed. - A tool call that applies file diffs by creating, deleting, or updating files. + - `sequence_number: int` - - `id: str` + The sequence number of this event. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `type: Literal["response.mcp_list_tools.in_progress"]` - - `call_id: str` + The type of the event. Always 'response.mcp_list_tools.in_progress'. - The unique ID of the apply patch tool call generated by the model. + - `"response.mcp_list_tools.in_progress"` - - `operation: Operation` + - `agent: Optional[Agent]` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The agent that owns this multi-agent streaming event. - - `class OperationCreateFile: …` + - `agent_name: str` - Instruction describing how to create a file via the apply_patch tool. + The canonical name of the agent that produced this item. - - `diff: str` + - `class BetaResponseOutputTextAnnotationAddedEvent: …` - Diff to apply. + Emitted when an annotation is added to output text content. - - `path: str` + - `annotation: object` - Path of the file to create. + The annotation object being added. (See annotation schema for details.) - - `type: Literal["create_file"]` + - `annotation_index: int` - Create a new file with the provided diff. + The index of the annotation within the content part. - - `"create_file"` + - `content_index: int` - - `class OperationDeleteFile: …` + The index of the content part within the output item. - Instruction describing how to delete a file via the apply_patch tool. + - `item_id: str` - - `path: str` + The unique identifier of the item to which the annotation is being added. - Path of the file to delete. + - `output_index: int` - - `type: Literal["delete_file"]` + The index of the output item in the response's output array. - Delete the specified file. + - `sequence_number: int` - - `"delete_file"` + The sequence number of this event. - - `class OperationUpdateFile: …` + - `type: Literal["response.output_text.annotation.added"]` - Instruction describing how to update a file via the apply_patch tool. + The type of the event. Always 'response.output_text.annotation.added'. - - `diff: str` + - `"response.output_text.annotation.added"` - Diff to apply. + - `agent: Optional[Agent]` - - `path: str` + The agent that owns this multi-agent streaming event. - Path of the file to update. + - `agent_name: str` - - `type: Literal["update_file"]` + The canonical name of the agent that produced this item. - Update an existing file with the provided diff. + - `class BetaResponseQueuedEvent: …` - - `"update_file"` + Emitted when a response is queued and waiting to be processed. - - `status: Literal["in_progress", "completed"]` + - `response: BetaResponse` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The full response object that is queued. - - `"in_progress"` + - `sequence_number: int` - - `"completed"` + The sequence number for this event. - - `type: Literal["apply_patch_call"]` + - `type: Literal["response.queued"]` - The type of the item. Always `apply_patch_call`. + The type of the event. Always 'response.queued'. - - `"apply_patch_call"` + - `"response.queued"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `class BetaResponseCustomToolCallInputDeltaEvent: …` - The execution context that produced this tool call. + Event representing a delta (partial update) to the input of a custom tool call. - - `class CallerDirect: …` + - `delta: str` - - `type: Literal["direct"]` + The incremental input data (delta) for the custom tool call. - - `"direct"` + - `item_id: str` - - `class CallerProgram: …` + Unique identifier for the API item associated with this event. - - `caller_id: str` + - `output_index: int` - The call ID of the program item that produced this tool call. + The index of the output this delta applies to. - - `type: Literal["program"]` + - `sequence_number: int` - - `"program"` + The sequence number of this event. - - `created_by: Optional[str]` + - `type: Literal["response.custom_tool_call_input.delta"]` - The ID of the entity that created this tool call. + The event type identifier. + + - `"response.custom_tool_call_input.delta"` + + - `agent: Optional[Agent]` + + The agent that owns this multi-agent streaming event. + + - `agent_name: str` + + The canonical name of the agent that produced this item. - - `class BetaResponseApplyPatchToolCallOutput: …` + - `class BetaResponseCustomToolCallInputDoneEvent: …` - The output emitted by an apply patch tool call. + Event indicating that input for a custom tool call is complete. - - `id: str` + - `input: str` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The complete input data for the custom tool call. - - `call_id: str` + - `item_id: str` - The unique ID of the apply patch tool call generated by the model. + Unique identifier for the API item associated with this event. - - `status: Literal["completed", "failed"]` + - `output_index: int` - The status of the apply patch tool call output. One of `completed` or `failed`. + The index of the output this event applies to. - - `"completed"` + - `sequence_number: int` - - `"failed"` + The sequence number of this event. - - `type: Literal["apply_patch_call_output"]` + - `type: Literal["response.custom_tool_call_input.done"]` - The type of the item. Always `apply_patch_call_output`. + The event type identifier. - - `"apply_patch_call_output"` + - `"response.custom_tool_call_input.done"` - `agent: Optional[Agent]` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: str` The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `class BetaResponseInjectCreatedEvent: …` - The execution context that produced this tool call. + Emitted when all injected input items were validated and committed to the + active response. - - `class CallerDirect: …` + - `response_id: str` - - `type: Literal["direct"]` + The ID of the response that accepted the input. - - `"direct"` + - `sequence_number: int` - - `class CallerProgram: …` + The sequence number for this event. - - `caller_id: str` + - `type: Literal["response.inject.created"]` - The call ID of the program item that produced this tool call. + The event discriminator. Always `response.inject.created`. - - `type: Literal["program"]` + - `"response.inject.created"` - - `"program"` + - `stream_id: Optional[str]` - - `created_by: Optional[str]` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - The ID of the entity that created this tool call output. + - `class BetaResponseInjectFailedEvent: …` - - `output: Optional[str]` + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. - Optional textual output returned by the apply patch tool. + - `error: Error` - - `class McpCall: …` + Information about why the input was not committed. - An invocation of a tool on an MCP server. + - `code: Literal["response_already_completed", "response_not_found"]` - - `id: str` + A machine-readable error code. - The unique ID of the tool call. + - `"response_already_completed"` - - `arguments: str` + - `"response_not_found"` - A JSON string of the arguments passed to the tool. + - `message: str` - - `name: str` + A human-readable description of the error. - The name of the tool that was run. + - `input: List[BetaResponseInputItem]` - - `server_label: str` + The raw input items that were not committed. - The label of the MCP server running the tool. + - `class BetaEasyInputMessage: …` - - `type: Literal["mcp_call"]` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - The type of the item. Always `mcp_call`. + - `class Message: …` - - `"mcp_call"` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `agent: Optional[McpCallAgent]` + - `class BetaResponseOutputMessage: …` - The agent that produced this item. + An output message from the model. - - `agent_name: str` + - `class BetaResponseFileSearchToolCall: …` - The canonical name of the agent that produced this item. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `approval_request_id: Optional[str]` + - `class BetaResponseComputerToolCall: …` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `error: Optional[str]` + - `class ComputerCallOutput: …` - The error from the tool call, if any. + The output of a computer tool call. - - `output: Optional[str]` + - `class BetaResponseFunctionWebSearch: …` - The output from the tool call. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `class BetaResponseFunctionToolCall: …` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `"in_progress"` + - `class FunctionCallOutput: …` - - `"completed"` + The output of a function tool call. - - `"incomplete"` + - `class AgentMessage: …` - - `"calling"` + A message routed between agents. - - `"failed"` + - `class MultiAgentCall: …` - - `class McpListTools: …` + - `class MultiAgentCallOutput: …` - A list of tools available on an MCP server. + - `class ToolSearchCall: …` - - `id: str` + - `class BetaResponseToolSearchOutputItemParam: …` - The unique ID of the list. + - `class AdditionalTools: …` - - `server_label: str` + - `class BetaResponseReasoningItem: …` - The label of the MCP server. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `tools: List[McpListToolsTool]` + - `class BetaResponseCompactionItemParam: …` - The tools available on the server. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `input_schema: object` + - `class ImageGenerationCall: …` - The JSON schema describing the tool's input. + An image generation request made by the model. - - `name: str` + - `class BetaResponseCodeInterpreterToolCall: …` - The name of the tool. + A tool call to run code. - - `annotations: Optional[object]` + - `class LocalShellCall: …` - Additional annotations about the tool. + A tool call to run a command on the local shell. - - `description: Optional[str]` + - `class LocalShellCallOutput: …` - The description of the tool. + The output of a local shell tool call. - - `type: Literal["mcp_list_tools"]` + - `class ShellCall: …` - The type of the item. Always `mcp_list_tools`. + A tool representing a request to execute one or more shell commands. - - `"mcp_list_tools"` + - `class ShellCallOutput: …` - - `agent: Optional[McpListToolsAgent]` + The streamed output items emitted by a shell tool call. - The agent that produced this item. + - `class ApplyPatchCall: …` - - `agent_name: str` + A tool call representing a request to create, delete, or update files using diff patches. - The canonical name of the agent that produced this item. + - `class ApplyPatchCallOutput: …` - - `error: Optional[str]` + The streamed output emitted by an apply patch tool call. - Error message if the server could not list tools. + - `class McpListTools: …` + + A list of tools available on an MCP server. - `class McpApprovalRequest: …` A request for human approval of a tool invocation. - - `id: str` + - `class McpApprovalResponse: …` - The unique ID of the approval request. + A response to an MCP approval request. - - `arguments: str` + - `class McpCall: …` - A JSON string of arguments for the tool. + An invocation of a tool on an MCP server. - - `name: str` + - `class BetaResponseCustomToolCallOutput: …` - The name of the tool to run. + The output of a custom tool call from your code, being sent back to the model. - - `server_label: str` + - `class BetaResponseCustomToolCall: …` - The label of the MCP server making the request. + A call to a custom tool created by the model. - - `type: Literal["mcp_approval_request"]` + - `class CompactionTrigger: …` - The type of the item. Always `mcp_approval_request`. + Compacts the current context. Must be the final input item. - - `"mcp_approval_request"` + - `class ItemReference: …` - - `agent: Optional[McpApprovalRequestAgent]` + An internal identifier for an item to reference. - The agent that produced this item. + - `class Program: …` - - `agent_name: str` + - `class ProgramOutput: …` - The canonical name of the agent that produced this item. + - `response_id: str` - - `class McpApprovalResponse: …` + The ID of the response that rejected the input. - A response to an MCP approval request. + - `sequence_number: int` - - `id: str` + The sequence number for this event. - The unique ID of the approval response + - `type: Literal["response.inject.failed"]` - - `approval_request_id: str` + The event discriminator. Always `response.inject.failed`. - The ID of the approval request being answered. + - `"response.inject.failed"` - - `approve: bool` + - `stream_id: Optional[str]` - Whether the request was approved. + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `type: Literal["mcp_approval_response"]` +### Beta Skill Reference - The type of the item. Always `mcp_approval_response`. +- `class BetaSkillReference: …` - - `"mcp_approval_response"` + - `skill_id: str` - - `agent: Optional[McpApprovalResponseAgent]` + The ID of the referenced skill. - The agent that produced this item. + - `type: Literal["skill_reference"]` - - `agent_name: str` + References a skill created with the /v1/skills endpoint. - The canonical name of the agent that produced this item. + - `"skill_reference"` - - `reason: Optional[str]` + - `version: Optional[str]` - Optional reason for the decision. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `class BetaResponseCustomToolCall: …` +### Beta Tool - A call to a custom tool created by the model. +- `BetaTool` - - `class BetaResponseCustomToolCallOutputItem: …` + A tool that can be used to generate a response. - The output of a custom tool call from your code, being sent back to the model. + - `class BetaFunctionTool: …` - - `id: str` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The unique ID of the custom tool call output item. + - `name: str` - - `status: Literal["in_progress", "completed", "incomplete"]` + The name of the function to call. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `parameters: Optional[Dict[str, object]]` - - `"in_progress"` + A JSON schema object describing the parameters of the function. - - `"completed"` + - `strict: Optional[bool]` - - `"incomplete"` + Whether strict parameter validation is enforced for this function tool. - - `created_by: Optional[str]` + - `type: Literal["function"]` - The identifier of the actor that created the item. + The type of the function tool. Always `function`. - - `parallel_tool_calls: bool` + - `"function"` - Whether to allow the model to run tool calls in parallel. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `temperature: Optional[float]` + The tool invocation context(s). - 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. - We generally recommend altering this or `top_p` but not both. + - `"direct"` - - `tool_choice: ToolChoice` + - `"programmatic"` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `defer_loading: Optional[bool]` - - `Literal["none", "auto", "required"]` + Whether this function is deferred and loaded via tool search. - - `"none"` + - `description: Optional[str]` - - `"auto"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"required"` + - `output_schema: Optional[Dict[str, object]]` - - `class BetaToolChoiceAllowed: …` + A JSON schema object describing the JSON value encoded in string outputs for this function. - Constrains the tools available to the model to a pre-defined set. + - `class BetaFileSearchTool: …` - - `mode: Literal["auto", "required"]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - Constrains the tools available to the model to a pre-defined set. + - `type: Literal["file_search"]` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The type of the file search tool. Always `file_search`. - `required` requires the model to call one or more of the allowed tools. + - `"file_search"` - - `"auto"` + - `vector_store_ids: List[str]` - - `"required"` + The IDs of the vector stores to search. - - `tools: List[Dict[str, object]]` + - `filters: Optional[Filters]` - A list of tool definitions that the model should be allowed to call. + A filter to apply. - For the Responses API, the list of tool definitions might look like: + - `class FiltersComparisonFilter: …` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: Literal["allowed_tools"]` + - `key: str` - Allowed tool configuration type. Always `allowed_tools`. + The key to compare against the value. - - `"allowed_tools"` + - `type: Literal["eq", "ne", "gt", 5 more]` - - `class BetaToolChoiceTypes: …` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + - `"eq"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"ne"` - Allowed values are: + - `"gt"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"gte"` - - `"file_search"` + - `"lt"` - - `"web_search_preview"` + - `"lte"` - - `"computer"` + - `"in"` - - `"computer_use_preview"` + - `"nin"` - - `"computer_use"` + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `"web_search_preview_2025_03_11"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"image_generation"` + - `str` - - `"code_interpreter"` + - `float` - - `class BetaToolChoiceFunction: …` + - `bool` - Use this option to force the model to call a specific function. + - `List[Union[str, float]]` - - `name: str` + - `str` - The name of the function to call. + - `float` - - `type: Literal["function"]` + - `class FiltersCompoundFilter: …` - For function calling, the type is always `function`. + Combine multiple filters using `and` or `or`. - - `"function"` + - `filters: List[FiltersCompoundFilterFilter]` - - `class BetaToolChoiceMcp: …` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `class FiltersCompoundFilterFilterComparisonFilter: …` - - `server_label: str` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The label of the MCP server to use. + - `key: str` - - `type: Literal["mcp"]` + The key to compare against the value. - For MCP tools, the type is always `mcp`. + - `type: Literal["eq", "ne", "gt", 5 more]` - - `"mcp"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `name: Optional[str]` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The name of the tool to call on the server. + - `"eq"` - - `class BetaToolChoiceCustom: …` + - `"ne"` - Use this option to force the model to call a specific custom tool. + - `"gt"` - - `name: str` + - `"gte"` - The name of the custom tool to call. + - `"lt"` - - `type: Literal["custom"]` + - `"lte"` - For custom tool calling, the type is always `custom`. + - `"in"` - - `"custom"` + - `"nin"` - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `type: Literal["programmatic_tool_calling"]` + The value to compare against the attribute key; supports string, number, or boolean types. - The tool to call. Always `programmatic_tool_calling`. + - `str` - - `"programmatic_tool_calling"` + - `float` - - `class BetaToolChoiceApplyPatch: …` + - `bool` - Forces the model to call the apply_patch tool when executing a tool call. + - `List[Union[str, float]]` - - `type: Literal["apply_patch"]` + - `str` - The tool to call. Always `apply_patch`. + - `float` - - `"apply_patch"` + - `object` - - `class BetaToolChoiceShell: …` + - `type: Literal["and", "or"]` - Forces the model to call the shell tool when a tool call is required. + Type of operation: `and` or `or`. - - `type: Literal["shell"]` + - `"and"` - The tool to call. Always `shell`. + - `"or"` - - `"shell"` + - `max_num_results: Optional[int]` - - `tools: List[BetaTool]` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `ranking_options: Optional[RankingOptions]` - We support the following categories of tools: + Ranking options for search. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - `class BetaFunctionTool: …` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `embedding_weight: float` - - `class BetaFileSearchTool: …` + The weight of the embedding in the reciprocal ranking fusion. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `text_weight: float` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: Optional[float]` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - `class BetaComputerTool: …` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: Literal["computer"]` + + The type of the computer tool. Always `computer`. + + - `"computer"` + - `class BetaComputerUsePreviewTool: …` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class BetaWebSearchTool: …` + - `display_height: int` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The height of the computer display. - - `class Mcp: …` + - `display_width: int` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The width of the computer display. - - `class CodeInterpreter: …` + - `environment: Literal["windows", "mac", "linux", 2 more]` - A tool that runs Python code to help generate a response to a prompt. + The type of computer environment to control. - - `class ProgrammaticToolCalling: …` + - `"windows"` - - `class ImageGeneration: …` + - `"mac"` - A tool that generates images using the GPT image models. + - `"linux"` - - `class LocalShell: …` + - `"ubuntu"` - A tool that allows the model to execute shell commands in a local environment. + - `"browser"` - - `class BetaFunctionShellTool: …` + - `type: Literal["computer_use_preview"]` - A tool that allows the model to execute shell commands. + The type of the computer use tool. Always `computer_use_preview`. - - `class BetaCustomTool: …` + - `"computer_use_preview"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `class BetaWebSearchTool: …` - - `class BetaNamespaceTool: …` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Groups function/custom tools under a shared namespace. + - `type: Literal["web_search", "web_search_2025_08_26"]` - - `class BetaToolSearchTool: …` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - Hosted or BYOT tool search configuration for deferred tools. + - `"web_search"` - - `class BetaWebSearchPreviewTool: …` + - `"web_search_2025_08_26"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `filters: Optional[Filters]` - - `class BetaApplyPatchTool: …` + Filters for the search. - Allows the assistant to create, delete, or update files using unified diffs. + - `allowed_domains: Optional[List[str]]` - - `top_p: Optional[float]` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - 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. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - We generally recommend altering this or `temperature` but not both. + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `background: Optional[bool]` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `"low"` - - `completed_at: Optional[float]` + - `"medium"` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `"high"` - - `conversation: Optional[Conversation]` + - `user_location: Optional[UserLocation]` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The approximate location of the user. - - `id: str` + - `city: Optional[str]` - The unique ID of the conversation that this response was associated with. + Free text input for the city of the user, e.g. `San Francisco`. - - `max_output_tokens: Optional[int]` + - `country: Optional[str]` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `max_tool_calls: Optional[int]` + - `region: Optional[str]` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + Free text input for the region of the user, e.g. `California`. - - `moderation: Optional[Moderation]` + - `timezone: Optional[str]` - Moderation results for the response input and output, if moderated completions were requested. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `input: ModerationInput` + - `type: Optional[Literal["approximate"]]` - Moderation for the response input. + The type of location approximation. Always `approximate`. - - `class ModerationInputModerationResult: …` + - `"approximate"` - A moderation result produced for the response input or output. + - `class Mcp: …` - - `categories: Dict[str, bool]` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `server_label: str` - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + A label for this MCP server, used to identify it in tool calls. - Which modalities of input are reflected by the score for each category. + - `type: Literal["mcp"]` - - `"text"` + The type of the MCP tool. Always `mcp`. - - `"image"` + - `"mcp"` - - `category_scores: Dict[str, float]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - A dictionary of moderation categories to scores. + The tool invocation context(s). - - `flagged: bool` + - `"direct"` - A boolean indicating whether the content was flagged by any category. + - `"programmatic"` - - `model: str` + - `allowed_tools: Optional[McpAllowedTools]` - The moderation model that produced this result. + List of allowed tool names or a filter object. - - `type: Literal["moderation_result"]` + - `List[str]` - The object type, which was always `moderation_result` for successful moderation results. + A string array of allowed tool names - - `"moderation_result"` + - `class McpAllowedToolsMcpToolFilter: …` - - `class ModerationInputError: …` + A filter object to specify which tools are allowed. - An error produced while attempting moderation for the response input or output. + - `read_only: Optional[bool]` - - `code: str` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The error code. + - `tool_names: Optional[List[str]]` - - `message: str` + List of allowed tool names. - The error message. + - `authorization: Optional[str]` - - `type: Literal["error"]` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The object type, which was always `error` for moderation failures. + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `"error"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `output: ModerationOutput` + Currently supported `connector_id` values are: - Moderation for the response output. + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `class ModerationOutputModerationResult: …` + - `"connector_dropbox"` - A moderation result produced for the response input or output. + - `"connector_gmail"` - - `categories: Dict[str, bool]` + - `"connector_googlecalendar"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"connector_googledrive"` - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `"connector_microsoftteams"` - Which modalities of input are reflected by the score for each category. + - `"connector_outlookcalendar"` - - `"text"` + - `"connector_outlookemail"` - - `"image"` + - `"connector_sharepoint"` - - `category_scores: Dict[str, float]` + - `defer_loading: Optional[bool]` - A dictionary of moderation categories to scores. + Whether this MCP tool is deferred and discovered via tool search. - - `flagged: bool` + - `headers: Optional[Dict[str, str]]` - A boolean indicating whether the content was flagged by any category. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `model: str` + - `require_approval: Optional[McpRequireApproval]` - The moderation model that produced this result. + Specify which of the MCP server's tools require approval. - - `type: Literal["moderation_result"]` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - The object type, which was always `moderation_result` for successful moderation results. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"moderation_result"` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `class ModerationOutputError: …` + A filter object to specify which tools are allowed. - An error produced while attempting moderation for the response input or output. + - `read_only: Optional[bool]` - - `code: str` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The error code. + - `tool_names: Optional[List[str]]` - - `message: str` + List of allowed tool names. - The error message. + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - - `type: Literal["error"]` + A filter object to specify which tools are allowed. - The object type, which was always `error` for moderation failures. + - `read_only: Optional[bool]` - - `"error"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `previous_response_id: Optional[str]` + - `tool_names: Optional[List[str]]` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + List of allowed tool names. - - `prompt: Optional[BetaResponsePrompt]` + - `Literal["always", "never"]` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `id: str` + - `"always"` - The unique identifier of the prompt template to use. + - `"never"` - - `variables: Optional[Dict[str, Variables]]` + - `server_description: Optional[str]` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + Optional description of the MCP server, used to provide more context. - - `str` + - `server_url: Optional[str]` - - `class BetaResponseInputText: …` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - A text input to the model. + - `tunnel_id: Optional[str]` - - `class BetaResponseInputImage: …` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class CodeInterpreter: …` - - `class BetaResponseInputFile: …` + A tool that runs Python code to help generate a response to a prompt. - A file input to the model. + - `container: CodeInterpreterContainer` - - `version: Optional[str]` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - Optional version of the prompt template. + - `str` - - `prompt_cache_key: Optional[str]` + The container ID. - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `prompt_cache_options: Optional[PromptCacheOptions]` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `type: Literal["auto"]` - - `mode: Literal["implicit", "explicit"]` + Always `auto`. - Whether implicit prompt-cache breakpoints were enabled. + - `"auto"` - - `"implicit"` + - `file_ids: Optional[List[str]]` - - `"explicit"` + An optional list of uploaded files to make available to your code. - - `ttl: Literal["30m"]` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The minimum lifetime applied to each cache breakpoint. + The memory limit for the code interpreter container. - - `"30m"` + - `"1g"` - - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + - `"4g"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `"16g"` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `"64g"` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + Network access policy for the container. - - `"in_memory"` + - `class BetaContainerNetworkPolicyDisabled: …` - - `"24h"` + - `type: Literal["disabled"]` - - `reasoning: Optional[Reasoning]` + Disable outbound network access. Always `disabled`. - **gpt-5 and o-series models only** + - `"disabled"` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `class BetaContainerNetworkPolicyAllowlist: …` - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + - `allowed_domains: List[str]` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + A list of allowed domains when type is `allowlist`. - - `"auto"` + - `type: Literal["allowlist"]` - - `"current_turn"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"all_turns"` + - `"allowlist"` - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + Optional domain-scoped secrets for allowlisted domains. - - `"none"` + - `domain: str` - - `"minimal"` + The domain associated with the secret. - - `"low"` + - `name: str` - - `"medium"` + The name of the secret to inject for the domain. - - `"high"` + - `value: str` - - `"xhigh"` + The secret value to inject for the domain. - - `"max"` + - `type: Literal["code_interpreter"]` - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + The type of the code interpreter tool. Always `code_interpreter`. - **Deprecated:** use `summary` instead. + - `"code_interpreter"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"auto"` + The tool invocation context(s). - - `"concise"` + - `"direct"` - - `"detailed"` + - `"programmatic"` - - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + - `class ProgrammaticToolCalling: …` - Controls the reasoning execution mode for the request. + - `type: Literal["programmatic_tool_calling"]` - When returned on a response, this is the effective execution mode. + The type of the tool. Always `programmatic_tool_calling`. - - `str` + - `"programmatic_tool_calling"` - - `Literal["standard", "pro"]` + - `class ImageGeneration: …` - Controls the reasoning execution mode for the request. + A tool that generates images using the GPT image models. - When returned on a response, this is the effective execution mode. + - `type: Literal["image_generation"]` - - `"standard"` + The type of the image generation tool. Always `image_generation`. - - `"pro"` + - `"image_generation"` - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + - `action: Optional[Literal["generate", "edit", "auto"]]` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + Whether to generate a new image or edit an existing image. Default: `auto`. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `"generate"` + + - `"edit"` - `"auto"` - - `"concise"` + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - - `"detailed"` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `safety_identifier: Optional[str]` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + - `"transparent"` - Specifies the processing type used for serving the request. + - `"opaque"` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `"auto"` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `input_fidelity: Optional[Literal["high", "low"]]` - - `"auto"` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `"default"` + - `"high"` - - `"flex"` + - `"low"` - - `"scale"` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - - `"priority"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `status: Optional[BetaResponseStatus]` + - `file_id: Optional[str]` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + File ID for the mask image. - - `"completed"` + - `image_url: Optional[str]` - - `"failed"` + Base64-encoded mask image. - - `"in_progress"` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - - `"cancelled"` + The image generation model to use. Default: `gpt-image-1`. - - `"queued"` + - `str` - - `"incomplete"` + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `text: Optional[BetaResponseTextConfig]` + The image generation model to use. Default: `gpt-image-1`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `"gpt-image-1"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `"gpt-image-1-mini"` - - `format: Optional[BetaResponseFormatTextConfig]` + - `"gpt-image-2"` - An object specifying the format that the model must output. + - `"gpt-image-2-2026-04-21"` - Configuring `{ "type": "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). + - `"gpt-image-1.5"` - The default format is `{ "type": "text" }` with no additional options. + - `"chatgpt-image-latest"` - **Not recommended for gpt-4o and newer models:** + - `moderation: Optional[Literal["auto", "low"]]` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + Moderation level for the generated image. Default: `auto`. - - `class Text: …` + - `"auto"` - Default response format. Used to generate text responses. + - `"low"` - - `type: Literal["text"]` + - `output_compression: Optional[int]` - The type of response format being defined. Always `text`. + Compression level for the output image. Default: 100. - - `"text"` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `class BetaResponseFormatTextJSONSchemaConfig: …` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"png"` - - `name: str` + - `"webp"` - 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. + - `"jpeg"` - - `schema: Dict[str, object]` + - `partial_images: Optional[int]` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: Literal["json_schema"]` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - The type of response format being defined. Always `json_schema`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"json_schema"` + - `"low"` - - `description: Optional[str]` + - `"medium"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"high"` - - `strict: Optional[bool]` + - `"auto"` + + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `str` + + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - 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). + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `class JSONObject: …` + - `"1024x1024"` - 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. + - `"1024x1536"` - - `type: Literal["json_object"]` + - `"1536x1024"` - The type of response format being defined. Always `json_object`. + - `"auto"` - - `"json_object"` + - `class LocalShell: …` - - `verbosity: Optional[Literal["low", "medium", "high"]]` + A tool that allows the model to execute shell commands in a local environment. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `type: Literal["local_shell"]` - - `"low"` + The type of the local shell tool. Always `local_shell`. - - `"medium"` + - `"local_shell"` - - `"high"` + - `class BetaFunctionShellTool: …` - - `top_logprobs: Optional[int]` + A tool that allows the model to execute shell commands. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `type: Literal["shell"]` - - `truncation: Optional[Literal["auto", "disabled"]]` + The type of the shell tool. Always `shell`. - The truncation strategy to use for the model response. + - `"shell"` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `"auto"` + The tool invocation context(s). - - `"disabled"` + - `"direct"` - - `usage: Optional[BetaResponseUsage]` + - `"programmatic"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `environment: Optional[Environment]` - - `input_tokens: int` + - `class BetaContainerAuto: …` - The number of input tokens. + - `type: Literal["container_auto"]` - - `input_tokens_details: InputTokensDetails` + Automatically creates a container for this request - A detailed breakdown of the input tokens. + - `"container_auto"` - - `cache_write_tokens: int` + - `file_ids: Optional[List[str]]` - The number of input tokens that were written to the cache. + An optional list of uploaded files to make available to your code. - - `cached_tokens: int` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The memory limit for the container. - - `output_tokens: int` + - `"1g"` - The number of output tokens. + - `"4g"` - - `output_tokens_details: OutputTokensDetails` + - `"16g"` - A detailed breakdown of the output tokens. + - `"64g"` - - `reasoning_tokens: int` + - `network_policy: Optional[NetworkPolicy]` - The number of reasoning tokens. + Network access policy for the container. - - `total_tokens: int` + - `class BetaContainerNetworkPolicyDisabled: …` - The total number of tokens used. + - `class BetaContainerNetworkPolicyAllowlist: …` - - `user: Optional[str]` + - `skills: Optional[List[Skill]]` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + An optional list of skills referenced by id or inline data. - - `sequence_number: int` + - `class BetaSkillReference: …` - The sequence number for this event. + - `skill_id: str` - - `type: Literal["response.completed"]` + The ID of the referenced skill. - The type of the event. Always `response.completed`. + - `type: Literal["skill_reference"]` - - `"response.completed"` + References a skill created with the /v1/skills endpoint. - - `agent: Optional[Agent]` + - `"skill_reference"` - The agent that owns this multi-agent streaming event. + - `version: Optional[str]` - - `agent_name: str` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The canonical name of the agent that produced this item. + - `class BetaInlineSkill: …` - - `class BetaResponseContentPartAddedEvent: …` + - `description: str` - Emitted when a new content part is added. + The description of the skill. - - `content_index: int` + - `name: str` - The index of the content part that was added. + The name of the skill. - - `item_id: str` + - `source: BetaInlineSkillSource` - The ID of the output item that the content part was added to. + Inline skill payload - - `output_index: int` + - `data: str` - The index of the output item that the content part was added to. + Base64-encoded skill zip bundle. - - `part: Part` + - `media_type: Literal["application/zip"]` - The content part that was added. + The media type of the inline skill payload. Must be `application/zip`. - - `class BetaResponseOutputText: …` + - `"application/zip"` - A text output from the model. + - `type: Literal["base64"]` - - `class BetaResponseOutputRefusal: …` + The type of the inline skill source. Must be `base64`. - A refusal from the model. + - `"base64"` - - `class PartReasoningText: …` + - `type: Literal["inline"]` - Reasoning text from the model. + Defines an inline skill for this request. - - `text: str` + - `"inline"` - The reasoning text from the model. + - `class BetaLocalEnvironment: …` - - `type: Literal["reasoning_text"]` + - `type: Literal["local"]` - The type of the reasoning text. Always `reasoning_text`. + Use a local computer environment. - - `"reasoning_text"` + - `"local"` - - `sequence_number: int` + - `skills: Optional[List[BetaLocalSkill]]` - The sequence number of this event. + An optional list of skills. - - `type: Literal["response.content_part.added"]` + - `description: str` - The type of the event. Always `response.content_part.added`. + The description of the skill. - - `"response.content_part.added"` + - `name: str` - - `agent: Optional[Agent]` + The name of the skill. - The agent that owns this multi-agent streaming event. + - `path: str` - - `agent_name: str` + The path to the directory containing the skill. - The canonical name of the agent that produced this item. + - `class BetaContainerReference: …` - - `class BetaResponseContentPartDoneEvent: …` + - `container_id: str` - Emitted when a content part is done. + The ID of the referenced container. - - `content_index: int` + - `type: Literal["container_reference"]` - The index of the content part that is done. + References a container created with the /v1/containers endpoint - - `item_id: str` + - `"container_reference"` - The ID of the output item that the content part was added to. + - `class BetaCustomTool: …` - - `output_index: int` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The index of the output item that the content part was added to. + - `name: str` - - `part: Part` + The name of the custom tool, used to identify it in tool calls. - The content part that is done. + - `type: Literal["custom"]` - - `class BetaResponseOutputText: …` + The type of the custom tool. Always `custom`. - A text output from the model. + - `"custom"` - - `class BetaResponseOutputRefusal: …` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - A refusal from the model. + The tool invocation context(s). - - `class PartReasoningText: …` + - `"direct"` - Reasoning text from the model. + - `"programmatic"` - - `text: str` + - `defer_loading: Optional[bool]` - The reasoning text from the model. + Whether this tool should be deferred and discovered via tool search. - - `type: Literal["reasoning_text"]` + - `description: Optional[str]` - The type of the reasoning text. Always `reasoning_text`. + Optional description of the custom tool, used to provide more context. - - `"reasoning_text"` + - `format: Optional[Format]` - - `sequence_number: int` + The input format for the custom tool. Default is unconstrained text. - The sequence number of this event. + - `class FormatText: …` - - `type: Literal["response.content_part.done"]` + Unconstrained free-form text. - The type of the event. Always `response.content_part.done`. + - `type: Literal["text"]` - - `"response.content_part.done"` + Unconstrained text format. Always `text`. - - `agent: Optional[Agent]` + - `"text"` - The agent that owns this multi-agent streaming event. + - `class FormatGrammar: …` - - `agent_name: str` + A grammar defined by the user. - The canonical name of the agent that produced this item. + - `definition: str` - - `class BetaResponseCreatedEvent: …` + The grammar definition. - An event that is emitted when a response is created. + - `syntax: Literal["lark", "regex"]` - - `response: BetaResponse` + The syntax of the grammar definition. One of `lark` or `regex`. - The response that was created. + - `"lark"` - - `sequence_number: int` + - `"regex"` - The sequence number for this event. + - `type: Literal["grammar"]` - - `type: Literal["response.created"]` + Grammar format. Always `grammar`. - The type of the event. Always `response.created`. + - `"grammar"` - - `"response.created"` + - `class BetaNamespaceTool: …` - - `agent: Optional[Agent]` + Groups function/custom tools under a shared namespace. - The agent that owns this multi-agent streaming event. + - `description: str` - - `agent_name: str` + A description of the namespace shown to the model. - The canonical name of the agent that produced this item. + - `name: str` - - `class BetaResponseErrorEvent: …` + The namespace name used in tool calls (for example, `crm`). - Emitted when an error occurs. + - `tools: List[Tool]` - - `code: Optional[str]` + The function/custom tools available inside this namespace. - The error code. + - `class ToolFunction: …` - - `message: str` + - `name: str` - The error message. + - `type: Literal["function"]` - - `param: Optional[str]` + - `"function"` - The error parameter. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `sequence_number: int` + The tool invocation context(s). - The sequence number of this event. + - `"direct"` - - `type: Literal["error"]` + - `"programmatic"` - The type of the event. Always `error`. + - `defer_loading: Optional[bool]` - - `"error"` + Whether this function should be deferred and discovered via tool search. - - `agent: Optional[Agent]` + - `description: Optional[str]` - The agent that owns this multi-agent streaming event. + - `output_schema: Optional[Dict[str, object]]` - - `agent_name: str` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The canonical name of the agent that produced this item. + - `parameters: Optional[object]` - - `class BetaResponseFileSearchCallCompletedEvent: …` + - `strict: Optional[bool]` - Emitted when a file search call is completed (results found). + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `item_id: str` + - `class BetaCustomTool: …` - The ID of the output item that the file search call is initiated. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `output_index: int` + - `type: Literal["namespace"]` - The index of the output item that the file search call is initiated. + The type of the tool. Always `namespace`. - - `sequence_number: int` + - `"namespace"` - The sequence number of this event. + - `class BetaToolSearchTool: …` - - `type: Literal["response.file_search_call.completed"]` + Hosted or BYOT tool search configuration for deferred tools. - The type of the event. Always `response.file_search_call.completed`. + - `type: Literal["tool_search"]` - - `"response.file_search_call.completed"` + The type of the tool. Always `tool_search`. - - `agent: Optional[Agent]` + - `"tool_search"` - The agent that owns this multi-agent streaming event. + - `description: Optional[str]` - - `agent_name: str` + Description shown to the model for a client-executed tool search tool. - The canonical name of the agent that produced this item. + - `execution: Optional[Literal["server", "client"]]` - - `class BetaResponseFileSearchCallInProgressEvent: …` + Whether tool search is executed by the server or by the client. - Emitted when a file search call is initiated. + - `"server"` - - `item_id: str` + - `"client"` - The ID of the output item that the file search call is initiated. + - `parameters: Optional[object]` - - `output_index: int` + Parameter schema for a client-executed tool search tool. - The index of the output item that the file search call is initiated. + - `class BetaWebSearchPreviewTool: …` - - `sequence_number: int` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The sequence number of this event. + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - - `type: Literal["response.file_search_call.in_progress"]` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The type of the event. Always `response.file_search_call.in_progress`. + - `"web_search_preview"` - - `"response.file_search_call.in_progress"` + - `"web_search_preview_2025_03_11"` - - `agent: Optional[Agent]` + - `search_content_types: Optional[List[Literal["text", "image"]]]` - The agent that owns this multi-agent streaming event. + - `"text"` - - `agent_name: str` + - `"image"` - The canonical name of the agent that produced this item. + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `class BetaResponseFileSearchCallSearchingEvent: …` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - Emitted when a file search is currently searching. + - `"low"` - - `item_id: str` + - `"medium"` - The ID of the output item that the file search call is initiated. + - `"high"` - - `output_index: int` + - `user_location: Optional[UserLocation]` - The index of the output item that the file search call is searching. + The user's location. - - `sequence_number: int` + - `type: Literal["approximate"]` - The sequence number of this event. + The type of location approximation. Always `approximate`. - - `type: Literal["response.file_search_call.searching"]` + - `"approximate"` - The type of the event. Always `response.file_search_call.searching`. + - `city: Optional[str]` - - `"response.file_search_call.searching"` + Free text input for the city of the user, e.g. `San Francisco`. - - `agent: Optional[Agent]` + - `country: Optional[str]` - The agent that owns this multi-agent streaming event. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `agent_name: str` + - `region: Optional[str]` - The canonical name of the agent that produced this item. + Free text input for the region of the user, e.g. `California`. - - `class BetaResponseFunctionCallArgumentsDeltaEvent: …` + - `timezone: Optional[str]` - Emitted when there is a partial function-call arguments delta. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `delta: str` + - `class BetaApplyPatchTool: …` - The function-call arguments delta that is added. + Allows the assistant to create, delete, or update files using unified diffs. - - `item_id: str` + - `type: Literal["apply_patch"]` - The ID of the output item that the function-call arguments delta is added to. + The type of the tool. Always `apply_patch`. - - `output_index: int` + - `"apply_patch"` - The index of the output item that the function-call arguments delta is added to. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `sequence_number: int` + The tool invocation context(s). - The sequence number of this event. + - `"direct"` - - `type: Literal["response.function_call_arguments.delta"]` + - `"programmatic"` - The type of the event. Always `response.function_call_arguments.delta`. +### Beta Tool Choice Allowed - - `"response.function_call_arguments.delta"` +- `class BetaToolChoiceAllowed: …` - - `agent: Optional[Agent]` + Constrains the tools available to the model to a pre-defined set. - The agent that owns this multi-agent streaming event. + - `mode: Literal["auto", "required"]` - - `agent_name: str` + Constrains the tools available to the model to a pre-defined set. - The canonical name of the agent that produced this item. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `class BetaResponseFunctionCallArgumentsDoneEvent: …` + `required` requires the model to call one or more of the allowed tools. - Emitted when function-call arguments are finalized. + - `"auto"` - - `arguments: str` + - `"required"` - The function-call arguments. + - `tools: List[Dict[str, object]]` - - `item_id: str` + A list of tool definitions that the model should be allowed to call. - The ID of the item. + For the Responses API, the list of tool definitions might look like: - - `name: str` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - The name of the function that was called. + - `type: Literal["allowed_tools"]` - - `output_index: int` + Allowed tool configuration type. Always `allowed_tools`. - The index of the output item. + - `"allowed_tools"` - - `sequence_number: int` +### Beta Tool Choice Apply Patch - The sequence number of this event. +- `class BetaToolChoiceApplyPatch: …` - - `type: Literal["response.function_call_arguments.done"]` + Forces the model to call the apply_patch tool when executing a tool call. - - `"response.function_call_arguments.done"` + - `type: Literal["apply_patch"]` - - `agent: Optional[Agent]` + The tool to call. Always `apply_patch`. - The agent that owns this multi-agent streaming event. + - `"apply_patch"` - - `agent_name: str` +### Beta Tool Choice Custom - The canonical name of the agent that produced this item. +- `class BetaToolChoiceCustom: …` - - `class BetaResponseInProgressEvent: …` + Use this option to force the model to call a specific custom tool. - Emitted when the response is in progress. + - `name: str` - - `response: BetaResponse` + The name of the custom tool to call. - The response that is in progress. + - `type: Literal["custom"]` - - `sequence_number: int` + For custom tool calling, the type is always `custom`. - The sequence number of this event. + - `"custom"` - - `type: Literal["response.in_progress"]` +### Beta Tool Choice Function - The type of the event. Always `response.in_progress`. +- `class BetaToolChoiceFunction: …` - - `"response.in_progress"` + Use this option to force the model to call a specific function. - - `agent: Optional[Agent]` + - `name: str` - The agent that owns this multi-agent streaming event. + The name of the function to call. - - `agent_name: str` + - `type: Literal["function"]` - The canonical name of the agent that produced this item. + For function calling, the type is always `function`. - - `class BetaResponseFailedEvent: …` + - `"function"` - An event that is emitted when a response fails. +### Beta Tool Choice Mcp - - `response: BetaResponse` +- `class BetaToolChoiceMcp: …` - The response that failed. + Use this option to force the model to call a specific tool on a remote MCP server. - - `sequence_number: int` + - `server_label: str` - The sequence number of this event. + The label of the MCP server to use. - - `type: Literal["response.failed"]` + - `type: Literal["mcp"]` - The type of the event. Always `response.failed`. + For MCP tools, the type is always `mcp`. - - `"response.failed"` + - `"mcp"` - - `agent: Optional[Agent]` + - `name: Optional[str]` - The agent that owns this multi-agent streaming event. + The name of the tool to call on the server. - - `agent_name: str` +### Beta Tool Choice Options - The canonical name of the agent that produced this item. +- `Literal["none", "auto", "required"]` - - `class BetaResponseIncompleteEvent: …` + Controls which (if any) tool is called by the model. - An event that is emitted when a response finishes as incomplete. + `none` means the model will not call any tool and instead generates a message. - - `response: BetaResponse` + `auto` means the model can pick between generating a message or calling one or + more tools. - The response that was incomplete. + `required` means the model must call one or more tools. - - `sequence_number: int` + - `"none"` - The sequence number of this event. + - `"auto"` - - `type: Literal["response.incomplete"]` + - `"required"` - The type of the event. Always `response.incomplete`. +### Beta Tool Choice Shell - - `"response.incomplete"` +- `class BetaToolChoiceShell: …` - - `agent: Optional[Agent]` + Forces the model to call the shell tool when a tool call is required. - The agent that owns this multi-agent streaming event. + - `type: Literal["shell"]` - - `agent_name: str` + The tool to call. Always `shell`. - The canonical name of the agent that produced this item. + - `"shell"` - - `class BetaResponseOutputItemAddedEvent: …` +### Beta Tool Choice Types - Emitted when a new output item is added. +- `class BetaToolChoiceTypes: …` - - `item: BetaResponseOutputItem` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - The output item that was added. + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` - - `class BetaResponseOutputMessage: …` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - An output message from the model. + Allowed values are: - - `class BetaResponseFileSearchToolCall: …` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"file_search"` - - `class BetaResponseFunctionToolCall: …` + - `"web_search_preview"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"computer"` - - `class BetaResponseFunctionToolCallOutputItem: …` + - `"computer_use_preview"` - - `class AgentMessage: …` + - `"computer_use"` - - `class MultiAgentCall: …` + - `"web_search_preview_2025_03_11"` - - `class MultiAgentCallOutput: …` + - `"image_generation"` - - `class BetaResponseFunctionWebSearch: …` + - `"code_interpreter"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. +### Beta Tool Search Tool - - `class BetaResponseComputerToolCall: …` +- `class BetaToolSearchTool: …` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Hosted or BYOT tool search configuration for deferred tools. - - `class BetaResponseComputerToolCallOutputItem: …` + - `type: Literal["tool_search"]` - - `class BetaResponseReasoningItem: …` + The type of the tool. Always `tool_search`. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `"tool_search"` - - `class Program: …` + - `description: Optional[str]` - - `class ProgramOutput: …` + Description shown to the model for a client-executed tool search tool. - - `class BetaResponseToolSearchCall: …` + - `execution: Optional[Literal["server", "client"]]` - - `class BetaResponseToolSearchOutputItem: …` + Whether tool search is executed by the server or by the client. - - `class AdditionalTools: …` + - `"server"` - - `class BetaResponseCompactionItem: …` + - `"client"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `parameters: Optional[object]` - - `class ImageGenerationCall: …` + Parameter schema for a client-executed tool search tool. - An image generation request made by the model. +### Beta Web Search Preview Tool - - `class BetaResponseCodeInterpreterToolCall: …` +- `class BetaWebSearchPreviewTool: …` - A tool call to run code. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class LocalShellCall: …` + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - A tool call to run a command on the local shell. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `class LocalShellCallOutput: …` + - `"web_search_preview"` - The output of a local shell tool call. + - `"web_search_preview_2025_03_11"` - - `class BetaResponseFunctionShellToolCall: …` + - `search_content_types: Optional[List[Literal["text", "image"]]]` - A tool call that executes one or more shell commands in a managed environment. + - `"text"` - - `class BetaResponseFunctionShellToolCallOutput: …` + - `"image"` - The output of a shell tool call that was emitted. + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `class BetaResponseApplyPatchToolCall: …` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - A tool call that applies file diffs by creating, deleting, or updating files. + - `"low"` - - `class BetaResponseApplyPatchToolCallOutput: …` + - `"medium"` - The output emitted by an apply patch tool call. + - `"high"` - - `class McpCall: …` + - `user_location: Optional[UserLocation]` - An invocation of a tool on an MCP server. + The user's location. - - `class McpListTools: …` + - `type: Literal["approximate"]` - A list of tools available on an MCP server. + The type of location approximation. Always `approximate`. - - `class McpApprovalRequest: …` + - `"approximate"` - A request for human approval of a tool invocation. + - `city: Optional[str]` - - `class McpApprovalResponse: …` + Free text input for the city of the user, e.g. `San Francisco`. - A response to an MCP approval request. + - `country: Optional[str]` - - `class BetaResponseCustomToolCall: …` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A call to a custom tool created by the model. + - `region: Optional[str]` - - `class BetaResponseCustomToolCallOutputItem: …` + Free text input for the region of the user, e.g. `California`. - The output of a custom tool call from your code, being sent back to the model. + - `timezone: Optional[str]` - - `output_index: int` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The index of the output item that was added. +### Beta Web Search Tool - - `sequence_number: int` +- `class BetaWebSearchTool: …` - The sequence number of this event. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `type: Literal["response.output_item.added"]` + - `type: Literal["web_search", "web_search_2025_08_26"]` - The type of the event. Always `response.output_item.added`. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"response.output_item.added"` + - `"web_search"` - - `agent: Optional[Agent]` + - `"web_search_2025_08_26"` - The agent that owns this multi-agent streaming event. + - `filters: Optional[Filters]` - - `agent_name: str` + Filters for the search. - The canonical name of the agent that produced this item. + - `allowed_domains: Optional[List[str]]` - - `class BetaResponseOutputItemDoneEvent: …` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Emitted when an output item is marked done. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `item: BetaResponseOutputItem` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - The output item that was marked done. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `output_index: int` + - `"low"` - The index of the output item that was marked done. + - `"medium"` - - `sequence_number: int` + - `"high"` - The sequence number of this event. + - `user_location: Optional[UserLocation]` - - `type: Literal["response.output_item.done"]` + The approximate location of the user. - The type of the event. Always `response.output_item.done`. + - `city: Optional[str]` - - `"response.output_item.done"` + Free text input for the city of the user, e.g. `San Francisco`. - - `agent: Optional[Agent]` + - `country: Optional[str]` - The agent that owns this multi-agent streaming event. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `agent_name: str` + - `region: Optional[str]` - The canonical name of the agent that produced this item. + Free text input for the region of the user, e.g. `California`. - - `class BetaResponseReasoningSummaryPartAddedEvent: …` + - `timezone: Optional[str]` - Emitted when a new reasoning summary part is added. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `item_id: str` + - `type: Optional[Literal["approximate"]]` - The ID of the item this summary part is associated with. + The type of location approximation. Always `approximate`. - - `output_index: int` + - `"approximate"` - The index of the output item this summary part is associated with. +# Input Items - - `part: Part` +## List input items - The summary part that was added. +`beta.responses.input_items.list(strresponse_id, InputItemListParams**kwargs) -> SyncCursorPage[BetaResponseItem]` - - `text: str` +**get** `/responses/{response_id}/input_items?beta=true` - The text of the summary part. +Returns a list of input items for a given response. - - `type: Literal["summary_text"]` +### Parameters - The type of the summary part. Always `summary_text`. +- `response_id: str` - - `"summary_text"` +- `after: Optional[str]` - - `sequence_number: int` + An item ID to list items after, used in pagination. - The sequence number of this event. +- `include: Optional[List[BetaResponseIncludable]]` - - `summary_index: int` + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. - The index of the summary part within the reasoning summary. + - `"file_search_call.results"` - - `type: Literal["response.reasoning_summary_part.added"]` + - `"web_search_call.results"` - The type of the event. Always `response.reasoning_summary_part.added`. + - `"web_search_call.action.sources"` - - `"response.reasoning_summary_part.added"` + - `"message.input_image.image_url"` - - `agent: Optional[Agent]` + - `"computer_call_output.output.image_url"` - The agent that owns this multi-agent streaming event. + - `"code_interpreter_call.outputs"` - - `agent_name: str` + - `"reasoning.encrypted_content"` - The canonical name of the agent that produced this item. + - `"message.output_text.logprobs"` - - `class BetaResponseReasoningSummaryPartDoneEvent: …` +- `limit: Optional[int]` - Emitted when a reasoning summary part is completed. + A limit on the number of objects to be returned. Limit can range between + 1 and 100, and the default is 20. - - `item_id: str` +- `order: Optional[Literal["asc", "desc"]]` - The ID of the item this summary part is associated with. + The order to return the input items in. Default is `desc`. - - `output_index: int` + - `asc`: Return the input items in ascending order. + - `desc`: Return the input items in descending order. - The index of the output item this summary part is associated with. + - `"asc"` - - `part: Part` + - `"desc"` - The completed summary part. +- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` - - `text: str` + - `"responses_multi_agent=v1"` - The text of the summary part. +### Returns - - `type: Literal["summary_text"]` +- `BetaResponseItem` - The type of the summary part. Always `summary_text`. + Content item used to generate a response. - - `"summary_text"` + - `class BetaResponseInputMessageItem: …` - - `sequence_number: int` + - `id: str` - The sequence number of this event. + The unique ID of the message input. - - `summary_index: int` + - `content: BetaResponseInputMessageContentList` - The index of the summary part within the reasoning summary. + A list of one or many input items to the model, containing different content + types. - - `type: Literal["response.reasoning_summary_part.done"]` + - `class BetaResponseInputText: …` - The type of the event. Always `response.reasoning_summary_part.done`. + A text input to the model. - - `"response.reasoning_summary_part.done"` + - `text: str` - - `agent: Optional[Agent]` + The text input to the model. - The agent that owns this multi-agent streaming event. + - `type: Literal["input_text"]` - - `agent_name: str` + The type of the input item. Always `input_text`. - The canonical name of the agent that produced this item. + - `"input_text"` - - `status: Optional[Literal["incomplete"]]` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"incomplete"` + - `mode: Literal["explicit"]` - - `class BetaResponseReasoningSummaryTextDeltaEvent: …` + The breakpoint mode. Always `explicit`. - Emitted when a delta is added to a reasoning summary text. + - `"explicit"` - - `delta: str` + - `class BetaResponseInputImage: …` - The text delta that was added to the summary. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `item_id: str` + - `detail: Literal["low", "high", "auto", "original"]` - The ID of the item this summary text delta is associated with. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `output_index: int` + - `"low"` - The index of the output item this summary text delta is associated with. + - `"high"` - - `sequence_number: int` + - `"auto"` - The sequence number of this event. + - `"original"` - - `summary_index: int` + - `type: Literal["input_image"]` - The index of the summary part within the reasoning summary. + The type of the input item. Always `input_image`. - - `type: Literal["response.reasoning_summary_text.delta"]` + - `"input_image"` - The type of the event. Always `response.reasoning_summary_text.delta`. + - `file_id: Optional[str]` - - `"response.reasoning_summary_text.delta"` + The ID of the file to be sent to the model. - - `agent: Optional[Agent]` + - `image_url: Optional[str]` - The agent that owns this multi-agent streaming event. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `agent_name: str` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The canonical name of the agent that produced this item. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaResponseReasoningSummaryTextDoneEvent: …` + - `mode: Literal["explicit"]` - Emitted when a reasoning summary text is completed. + The breakpoint mode. Always `explicit`. - - `item_id: str` + - `"explicit"` - The ID of the item this summary text is associated with. + - `class BetaResponseInputFile: …` - - `output_index: int` + A file input to the model. - The index of the output item this summary text is associated with. + - `type: Literal["input_file"]` - - `sequence_number: int` + The type of the input item. Always `input_file`. - The sequence number of this event. + - `"input_file"` - - `summary_index: int` + - `detail: Optional[Literal["auto", "low", "high"]]` - The index of the summary part within the reasoning summary. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `text: str` + - `"auto"` - The full text of the completed reasoning summary. + - `"low"` - - `type: Literal["response.reasoning_summary_text.done"]` + - `"high"` - The type of the event. Always `response.reasoning_summary_text.done`. + - `file_data: Optional[str]` - - `"response.reasoning_summary_text.done"` + The content of the file to be sent to the model. - - `agent: Optional[Agent]` + - `file_id: Optional[str]` - The agent that owns this multi-agent streaming event. + The ID of the file to be sent to the model. - - `agent_name: str` + - `file_url: Optional[str]` - The canonical name of the agent that produced this item. + The URL of the file to be sent to the model. - - `class BetaResponseReasoningTextDeltaEvent: …` + - `filename: Optional[str]` - Emitted when a delta is added to a reasoning text. + The name of the file to be sent to the model. - - `content_index: int` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - The index of the reasoning content part this delta is associated with. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `delta: str` + - `mode: Literal["explicit"]` - The text delta that was added to the reasoning content. + The breakpoint mode. Always `explicit`. - - `item_id: str` + - `"explicit"` - The ID of the item this reasoning text delta is associated with. + - `role: Literal["user", "system", "developer"]` - - `output_index: int` + The role of the message input. One of `user`, `system`, or `developer`. - The index of the output item this reasoning text delta is associated with. + - `"user"` - - `sequence_number: int` + - `"system"` - The sequence number of this event. + - `"developer"` - - `type: Literal["response.reasoning_text.delta"]` + - `type: Literal["message"]` - The type of the event. Always `response.reasoning_text.delta`. + The type of the message input. Always set to `message`. - - `"response.reasoning_text.delta"` + - `"message"` - `agent: Optional[Agent]` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. - - `class BetaResponseReasoningTextDoneEvent: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - Emitted when a reasoning text is completed. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `content_index: int` + - `"in_progress"` - The index of the reasoning content part. + - `"completed"` - - `item_id: str` + - `"incomplete"` - The ID of the item this reasoning text is associated with. + - `class BetaResponseOutputMessage: …` - - `output_index: int` + An output message from the model. - The index of the output item this reasoning text is associated with. + - `id: str` - - `sequence_number: int` + The unique ID of the output message. - The sequence number of this event. + - `content: List[Content]` - - `text: str` + The content of the output message. - The full text of the completed reasoning content. + - `class BetaResponseOutputText: …` - - `type: Literal["response.reasoning_text.done"]` + A text output from the model. - The type of the event. Always `response.reasoning_text.done`. + - `annotations: List[Annotation]` - - `"response.reasoning_text.done"` + The annotations of the text output. - - `agent: Optional[Agent]` + - `class AnnotationFileCitation: …` - The agent that owns this multi-agent streaming event. + A citation to a file. - - `agent_name: str` + - `file_id: str` - The canonical name of the agent that produced this item. + The ID of the file. - - `class BetaResponseRefusalDeltaEvent: …` + - `filename: str` - Emitted when there is a partial refusal text. + The filename of the file cited. - - `content_index: int` + - `index: int` - The index of the content part that the refusal text is added to. + The index of the file in the list of files. - - `delta: str` + - `type: Literal["file_citation"]` - The refusal text that is added. + The type of the file citation. Always `file_citation`. - - `item_id: str` + - `"file_citation"` - The ID of the output item that the refusal text is added to. + - `class AnnotationURLCitation: …` - - `output_index: int` + A citation for a web resource used to generate a model response. - The index of the output item that the refusal text is added to. + - `end_index: int` - - `sequence_number: int` + The index of the last character of the URL citation in the message. - The sequence number of this event. + - `start_index: int` - - `type: Literal["response.refusal.delta"]` + The index of the first character of the URL citation in the message. - The type of the event. Always `response.refusal.delta`. + - `title: str` - - `"response.refusal.delta"` + The title of the web resource. - - `agent: Optional[Agent]` + - `type: Literal["url_citation"]` - The agent that owns this multi-agent streaming event. + The type of the URL citation. Always `url_citation`. - - `agent_name: str` + - `"url_citation"` - The canonical name of the agent that produced this item. + - `url: str` - - `class BetaResponseRefusalDoneEvent: …` + The URL of the web resource. - Emitted when refusal text is finalized. + - `class AnnotationContainerFileCitation: …` - - `content_index: int` + A citation for a container file used to generate a model response. - The index of the content part that the refusal text is finalized. + - `container_id: str` + + The ID of the container file. + + - `end_index: int` - - `item_id: str` + The index of the last character of the container file citation in the message. - The ID of the output item that the refusal text is finalized. + - `file_id: str` - - `output_index: int` + The ID of the file. - The index of the output item that the refusal text is finalized. + - `filename: str` - - `refusal: str` + The filename of the container file cited. - The refusal text that is finalized. + - `start_index: int` - - `sequence_number: int` + The index of the first character of the container file citation in the message. - The sequence number of this event. + - `type: Literal["container_file_citation"]` - - `type: Literal["response.refusal.done"]` + The type of the container file citation. Always `container_file_citation`. - The type of the event. Always `response.refusal.done`. + - `"container_file_citation"` - - `"response.refusal.done"` + - `class AnnotationFilePath: …` - - `agent: Optional[Agent]` + A path to a file. - The agent that owns this multi-agent streaming event. + - `file_id: str` - - `agent_name: str` + The ID of the file. - The canonical name of the agent that produced this item. + - `index: int` - - `class BetaResponseTextDeltaEvent: …` + The index of the file in the list of files. - Emitted when there is an additional text delta. + - `type: Literal["file_path"]` - - `content_index: int` + The type of the file path. Always `file_path`. - The index of the content part that the text delta was added to. + - `"file_path"` - - `delta: str` + - `text: str` - The text delta that was added. + The text output from the model. - - `item_id: str` + - `type: Literal["output_text"]` - The ID of the output item that the text delta was added to. + The type of the output text. Always `output_text`. - - `logprobs: List[Logprob]` + - `"output_text"` - The log probabilities of the tokens in the delta. + - `logprobs: Optional[List[Logprob]]` - `token: str` - A possible text token. + - `bytes: List[int]` - `logprob: float` - The log probability of this token. + - `top_logprobs: List[LogprobTopLogprob]` - - `top_logprobs: Optional[List[LogprobTopLogprob]]` + - `token: str` - The log probabilities of up to 20 of the most likely tokens. + - `bytes: List[int]` - - `token: Optional[str]` + - `logprob: float` - A possible text token. + - `class BetaResponseOutputRefusal: …` - - `logprob: Optional[float]` + A refusal from the model. - The log probability of this token. + - `refusal: str` - - `output_index: int` + The refusal explanation from the model. - The index of the output item that the text delta was added to. + - `type: Literal["refusal"]` - - `sequence_number: int` + The type of the refusal. Always `refusal`. - The sequence number for this event. + - `"refusal"` - - `type: Literal["response.output_text.delta"]` + - `role: Literal["assistant"]` - The type of the event. Always `response.output_text.delta`. + The role of the output message. Always `assistant`. - - `"response.output_text.delta"` + - `"assistant"` - - `agent: Optional[Agent]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The agent that owns this multi-agent streaming event. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `agent_name: str` + - `"in_progress"` - The canonical name of the agent that produced this item. + - `"completed"` - - `class BetaResponseTextDoneEvent: …` + - `"incomplete"` - Emitted when text content is finalized. + - `type: Literal["message"]` - - `content_index: int` + The type of the output message. Always `message`. - The index of the content part that the text content is finalized. + - `"message"` - - `item_id: str` + - `agent: Optional[Agent]` - The ID of the output item that the text content is finalized. + The agent that produced this item. - - `logprobs: List[Logprob]` + - `agent_name: str` - The log probabilities of the tokens in the delta. + The canonical name of the agent that produced this item. - - `token: str` + - `phase: Optional[Literal["commentary", "final_answer"]]` - A possible text token. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `logprob: float` + - `"commentary"` - The log probability of this token. + - `"final_answer"` - - `top_logprobs: Optional[List[LogprobTopLogprob]]` + - `class BetaResponseFileSearchToolCall: …` - The log probabilities of up to 20 of the most likely tokens. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `token: Optional[str]` + - `id: str` - A possible text token. + The unique ID of the file search tool call. - - `logprob: Optional[float]` + - `queries: List[str]` - The log probability of this token. + The queries used to search for files. - - `output_index: int` + - `status: Literal["in_progress", "searching", "completed", 2 more]` - The index of the output item that the text content is finalized. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `sequence_number: int` + - `"in_progress"` - The sequence number for this event. + - `"searching"` - - `text: str` + - `"completed"` - The text content that is finalized. + - `"incomplete"` - - `type: Literal["response.output_text.done"]` + - `"failed"` - The type of the event. Always `response.output_text.done`. + - `type: Literal["file_search_call"]` - - `"response.output_text.done"` + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` - `agent: Optional[Agent]` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. - - `class BetaResponseWebSearchCallCompletedEvent: …` - - Emitted when a web search call is completed. - - - `item_id: str` + - `results: Optional[List[Result]]` - Unique ID for the output item associated with the web search call. + The results of the file search tool call. - - `output_index: int` + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` - The index of the output item that the web search call is associated with. + 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, booleans, or numbers. - - `sequence_number: int` + - `str` - The sequence number of the web search call being processed. + - `float` - - `type: Literal["response.web_search_call.completed"]` + - `bool` - The type of the event. Always `response.web_search_call.completed`. + - `file_id: Optional[str]` - - `"response.web_search_call.completed"` + The unique ID of the file. - - `agent: Optional[Agent]` + - `filename: Optional[str]` - The agent that owns this multi-agent streaming event. + The name of the file. - - `agent_name: str` + - `score: Optional[float]` - The canonical name of the agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `class BetaResponseWebSearchCallInProgressEvent: …` + - `text: Optional[str]` - Emitted when a web search call is initiated. + The text that was retrieved from the file. - - `item_id: str` + - `class BetaResponseComputerToolCall: …` - Unique ID for the output item associated with the web search call. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `output_index: int` + - `id: str` - The index of the output item that the web search call is associated with. + The unique ID of the computer call. - - `sequence_number: int` + - `call_id: str` - The sequence number of the web search call being processed. + An identifier used when responding to the tool call with output. - - `type: Literal["response.web_search_call.in_progress"]` + - `pending_safety_checks: List[PendingSafetyCheck]` - The type of the event. Always `response.web_search_call.in_progress`. + The pending safety checks for the computer call. - - `"response.web_search_call.in_progress"` + - `id: str` - - `agent: Optional[Agent]` + The ID of the pending safety check. - The agent that owns this multi-agent streaming event. + - `code: Optional[str]` - - `agent_name: str` + The type of the pending safety check. - The canonical name of the agent that produced this item. + - `message: Optional[str]` - - `class BetaResponseWebSearchCallSearchingEvent: …` + Details about the pending safety check. - Emitted when a web search call is executing. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `item_id: str` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Unique ID for the output item associated with the web search call. + - `"in_progress"` - - `output_index: int` + - `"completed"` - The index of the output item that the web search call is associated with. + - `"incomplete"` - - `sequence_number: int` + - `type: Literal["computer_call"]` - The sequence number of the web search call being processed. + The type of the computer call. Always `computer_call`. - - `type: Literal["response.web_search_call.searching"]` + - `"computer_call"` - The type of the event. Always `response.web_search_call.searching`. + - `action: Optional[BetaComputerAction]` - - `"response.web_search_call.searching"` + A click action. - - `agent: Optional[Agent]` + - `class Click: …` - The agent that owns this multi-agent streaming event. + A click action. - - `agent_name: str` + - `button: Literal["left", "right", "wheel", 2 more]` - The canonical name of the agent that produced this item. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `class BetaResponseImageGenCallCompletedEvent: …` + - `"left"` - Emitted when an image generation tool call has completed and the final image is available. + - `"right"` - - `item_id: str` + - `"wheel"` - The unique identifier of the image generation item being processed. + - `"back"` - - `output_index: int` + - `"forward"` - The index of the output item in the response's output array. + - `type: Literal["click"]` - - `sequence_number: int` + Specifies the event type. For a click action, this property is always `click`. - The sequence number of this event. + - `"click"` - - `type: Literal["response.image_generation_call.completed"]` + - `x: int` - The type of the event. Always 'response.image_generation_call.completed'. + The x-coordinate where the click occurred. - - `"response.image_generation_call.completed"` + - `y: int` - - `agent: Optional[Agent]` + The y-coordinate where the click occurred. - The agent that owns this multi-agent streaming event. + - `keys: Optional[List[str]]` - - `agent_name: str` + The keys being held while clicking. - The canonical name of the agent that produced this item. + - `class DoubleClick: …` - - `class BetaResponseImageGenCallGeneratingEvent: …` + A double click action. - Emitted when an image generation tool call is actively generating an image (intermediate state). + - `keys: Optional[List[str]]` - - `item_id: str` + The keys being held while double-clicking. - The unique identifier of the image generation item being processed. + - `type: Literal["double_click"]` - - `output_index: int` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The index of the output item in the response's output array. + - `"double_click"` - - `sequence_number: int` + - `x: int` - The sequence number of the image generation item being processed. + The x-coordinate where the double click occurred. - - `type: Literal["response.image_generation_call.generating"]` + - `y: int` - The type of the event. Always 'response.image_generation_call.generating'. + The y-coordinate where the double click occurred. - - `"response.image_generation_call.generating"` + - `class Drag: …` - - `agent: Optional[Agent]` + A drag action. - The agent that owns this multi-agent streaming event. + - `path: List[DragPath]` - - `agent_name: str` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The canonical name of the agent that produced this item. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `class BetaResponseImageGenCallInProgressEvent: …` + - `x: int` - Emitted when an image generation tool call is in progress. + The x-coordinate. - - `item_id: str` + - `y: int` - The unique identifier of the image generation item being processed. + The y-coordinate. - - `output_index: int` + - `type: Literal["drag"]` - The index of the output item in the response's output array. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `sequence_number: int` + - `"drag"` - The sequence number of the image generation item being processed. + - `keys: Optional[List[str]]` - - `type: Literal["response.image_generation_call.in_progress"]` + The keys being held while dragging the mouse. - The type of the event. Always 'response.image_generation_call.in_progress'. + - `class Keypress: …` - - `"response.image_generation_call.in_progress"` + A collection of keypresses the model would like to perform. - - `agent: Optional[Agent]` + - `keys: List[str]` - The agent that owns this multi-agent streaming event. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `agent_name: str` + - `type: Literal["keypress"]` - The canonical name of the agent that produced this item. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `class BetaResponseImageGenCallPartialImageEvent: …` + - `"keypress"` - Emitted when a partial image is available during image generation streaming. + - `class Move: …` - - `item_id: str` + A mouse move action. - The unique identifier of the image generation item being processed. + - `type: Literal["move"]` - - `output_index: int` + Specifies the event type. For a move action, this property is always set to `move`. - The index of the output item in the response's output array. + - `"move"` - - `partial_image_b64: str` + - `x: int` - Base64-encoded partial image data, suitable for rendering as an image. + The x-coordinate to move to. - - `partial_image_index: int` + - `y: int` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + The y-coordinate to move to. - - `sequence_number: int` + - `keys: Optional[List[str]]` - The sequence number of the image generation item being processed. + The keys being held while moving the mouse. - - `type: Literal["response.image_generation_call.partial_image"]` + - `class Screenshot: …` - The type of the event. Always 'response.image_generation_call.partial_image'. + A screenshot action. - - `"response.image_generation_call.partial_image"` + - `type: Literal["screenshot"]` - - `agent: Optional[Agent]` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The agent that owns this multi-agent streaming event. + - `"screenshot"` - - `agent_name: str` + - `class Scroll: …` - The canonical name of the agent that produced this item. + A scroll action. - - `class BetaResponseMcpCallArgumentsDeltaEvent: …` + - `scroll_x: int` - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + The horizontal scroll distance. - - `delta: str` + - `scroll_y: int` - A JSON string containing the partial update to the arguments for the MCP tool call. + The vertical scroll distance. - - `item_id: str` + - `type: Literal["scroll"]` - The unique identifier of the MCP tool call item being processed. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `output_index: int` + - `"scroll"` - The index of the output item in the response's output array. + - `x: int` - - `sequence_number: int` + The x-coordinate where the scroll occurred. - The sequence number of this event. + - `y: int` - - `type: Literal["response.mcp_call_arguments.delta"]` + The y-coordinate where the scroll occurred. - The type of the event. Always 'response.mcp_call_arguments.delta'. + - `keys: Optional[List[str]]` - - `"response.mcp_call_arguments.delta"` + The keys being held while scrolling. - - `agent: Optional[Agent]` + - `class Type: …` - The agent that owns this multi-agent streaming event. + An action to type in text. - - `agent_name: str` + - `text: str` - The canonical name of the agent that produced this item. + The text to type. - - `class BetaResponseMcpCallArgumentsDoneEvent: …` + - `type: Literal["type"]` - Emitted when the arguments for an MCP tool call are finalized. + Specifies the event type. For a type action, this property is always set to `type`. - - `arguments: str` + - `"type"` - A JSON string containing the finalized arguments for the MCP tool call. + - `class Wait: …` - - `item_id: str` + A wait action. - The unique identifier of the MCP tool call item being processed. + - `type: Literal["wait"]` - - `output_index: int` + Specifies the event type. For a wait action, this property is always set to `wait`. - The index of the output item in the response's output array. + - `"wait"` - - `sequence_number: int` + - `actions: Optional[BetaComputerActionList]` - The sequence number of this event. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `type: Literal["response.mcp_call_arguments.done"]` + - `class Click: …` - The type of the event. Always 'response.mcp_call_arguments.done'. + A click action. - - `"response.mcp_call_arguments.done"` + - `class DoubleClick: …` - - `agent: Optional[Agent]` + A double click action. - The agent that owns this multi-agent streaming event. + - `class Drag: …` - - `agent_name: str` + A drag action. - The canonical name of the agent that produced this item. + - `class Keypress: …` - - `class BetaResponseMcpCallCompletedEvent: …` + A collection of keypresses the model would like to perform. - Emitted when an MCP tool call has completed successfully. + - `class Move: …` - - `item_id: str` + A mouse move action. - The ID of the MCP tool call item that completed. + - `class Screenshot: …` - - `output_index: int` + A screenshot action. - The index of the output item that completed. + - `class Scroll: …` - - `sequence_number: int` + A scroll action. - The sequence number of this event. + - `class Type: …` - - `type: Literal["response.mcp_call.completed"]` + An action to type in text. - The type of the event. Always 'response.mcp_call.completed'. + - `class Wait: …` - - `"response.mcp_call.completed"` + A wait action. - `agent: Optional[Agent]` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. - - `class BetaResponseMcpCallFailedEvent: …` + - `class BetaResponseComputerToolCallOutputItem: …` - Emitted when an MCP tool call has failed. + - `id: str` - - `item_id: str` + The unique ID of the computer call tool output. - The ID of the MCP tool call item that failed. + - `call_id: str` - - `output_index: int` + The ID of the computer tool call that produced the output. - The index of the output item that failed. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `sequence_number: int` + A computer screenshot image used with the computer use tool. - The sequence number of this event. + - `type: Literal["computer_screenshot"]` - - `type: Literal["response.mcp_call.failed"]` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The type of the event. Always 'response.mcp_call.failed'. + - `"computer_screenshot"` - - `"response.mcp_call.failed"` + - `file_id: Optional[str]` - - `agent: Optional[Agent]` + The identifier of an uploaded file that contains the screenshot. - The agent that owns this multi-agent streaming event. + - `image_url: Optional[str]` - - `agent_name: str` + The URL of the screenshot image. - The canonical name of the agent that produced this item. + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` - - `class BetaResponseMcpCallInProgressEvent: …` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Emitted when an MCP tool call is in progress. + - `"completed"` - - `item_id: str` + - `"incomplete"` - The unique identifier of the MCP tool call item being processed. + - `"failed"` - - `output_index: int` + - `"in_progress"` - The index of the output item in the response's output array. + - `type: Literal["computer_call_output"]` - - `sequence_number: int` + The type of the computer tool call output. Always `computer_call_output`. - The sequence number of this event. + - `"computer_call_output"` - - `type: Literal["response.mcp_call.in_progress"]` + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - The type of the event. Always 'response.mcp_call.in_progress'. + The safety checks reported by the API that have been acknowledged by the + developer. - - `"response.mcp_call.in_progress"` + - `id: str` + + The ID of the pending safety check. + + - `code: Optional[str]` + + The type of the pending safety check. + + - `message: Optional[str]` + + Details about the pending safety check. - `agent: Optional[Agent]` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. - - `class BetaResponseMcpListToolsCompletedEvent: …` + - `created_by: Optional[str]` - Emitted when the list of available MCP tools has been successfully retrieved. + The identifier of the actor that created the item. - - `item_id: str` + - `class BetaResponseFunctionWebSearch: …` - The ID of the MCP tool call item that produced this output. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `output_index: int` + - `id: str` - The index of the output item that was processed. + The unique ID of the web search tool call. - - `sequence_number: int` + - `action: Action` - The sequence number of this event. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `type: Literal["response.mcp_list_tools.completed"]` + - `class ActionSearch: …` - The type of the event. Always 'response.mcp_list_tools.completed'. + Action type "search" - Performs a web search query. - - `"response.mcp_list_tools.completed"` + - `type: Literal["search"]` - - `agent: Optional[Agent]` + The action type. - The agent that owns this multi-agent streaming event. + - `"search"` - - `agent_name: str` + - `queries: Optional[List[str]]` - The canonical name of the agent that produced this item. + The search queries. - - `class BetaResponseMcpListToolsFailedEvent: …` + - `query: Optional[str]` - Emitted when the attempt to list available MCP tools has failed. + The search query. - - `item_id: str` + - `sources: Optional[List[ActionSearchSource]]` - The ID of the MCP tool call item that failed. + The sources used in the search. - - `output_index: int` + - `type: Literal["url"]` - The index of the output item that failed. + The type of source. Always `url`. - - `sequence_number: int` + - `"url"` - The sequence number of this event. + - `url: str` - - `type: Literal["response.mcp_list_tools.failed"]` + The URL of the source. - The type of the event. Always 'response.mcp_list_tools.failed'. + - `class ActionOpenPage: …` - - `"response.mcp_list_tools.failed"` + Action type "open_page" - Opens a specific URL from search results. - - `agent: Optional[Agent]` + - `type: Literal["open_page"]` - The agent that owns this multi-agent streaming event. + The action type. - - `agent_name: str` + - `"open_page"` - The canonical name of the agent that produced this item. + - `url: Optional[str]` - - `class BetaResponseMcpListToolsInProgressEvent: …` + The URL opened by the model. - Emitted when the system is in the process of retrieving the list of available MCP tools. + - `class ActionFindInPage: …` - - `item_id: str` + Action type "find_in_page": Searches for a pattern within a loaded page. - The ID of the MCP tool call item that is being processed. + - `pattern: str` - - `output_index: int` + The pattern or text to search for within the page. - The index of the output item that is being processed. + - `type: Literal["find_in_page"]` - - `sequence_number: int` + The action type. - The sequence number of this event. + - `"find_in_page"` - - `type: Literal["response.mcp_list_tools.in_progress"]` + - `url: str` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + The URL of the page searched for the pattern. - - `"response.mcp_list_tools.in_progress"` + - `status: Literal["in_progress", "searching", "completed", "failed"]` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: Literal["web_search_call"]` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` - `agent: Optional[Agent]` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. - - `class BetaResponseOutputTextAnnotationAddedEvent: …` + - `class BetaResponseFunctionToolCallItem: …` - Emitted when an annotation is added to output text content. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `annotation: object` + - `id: str` - The annotation object being added. (See annotation schema for details.) + The unique ID of the function tool call. - - `annotation_index: int` + - `status: Literal["in_progress", "completed", "incomplete"]` - The index of the annotation within the content part. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `content_index: int` + - `"in_progress"` - The index of the content part within the output item. + - `"completed"` - - `item_id: str` + - `"incomplete"` - The unique identifier of the item to which the annotation is being added. + - `created_by: Optional[str]` - - `output_index: int` + The identifier of the actor that created the item. - The index of the output item in the response's output array. + - `class BetaResponseFunctionToolCallOutputItem: …` - - `sequence_number: int` + - `id: str` - The sequence number of this event. + The unique ID of the function call tool output. - - `type: Literal["response.output_text.annotation.added"]` + - `call_id: str` - The type of the event. Always 'response.output_text.annotation.added'. + The unique ID of the function tool call generated by the model. - - `"response.output_text.annotation.added"` + - `output: Union[str, List[OutputOutputContentList]]` - - `agent: Optional[Agent]` + The output from the function call generated by your code. + Can be a string or an list of output content. - The agent that owns this multi-agent streaming event. + - `str` - - `agent_name: str` + A string of the output of the function call. - The canonical name of the agent that produced this item. + - `List[OutputOutputContentList]` - - `class BetaResponseQueuedEvent: …` + Text, image, or file output of the function call. - Emitted when a response is queued and waiting to be processed. + - `class BetaResponseInputText: …` - - `response: BetaResponse` + A text input to the model. - The full response object that is queued. + - `class BetaResponseInputImage: …` - - `sequence_number: int` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The sequence number for this event. + - `class BetaResponseInputFile: …` - - `type: Literal["response.queued"]` + A file input to the model. - The type of the event. Always 'response.queued'. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"response.queued"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["function_call_output"]` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` - `agent: Optional[Agent]` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. - - `class BetaResponseCustomToolCallInputDeltaEvent: …` + - `caller: Optional[Caller]` - Event representing a delta (partial update) to the input of a custom tool call. + The execution context that produced this tool call. - - `delta: str` + - `class CallerDirect: …` - The incremental input data (delta) for the custom tool call. + - `type: Literal["direct"]` - - `item_id: str` + The caller type. Always `direct`. - Unique identifier for the API item associated with this event. + - `"direct"` - - `output_index: int` + - `class CallerProgram: …` - The index of the output this delta applies to. + - `caller_id: str` - - `sequence_number: int` + The call ID of the program item that produced this tool call. - The sequence number of this event. + - `type: Literal["program"]` - - `type: Literal["response.custom_tool_call_input.delta"]` + The caller type. Always `program`. - The event type identifier. + - `"program"` - - `"response.custom_tool_call_input.delta"` + - `created_by: Optional[str]` - - `agent: Optional[Agent]` + The identifier of the actor that created the item. - The agent that owns this multi-agent streaming event. + - `class AgentMessage: …` - - `agent_name: str` + - `id: str` - The canonical name of the agent that produced this item. + The unique ID of the agent message. - - `class BetaResponseCustomToolCallInputDoneEvent: …` + - `author: str` - Event indicating that input for a custom tool call is complete. + The sending agent identity. - - `input: str` + - `content: List[AgentMessageContent]` - The complete input data for the custom tool call. + Encrypted content sent between agents. - - `item_id: str` + - `class BetaResponseInputText: …` - Unique identifier for the API item associated with this event. + A text input to the model. - - `output_index: int` + - `class BetaResponseOutputText: …` - The index of the output this event applies to. + A text output from the model. - - `sequence_number: int` + - `class AgentMessageContentText: …` - The sequence number of this event. + A text content. - - `type: Literal["response.custom_tool_call_input.done"]` + - `text: str` - The event type identifier. + - `type: Literal["text"]` - - `"response.custom_tool_call_input.done"` + - `"text"` - - `agent: Optional[Agent]` + - `class AgentMessageContentSummaryText: …` - The agent that owns this multi-agent streaming event. + A summary text from the model. - - `agent_name: str` + - `text: str` - The canonical name of the agent that produced this item. + A summary of the reasoning output from the model so far. -### Beta Response Text Config + - `type: Literal["summary_text"]` -- `class BetaResponseTextConfig: …` + The type of the object. Always `summary_text`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `"summary_text"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `class AgentMessageContentReasoningText: …` - - `format: Optional[BetaResponseFormatTextConfig]` + Reasoning text from the model. - An object specifying the format that the model must output. + - `text: str` - Configuring `{ "type": "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). + The reasoning text from the model. - The default format is `{ "type": "text" }` with no additional options. + - `type: Literal["reasoning_text"]` - **Not recommended for gpt-4o and newer models:** + The type of the reasoning text. Always `reasoning_text`. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `"reasoning_text"` - - `class Text: …` + - `class BetaResponseOutputRefusal: …` - Default response format. Used to generate text responses. + A refusal from the model. - - `type: Literal["text"]` + - `class BetaResponseInputImage: …` - The type of response format being defined. Always `text`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"text"` + - `class AgentMessageContentComputerScreenshot: …` - - `class BetaResponseFormatTextJSONSchemaConfig: …` + A screenshot of a computer. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `detail: Literal["low", "high", "auto", "original"]` - - `name: str` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - 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. + - `"low"` - - `schema: Dict[str, object]` + - `"high"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"auto"` - - `type: Literal["json_schema"]` + - `"original"` - The type of response format being defined. Always `json_schema`. + - `file_id: Optional[str]` - - `"json_schema"` + The identifier of an uploaded file that contains the screenshot. - - `description: Optional[str]` + - `image_url: Optional[str]` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The URL of the screenshot image. - - `strict: Optional[bool]` + - `type: Literal["computer_screenshot"]` - 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). + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `class JSONObject: …` + - `"computer_screenshot"` - 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. + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - - `type: Literal["json_object"]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The type of response format being defined. Always `json_object`. + - `mode: Literal["explicit"]` - - `"json_object"` + The breakpoint mode. Always `explicit`. - - `verbosity: Optional[Literal["low", "medium", "high"]]` + - `"explicit"` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `class BetaResponseInputFile: …` - - `"low"` + A file input to the model. - - `"medium"` + - `class AgentMessageContentEncryptedContent: …` - - `"high"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. -### Beta Response Text Delta Event + - `encrypted_content: str` -- `class BetaResponseTextDeltaEvent: …` + Opaque encrypted content. - Emitted when there is an additional text delta. + - `type: Literal["encrypted_content"]` - - `content_index: int` + The type of the input item. Always `encrypted_content`. - The index of the content part that the text delta was added to. + - `"encrypted_content"` - - `delta: str` + - `recipient: str` - The text delta that was added. + The destination agent identity. - - `item_id: str` + - `type: Literal["agent_message"]` - The ID of the output item that the text delta was added to. + The type of the item. Always `agent_message`. - - `logprobs: List[Logprob]` + - `"agent_message"` - The log probabilities of the tokens in the delta. + - `agent: Optional[AgentMessageAgent]` - - `token: str` + The agent that produced this item. - A possible text token. + - `agent_name: str` - - `logprob: float` + The canonical name of the agent that produced this item. - The log probability of this token. + - `class MultiAgentCall: …` - - `top_logprobs: Optional[List[LogprobTopLogprob]]` + - `id: str` - The log probabilities of up to 20 of the most likely tokens. + The unique ID of the multi-agent call item. - - `token: Optional[str]` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - A possible text token. + The multi-agent action to execute. - - `logprob: Optional[float]` + - `"spawn_agent"` - The log probability of this token. + - `"interrupt_agent"` - - `output_index: int` + - `"list_agents"` - The index of the output item that the text delta was added to. + - `"send_message"` - - `sequence_number: int` + - `"followup_task"` - The sequence number for this event. + - `"wait_agent"` - - `type: Literal["response.output_text.delta"]` + - `arguments: str` - The type of the event. Always `response.output_text.delta`. + The JSON string of arguments generated for the action. - - `"response.output_text.delta"` + - `call_id: str` - - `agent: Optional[Agent]` + The unique ID linking this call to its output. - The agent that owns this multi-agent streaming event. + - `type: Literal["multi_agent_call"]` - - `agent_name: str` + The type of the multi-agent call. Always `multi_agent_call`. - The canonical name of the agent that produced this item. + - `"multi_agent_call"` -### Beta Response Text Done Event + - `agent: Optional[MultiAgentCallAgent]` -- `class BetaResponseTextDoneEvent: …` + The agent that produced this item. - Emitted when text content is finalized. + - `agent_name: str` - - `content_index: int` + The canonical name of the agent that produced this item. - The index of the content part that the text content is finalized. + - `class MultiAgentCallOutput: …` - - `item_id: str` + - `id: str` - The ID of the output item that the text content is finalized. + The unique ID of the multi-agent call output item. - - `logprobs: List[Logprob]` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - The log probabilities of the tokens in the delta. + The multi-agent action that produced this result. - - `token: str` + - `"spawn_agent"` - A possible text token. + - `"interrupt_agent"` - - `logprob: float` + - `"list_agents"` - The log probability of this token. + - `"send_message"` - - `top_logprobs: Optional[List[LogprobTopLogprob]]` + - `"followup_task"` - The log probabilities of up to 20 of the most likely tokens. + - `"wait_agent"` - - `token: Optional[str]` + - `call_id: str` - A possible text token. + The unique ID of the multi-agent call. - - `logprob: Optional[float]` + - `output: List[BetaResponseOutputText]` - The log probability of this token. + Text output returned by the multi-agent action. - - `output_index: int` + - `annotations: List[Annotation]` - The index of the output item that the text content is finalized. + The annotations of the text output. - - `sequence_number: int` + - `text: str` - The sequence number for this event. + The text output from the model. - - `text: str` + - `type: Literal["output_text"]` - The text content that is finalized. + The type of the output text. Always `output_text`. - - `type: Literal["response.output_text.done"]` + - `logprobs: Optional[List[Logprob]]` - The type of the event. Always `response.output_text.done`. + - `type: Literal["multi_agent_call_output"]` - - `"response.output_text.done"` + The type of the multi-agent result. Always `multi_agent_call_output`. - - `agent: Optional[Agent]` + - `"multi_agent_call_output"` - The agent that owns this multi-agent streaming event. + - `agent: Optional[MultiAgentCallOutputAgent]` + + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. -### Beta Response Tool Search Call - -- `class BetaResponseToolSearchCall: …` + - `class BetaResponseToolSearchCall: …` - `id: str` @@ -135364,9 +146457,7 @@ print(compacted_response) The identifier of the actor that created the item. -### Beta Response Tool Search Output Item - -- `class BetaResponseToolSearchOutputItem: …` + - `class BetaResponseToolSearchOutputItem: …` - `id: str` @@ -135495,7 +146586,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -135505,7 +146596,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `class FiltersCompoundFilter: …` @@ -135552,7 +146647,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -135562,7 +146657,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `object` @@ -136502,1397 +147601,1208 @@ print(compacted_response) The identifier of the actor that created the item. -### Beta Response Tool Search Output Item Param - -- `class BetaResponseToolSearchOutputItemParam: …` - - - `tools: List[BetaTool]` - - The loaded tool definitions returned by the tool search output. - - - `class BetaFunctionTool: …` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `name: str` - - The name of the function to call. - - - `parameters: Optional[Dict[str, object]]` + - `class AdditionalTools: …` - A JSON schema object describing the parameters of the function. + - `id: str` - - `strict: Optional[bool]` + The unique ID of the additional tools item. - Whether strict parameter validation is enforced for this function tool. + - `role: Literal["unknown", "user", "assistant", 5 more]` - - `type: Literal["function"]` + The role that provided the additional tools. - The type of the function tool. Always `function`. + - `"unknown"` - - `"function"` + - `"user"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"assistant"` - The tool invocation context(s). + - `"system"` - - `"direct"` + - `"critic"` - - `"programmatic"` + - `"discriminator"` - - `defer_loading: Optional[bool]` + - `"developer"` - Whether this function is deferred and loaded via tool search. + - `"tool"` - - `description: Optional[str]` + - `tools: List[BetaTool]` - A description of the function. Used by the model to determine whether or not to call the function. + The additional tool definitions made available at this item. - - `output_schema: Optional[Dict[str, object]]` + - `class BetaFunctionTool: …` - A JSON schema object describing the JSON value encoded in string outputs for this function. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `class BetaFileSearchTool: …` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: Literal["file_search"]` - - The type of the file search tool. Always `file_search`. - - - `"file_search"` - - - `vector_store_ids: List[str]` - - The IDs of the vector stores to search. - - - `filters: Optional[Filters]` - - A filter to apply. - - - `class FiltersComparisonFilter: …` - - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - - `key: str` - - The key to compare against the value. - - - `type: Literal["eq", "ne", "gt", 5 more]` - - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - - - `"eq"` - - - `"ne"` - - - `"gt"` - - - `"gte"` - - - `"lt"` - - - `"lte"` - - - `"in"` - - - `"nin"` - - - `value: Union[str, float, bool, List[object]]` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `str` - - - `float` - - - `bool` - - - `List[object]` - - - `class FiltersCompoundFilter: …` - - Combine multiple filters using `and` or `or`. - - - `filters: List[FiltersCompoundFilterFilter]` - - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - - `class FiltersCompoundFilterFilterComparisonFilter: …` - - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - - `key: str` - - The key to compare against the value. - - - `type: Literal["eq", "ne", "gt", 5 more]` - - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - - - `"eq"` - - - `"ne"` - - - `"gt"` - - - `"gte"` - - - `"lt"` - - - `"lte"` - - - `"in"` - - - `"nin"` - - - `value: Union[str, float, bool, List[object]]` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `str` - - - `float` - - - `bool` - - - `List[object]` - - - `object` - - - `type: Literal["and", "or"]` - - Type of operation: `and` or `or`. - - - `"and"` - - - `"or"` - - - `max_num_results: Optional[int]` - - The maximum number of results to return. This number should be between 1 and 50 inclusive. - - - `ranking_options: Optional[RankingOptions]` - - Ranking options for search. - - - `hybrid_search: Optional[RankingOptionsHybridSearch]` - - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - - `embedding_weight: float` - - The weight of the embedding in the reciprocal ranking fusion. - - - `text_weight: float` - - The weight of the text in the reciprocal ranking fusion. - - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - - The ranker to use for the file search. - - - `"auto"` - - - `"default-2024-11-15"` - - - `score_threshold: Optional[float]` - - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `class BetaComputerTool: …` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: Literal["computer"]` - - The type of the computer tool. Always `computer`. - - - `"computer"` - - `class BetaComputerUsePreviewTool: …` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `display_height: int` - - The height of the computer display. - - - `display_width: int` - - The width of the computer display. - - - `environment: Literal["windows", "mac", "linux", 2 more]` - - The type of computer environment to control. - - - `"windows"` - - - `"mac"` - - - `"linux"` - - - `"ubuntu"` - - - `"browser"` - - - `type: Literal["computer_use_preview"]` - - The type of the computer use tool. Always `computer_use_preview`. - - - `"computer_use_preview"` - - `class BetaWebSearchTool: …` Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `type: Literal["web_search", "web_search_2025_08_26"]` - - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `class Mcp: …` - - `"web_search"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"web_search_2025_08_26"` + - `class CodeInterpreter: …` - - `filters: Optional[Filters]` + A tool that runs Python code to help generate a response to a prompt. - Filters for the search. + - `class ProgrammaticToolCalling: …` - - `allowed_domains: Optional[List[str]]` + - `class ImageGeneration: …` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + A tool that generates images using the GPT image models. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `class LocalShell: …` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + A tool that allows the model to execute shell commands in a local environment. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `class BetaFunctionShellTool: …` - - `"low"` + A tool that allows the model to execute shell commands. - - `"medium"` + - `class BetaCustomTool: …` - - `"high"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `user_location: Optional[UserLocation]` + - `class BetaNamespaceTool: …` - The approximate location of the user. + Groups function/custom tools under a shared namespace. - - `city: Optional[str]` + - `class BetaToolSearchTool: …` - Free text input for the city of the user, e.g. `San Francisco`. + Hosted or BYOT tool search configuration for deferred tools. - - `country: Optional[str]` + - `class BetaWebSearchPreviewTool: …` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `region: Optional[str]` + - `class BetaApplyPatchTool: …` - Free text input for the region of the user, e.g. `California`. + Allows the assistant to create, delete, or update files using unified diffs. - - `timezone: Optional[str]` + - `type: Literal["additional_tools"]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The type of the item. Always `additional_tools`. - - `type: Optional[Literal["approximate"]]` + - `"additional_tools"` - The type of location approximation. Always `approximate`. + - `agent: Optional[AdditionalToolsAgent]` - - `"approximate"` + The agent that produced this item. - - `class Mcp: …` + - `agent_name: str` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The canonical name of the agent that produced this item. - - `server_label: str` + - `class BetaResponseReasoningItem: …` - A label for this MCP server, used to identify it in tool calls. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `type: Literal["mcp"]` + - `id: str` - The type of the MCP tool. Always `mcp`. + The unique identifier of the reasoning content. - - `"mcp"` + - `summary: List[Summary]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + Reasoning summary content. - The tool invocation context(s). + - `text: str` - - `"direct"` + A summary of the reasoning output from the model so far. - - `"programmatic"` + - `type: Literal["summary_text"]` - - `allowed_tools: Optional[McpAllowedTools]` + The type of the object. Always `summary_text`. - List of allowed tool names or a filter object. + - `"summary_text"` - - `List[str]` + - `type: Literal["reasoning"]` - A string array of allowed tool names + The type of the object. Always `reasoning`. - - `class McpAllowedToolsMcpToolFilter: …` + - `"reasoning"` - A filter object to specify which tools are allowed. + - `agent: Optional[Agent]` - - `read_only: Optional[bool]` + The agent that produced this item. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `agent_name: str` - - `tool_names: Optional[List[str]]` + The canonical name of the agent that produced this item. - List of allowed tool names. + - `content: Optional[List[Content]]` - - `authorization: Optional[str]` + Reasoning text content. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `text: str` - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + The reasoning text from the model. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `type: Literal["reasoning_text"]` - Currently supported `connector_id` values are: + The type of the reasoning text. Always `reasoning_text`. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `"reasoning_text"` - - `"connector_dropbox"` + - `encrypted_content: Optional[str]` - - `"connector_gmail"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `"connector_googlecalendar"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"connector_googledrive"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"connector_microsoftteams"` + - `"in_progress"` - - `"connector_outlookcalendar"` + - `"completed"` - - `"connector_outlookemail"` + - `"incomplete"` - - `"connector_sharepoint"` + - `class Program: …` - - `defer_loading: Optional[bool]` + - `id: str` - Whether this MCP tool is deferred and discovered via tool search. + The unique ID of the program item. - - `headers: Optional[Dict[str, str]]` + - `call_id: str` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The stable call ID of the program item. - - `require_approval: Optional[McpRequireApproval]` + - `code: str` - Specify which of the MCP server's tools require approval. + The JavaScript source executed by programmatic tool calling. - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `fingerprint: str` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + Opaque program replay fingerprint that must be round-tripped. - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `type: Literal["program"]` - A filter object to specify which tools are allowed. + The type of the item. Always `program`. - - `read_only: Optional[bool]` + - `"program"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `agent: Optional[ProgramAgent]` - - `tool_names: Optional[List[str]]` + The agent that produced this item. - List of allowed tool names. + - `agent_name: str` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + The canonical name of the agent that produced this item. - A filter object to specify which tools are allowed. + - `class ProgramOutput: …` - - `read_only: Optional[bool]` + - `id: str` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The unique ID of the program output item. - - `tool_names: Optional[List[str]]` + - `call_id: str` - List of allowed tool names. + The call ID of the program item. - - `Literal["always", "never"]` + - `result: str` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The result produced by the program item. - - `"always"` + - `status: Literal["completed", "incomplete"]` - - `"never"` + The terminal status of the program output item. - - `server_description: Optional[str]` + - `"completed"` - Optional description of the MCP server, used to provide more context. + - `"incomplete"` - - `server_url: Optional[str]` + - `type: Literal["program_output"]` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The type of the item. Always `program_output`. - - `tunnel_id: Optional[str]` + - `"program_output"` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `agent: Optional[ProgramOutputAgent]` - - `class CodeInterpreter: …` + The agent that produced this item. - A tool that runs Python code to help generate a response to a prompt. + - `agent_name: str` - - `container: CodeInterpreterContainer` + The canonical name of the agent that produced this item. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `class BetaResponseCompactionItem: …` - - `str` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The container ID. + - `id: str` - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + The unique ID of the compaction item. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `encrypted_content: str` - - `type: Literal["auto"]` + The encrypted content that was produced by compaction. - Always `auto`. + - `type: Literal["compaction"]` - - `"auto"` + The type of the item. Always `compaction`. - - `file_ids: Optional[List[str]]` + - `"compaction"` - An optional list of uploaded files to make available to your code. + - `agent: Optional[Agent]` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + The agent that produced this item. - The memory limit for the code interpreter container. + - `agent_name: str` - - `"1g"` + The canonical name of the agent that produced this item. - - `"4g"` + - `created_by: Optional[str]` - - `"16g"` + The identifier of the actor that created the item. - - `"64g"` + - `class ImageGenerationCall: …` - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + An image generation request made by the model. - Network access policy for the container. + - `id: str` - - `class BetaContainerNetworkPolicyDisabled: …` + The unique ID of the image generation call. - - `type: Literal["disabled"]` + - `result: Optional[str]` - Disable outbound network access. Always `disabled`. + The generated image encoded in base64. - - `"disabled"` + - `status: Literal["in_progress", "completed", "generating", "failed"]` - - `class BetaContainerNetworkPolicyAllowlist: …` + The status of the image generation call. - - `allowed_domains: List[str]` + - `"in_progress"` - A list of allowed domains when type is `allowlist`. + - `"completed"` - - `type: Literal["allowlist"]` + - `"generating"` - Allow outbound network access only to specified domains. Always `allowlist`. + - `"failed"` - - `"allowlist"` + - `type: Literal["image_generation_call"]` - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + The type of the image generation call. Always `image_generation_call`. - Optional domain-scoped secrets for allowlisted domains. + - `"image_generation_call"` - - `domain: str` + - `agent: Optional[ImageGenerationCallAgent]` - The domain associated with the secret. + The agent that produced this item. - - `name: str` + - `agent_name: str` - The name of the secret to inject for the domain. + The canonical name of the agent that produced this item. - - `value: str` + - `class BetaResponseCodeInterpreterToolCall: …` - The secret value to inject for the domain. + A tool call to run code. - - `type: Literal["code_interpreter"]` + - `id: str` - The type of the code interpreter tool. Always `code_interpreter`. + The unique ID of the code interpreter tool call. - - `"code_interpreter"` + - `code: Optional[str]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The code to run, or null if not available. - The tool invocation context(s). + - `container_id: str` - - `"direct"` + The ID of the container used to run the code. - - `"programmatic"` + - `outputs: Optional[List[Output]]` - - `class ProgrammaticToolCalling: …` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `type: Literal["programmatic_tool_calling"]` + - `class OutputLogs: …` - The type of the tool. Always `programmatic_tool_calling`. + The logs output from the code interpreter. - - `"programmatic_tool_calling"` + - `logs: str` - - `class ImageGeneration: …` + The logs output from the code interpreter. - A tool that generates images using the GPT image models. + - `type: Literal["logs"]` - - `type: Literal["image_generation"]` + The type of the output. Always `logs`. - The type of the image generation tool. Always `image_generation`. + - `"logs"` - - `"image_generation"` + - `class OutputImage: …` - - `action: Optional[Literal["generate", "edit", "auto"]]` + The image output from the code interpreter. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `type: Literal["image"]` - - `"generate"` + The type of the output. Always `image`. - - `"edit"` + - `"image"` - - `"auto"` + - `url: str` - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + The URL of the image output from the code interpreter. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"in_progress"` - - `"transparent"` + - `"completed"` - - `"opaque"` + - `"incomplete"` - - `"auto"` + - `"interpreting"` - - `input_fidelity: Optional[Literal["high", "low"]]` + - `"failed"` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `type: Literal["code_interpreter_call"]` - - `"high"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"low"` + - `"code_interpreter_call"` - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + - `agent: Optional[Agent]` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The agent that produced this item. - - `file_id: Optional[str]` + - `agent_name: str` - File ID for the mask image. + The canonical name of the agent that produced this item. - - `image_url: Optional[str]` + - `class LocalShellCall: …` - Base64-encoded mask image. + A tool call to run a command on the local shell. - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + - `id: str` - The image generation model to use. Default: `gpt-image-1`. + The unique ID of the local shell call. - - `str` + - `action: LocalShellCallAction` - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + Execute a shell command on the server. - The image generation model to use. Default: `gpt-image-1`. + - `command: List[str]` - - `"gpt-image-1"` + The command to run. - - `"gpt-image-1-mini"` + - `env: Dict[str, str]` - - `"gpt-image-2"` + Environment variables to set for the command. - - `"gpt-image-2-2026-04-21"` + - `type: Literal["exec"]` - - `"gpt-image-1.5"` + The type of the local shell action. Always `exec`. - - `"chatgpt-image-latest"` + - `"exec"` - - `moderation: Optional[Literal["auto", "low"]]` + - `timeout_ms: Optional[int]` - Moderation level for the generated image. Default: `auto`. + Optional timeout in milliseconds for the command. - - `"auto"` + - `user: Optional[str]` - - `"low"` + Optional user to run the command as. - - `output_compression: Optional[int]` + - `working_directory: Optional[str]` - Compression level for the output image. Default: 100. + Optional working directory to run the command in. - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + - `call_id: str` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The unique ID of the local shell tool call generated by the model. - - `"png"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `"webp"` + The status of the local shell call. - - `"jpeg"` + - `"in_progress"` - - `partial_images: Optional[int]` + - `"completed"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"incomplete"` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + - `type: Literal["local_shell_call"]` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The type of the local shell call. Always `local_shell_call`. - - `"low"` + - `"local_shell_call"` - - `"medium"` + - `agent: Optional[LocalShellCallAgent]` - - `"high"` + The agent that produced this item. - - `"auto"` + - `agent_name: str` - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + The canonical name of the agent that produced this item. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `class LocalShellCallOutput: …` - - `str` + The output of a local shell tool call. - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `id: str` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The unique ID of the local shell tool call generated by the model. - - `"1024x1024"` + - `output: str` - - `"1024x1536"` + A JSON string of the output of the local shell tool call. - - `"1536x1024"` + - `type: Literal["local_shell_call_output"]` - - `"auto"` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `class LocalShell: …` + - `"local_shell_call_output"` - A tool that allows the model to execute shell commands in a local environment. + - `agent: Optional[LocalShellCallOutputAgent]` - - `type: Literal["local_shell"]` + The agent that produced this item. - The type of the local shell tool. Always `local_shell`. + - `agent_name: str` - - `"local_shell"` + The canonical name of the agent that produced this item. - - `class BetaFunctionShellTool: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - A tool that allows the model to execute shell commands. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `type: Literal["shell"]` + - `"in_progress"` - The type of the shell tool. Always `shell`. + - `"completed"` - - `"shell"` + - `"incomplete"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `class BetaResponseFunctionShellToolCall: …` - The tool invocation context(s). + A tool call that executes one or more shell commands in a managed environment. - - `"direct"` + - `id: str` - - `"programmatic"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `environment: Optional[Environment]` + - `action: Action` - - `class BetaContainerAuto: …` + The shell commands and limits that describe how to run the tool call. - - `type: Literal["container_auto"]` + - `commands: List[str]` - Automatically creates a container for this request + - `max_output_length: Optional[int]` - - `"container_auto"` + Optional maximum number of characters to return from each command. - - `file_ids: Optional[List[str]]` + - `timeout_ms: Optional[int]` - An optional list of uploaded files to make available to your code. + Optional timeout in milliseconds for the commands. - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `call_id: str` - The memory limit for the container. + The unique ID of the shell tool call generated by the model. - - `"1g"` + - `environment: Optional[Environment]` - - `"4g"` + Represents the use of a local environment to perform shell actions. - - `"16g"` + - `class BetaResponseLocalEnvironment: …` - - `"64g"` + Represents the use of a local environment to perform shell actions. - - `network_policy: Optional[NetworkPolicy]` + - `type: Literal["local"]` - Network access policy for the container. + The environment type. Always `local`. - - `class BetaContainerNetworkPolicyDisabled: …` + - `"local"` - - `class BetaContainerNetworkPolicyAllowlist: …` + - `class BetaResponseContainerReference: …` - - `skills: Optional[List[Skill]]` + Represents a container created with /v1/containers. - An optional list of skills referenced by id or inline data. + - `container_id: str` - - `class BetaSkillReference: …` + - `type: Literal["container_reference"]` - - `skill_id: str` + The environment type. Always `container_reference`. - The ID of the referenced skill. + - `"container_reference"` - - `type: Literal["skill_reference"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - References a skill created with the /v1/skills endpoint. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `"skill_reference"` + - `"in_progress"` - - `version: Optional[str]` + - `"completed"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"incomplete"` - - `class BetaInlineSkill: …` + - `type: Literal["shell_call"]` - - `description: str` + The type of the item. Always `shell_call`. - The description of the skill. + - `"shell_call"` - - `name: str` + - `agent: Optional[Agent]` - The name of the skill. + The agent that produced this item. - - `source: BetaInlineSkillSource` + - `agent_name: str` - Inline skill payload + The canonical name of the agent that produced this item. - - `data: str` + - `caller: Optional[Caller]` - Base64-encoded skill zip bundle. + The execution context that produced this tool call. - - `media_type: Literal["application/zip"]` + - `class CallerDirect: …` - The media type of the inline skill payload. Must be `application/zip`. + - `type: Literal["direct"]` - - `"application/zip"` + - `"direct"` - - `type: Literal["base64"]` + - `class CallerProgram: …` - The type of the inline skill source. Must be `base64`. + - `caller_id: str` - - `"base64"` + The call ID of the program item that produced this tool call. - - `type: Literal["inline"]` + - `type: Literal["program"]` - Defines an inline skill for this request. + - `"program"` - - `"inline"` + - `created_by: Optional[str]` - - `class BetaLocalEnvironment: …` + The ID of the entity that created this tool call. - - `type: Literal["local"]` + - `class BetaResponseFunctionShellToolCallOutput: …` - Use a local computer environment. + The output of a shell tool call that was emitted. - - `"local"` + - `id: str` - - `skills: Optional[List[BetaLocalSkill]]` + The unique ID of the shell call output. Populated when this item is returned via API. - An optional list of skills. + - `call_id: str` - - `description: str` + The unique ID of the shell tool call generated by the model. - The description of the skill. + - `max_output_length: Optional[int]` - - `name: str` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - The name of the skill. + - `output: List[Output]` - - `path: str` + An array of shell call output contents - The path to the directory containing the skill. + - `outcome: OutputOutcome` - - `class BetaContainerReference: …` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `container_id: str` + - `class OutputOutcomeTimeout: …` - The ID of the referenced container. + Indicates that the shell call exceeded its configured time limit. - - `type: Literal["container_reference"]` + - `type: Literal["timeout"]` - References a container created with the /v1/containers endpoint + The outcome type. Always `timeout`. - - `"container_reference"` + - `"timeout"` - - `class BetaCustomTool: …` + - `class OutputOutcomeExit: …` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + Indicates that the shell commands finished and returned an exit code. - - `name: str` + - `exit_code: int` - The name of the custom tool, used to identify it in tool calls. + Exit code from the shell process. - - `type: Literal["custom"]` + - `type: Literal["exit"]` - The type of the custom tool. Always `custom`. + The outcome type. Always `exit`. - - `"custom"` + - `"exit"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `stderr: str` - The tool invocation context(s). + The standard error output that was captured. - - `"direct"` + - `stdout: str` - - `"programmatic"` + The standard output that was captured. - - `defer_loading: Optional[bool]` + - `created_by: Optional[str]` - Whether this tool should be deferred and discovered via tool search. + The identifier of the actor that created the item. - - `description: Optional[str]` + - `status: Literal["in_progress", "completed", "incomplete"]` - Optional description of the custom tool, used to provide more context. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `format: Optional[Format]` + - `"in_progress"` - The input format for the custom tool. Default is unconstrained text. + - `"completed"` - - `class FormatText: …` + - `"incomplete"` - Unconstrained free-form text. + - `type: Literal["shell_call_output"]` - - `type: Literal["text"]` + The type of the shell call output. Always `shell_call_output`. - Unconstrained text format. Always `text`. + - `"shell_call_output"` - - `"text"` + - `agent: Optional[Agent]` - - `class FormatGrammar: …` + The agent that produced this item. - A grammar defined by the user. + - `agent_name: str` - - `definition: str` + The canonical name of the agent that produced this item. - The grammar definition. + - `caller: Optional[Caller]` - - `syntax: Literal["lark", "regex"]` + The execution context that produced this tool call. - The syntax of the grammar definition. One of `lark` or `regex`. + - `class CallerDirect: …` - - `"lark"` + - `type: Literal["direct"]` - - `"regex"` + - `"direct"` - - `type: Literal["grammar"]` + - `class CallerProgram: …` - Grammar format. Always `grammar`. + - `caller_id: str` - - `"grammar"` + The call ID of the program item that produced this tool call. - - `class BetaNamespaceTool: …` + - `type: Literal["program"]` - Groups function/custom tools under a shared namespace. + - `"program"` - - `description: str` + - `created_by: Optional[str]` - A description of the namespace shown to the model. + The identifier of the actor that created the item. - - `name: str` + - `class BetaResponseApplyPatchToolCall: …` - The namespace name used in tool calls (for example, `crm`). + A tool call that applies file diffs by creating, deleting, or updating files. - - `tools: List[Tool]` + - `id: str` - The function/custom tools available inside this namespace. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `class ToolFunction: …` + - `call_id: str` - - `name: str` + The unique ID of the apply patch tool call generated by the model. - - `type: Literal["function"]` + - `operation: Operation` - - `"function"` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `class OperationCreateFile: …` - The tool invocation context(s). + Instruction describing how to create a file via the apply_patch tool. - - `"direct"` + - `diff: str` - - `"programmatic"` + Diff to apply. - - `defer_loading: Optional[bool]` + - `path: str` - Whether this function should be deferred and discovered via tool search. + Path of the file to create. - - `description: Optional[str]` + - `type: Literal["create_file"]` - - `output_schema: Optional[Dict[str, object]]` + Create a new file with the provided diff. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `"create_file"` - - `parameters: Optional[object]` + - `class OperationDeleteFile: …` - - `strict: Optional[bool]` + Instruction describing how to delete a file via the apply_patch tool. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `path: str` - - `class BetaCustomTool: …` + Path of the file to delete. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: Literal["delete_file"]` - - `type: Literal["namespace"]` + Delete the specified file. - The type of the tool. Always `namespace`. + - `"delete_file"` - - `"namespace"` + - `class OperationUpdateFile: …` - - `class BetaToolSearchTool: …` + Instruction describing how to update a file via the apply_patch tool. - Hosted or BYOT tool search configuration for deferred tools. + - `diff: str` - - `type: Literal["tool_search"]` + Diff to apply. - The type of the tool. Always `tool_search`. + - `path: str` - - `"tool_search"` + Path of the file to update. - - `description: Optional[str]` + - `type: Literal["update_file"]` - Description shown to the model for a client-executed tool search tool. + Update an existing file with the provided diff. - - `execution: Optional[Literal["server", "client"]]` + - `"update_file"` - Whether tool search is executed by the server or by the client. + - `status: Literal["in_progress", "completed"]` - - `"server"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"client"` + - `"in_progress"` - - `parameters: Optional[object]` + - `"completed"` - Parameter schema for a client-executed tool search tool. + - `type: Literal["apply_patch_call"]` - - `class BetaWebSearchPreviewTool: …` + The type of the item. Always `apply_patch_call`. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"apply_patch_call"` - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + - `agent: Optional[Agent]` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The agent that produced this item. - - `"web_search_preview"` + - `agent_name: str` - - `"web_search_preview_2025_03_11"` + The canonical name of the agent that produced this item. - - `search_content_types: Optional[List[Literal["text", "image"]]]` + - `caller: Optional[Caller]` - - `"text"` + The execution context that produced this tool call. - - `"image"` + - `class CallerDirect: …` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `type: Literal["direct"]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"direct"` - - `"low"` + - `class CallerProgram: …` - - `"medium"` + - `caller_id: str` - - `"high"` + The call ID of the program item that produced this tool call. - - `user_location: Optional[UserLocation]` + - `type: Literal["program"]` - The user's location. + - `"program"` - - `type: Literal["approximate"]` + - `created_by: Optional[str]` - The type of location approximation. Always `approximate`. + The ID of the entity that created this tool call. - - `"approximate"` + - `class BetaResponseApplyPatchToolCallOutput: …` - - `city: Optional[str]` + The output emitted by an apply patch tool call. - Free text input for the city of the user, e.g. `San Francisco`. + - `id: str` - - `country: Optional[str]` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `call_id: str` - - `region: Optional[str]` + The unique ID of the apply patch tool call generated by the model. - Free text input for the region of the user, e.g. `California`. + - `status: Literal["completed", "failed"]` - - `timezone: Optional[str]` + The status of the apply patch tool call output. One of `completed` or `failed`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"completed"` - - `class BetaApplyPatchTool: …` + - `"failed"` - Allows the assistant to create, delete, or update files using unified diffs. + - `type: Literal["apply_patch_call_output"]` - - `type: Literal["apply_patch"]` + The type of the item. Always `apply_patch_call_output`. - The type of the tool. Always `apply_patch`. + - `"apply_patch_call_output"` - - `"apply_patch"` + - `agent: Optional[Agent]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The agent that produced this item. - The tool invocation context(s). + - `agent_name: str` - - `"direct"` + The canonical name of the agent that produced this item. - - `"programmatic"` + - `caller: Optional[Caller]` - - `type: Literal["tool_search_output"]` + The execution context that produced this tool call. - The item type. Always `tool_search_output`. + - `class CallerDirect: …` - - `"tool_search_output"` + - `type: Literal["direct"]` - - `id: Optional[str]` + - `"direct"` - The unique ID of this tool search output. + - `class CallerProgram: …` - - `agent: Optional[Agent]` + - `caller_id: str` - The agent that produced this item. + The call ID of the program item that produced this tool call. - - `agent_name: str` + - `type: Literal["program"]` - The canonical name of the agent that produced this item. + - `"program"` - - `call_id: Optional[str]` + - `created_by: Optional[str]` - The unique ID of the tool search call generated by the model. + The ID of the entity that created this tool call output. - - `execution: Optional[Literal["server", "client"]]` + - `output: Optional[str]` - Whether tool search was executed by the server or by the client. + Optional textual output returned by the apply patch tool. - - `"server"` + - `class McpListTools: …` - - `"client"` + A list of tools available on an MCP server. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `id: str` - The status of the tool search output. + The unique ID of the list. - - `"in_progress"` + - `server_label: str` - - `"completed"` + The label of the MCP server. - - `"incomplete"` + - `tools: List[McpListToolsTool]` -### Beta Response Usage + The tools available on the server. -- `class BetaResponseUsage: …` + - `input_schema: object` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The JSON schema describing the tool's input. - - `input_tokens: int` + - `name: str` - The number of input tokens. + The name of the tool. - - `input_tokens_details: InputTokensDetails` + - `annotations: Optional[object]` - A detailed breakdown of the input tokens. + Additional annotations about the tool. - - `cache_write_tokens: int` + - `description: Optional[str]` - The number of input tokens that were written to the cache. + The description of the tool. - - `cached_tokens: int` + - `type: Literal["mcp_list_tools"]` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The type of the item. Always `mcp_list_tools`. - - `output_tokens: int` + - `"mcp_list_tools"` - The number of output tokens. + - `agent: Optional[McpListToolsAgent]` - - `output_tokens_details: OutputTokensDetails` + The agent that produced this item. - A detailed breakdown of the output tokens. + - `agent_name: str` - - `reasoning_tokens: int` + The canonical name of the agent that produced this item. - The number of reasoning tokens. + - `error: Optional[str]` - - `total_tokens: int` + Error message if the server could not list tools. - The total number of tokens used. + - `class McpApprovalRequest: …` -### Beta Response Web Search Call Completed Event + A request for human approval of a tool invocation. -- `class BetaResponseWebSearchCallCompletedEvent: …` + - `id: str` - Emitted when a web search call is completed. + The unique ID of the approval request. - - `item_id: str` + - `arguments: str` - Unique ID for the output item associated with the web search call. + A JSON string of arguments for the tool. - - `output_index: int` + - `name: str` - The index of the output item that the web search call is associated with. + The name of the tool to run. - - `sequence_number: int` + - `server_label: str` - The sequence number of the web search call being processed. + The label of the MCP server making the request. - - `type: Literal["response.web_search_call.completed"]` + - `type: Literal["mcp_approval_request"]` - The type of the event. Always `response.web_search_call.completed`. + The type of the item. Always `mcp_approval_request`. - - `"response.web_search_call.completed"` + - `"mcp_approval_request"` - - `agent: Optional[Agent]` + - `agent: Optional[McpApprovalRequestAgent]` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. -### Beta Response Web Search Call In Progress Event - -- `class BetaResponseWebSearchCallInProgressEvent: …` + - `class McpApprovalResponse: …` - Emitted when a web search call is initiated. + A response to an MCP approval request. - - `item_id: str` + - `id: str` - Unique ID for the output item associated with the web search call. + The unique ID of the approval response - - `output_index: int` + - `approval_request_id: str` - The index of the output item that the web search call is associated with. + The ID of the approval request being answered. - - `sequence_number: int` + - `approve: bool` - The sequence number of the web search call being processed. + Whether the request was approved. - - `type: Literal["response.web_search_call.in_progress"]` + - `type: Literal["mcp_approval_response"]` - The type of the event. Always `response.web_search_call.in_progress`. + The type of the item. Always `mcp_approval_response`. - - `"response.web_search_call.in_progress"` + - `"mcp_approval_response"` - - `agent: Optional[Agent]` + - `agent: Optional[McpApprovalResponseAgent]` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. -### Beta Response Web Search Call Searching Event + - `reason: Optional[str]` -- `class BetaResponseWebSearchCallSearchingEvent: …` + Optional reason for the decision. - Emitted when a web search call is executing. + - `class McpCall: …` - - `item_id: str` + An invocation of a tool on an MCP server. - Unique ID for the output item associated with the web search call. + - `id: str` - - `output_index: int` + The unique ID of the tool call. - The index of the output item that the web search call is associated with. + - `arguments: str` - - `sequence_number: int` + A JSON string of the arguments passed to the tool. - The sequence number of the web search call being processed. + - `name: str` - - `type: Literal["response.web_search_call.searching"]` + The name of the tool that was run. - The type of the event. Always `response.web_search_call.searching`. + - `server_label: str` - - `"response.web_search_call.searching"` + The label of the MCP server running the tool. - - `agent: Optional[Agent]` + - `type: Literal["mcp_call"]` - The agent that owns this multi-agent streaming event. + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `agent: Optional[McpCallAgent]` + + The agent that produced this item. - `agent_name: str` The canonical name of the agent that produced this item. -### Beta Responses Client Event + - `approval_request_id: Optional[str]` -- `BetaResponsesClientEvent` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - Client events accepted by the Responses WebSocket server. + - `error: Optional[str]` - - `class ResponseCreate: …` + The error from the tool call, if any. - Client event for creating a response over a persistent WebSocket connection. - This payload uses the same top-level fields as `POST /v1/responses`. + - `output: Optional[str]` - Notes: + The output from the tool call. - - `stream` is implicit over WebSocket and should not be sent. - - `background` is not supported over WebSocket. + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - - `type: Literal["response.create"]` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The type of the client event. Always `response.create`. + - `"in_progress"` - - `"response.create"` + - `"completed"` - - `background: Optional[bool]` + - `"incomplete"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `"calling"` - - `context_management: Optional[List[ResponseCreateContextManagement]]` + - `"failed"` - Context management configuration for this request. + - `class BetaResponseCustomToolCallItem: …` - - `type: str` + A call to a custom tool created by the model. - The context management entry type. Currently only 'compaction' is supported. + - `id: str` - - `compact_threshold: Optional[int]` + The unique ID of the custom tool call item. - Token threshold at which compaction should be triggered for this entry. + - `status: Literal["in_progress", "completed", "incomplete"]` - - `conversation: Optional[ResponseCreateConversation]` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. - Input items and output items from this response are automatically added to this conversation after this response completes. + - `"in_progress"` - - `str` + - `"completed"` - The unique ID of the conversation. + - `"incomplete"` - - `class BetaResponseConversationParam: …` + - `created_by: Optional[str]` - The conversation that this response belongs to. + The identifier of the actor that created the item. + + - `class BetaResponseCustomToolCallOutputItem: …` + + The output of a custom tool call from your code, being sent back to the model. - `id: str` - The unique ID of the conversation. + The unique ID of the custom tool call output item. - - `include: Optional[List[BetaResponseIncludable]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - Specify additional output data to include in the model response. Currently supported values are: + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + - `"in_progress"` - - `"file_search_call.results"` + - `"completed"` - - `"web_search_call.results"` + - `"incomplete"` - - `"web_search_call.action.sources"` + - `created_by: Optional[str]` - - `"message.input_image.image_url"` + The identifier of the actor that created the item. - - `"computer_call_output.output.image_url"` +### Example - - `"code_interpreter_call.outputs"` +```python +import os +from openai import OpenAI - - `"reasoning.encrypted_content"` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +page = client.beta.responses.input_items.list( + response_id="response_id", +) +page = page.data[0] +print(page) +``` - - `"message.output_text.logprobs"` +#### Response - - `input: Optional[Union[str, BetaResponseInput, null]]` +```json +{ + "data": [ + { + "id": "id", + "content": [ + { + "text": "text", + "type": "input_text", + "prompt_cache_breakpoint": { + "mode": "explicit" + } + } + ], + "role": "user", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "status": "in_progress" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - Text, image, or file inputs to the model, used to generate a response. +### Example - Learn more: +```python +from openai import OpenAI +client = OpenAI() - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Image inputs](https://platform.openai.com/docs/guides/images) - - [File inputs](https://platform.openai.com/docs/guides/pdf-files) - - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) - - [Function calling](https://platform.openai.com/docs/guides/function-calling) +response = client.responses.input_items.list("resp_123") +print(response.data) +``` - - `str` +#### Response - A text input to the model, equivalent to a text input with the - `user` role. +```json +{ + "object": "list", + "data": [ + { + "id": "msg_abc123", + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Tell me a three sentence bedtime story about a unicorn." + } + ] + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc123", + "has_more": false +} +``` - - `List[BetaResponseInputItem]` +## Domain Types - - `class BetaEasyInputMessage: …` +### Beta Response Item List - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. +- `class BetaResponseItemList: …` - - `content: Union[str, BetaResponseInputMessageContentList]` + A list of Response items. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `data: List[BetaResponseItem]` - - `str` + A list of items used to generate this response. - A text input to the model. + - `class BetaResponseInputMessageItem: …` - - `List[BetaResponseInputContent]` + - `id: str` + + The unique ID of the message input. + + - `content: BetaResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. - `class BetaResponseInputText: …` @@ -138004,67 +148914,23 @@ print(compacted_response) - `"explicit"` - - `role: Literal["user", "assistant", "system", "developer"]` + - `role: Literal["user", "system", "developer"]` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The role of the message input. One of `user`, `system`, or `developer`. - `"user"` - - `"assistant"` - - `"system"` - `"developer"` - - `phase: Optional[Literal["commentary"]]` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - - `"commentary"` - - - `type: Optional[Literal["message"]]` + - `type: Literal["message"]` - The type of the message input. Always `message`. + The type of the message input. Always set to `message`. - `"message"` - - `class Message: …` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. - - - `content: BetaResponseInputMessageContentList` - - A list of one or many input items to the model, containing different content - types. - - - `class BetaResponseInputText: …` - - A text input to the model. - - - `class BetaResponseInputImage: …` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class BetaResponseInputFile: …` - - A file input to the model. - - - `role: Literal["user", "system", "developer"]` - - The role of the message input. One of `user`, `system`, or `developer`. - - - `"user"` - - - `"system"` - - - `"developer"` - - - `agent: Optional[MessageAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -138083,12 +148949,6 @@ print(compacted_response) - `"incomplete"` - - `type: Optional[Literal["message"]]` - - The type of the message input. Always set to `message`. - - - `"message"` - - `class BetaResponseOutputMessage: …` An output message from the model. @@ -138276,7 +149136,7 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `phase: Optional[Literal["commentary"]]` + - `phase: Optional[Literal["commentary", "final_answer"]]` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -138284,6 +149144,8 @@ print(compacted_response) - `"commentary"` + - `"final_answer"` + - `class BetaResponseFileSearchToolCall: …` The results of a file search tool call. See the @@ -138650,9 +149512,11 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ComputerCallOutput: …` + - `class BetaResponseComputerToolCallOutputItem: …` - The output of a computer tool call. + - `id: str` + + The unique ID of the computer call tool output. - `call_id: str` @@ -138677,19 +149541,29 @@ print(compacted_response) The URL of the screenshot image. + - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + - `type: Literal["computer_call_output"]` The type of the computer tool call output. Always `computer_call_output`. - `"computer_call_output"` - - `id: Optional[str]` - - The ID of the computer tool call output. - - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` - The safety checks reported by the API that have been acknowledged by the developer. + The safety checks reported by the API that have been acknowledged by the + developer. - `id: str` @@ -138703,7 +149577,7 @@ print(compacted_response) Details about the pending safety check. - - `agent: Optional[ComputerCallOutputAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -138711,15 +149585,9 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - - `"in_progress"` - - - `"completed"` + - `created_by: Optional[str]` - - `"incomplete"` + The identifier of the actor that created the item. - `class BetaResponseFunctionWebSearch: …` @@ -138825,66 +149693,16 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall: …` + - `class BetaResponseFunctionToolCallItem: …` A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `arguments: str` - - A JSON string of the arguments to pass to the function. - - - `call_id: str` - - The unique ID of the function tool call generated by the model. - - - `name: str` - - The name of the function to run. - - - `type: Literal["function_call"]` - - The type of the function tool call. Always `function_call`. - - - `"function_call"` - - - `id: Optional[str]` + - `id: str` The unique ID of the function tool call. - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `caller: Optional[Caller]` - - The execution context that produced this tool call. - - - `class CallerDirect: …` - - - `type: Literal["direct"]` - - - `"direct"` - - - `class CallerProgram: …` - - - `caller_id: str` - - The call ID of the program item that produced this tool call. - - - `type: Literal["program"]` - - - `"program"` - - - `namespace: Optional[str]` - - The namespace of the function to run. - - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `status: Literal["in_progress", "completed", "incomplete"]` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -138895,205 +149713,209 @@ print(compacted_response) - `"incomplete"` - - `class FunctionCallOutput: …` + - `created_by: Optional[str]` - The output of a function tool call. + The identifier of the actor that created the item. + + - `class BetaResponseFunctionToolCallOutputItem: …` + + - `id: str` + + The unique ID of the function call tool output. - `call_id: str` The unique ID of the function tool call generated by the model. - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + - `output: Union[str, List[OutputOutputContentList]]` - Text, image, or file output of the function tool call. + The output from the function call generated by your code. + Can be a string or an list of output content. - `str` - A JSON string of the output of the function tool call. - - - `List[BetaResponseFunctionCallOutputItem]` - - - `class BetaResponseInputTextContent: …` + A string of the output of the function call. - A text input to the model. + - `List[OutputOutputContentList]` - - `text: str` + Text, image, or file output of the function call. - The text input to the model. + - `class BetaResponseInputText: …` - - `type: Literal["input_text"]` + A text input to the model. - The type of the input item. Always `input_text`. + - `class BetaResponseInputImage: …` - - `"input_text"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `class BetaResponseInputFile: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A file input to the model. - - `mode: Literal["explicit"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The breakpoint mode. Always `explicit`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"explicit"` + - `"in_progress"` - - `class BetaResponseInputImageContent: …` + - `"completed"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"incomplete"` - - `type: Literal["input_image"]` + - `type: Literal["function_call_output"]` - The type of the input item. Always `input_image`. + The type of the function tool call output. Always `function_call_output`. - - `"input_image"` + - `"function_call_output"` - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + - `agent: Optional[Agent]` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The agent that produced this item. - - `"low"` + - `agent_name: str` - - `"high"` + The canonical name of the agent that produced this item. - - `"auto"` + - `caller: Optional[Caller]` - - `"original"` + The execution context that produced this tool call. - - `file_id: Optional[str]` + - `class CallerDirect: …` - The ID of the file to be sent to the model. + - `type: Literal["direct"]` - - `image_url: Optional[str]` + The caller type. Always `direct`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"direct"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `class CallerProgram: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `caller_id: str` - - `mode: Literal["explicit"]` + The call ID of the program item that produced this tool call. - The breakpoint mode. Always `explicit`. + - `type: Literal["program"]` - - `"explicit"` + The caller type. Always `program`. - - `class BetaResponseInputFileContent: …` + - `"program"` - A file input to the model. + - `created_by: Optional[str]` - - `type: Literal["input_file"]` + The identifier of the actor that created the item. - The type of the input item. Always `input_file`. + - `class AgentMessage: …` - - `"input_file"` + - `id: str` - - `detail: Optional[Literal["auto", "low", "high"]]` + The unique ID of the agent message. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `author: str` - - `"auto"` + The sending agent identity. - - `"low"` + - `content: List[AgentMessageContent]` - - `"high"` + Encrypted content sent between agents. - - `file_data: Optional[str]` + - `class BetaResponseInputText: …` - The base64-encoded data of the file to be sent to the model. + A text input to the model. - - `file_id: Optional[str]` + - `class BetaResponseOutputText: …` - The ID of the file to be sent to the model. + A text output from the model. - - `file_url: Optional[str]` + - `class AgentMessageContentText: …` - The URL of the file to be sent to the model. + A text content. - - `filename: Optional[str]` + - `text: str` - The name of the file to be sent to the model. + - `type: Literal["text"]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"text"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class AgentMessageContentSummaryText: …` - - `mode: Literal["explicit"]` + A summary text from the model. - The breakpoint mode. Always `explicit`. + - `text: str` - - `"explicit"` + A summary of the reasoning output from the model so far. - - `type: Literal["function_call_output"]` + - `type: Literal["summary_text"]` - The type of the function tool call output. Always `function_call_output`. + The type of the object. Always `summary_text`. - - `"function_call_output"` + - `"summary_text"` - - `id: Optional[str]` + - `class AgentMessageContentReasoningText: …` - The unique ID of the function tool call output. Populated when this item is returned via API. + Reasoning text from the model. - - `agent: Optional[FunctionCallOutputAgent]` + - `text: str` - The agent that produced this item. + The reasoning text from the model. - - `agent_name: str` + - `type: Literal["reasoning_text"]` - The canonical name of the agent that produced this item. + The type of the reasoning text. Always `reasoning_text`. - - `caller: Optional[FunctionCallOutputCaller]` + - `"reasoning_text"` - The execution context that produced this tool call. + - `class BetaResponseOutputRefusal: …` - - `class FunctionCallOutputCallerDirect: …` + A refusal from the model. - - `type: Literal["direct"]` + - `class BetaResponseInputImage: …` - The caller type. Always `direct`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"direct"` + - `class AgentMessageContentComputerScreenshot: …` - - `class FunctionCallOutputCallerProgram: …` + A screenshot of a computer. - - `caller_id: str` + - `detail: Literal["low", "high", "auto", "original"]` - The call ID of the program item that produced this tool call. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: Literal["program"]` + - `"low"` - The caller type. Always `program`. + - `"high"` - - `"program"` + - `"auto"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"original"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `file_id: Optional[str]` - - `"in_progress"` + The identifier of an uploaded file that contains the screenshot. - - `"completed"` + - `image_url: Optional[str]` - - `"incomplete"` + The URL of the screenshot image. - - `class AgentMessage: …` + - `type: Literal["computer_screenshot"]` - A message routed between agents. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `author: str` + - `"computer_screenshot"` - The sending agent identity. + - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` - - `content: List[AgentMessageContent]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Plaintext, image, or encrypted content sent between agents. + - `mode: Literal["explicit"]` - - `class BetaResponseInputTextContent: …` + The breakpoint mode. Always `explicit`. - A text input to the model. + - `"explicit"` - - `class BetaResponseInputImageContent: …` + - `class BetaResponseInputFile: …` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + A file input to the model. - `class AgentMessageContentEncryptedContent: …` @@ -139115,14 +149937,10 @@ print(compacted_response) - `type: Literal["agent_message"]` - The item type. Always `agent_message`. + The type of the item. Always `agent_message`. - `"agent_message"` - - `id: Optional[str]` - - The unique ID of this agent message item. - - `agent: Optional[AgentMessageAgent]` The agent that produced this item. @@ -139133,9 +149951,13 @@ print(compacted_response) - `class MultiAgentCall: …` + - `id: str` + + The unique ID of the multi-agent call item. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - The multi-agent action that was executed. + The multi-agent action to execute. - `"spawn_agent"` @@ -139151,7 +149973,7 @@ print(compacted_response) - `arguments: str` - The action arguments as a JSON string. + The JSON string of arguments generated for the action. - `call_id: str` @@ -139159,14 +149981,10 @@ print(compacted_response) - `type: Literal["multi_agent_call"]` - The item type. Always `multi_agent_call`. + The type of the multi-agent call. Always `multi_agent_call`. - `"multi_agent_call"` - - `id: Optional[str]` - - The unique ID of this multi-agent call. - - `agent: Optional[MultiAgentCallAgent]` The agent that produced this item. @@ -139177,6 +149995,10 @@ print(compacted_response) - `class MultiAgentCallOutput: …` + - `id: str` + + The unique ID of the multi-agent call output item. + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` The multi-agent action that produced this result. @@ -139197,107 +150019,77 @@ print(compacted_response) The unique ID of the multi-agent call. - - `output: List[MultiAgentCallOutputOutput]` + - `output: List[BetaResponseOutputText]` Text output returned by the multi-agent action. - - `text: str` - - The text content. - - - `type: Literal["output_text"]` - - The content type. Always `output_text`. - - - `"output_text"` - - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - - Citations associated with the text content. - - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - - - `file_id: str` - - The ID of the file. - - - `filename: str` - - The filename of the file cited. - - - `index: int` - - The index of the file in the list of files. - - - `type: Literal["file_citation"]` - - The citation type. Always `file_citation`. + - `annotations: List[Annotation]` - - `"file_citation"` + The annotations of the text output. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + - `text: str` - - `end_index: int` + The text output from the model. - The index of the last character of the citation in the message. + - `type: Literal["output_text"]` - - `start_index: int` + The type of the output text. Always `output_text`. - The index of the first character of the citation in the message. + - `logprobs: Optional[List[Logprob]]` - - `title: str` + - `type: Literal["multi_agent_call_output"]` - The title of the cited resource. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `type: Literal["url_citation"]` + - `"multi_agent_call_output"` - The citation type. Always `url_citation`. + - `agent: Optional[MultiAgentCallOutputAgent]` - - `"url_citation"` + The agent that produced this item. - - `url: str` + - `agent_name: str` - The URL of the cited resource. + The canonical name of the agent that produced this item. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `class BetaResponseToolSearchCall: …` - - `container_id: str` + - `id: str` - The ID of the container. + The unique ID of the tool search call item. - - `end_index: int` + - `arguments: object` - The index of the last character of the citation in the message. + Arguments used for the tool search call. - - `file_id: str` + - `call_id: Optional[str]` - The ID of the container file. + The unique ID of the tool search call generated by the model. - - `filename: str` + - `execution: Literal["server", "client"]` - The filename of the container file cited. + Whether tool search was executed by the server or by the client. - - `start_index: int` + - `"server"` - The index of the first character of the citation in the message. + - `"client"` - - `type: Literal["container_file_citation"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The citation type. Always `container_file_citation`. + The status of the tool search call item that was recorded. - - `"container_file_citation"` + - `"in_progress"` - - `type: Literal["multi_agent_call_output"]` + - `"completed"` - The item type. Always `multi_agent_call_output`. + - `"incomplete"` - - `"multi_agent_call_output"` + - `type: Literal["tool_search_call"]` - - `id: Optional[str]` + The type of the item. Always `tool_search_call`. - The unique ID of this multi-agent call output. + - `"tool_search_call"` - - `agent: Optional[MultiAgentCallOutputAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -139305,35 +150097,21 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ToolSearchCall: …` - - - `arguments: object` - - The arguments supplied to the tool search call. - - - `type: Literal["tool_search_call"]` - - The item type. Always `tool_search_call`. - - - `"tool_search_call"` - - - `id: Optional[str]` - - The unique ID of this tool search call. + - `created_by: Optional[str]` - - `agent: Optional[ToolSearchCallAgent]` + The identifier of the actor that created the item. - The agent that produced this item. + - `class BetaResponseToolSearchOutputItem: …` - - `agent_name: str` + - `id: str` - The canonical name of the agent that produced this item. + The unique ID of the tool search output item. - `call_id: Optional[str]` The unique ID of the tool search call generated by the model. - - `execution: Optional[Literal["server", "client"]]` + - `execution: Literal["server", "client"]` Whether tool search was executed by the server or by the client. @@ -139341,9 +150119,9 @@ print(compacted_response) - `"client"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `status: Literal["in_progress", "completed", "incomplete"]` - The status of the tool search call. + The status of the tool search output item that was recorded. - `"in_progress"` @@ -139351,11 +150129,9 @@ print(compacted_response) - `"incomplete"` - - `class BetaResponseToolSearchOutputItemParam: …` - - `tools: List[BetaTool]` - The loaded tool definitions returned by the tool search output. + The loaded tool definitions returned by tool search. - `class BetaFunctionTool: …` @@ -139454,7 +150230,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -139464,7 +150240,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `class FiltersCompoundFilter: …` @@ -139511,7 +150291,7 @@ print(compacted_response) - `"nin"` - - `value: Union[str, float, bool, List[object]]` + - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -139521,7 +150301,11 @@ print(compacted_response) - `bool` - - `List[object]` + - `List[Union[str, float]]` + + - `str` + + - `float` - `object` @@ -140445,14 +151229,10 @@ print(compacted_response) - `type: Literal["tool_search_output"]` - The item type. Always `tool_search_output`. + The type of the item. Always `tool_search_output`. - `"tool_search_output"` - - `id: Optional[str]` - - The unique ID of this tool search output. - - `agent: Optional[Agent]` The agent that produced this item. @@ -140461,39 +151241,39 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `call_id: Optional[str]` - - The unique ID of the tool search call generated by the model. + - `created_by: Optional[str]` - - `execution: Optional[Literal["server", "client"]]` + The identifier of the actor that created the item. - Whether tool search was executed by the server or by the client. + - `class AdditionalTools: …` - - `"server"` + - `id: str` - - `"client"` + The unique ID of the additional tools item. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `role: Literal["unknown", "user", "assistant", 5 more]` - The status of the tool search output. + The role that provided the additional tools. - - `"in_progress"` + - `"unknown"` - - `"completed"` + - `"user"` - - `"incomplete"` + - `"assistant"` - - `class AdditionalTools: …` + - `"system"` - - `role: Literal["developer"]` + - `"critic"` - The role that provided the additional tools. Only `developer` is supported. + - `"discriminator"` - `"developer"` + - `"tool"` + - `tools: List[BetaTool]` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `class BetaFunctionTool: …` @@ -140561,14 +151341,10 @@ print(compacted_response) - `type: Literal["additional_tools"]` - The item type. Always `additional_tools`. + The type of the item. Always `additional_tools`. - `"additional_tools"` - - `id: Optional[str]` - - The unique ID of this additional tools item. - - `agent: Optional[AdditionalToolsAgent]` The agent that produced this item. @@ -140608,7 +151384,69 @@ print(compacted_response) - `"reasoning"` - - `agent: Optional[Agent]` + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `content: Optional[List[Content]]` + + Reasoning text content. + + - `text: str` + + The reasoning text from the model. + + - `type: Literal["reasoning_text"]` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: Optional[str]` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `class Program: …` + + - `id: str` + + The unique ID of the program item. + + - `call_id: str` + + The stable call ID of the program item. + + - `code: str` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: str` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: Literal["program"]` + + The type of the item. Always `program`. + + - `"program"` + + - `agent: Optional[ProgramAgent]` The agent that produced this item. @@ -140616,43 +151454,53 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `content: Optional[List[Content]]` + - `class ProgramOutput: …` - Reasoning text content. + - `id: str` - - `text: str` + The unique ID of the program output item. - The reasoning text from the model. + - `call_id: str` - - `type: Literal["reasoning_text"]` + The call ID of the program item. - The type of the reasoning text. Always `reasoning_text`. + - `result: str` - - `"reasoning_text"` + The result produced by the program item. - - `encrypted_content: Optional[str]` + - `status: Literal["completed", "incomplete"]` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The terminal status of the program output item. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"completed"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"incomplete"` - - `"in_progress"` + - `type: Literal["program_output"]` - - `"completed"` + The type of the item. Always `program_output`. - - `"incomplete"` + - `"program_output"` - - `class BetaResponseCompactionItemParam: …` + - `agent: Optional[ProgramOutputAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCompactionItem: …` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `id: str` + + The unique ID of the compaction item. + - `encrypted_content: str` - The encrypted content of the compaction summary. + The encrypted content that was produced by compaction. - `type: Literal["compaction"]` @@ -140660,10 +151508,6 @@ print(compacted_response) - `"compaction"` - - `id: Optional[str]` - - The ID of the compaction item. - - `agent: Optional[Agent]` The agent that produced this item. @@ -140672,6 +151516,10 @@ print(compacted_response) The canonical name of the agent that produced this item. + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + - `class ImageGenerationCall: …` An image generation request made by the model. @@ -140889,41 +151737,75 @@ print(compacted_response) - `"incomplete"` - - `class ShellCall: …` + - `class BetaResponseFunctionShellToolCall: …` - A tool representing a request to execute one or more shell commands. + A tool call that executes one or more shell commands in a managed environment. - - `action: ShellCallAction` + - `id: str` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `action: Action` The shell commands and limits that describe how to run the tool call. - `commands: List[str]` - Ordered shell commands for the execution environment to run. - - `max_output_length: Optional[int]` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Optional maximum number of characters to return from each command. - `timeout_ms: Optional[int]` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Optional timeout in milliseconds for the commands. - `call_id: str` The unique ID of the shell tool call generated by the model. + - `environment: Optional[Environment]` + + Represents the use of a local environment to perform shell actions. + + - `class BetaResponseLocalEnvironment: …` + + Represents the use of a local environment to perform shell actions. + + - `type: Literal["local"]` + + The environment type. Always `local`. + + - `"local"` + + - `class BetaResponseContainerReference: …` + + Represents a container created with /v1/containers. + + - `container_id: str` + + - `type: Literal["container_reference"]` + + The environment type. Always `container_reference`. + + - `"container_reference"` + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + - `type: Literal["shell_call"]` The type of the item. Always `shell_call`. - `"shell_call"` - - `id: Optional[str]` - - The unique ID of the shell tool call. Populated when this item is returned via API. - - - `agent: Optional[ShellCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -140931,19 +151813,17 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ShellCallCaller]` + - `caller: Optional[Caller]` The execution context that produced this tool call. - - `class ShellCallCallerDirect: …` + - `class CallerDirect: …` - `type: Literal["direct"]` - The caller type. Always `direct`. - - `"direct"` - - `class ShellCallCallerProgram: …` + - `class CallerProgram: …` - `caller_id: str` @@ -140951,45 +151831,37 @@ print(compacted_response) - `type: Literal["program"]` - The caller type. Always `program`. - - `"program"` - - `environment: Optional[ShellCallEnvironment]` - - The environment to execute the shell commands in. - - - `class BetaLocalEnvironment: …` - - - `class BetaContainerReference: …` - - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `created_by: Optional[str]` - - `"in_progress"` + The ID of the entity that created this tool call. - - `"completed"` + - `class BetaResponseFunctionShellToolCallOutput: …` - - `"incomplete"` + The output of a shell tool call that was emitted. - - `class ShellCallOutput: …` + - `id: str` - The streamed output items emitted by a shell tool call. + The unique ID of the shell call output. Populated when this item is returned via API. - `call_id: str` The unique ID of the shell tool call generated by the model. - - `output: List[BetaResponseFunctionShellCallOutputContent]` + - `max_output_length: Optional[int]` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `outcome: Outcome` + - `output: List[Output]` - The exit or timeout outcome associated with this shell call. + An array of shell call output contents - - `class OutcomeTimeout: …` + - `outcome: OutputOutcome` + + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + + - `class OutputOutcomeTimeout: …` Indicates that the shell call exceeded its configured time limit. @@ -140999,13 +151871,13 @@ print(compacted_response) - `"timeout"` - - `class OutcomeExit: …` + - `class OutputOutcomeExit: …` Indicates that the shell commands finished and returned an exit code. - `exit_code: int` - The exit code returned by the shell process. + Exit code from the shell process. - `type: Literal["exit"]` @@ -141015,23 +151887,33 @@ print(compacted_response) - `stderr: str` - Captured stderr output for the shell call. + The standard error output that was captured. - `stdout: str` - Captured stdout output for the shell call. + The standard output that was captured. - - `type: Literal["shell_call_output"]` + - `created_by: Optional[str]` - The type of the item. Always `shell_call_output`. + The identifier of the actor that created the item. - - `"shell_call_output"` + - `status: Literal["in_progress", "completed", "incomplete"]` - - `id: Optional[str]` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"in_progress"` - - `agent: Optional[ShellCallOutputAgent]` + - `"completed"` + + - `"incomplete"` + + - `type: Literal["shell_call_output"]` + + The type of the shell call output. Always `shell_call_output`. + + - `"shell_call_output"` + + - `agent: Optional[Agent]` The agent that produced this item. @@ -141039,19 +151921,17 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ShellCallOutputCaller]` + - `caller: Optional[Caller]` The execution context that produced this tool call. - - `class ShellCallOutputCallerDirect: …` + - `class CallerDirect: …` - `type: Literal["direct"]` - The caller type. Always `direct`. - - `"direct"` - - `class ShellCallOutputCallerProgram: …` + - `class CallerProgram: …` - `caller_id: str` @@ -141059,83 +151939,75 @@ print(compacted_response) - `type: Literal["program"]` - The caller type. Always `program`. - - `"program"` - - `max_output_length: Optional[int]` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the shell call output. + - `created_by: Optional[str]` - - `"in_progress"` + The identifier of the actor that created the item. - - `"completed"` + - `class BetaResponseApplyPatchToolCall: …` - - `"incomplete"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `class ApplyPatchCall: …` + - `id: str` - A tool call representing a request to create, delete, or update files using diff patches. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id: str` The unique ID of the apply patch tool call generated by the model. - - `operation: ApplyPatchCallOperation` + - `operation: Operation` - The specific create, delete, or update instruction for the apply_patch tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `class ApplyPatchCallOperationCreateFile: …` + - `class OperationCreateFile: …` - Instruction for creating a new file via the apply_patch tool. + Instruction describing how to create a file via the apply_patch tool. - `diff: str` - Unified diff content to apply when creating the file. + Diff to apply. - `path: str` - Path of the file to create relative to the workspace root. + Path of the file to create. - `type: Literal["create_file"]` - The operation type. Always `create_file`. + Create a new file with the provided diff. - `"create_file"` - - `class ApplyPatchCallOperationDeleteFile: …` + - `class OperationDeleteFile: …` - Instruction for deleting an existing file via the apply_patch tool. + Instruction describing how to delete a file via the apply_patch tool. - `path: str` - Path of the file to delete relative to the workspace root. + Path of the file to delete. - `type: Literal["delete_file"]` - The operation type. Always `delete_file`. + Delete the specified file. - `"delete_file"` - - `class ApplyPatchCallOperationUpdateFile: …` + - `class OperationUpdateFile: …` - Instruction for updating an existing file via the apply_patch tool. + Instruction describing how to update a file via the apply_patch tool. - `diff: str` - Unified diff content to apply to the existing file. + Diff to apply. - `path: str` - Path of the file to update relative to the workspace root. + Path of the file to update. - `type: Literal["update_file"]` - The operation type. Always `update_file`. + Update an existing file with the provided diff. - `"update_file"` @@ -141153,11 +152025,7 @@ print(compacted_response) - `"apply_patch_call"` - - `id: Optional[str]` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `agent: Optional[ApplyPatchCallAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -141165,19 +152033,17 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ApplyPatchCallCaller]` + - `caller: Optional[Caller]` The execution context that produced this tool call. - - `class ApplyPatchCallCallerDirect: …` + - `class CallerDirect: …` - `type: Literal["direct"]` - The caller type. Always `direct`. - - `"direct"` - - `class ApplyPatchCallCallerProgram: …` + - `class CallerProgram: …` - `caller_id: str` @@ -141185,13 +152051,19 @@ print(compacted_response) - `type: Literal["program"]` - The caller type. Always `program`. - - `"program"` - - `class ApplyPatchCallOutput: …` + - `created_by: Optional[str]` - The streamed output emitted by an apply patch tool call. + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput: …` + + The output emitted by an apply patch tool call. + + - `id: str` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id: str` @@ -141211,11 +152083,7 @@ print(compacted_response) - `"apply_patch_call_output"` - - `id: Optional[str]` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - - `agent: Optional[ApplyPatchCallOutputAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -141223,19 +152091,17 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[ApplyPatchCallOutputCaller]` + - `caller: Optional[Caller]` The execution context that produced this tool call. - - `class ApplyPatchCallOutputCallerDirect: …` + - `class CallerDirect: …` - `type: Literal["direct"]` - The caller type. Always `direct`. - - `"direct"` - - `class ApplyPatchCallOutputCallerProgram: …` + - `class CallerProgram: …` - `caller_id: str` @@ -141243,13 +152109,15 @@ print(compacted_response) - `type: Literal["program"]` - The caller type. Always `program`. - - `"program"` + - `created_by: Optional[str]` + + The ID of the entity that created this tool call output. + - `output: Optional[str]` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Optional textual output returned by the apply patch tool. - `class McpListTools: …` @@ -141327,253 +152195,988 @@ print(compacted_response) - `"mcp_approval_request"` - - `agent: Optional[McpApprovalRequestAgent]` + - `agent: Optional[McpApprovalRequestAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse: …` + + A response to an MCP approval request. + + - `id: str` + + The unique ID of the approval response + + - `approval_request_id: str` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: Literal["mcp_approval_response"]` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `agent: Optional[McpApprovalResponseAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `reason: Optional[str]` + + Optional reason for the decision. + + - `class McpCall: …` + + An invocation of a tool on an MCP server. + + - `id: str` + + The unique ID of the tool call. + + - `arguments: str` + + A JSON string of the arguments passed to the tool. + + - `name: str` + + The name of the tool that was run. + + - `server_label: str` + + The label of the MCP server running the tool. + + - `type: Literal["mcp_call"]` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `agent: Optional[McpCallAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `approval_request_id: Optional[str]` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: Optional[str]` + + The error from the tool call, if any. + + - `output: Optional[str]` + + The output from the tool call. + + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `class BetaResponseCustomToolCallItem: …` + + A call to a custom tool created by the model. + + - `id: str` + + The unique ID of the custom tool call item. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `class BetaResponseCustomToolCallOutputItem: …` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: str` + + The unique ID of the custom tool call output item. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `created_by: Optional[str]` + + The identifier of the actor that created the item. + + - `first_id: str` + + The ID of the first item in the list. + + - `has_more: bool` + + Whether there are more items available. + + - `last_id: str` + + The ID of the last item in the list. + + - `object: Literal["list"]` + + The type of object returned, must be `list`. + + - `"list"` + +# Input Tokens + +## Get input token counts + +`beta.responses.input_tokens.count(InputTokenCountParams**kwargs) -> InputTokenCountResponse` + +**post** `/responses/input_tokens?beta=true` + +Returns input token counts of the request. + +Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. + +### Parameters + +- `conversation: Optional[Conversation]` + + The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. + + - `str` + + The unique ID of the conversation. + + - `class BetaResponseConversationParam: …` + + The conversation that this response belongs to. + + - `id: str` + + The unique ID of the conversation. + +- `input: Optional[Union[str, Iterable[BetaResponseInputItemParam], null]]` + + Text, image, or file inputs to the model, used to generate a response + + - `str` + + A text input to the model, equivalent to a text input with the `user` role. + + - `Iterable[BetaResponseInputItemParam]` + + A list of one or many input items to the model, containing different content types. + + - `class BetaEasyInputMessage: …` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: Union[str, BetaResponseInputMessageContentList]` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `str` + + A text input to the model. + + - `List[BetaResponseInputContent]` + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `text: str` + + The text input to the model. + + - `type: Literal["input_text"]` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: Literal["low", "high", "auto", "original"]` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: Literal["input_image"]` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `image_url: Optional[str]` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `type: Literal["input_file"]` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: Optional[Literal["auto", "low", "high"]]` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: Optional[str]` + + The content of the file to be sent to the model. + + - `file_id: Optional[str]` + + The ID of the file to be sent to the model. + + - `file_url: Optional[str]` + + The URL of the file to be sent to the model. + + - `filename: Optional[str]` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: Literal["explicit"]` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `role: Literal["user", "assistant", "system", "developer"]` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"developer"` + + - `phase: Optional[Literal["commentary", "final_answer"]]` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `type: Optional[Literal["message"]]` + + The type of the message input. Always `message`. + + - `"message"` + + - `class Message: …` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: BetaResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText: …` + + A text input to the model. + + - `class BetaResponseInputImage: …` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile: …` + + A file input to the model. + + - `role: Literal["user", "system", "developer"]` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `agent: Optional[MessageAgent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Optional[Literal["message"]]` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `class BetaResponseOutputMessage: …` + + An output message from the model. + + - `id: str` + + The unique ID of the output message. + + - `content: List[Content]` + + The content of the output message. + + - `class BetaResponseOutputText: …` + + A text output from the model. + + - `annotations: List[Annotation]` + + The annotations of the text output. + + - `class AnnotationFileCitation: …` + + A citation to a file. + + - `file_id: str` + + The ID of the file. + + - `filename: str` + + The filename of the file cited. + + - `index: int` + + The index of the file in the list of files. + + - `type: Literal["file_citation"]` + + The type of the file citation. Always `file_citation`. + + - `"file_citation"` + + - `class AnnotationURLCitation: …` + + A citation for a web resource used to generate a model response. + + - `end_index: int` + + The index of the last character of the URL citation in the message. + + - `start_index: int` + + The index of the first character of the URL citation in the message. + + - `title: str` + + The title of the web resource. + + - `type: Literal["url_citation"]` + + The type of the URL citation. Always `url_citation`. + + - `"url_citation"` + + - `url: str` + + The URL of the web resource. + + - `class AnnotationContainerFileCitation: …` + + A citation for a container file used to generate a model response. + + - `container_id: str` + + The ID of the container file. + + - `end_index: int` + + The index of the last character of the container file citation in the message. + + - `file_id: str` + + The ID of the file. + + - `filename: str` + + The filename of the container file cited. + + - `start_index: int` + + The index of the first character of the container file citation in the message. + + - `type: Literal["container_file_citation"]` + + The type of the container file citation. Always `container_file_citation`. + + - `"container_file_citation"` + + - `class AnnotationFilePath: …` + + A path to a file. + + - `file_id: str` + + The ID of the file. + + - `index: int` + + The index of the file in the list of files. + + - `type: Literal["file_path"]` + + The type of the file path. Always `file_path`. + + - `"file_path"` + + - `text: str` + + The text output from the model. + + - `type: Literal["output_text"]` + + The type of the output text. Always `output_text`. + + - `"output_text"` + + - `logprobs: Optional[List[Logprob]]` + + - `token: str` + + - `bytes: List[int]` + + - `logprob: float` + + - `top_logprobs: List[LogprobTopLogprob]` + + - `token: str` + + - `bytes: List[int]` + + - `logprob: float` + + - `class BetaResponseOutputRefusal: …` + + A refusal from the model. + + - `refusal: str` + + The refusal explanation from the model. + + - `type: Literal["refusal"]` + + The type of the refusal. Always `refusal`. + + - `"refusal"` + + - `role: Literal["assistant"]` + + The role of the output message. Always `assistant`. + + - `"assistant"` + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: Literal["message"]` + + The type of the output message. Always `message`. + + - `"message"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `phase: Optional[Literal["commentary", "final_answer"]]` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `class BetaResponseFileSearchToolCall: …` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `id: str` + + The unique ID of the file search tool call. + + - `queries: List[str]` + + The queries used to search for files. + + - `status: Literal["in_progress", "searching", "completed", 2 more]` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: Literal["file_search_call"]` + + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` + + - `agent: Optional[Agent]` + + The agent that produced this item. + + - `agent_name: str` + + The canonical name of the agent that produced this item. + + - `results: Optional[List[Result]]` + + The results of the file search tool call. + + - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + + 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, booleans, or numbers. + + - `str` + + - `float` + + - `bool` + + - `file_id: Optional[str]` + + The unique ID of the file. + + - `filename: Optional[str]` + + The name of the file. + + - `score: Optional[float]` + + The relevance score of the file - a value between 0 and 1. + + - `text: Optional[str]` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall: …` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `id: str` + + The unique ID of the computer call. + + - `call_id: str` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: List[PendingSafetyCheck]` + + The pending safety checks for the computer call. + + - `id: str` + + The ID of the pending safety check. + + - `code: Optional[str]` + + The type of the pending safety check. + + - `message: Optional[str]` + + Details about the pending safety check. + + - `status: Literal["in_progress", "completed", "incomplete"]` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The agent that produced this item. + - `"in_progress"` - - `agent_name: str` + - `"completed"` - The canonical name of the agent that produced this item. + - `"incomplete"` - - `class McpApprovalResponse: …` + - `type: Literal["computer_call"]` - A response to an MCP approval request. + The type of the computer call. Always `computer_call`. - - `approval_request_id: str` + - `"computer_call"` - The ID of the approval request being answered. + - `action: Optional[BetaComputerAction]` - - `approve: bool` + A click action. - Whether the request was approved. + - `class Click: …` - - `type: Literal["mcp_approval_response"]` + A click action. - The type of the item. Always `mcp_approval_response`. + - `button: Literal["left", "right", "wheel", 2 more]` - - `"mcp_approval_response"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `id: Optional[str]` + - `"left"` - The unique ID of the approval response + - `"right"` - - `agent: Optional[McpApprovalResponseAgent]` + - `"wheel"` - The agent that produced this item. + - `"back"` - - `agent_name: str` + - `"forward"` - The canonical name of the agent that produced this item. + - `type: Literal["click"]` - - `reason: Optional[str]` + Specifies the event type. For a click action, this property is always `click`. - Optional reason for the decision. + - `"click"` - - `class McpCall: …` + - `x: int` - An invocation of a tool on an MCP server. + The x-coordinate where the click occurred. - - `id: str` + - `y: int` - The unique ID of the tool call. + The y-coordinate where the click occurred. - - `arguments: str` + - `keys: Optional[List[str]]` - A JSON string of the arguments passed to the tool. + The keys being held while clicking. - - `name: str` + - `class DoubleClick: …` - The name of the tool that was run. + A double click action. - - `server_label: str` + - `keys: Optional[List[str]]` - The label of the MCP server running the tool. + The keys being held while double-clicking. - - `type: Literal["mcp_call"]` + - `type: Literal["double_click"]` - The type of the item. Always `mcp_call`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"mcp_call"` + - `"double_click"` - - `agent: Optional[McpCallAgent]` + - `x: int` - The agent that produced this item. + The x-coordinate where the double click occurred. - - `agent_name: str` + - `y: int` - The canonical name of the agent that produced this item. + The y-coordinate where the double click occurred. - - `approval_request_id: Optional[str]` + - `class Drag: …` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + A drag action. - - `error: Optional[str]` + - `path: List[DragPath]` - The error from the tool call, if any. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `output: Optional[str]` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The output from the tool call. + - `x: int` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + The x-coordinate. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `y: int` - - `"in_progress"` + The y-coordinate. - - `"completed"` + - `type: Literal["drag"]` - - `"incomplete"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"calling"` + - `"drag"` - - `"failed"` + - `keys: Optional[List[str]]` - - `class BetaResponseCustomToolCallOutput: …` + The keys being held while dragging the mouse. - The output of a custom tool call from your code, being sent back to the model. + - `class Keypress: …` - - `call_id: str` + A collection of keypresses the model would like to perform. - The call ID, used to map this custom tool call output to a custom tool call. + - `keys: List[str]` - - `output: Union[str, List[OutputOutputContentList]]` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `type: Literal["keypress"]` - - `str` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - A string of the output of the custom tool call. + - `"keypress"` - - `List[OutputOutputContentList]` + - `class Move: …` - Text, image, or file output of the custom tool call. + A mouse move action. - - `class BetaResponseInputText: …` + - `type: Literal["move"]` - A text input to the model. + Specifies the event type. For a move action, this property is always set to `move`. - - `class BetaResponseInputImage: …` + - `"move"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `x: int` - - `class BetaResponseInputFile: …` + The x-coordinate to move to. - A file input to the model. + - `y: int` - - `type: Literal["custom_tool_call_output"]` + The y-coordinate to move to. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `keys: Optional[List[str]]` - - `"custom_tool_call_output"` + The keys being held while moving the mouse. - - `id: Optional[str]` + - `class Screenshot: …` - The unique ID of the custom tool call output in the OpenAI platform. + A screenshot action. - - `agent: Optional[Agent]` + - `type: Literal["screenshot"]` - The agent that produced this item. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `agent_name: str` + - `"screenshot"` - The canonical name of the agent that produced this item. + - `class Scroll: …` - - `caller: Optional[Caller]` + A scroll action. - The execution context that produced this tool call. + - `scroll_x: int` - - `class CallerDirect: …` + The horizontal scroll distance. - - `type: Literal["direct"]` + - `scroll_y: int` - The caller type. Always `direct`. + The vertical scroll distance. - - `"direct"` + - `type: Literal["scroll"]` - - `class CallerProgram: …` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `caller_id: str` + - `"scroll"` - The call ID of the program item that produced this tool call. + - `x: int` - - `type: Literal["program"]` + The x-coordinate where the scroll occurred. - The caller type. Always `program`. + - `y: int` - - `"program"` + The y-coordinate where the scroll occurred. - - `class BetaResponseCustomToolCall: …` + - `keys: Optional[List[str]]` - A call to a custom tool created by the model. + The keys being held while scrolling. - - `call_id: str` + - `class Type: …` - An identifier used to map this custom tool call to a tool call output. + An action to type in text. - - `input: str` + - `text: str` - The input for the custom tool call generated by the model. + The text to type. - - `name: str` + - `type: Literal["type"]` - The name of the custom tool being called. + Specifies the event type. For a type action, this property is always set to `type`. - - `type: Literal["custom_tool_call"]` + - `"type"` - The type of the custom tool call. Always `custom_tool_call`. + - `class Wait: …` - - `"custom_tool_call"` + A wait action. - - `id: Optional[str]` + - `type: Literal["wait"]` - The unique ID of the custom tool call in the OpenAI platform. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `agent: Optional[Agent]` + - `"wait"` - The agent that produced this item. + - `actions: Optional[BetaComputerActionList]` - - `agent_name: str` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The canonical name of the agent that produced this item. + - `class Click: …` - - `caller: Optional[Caller]` + A click action. - The execution context that produced this tool call. + - `class DoubleClick: …` - - `class CallerDirect: …` + A double click action. - - `type: Literal["direct"]` + - `class Drag: …` - - `"direct"` + A drag action. - - `class CallerProgram: …` + - `class Keypress: …` - - `caller_id: str` + A collection of keypresses the model would like to perform. - The call ID of the program item that produced this tool call. + - `class Move: …` - - `type: Literal["program"]` + A mouse move action. - - `"program"` + - `class Screenshot: …` - - `namespace: Optional[str]` + A screenshot action. - The namespace of the custom tool being called. + - `class Scroll: …` - - `class CompactionTrigger: …` + A scroll action. - Compacts the current context. Must be the final input item. + - `class Type: …` - - `type: Literal["compaction_trigger"]` + An action to type in text. - The type of the item. Always `compaction_trigger`. + - `class Wait: …` - - `"compaction_trigger"` + A wait action. - - `agent: Optional[CompactionTriggerAgent]` + - `agent: Optional[Agent]` The agent that produced this item. @@ -141581,53 +153184,60 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ItemReference: …` + - `class ComputerCallOutput: …` - An internal identifier for an item to reference. + The output of a computer tool call. - - `id: str` + - `call_id: str` - The ID of the item to reference. + The ID of the computer tool call that produced the output. - - `agent: Optional[ItemReferenceAgent]` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The agent that produced this item. + A computer screenshot image used with the computer use tool. - - `agent_name: str` + - `type: Literal["computer_screenshot"]` - The canonical name of the agent that produced this item. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `type: Optional[Literal["item_reference"]]` + - `"computer_screenshot"` - The type of item to reference. Always `item_reference`. + - `file_id: Optional[str]` - - `"item_reference"` + The identifier of an uploaded file that contains the screenshot. - - `class Program: …` + - `image_url: Optional[str]` - - `id: str` + The URL of the screenshot image. - The unique ID of this program item. + - `type: Literal["computer_call_output"]` - - `call_id: str` + The type of the computer tool call output. Always `computer_call_output`. - The stable call ID of the program item. + - `"computer_call_output"` - - `code: str` + - `id: Optional[str]` - The JavaScript source executed by programmatic tool calling. + The ID of the computer tool call output. - - `fingerprint: str` + - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` - Opaque program replay fingerprint that must be round-tripped. + The safety checks reported by the API that have been acknowledged by the developer. - - `type: Literal["program"]` + - `id: str` - The item type. Always `program`. + The ID of the pending safety check. - - `"program"` + - `code: Optional[str]` - - `agent: Optional[ProgramAgent]` + The type of the pending safety check. + + - `message: Optional[str]` + + Details about the pending safety check. + + - `agent: Optional[ComputerCallOutputAgent]` The agent that produced this item. @@ -141635,1829 +153245,1755 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ProgramOutput: …` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `id: str` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The unique ID of this program output item. + - `"in_progress"` - - `call_id: str` + - `"completed"` - The call ID of the program item. + - `"incomplete"` - - `result: str` + - `class BetaResponseFunctionWebSearch: …` - The result produced by the program item. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `status: Literal["completed", "incomplete"]` + - `id: str` - The terminal status of the program output. + The unique ID of the web search tool call. - - `"completed"` + - `action: Action` - - `"incomplete"` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `type: Literal["program_output"]` + - `class ActionSearch: …` - The item type. Always `program_output`. + Action type "search" - Performs a web search query. - - `"program_output"` + - `type: Literal["search"]` - - `agent: Optional[ProgramOutputAgent]` + The action type. - The agent that produced this item. + - `"search"` - - `agent_name: str` + - `queries: Optional[List[str]]` - The canonical name of the agent that produced this item. + The search queries. - - `instructions: Optional[str]` + - `query: Optional[str]` - A system (or developer) message inserted into the model's context. + The search query. - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `sources: Optional[List[ActionSearchSource]]` - - `max_output_tokens: Optional[int]` + The sources used in the search. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `type: Literal["url"]` - - `max_tool_calls: Optional[int]` + The type of source. Always `url`. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `"url"` - - `metadata: Optional[Dict[str, str]]` + - `url: str` - 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. + The URL of the source. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `class ActionOpenPage: …` - - `model: Optional[Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str, null]]` + Action type "open_page" - Opens a specific URL from search results. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `type: Literal["open_page"]` - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` + The action type. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `"open_page"` - - `"gpt-5.6-sol"` + - `url: Optional[str]` - - `"gpt-5.6-terra"` + The URL opened by the model. - - `"gpt-5.6-luna"` + - `class ActionFindInPage: …` - - `"gpt-5.4"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"gpt-5.4-mini"` + - `pattern: str` - - `"gpt-5.4-nano"` + The pattern or text to search for within the page. - - `"gpt-5.4-mini-2026-03-17"` + - `type: Literal["find_in_page"]` - - `"gpt-5.4-nano-2026-03-17"` + The action type. - - `"gpt-5.3-chat-latest"` + - `"find_in_page"` - - `"gpt-5.2"` + - `url: str` - - `"gpt-5.2-2025-12-11"` + The URL of the page searched for the pattern. - - `"gpt-5.2-chat-latest"` + - `status: Literal["in_progress", "searching", "completed", "failed"]` - - `"gpt-5.2-pro"` + The status of the web search tool call. - - `"gpt-5.2-pro-2025-12-11"` + - `"in_progress"` - - `"gpt-5.1"` + - `"searching"` - - `"gpt-5.1-2025-11-13"` + - `"completed"` - - `"gpt-5.1-codex"` + - `"failed"` - - `"gpt-5.1-mini"` + - `type: Literal["web_search_call"]` - - `"gpt-5.1-chat-latest"` + The type of the web search tool call. Always `web_search_call`. - - `"gpt-5"` + - `"web_search_call"` - - `"gpt-5-mini"` + - `agent: Optional[Agent]` - - `"gpt-5-nano"` + The agent that produced this item. - - `"gpt-5-2025-08-07"` + - `agent_name: str` - - `"gpt-5-mini-2025-08-07"` + The canonical name of the agent that produced this item. - - `"gpt-5-nano-2025-08-07"` + - `class BetaResponseFunctionToolCall: …` - - `"gpt-5-chat-latest"` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `"gpt-4.1"` + - `arguments: str` - - `"gpt-4.1-mini"` + A JSON string of the arguments to pass to the function. - - `"gpt-4.1-nano"` + - `call_id: str` - - `"gpt-4.1-2025-04-14"` + The unique ID of the function tool call generated by the model. - - `"gpt-4.1-mini-2025-04-14"` + - `name: str` - - `"gpt-4.1-nano-2025-04-14"` + The name of the function to run. - - `"o4-mini"` + - `type: Literal["function_call"]` - - `"o4-mini-2025-04-16"` + The type of the function tool call. Always `function_call`. - - `"o3"` + - `"function_call"` - - `"o3-2025-04-16"` + - `id: Optional[str]` - - `"o3-mini"` + The unique ID of the function tool call. - - `"o3-mini-2025-01-31"` + - `agent: Optional[Agent]` - - `"o1"` + The agent that produced this item. - - `"o1-2024-12-17"` + - `agent_name: str` - - `"o1-preview"` + The canonical name of the agent that produced this item. - - `"o1-preview-2024-09-12"` + - `caller: Optional[Caller]` - - `"o1-mini"` + The execution context that produced this tool call. - - `"o1-mini-2024-09-12"` + - `class CallerDirect: …` - - `"gpt-4o"` + - `type: Literal["direct"]` - - `"gpt-4o-2024-11-20"` + - `"direct"` - - `"gpt-4o-2024-08-06"` + - `class CallerProgram: …` - - `"gpt-4o-2024-05-13"` + - `caller_id: str` - - `"gpt-4o-audio-preview"` + The call ID of the program item that produced this tool call. - - `"gpt-4o-audio-preview-2024-10-01"` + - `type: Literal["program"]` - - `"gpt-4o-audio-preview-2024-12-17"` + - `"program"` - - `"gpt-4o-audio-preview-2025-06-03"` + - `namespace: Optional[str]` - - `"gpt-4o-mini-audio-preview"` + The namespace of the function to run. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"gpt-4o-search-preview"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"gpt-4o-mini-search-preview"` + - `"in_progress"` - - `"gpt-4o-search-preview-2025-03-11"` + - `"completed"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `"incomplete"` - - `"chatgpt-4o-latest"` + - `class FunctionCallOutput: …` - - `"codex-mini-latest"` + The output of a function tool call. - - `"gpt-4o-mini"` + - `call_id: str` - - `"gpt-4o-mini-2024-07-18"` + The unique ID of the function tool call generated by the model. - - `"gpt-4-turbo"` + - `output: Union[str, BetaResponseFunctionCallOutputItemList]` - - `"gpt-4-turbo-2024-04-09"` + Text, image, or file output of the function tool call. - - `"gpt-4-0125-preview"` + - `str` - - `"gpt-4-turbo-preview"` + A JSON string of the output of the function tool call. - - `"gpt-4-1106-preview"` + - `List[BetaResponseFunctionCallOutputItem]` - - `"gpt-4-vision-preview"` + - `class BetaResponseInputTextContent: …` - - `"gpt-4"` + A text input to the model. - - `"gpt-4-0314"` + - `text: str` - - `"gpt-4-0613"` + The text input to the model. - - `"gpt-4-32k"` + - `type: Literal["input_text"]` - - `"gpt-4-32k-0314"` + The type of the input item. Always `input_text`. - - `"gpt-4-32k-0613"` + - `"input_text"` - - `"gpt-3.5-turbo"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `"gpt-3.5-turbo-16k"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"gpt-3.5-turbo-0301"` + - `mode: Literal["explicit"]` - - `"gpt-3.5-turbo-0613"` + The breakpoint mode. Always `explicit`. - - `"gpt-3.5-turbo-1106"` + - `"explicit"` - - `"gpt-3.5-turbo-0125"` + - `class BetaResponseInputImageContent: …` - - `"gpt-3.5-turbo-16k-0613"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `"o1-pro"` + - `type: Literal["input_image"]` - - `"o1-pro-2025-03-19"` + The type of the input item. Always `input_image`. - - `"o3-pro"` + - `"input_image"` - - `"o3-pro-2025-06-10"` + - `detail: Optional[Literal["low", "high", "auto", "original"]]` - - `"o3-deep-research"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"o3-deep-research-2025-06-26"` + - `"low"` - - `"o4-mini-deep-research"` + - `"high"` - - `"o4-mini-deep-research-2025-06-26"` + - `"auto"` - - `"computer-use-preview"` + - `"original"` - - `"computer-use-preview-2025-03-11"` + - `file_id: Optional[str]` - - `"gpt-5-codex"` + The ID of the file to be sent to the model. - - `"gpt-5-pro"` + - `image_url: Optional[str]` - - `"gpt-5-pro-2025-10-06"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"gpt-5.1-codex-max"` + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `str` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `moderation: Optional[ResponseCreateModeration]` + - `mode: Literal["explicit"]` - Configuration for running moderation on the input and output of this response. + The breakpoint mode. Always `explicit`. - - `model: str` + - `"explicit"` - The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + - `class BetaResponseInputFileContent: …` - - `policy: Optional[ResponseCreateModerationPolicy]` + A file input to the model. - The policy to apply to moderated response input and output. + - `type: Literal["input_file"]` - - `input: Optional[ResponseCreateModerationPolicyInput]` + The type of the input item. Always `input_file`. - The moderation policy for the response input. + - `"input_file"` - - `mode: Literal["score", "block"]` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"score"` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `"block"` + - `"auto"` - - `output: Optional[ResponseCreateModerationPolicyOutput]` + - `"low"` - The moderation policy for the response output. + - `"high"` - - `mode: Literal["score", "block"]` + - `file_data: Optional[str]` - - `"score"` + The base64-encoded data of the file to be sent to the model. - - `"block"` + - `file_id: Optional[str]` - - `multi_agent: Optional[ResponseCreateMultiAgent]` + The ID of the file to be sent to the model. - Configuration for server-hosted multi-agent execution. + - `file_url: Optional[str]` - - `enabled: bool` + The URL of the file to be sent to the model. - Whether to enable server-hosted multi-agent execution for this response. + - `filename: Optional[str]` - - `max_concurrent_subagents: Optional[int]` + The name of the file to be sent to the model. - `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. - The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. + - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` - - `parallel_tool_calls: Optional[bool]` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Whether to allow the model to run tool calls in parallel. + - `mode: Literal["explicit"]` - - `previous_response_id: Optional[str]` + The breakpoint mode. Always `explicit`. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `"explicit"` - - `prompt: Optional[BetaResponsePrompt]` + - `type: Literal["function_call_output"]` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The type of the function tool call output. Always `function_call_output`. - - `id: str` + - `"function_call_output"` - The unique identifier of the prompt template to use. + - `id: Optional[str]` - - `variables: Optional[Dict[str, Variables]]` + The unique ID of the function tool call output. Populated when this item is returned via API. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `agent: Optional[FunctionCallOutputAgent]` - - `str` + The agent that produced this item. - - `class BetaResponseInputText: …` + - `agent_name: str` - A text input to the model. + The canonical name of the agent that produced this item. - - `class BetaResponseInputImage: …` + - `caller: Optional[FunctionCallOutputCaller]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The execution context that produced this tool call. - - `class BetaResponseInputFile: …` + - `class FunctionCallOutputCallerDirect: …` - A file input to the model. + - `type: Literal["direct"]` - - `version: Optional[str]` + The caller type. Always `direct`. - Optional version of the prompt template. + - `"direct"` - - `prompt_cache_key: Optional[str]` + - `class FunctionCallOutputCallerProgram: …` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `caller_id: str` - - `prompt_cache_options: Optional[ResponseCreatePromptCacheOptions]` + The call ID of the program item that produced this tool call. - Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. + - `type: Literal["program"]` - - `mode: Optional[Literal["implicit", "explicit"]]` + The caller type. Always `program`. - Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + - `"program"` - - `"implicit"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"explicit"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `ttl: Optional[Literal["30m"]]` + - `"in_progress"` - The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + - `"completed"` - - `"30m"` + - `"incomplete"` - - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + - `class AgentMessage: …` - Deprecated. Use `prompt_cache_options.ttl` instead. + A message routed between agents. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `author: str` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The sending agent identity. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `content: List[AgentMessageContent]` - - `"in_memory"` + Plaintext, image, or encrypted content sent between agents. - - `"24h"` + - `class BetaResponseInputTextContent: …` - - `reasoning: Optional[ResponseCreateReasoning]` + A text input to the model. - **gpt-5 and o-series models only** + - `class BetaResponseInputImageContent: …` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + - `class AgentMessageContentEncryptedContent: …` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"auto"` + - `encrypted_content: str` - - `"current_turn"` + Opaque encrypted content. - - `"all_turns"` + - `type: Literal["encrypted_content"]` - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + The type of the input item. Always `encrypted_content`. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `"encrypted_content"` - - `"none"` + - `recipient: str` - - `"minimal"` + The destination agent identity. - - `"low"` + - `type: Literal["agent_message"]` - - `"medium"` + The item type. Always `agent_message`. - - `"high"` + - `"agent_message"` - - `"xhigh"` + - `id: Optional[str]` - - `"max"` + The unique ID of this agent message item. - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + - `agent: Optional[AgentMessageAgent]` - **Deprecated:** use `summary` instead. + The agent that produced this item. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `agent_name: str` - - `"auto"` + The canonical name of the agent that produced this item. - - `"concise"` + - `class MultiAgentCall: …` - - `"detailed"` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + The multi-agent action that was executed. - Controls the reasoning execution mode for the request. + - `"spawn_agent"` - When returned on a response, this is the effective execution mode. + - `"interrupt_agent"` - - `str` + - `"list_agents"` - - `Literal["standard", "pro"]` + - `"send_message"` - Controls the reasoning execution mode for the request. + - `"followup_task"` - When returned on a response, this is the effective execution mode. + - `"wait_agent"` - - `"standard"` + - `arguments: str` - - `"pro"` + The action arguments as a JSON string. - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + - `call_id: str` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The unique ID linking this call to its output. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `type: Literal["multi_agent_call"]` - - `"auto"` + The item type. Always `multi_agent_call`. - - `"concise"` + - `"multi_agent_call"` - - `"detailed"` + - `id: Optional[str]` - - `safety_identifier: Optional[str]` + The unique ID of this multi-agent call. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `agent: Optional[MultiAgentCallAgent]` - - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + The agent that produced this item. - Specifies the processing type used for serving the request. + - `agent_name: str` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The canonical name of the agent that produced this item. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `class MultiAgentCallOutput: …` - - `"auto"` + - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - `"default"` + The multi-agent action that produced this result. - - `"flex"` + - `"spawn_agent"` - - `"scale"` + - `"interrupt_agent"` - - `"priority"` + - `"list_agents"` - - `store: Optional[bool]` + - `"send_message"` - Whether to store the generated model response for later retrieval via - API. + - `"followup_task"` - - `stream: Optional[bool]` + - `"wait_agent"` - If set to true, the model response data will be streamed to the client - as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). - See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) - for more information. + - `call_id: str` - - `stream_options: Optional[ResponseCreateStreamOptions]` + The unique ID of the multi-agent call. - Options for streaming responses. Only set this when you set `stream: true`. + - `output: List[MultiAgentCallOutputOutput]` - - `include_obfuscation: Optional[bool]` + Text output returned by the multi-agent action. - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events to - normalize payload sizes as a mitigation to certain side-channel attacks. - These obfuscation fields are included by default, but add a small amount - of overhead to the data stream. You can set `include_obfuscation` to - false to optimize for bandwidth if you trust the network links between - your application and the OpenAI API. + - `text: str` - - `temperature: Optional[float]` + The text content. - 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. - We generally recommend altering this or `top_p` but not both. + - `type: Literal["output_text"]` - - `text: Optional[BetaResponseTextConfig]` + The content type. Always `output_text`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `"output_text"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - - `format: Optional[BetaResponseFormatTextConfig]` + Citations associated with the text content. - An object specifying the format that the model must output. + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` - Configuring `{ "type": "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). + - `file_id: str` - The default format is `{ "type": "text" }` with no additional options. + The ID of the file. - **Not recommended for gpt-4o and newer models:** + - `filename: str` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The filename of the file cited. - - `class Text: …` + - `index: int` - Default response format. Used to generate text responses. + The index of the file in the list of files. - - `type: Literal["text"]` + - `type: Literal["file_citation"]` - The type of response format being defined. Always `text`. + The citation type. Always `file_citation`. - - `"text"` + - `"file_citation"` - - `class BetaResponseFormatTextJSONSchemaConfig: …` + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `end_index: int` - - `name: str` + The index of the last character of the citation in the message. - 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. + - `start_index: int` - - `schema: Dict[str, object]` + The index of the first character of the citation in the message. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `title: str` - - `type: Literal["json_schema"]` + The title of the cited resource. - The type of response format being defined. Always `json_schema`. + - `type: Literal["url_citation"]` - - `"json_schema"` + The citation type. Always `url_citation`. - - `description: Optional[str]` + - `"url_citation"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `url: str` - - `strict: Optional[bool]` + The URL of the cited resource. - 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). + - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` - - `class JSONObject: …` + - `container_id: str` - 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. + The ID of the container. - - `type: Literal["json_object"]` + - `end_index: int` - The type of response format being defined. Always `json_object`. + The index of the last character of the citation in the message. - - `"json_object"` + - `file_id: str` - - `verbosity: Optional[Literal["low", "medium", "high"]]` + The ID of the container file. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `filename: str` - - `"low"` + The filename of the container file cited. - - `"medium"` + - `start_index: int` - - `"high"` + The index of the first character of the citation in the message. - - `tool_choice: Optional[ResponseCreateToolChoice]` + - `type: Literal["container_file_citation"]` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + The citation type. Always `container_file_citation`. - - `Literal["none", "auto", "required"]` + - `"container_file_citation"` - - `"none"` + - `type: Literal["multi_agent_call_output"]` - - `"auto"` + The item type. Always `multi_agent_call_output`. - - `"required"` + - `"multi_agent_call_output"` - - `class BetaToolChoiceAllowed: …` + - `id: Optional[str]` - Constrains the tools available to the model to a pre-defined set. + The unique ID of this multi-agent call output. - - `mode: Literal["auto", "required"]` + - `agent: Optional[MultiAgentCallOutputAgent]` - Constrains the tools available to the model to a pre-defined set. + The agent that produced this item. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `agent_name: str` - `required` requires the model to call one or more of the allowed tools. + The canonical name of the agent that produced this item. - - `"auto"` + - `class ToolSearchCall: …` - - `"required"` + - `arguments: object` - - `tools: List[Dict[str, object]]` + The arguments supplied to the tool search call. - A list of tool definitions that the model should be allowed to call. + - `type: Literal["tool_search_call"]` - For the Responses API, the list of tool definitions might look like: + The item type. Always `tool_search_call`. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `"tool_search_call"` - - `type: Literal["allowed_tools"]` + - `id: Optional[str]` - Allowed tool configuration type. Always `allowed_tools`. + The unique ID of this tool search call. - - `"allowed_tools"` + - `agent: Optional[ToolSearchCallAgent]` - - `class BetaToolChoiceTypes: …` + The agent that produced this item. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `agent_name: str` - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + The canonical name of the agent that produced this item. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `call_id: Optional[str]` - Allowed values are: + The unique ID of the tool search call generated by the model. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `execution: Optional[Literal["server", "client"]]` + + Whether tool search was executed by the server or by the client. + + - `"server"` - - `"file_search"` + - `"client"` - - `"web_search_preview"` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - `"computer"` + The status of the tool search call. - - `"computer_use_preview"` + - `"in_progress"` - - `"computer_use"` + - `"completed"` - - `"web_search_preview_2025_03_11"` + - `"incomplete"` - - `"image_generation"` + - `class BetaResponseToolSearchOutputItemParam: …` - - `"code_interpreter"` + - `tools: List[BetaTool]` - - `class BetaToolChoiceFunction: …` + The loaded tool definitions returned by the tool search output. - Use this option to force the model to call a specific function. + - `class BetaFunctionTool: …` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `name: str` The name of the function to call. + - `parameters: Optional[Dict[str, object]]` + + A JSON schema object describing the parameters of the function. + + - `strict: Optional[bool]` + + Whether strict parameter validation is enforced for this function tool. + - `type: Literal["function"]` - For function calling, the type is always `function`. + The type of the function tool. Always `function`. - `"function"` - - `class BetaToolChoiceMcp: …` - - Use this option to force the model to call a specific tool on a remote MCP server. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `server_label: str` + The tool invocation context(s). - The label of the MCP server to use. + - `"direct"` - - `type: Literal["mcp"]` + - `"programmatic"` - For MCP tools, the type is always `mcp`. + - `defer_loading: Optional[bool]` - - `"mcp"` + Whether this function is deferred and loaded via tool search. - - `name: Optional[str]` + - `description: Optional[str]` - The name of the tool to call on the server. + A description of the function. Used by the model to determine whether or not to call the function. - - `class BetaToolChoiceCustom: …` + - `output_schema: Optional[Dict[str, object]]` - Use this option to force the model to call a specific custom tool. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `name: str` + - `class BetaFileSearchTool: …` - The name of the custom tool to call. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: Literal["custom"]` + - `type: Literal["file_search"]` - For custom tool calling, the type is always `custom`. + The type of the file search tool. Always `file_search`. - - `"custom"` + - `"file_search"` - - `class ResponseCreateToolChoiceBetaSpecificProgrammaticToolCallingParam: …` + - `vector_store_ids: List[str]` - - `type: Literal["programmatic_tool_calling"]` + The IDs of the vector stores to search. - The tool to call. Always `programmatic_tool_calling`. + - `filters: Optional[Filters]` - - `"programmatic_tool_calling"` + A filter to apply. - - `class BetaToolChoiceApplyPatch: …` + - `class FiltersComparisonFilter: …` - Forces the model to call the apply_patch tool when executing a tool call. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: Literal["apply_patch"]` + - `key: str` - The tool to call. Always `apply_patch`. + The key to compare against the value. - - `"apply_patch"` + - `type: Literal["eq", "ne", "gt", 5 more]` - - `class BetaToolChoiceShell: …` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Forces the model to call the shell tool when a tool call is required. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `type: Literal["shell"]` + - `"eq"` - The tool to call. Always `shell`. + - `"ne"` - - `"shell"` + - `"gt"` - - `tools: Optional[List[BetaTool]]` + - `"gte"` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `"lt"` - We support the following categories of tools: + - `"lte"` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `"in"` - - `class BetaFunctionTool: …` + - `"nin"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `class BetaFileSearchTool: …` + The value to compare against the attribute key; supports string, number, or boolean types. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `str` - - `class BetaComputerTool: …` + - `float` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `bool` - - `class BetaComputerUsePreviewTool: …` + - `List[Union[str, float]]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `str` - - `class BetaWebSearchTool: …` + - `float` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class FiltersCompoundFilter: …` - - `class Mcp: …` + Combine multiple filters using `and` or `or`. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `filters: List[FiltersCompoundFilterFilter]` - - `class CodeInterpreter: …` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - A tool that runs Python code to help generate a response to a prompt. + - `class FiltersCompoundFilterFilterComparisonFilter: …` - - `class ProgrammaticToolCalling: …` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `class ImageGeneration: …` + - `key: str` - A tool that generates images using the GPT image models. + The key to compare against the value. - - `class LocalShell: …` + - `type: Literal["eq", "ne", "gt", 5 more]` - A tool that allows the model to execute shell commands in a local environment. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `class BetaFunctionShellTool: …` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - A tool that allows the model to execute shell commands. + - `"eq"` - - `class BetaCustomTool: …` + - `"ne"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"gt"` - - `class BetaNamespaceTool: …` + - `"gte"` - Groups function/custom tools under a shared namespace. + - `"lt"` - - `class BetaToolSearchTool: …` + - `"lte"` - Hosted or BYOT tool search configuration for deferred tools. + - `"in"` - - `class BetaWebSearchPreviewTool: …` + - `"nin"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `value: Union[str, float, bool, List[Union[str, float]]]` - - `class BetaApplyPatchTool: …` + The value to compare against the attribute key; supports string, number, or boolean types. - Allows the assistant to create, delete, or update files using unified diffs. + - `str` - - `top_logprobs: Optional[int]` + - `float` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `bool` - - `top_p: Optional[float]` + - `List[Union[str, 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. + - `str` - We generally recommend altering this or `temperature` but not both. + - `float` - - `truncation: Optional[Literal["auto", "disabled"]]` + - `object` - The truncation strategy to use for the model response. + - `type: Literal["and", "or"]` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + Type of operation: `and` or `or`. - - `"auto"` + - `"and"` - - `"disabled"` + - `"or"` - - `user: Optional[str]` + - `max_num_results: Optional[int]` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `class ResponseInject: …` + - `ranking_options: Optional[RankingOptions]` - Injects input items into an active response over a WebSocket connection. - The items are validated and committed atomically. Currently, the server - accepts client-owned tool outputs that resume a waiting agent. + Ranking options for search. - - `input: List[BetaResponseInputItem]` + - `hybrid_search: Optional[RankingOptionsHybridSearch]` - Input items to inject into the active response. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `class BetaEasyInputMessage: …` + - `embedding_weight: float` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The weight of the embedding in the reciprocal ranking fusion. - - `class Message: …` + - `text_weight: float` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + The weight of the text in the reciprocal ranking fusion. - - `class BetaResponseOutputMessage: …` + - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` - An output message from the model. + The ranker to use for the file search. - - `class BetaResponseFileSearchToolCall: …` + - `"auto"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `"default-2024-11-15"` - - `class BetaResponseComputerToolCall: …` + - `score_threshold: Optional[float]` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `class ComputerCallOutput: …` + - `class BetaComputerTool: …` - The output of a computer tool call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class BetaResponseFunctionWebSearch: …` + - `type: Literal["computer"]` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The type of the computer tool. Always `computer`. - - `class BetaResponseFunctionToolCall: …` + - `"computer"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `class BetaComputerUsePreviewTool: …` - - `class FunctionCallOutput: …` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The output of a function tool call. + - `display_height: int` - - `class AgentMessage: …` + The height of the computer display. - A message routed between agents. + - `display_width: int` - - `class MultiAgentCall: …` + The width of the computer display. - - `class MultiAgentCallOutput: …` + - `environment: Literal["windows", "mac", "linux", 2 more]` - - `class ToolSearchCall: …` + The type of computer environment to control. - - `class BetaResponseToolSearchOutputItemParam: …` + - `"windows"` - - `class AdditionalTools: …` + - `"mac"` - - `class BetaResponseReasoningItem: …` + - `"linux"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `"ubuntu"` - - `class BetaResponseCompactionItemParam: …` + - `"browser"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `type: Literal["computer_use_preview"]` - - `class ImageGenerationCall: …` + The type of the computer use tool. Always `computer_use_preview`. - An image generation request made by the model. + - `"computer_use_preview"` - - `class BetaResponseCodeInterpreterToolCall: …` + - `class BetaWebSearchTool: …` - A tool call to run code. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class LocalShellCall: …` + - `type: Literal["web_search", "web_search_2025_08_26"]` - A tool call to run a command on the local shell. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `class LocalShellCallOutput: …` + - `"web_search"` - The output of a local shell tool call. + - `"web_search_2025_08_26"` - - `class ShellCall: …` + - `filters: Optional[Filters]` - A tool representing a request to execute one or more shell commands. + Filters for the search. - - `class ShellCallOutput: …` + - `allowed_domains: Optional[List[str]]` - The streamed output items emitted by a shell tool call. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `class ApplyPatchCall: …` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - A tool call representing a request to create, delete, or update files using diff patches. + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `class ApplyPatchCallOutput: …` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The streamed output emitted by an apply patch tool call. + - `"low"` - - `class McpListTools: …` + - `"medium"` - A list of tools available on an MCP server. + - `"high"` - - `class McpApprovalRequest: …` + - `user_location: Optional[UserLocation]` - A request for human approval of a tool invocation. + The approximate location of the user. - - `class McpApprovalResponse: …` + - `city: Optional[str]` - A response to an MCP approval request. + Free text input for the city of the user, e.g. `San Francisco`. - - `class McpCall: …` + - `country: Optional[str]` - An invocation of a tool on an MCP server. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `class BetaResponseCustomToolCallOutput: …` + - `region: Optional[str]` - The output of a custom tool call from your code, being sent back to the model. + Free text input for the region of the user, e.g. `California`. - - `class BetaResponseCustomToolCall: …` + - `timezone: Optional[str]` - A call to a custom tool created by the model. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `class CompactionTrigger: …` + - `type: Optional[Literal["approximate"]]` - Compacts the current context. Must be the final input item. + The type of location approximation. Always `approximate`. - - `class ItemReference: …` + - `"approximate"` - An internal identifier for an item to reference. + - `class Mcp: …` - - `class Program: …` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `class ProgramOutput: …` + - `server_label: str` - - `response_id: str` + A label for this MCP server, used to identify it in tool calls. - The ID of the active response that should receive the input. + - `type: Literal["mcp"]` - - `type: Literal["response.inject"]` + The type of the MCP tool. Always `mcp`. - The event discriminator. Always `response.inject`. + - `"mcp"` - - `"response.inject"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` -### Beta Responses Server Event + The tool invocation context(s). -- `BetaResponsesServerEvent` + - `"direct"` - Server events emitted by the Responses WebSocket server. + - `"programmatic"` - - `class BetaResponseAudioDeltaEvent: …` + - `allowed_tools: Optional[McpAllowedTools]` - Emitted when there is a partial audio response. + List of allowed tool names or a filter object. - - `delta: str` + - `List[str]` - A chunk of Base64 encoded response audio bytes. + A string array of allowed tool names - - `sequence_number: int` + - `class McpAllowedToolsMcpToolFilter: …` - A sequence number for this chunk of the stream response. + A filter object to specify which tools are allowed. - - `type: Literal["response.audio.delta"]` + - `read_only: Optional[bool]` - The type of the event. Always `response.audio.delta`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"response.audio.delta"` + - `tool_names: Optional[List[str]]` - - `agent: Optional[Agent]` + List of allowed tool names. - The agent that owns this multi-agent streaming event. + - `authorization: Optional[str]` - - `agent_name: str` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The canonical name of the agent that produced this item. + - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` - - `class BetaResponseAudioDoneEvent: …` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - Emitted when the audio response is complete. + Currently supported `connector_id` values are: - - `sequence_number: int` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The sequence number of the delta. + - `"connector_dropbox"` - - `type: Literal["response.audio.done"]` + - `"connector_gmail"` - The type of the event. Always `response.audio.done`. + - `"connector_googlecalendar"` - - `"response.audio.done"` + - `"connector_googledrive"` - - `agent: Optional[Agent]` + - `"connector_microsoftteams"` - The agent that owns this multi-agent streaming event. + - `"connector_outlookcalendar"` - - `agent_name: str` + - `"connector_outlookemail"` - The canonical name of the agent that produced this item. + - `"connector_sharepoint"` - - `class BetaResponseAudioTranscriptDeltaEvent: …` + - `defer_loading: Optional[bool]` - Emitted when there is a partial transcript of audio. + Whether this MCP tool is deferred and discovered via tool search. - - `delta: str` + - `headers: Optional[Dict[str, str]]` - The partial transcript of the audio response. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `sequence_number: int` + - `require_approval: Optional[McpRequireApproval]` - The sequence number of this event. + Specify which of the MCP server's tools require approval. - - `type: Literal["response.audio.transcript.delta"]` + - `class McpRequireApprovalMcpToolApprovalFilter: …` - The type of the event. Always `response.audio.transcript.delta`. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"response.audio.transcript.delta"` + - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` - - `agent: Optional[Agent]` + A filter object to specify which tools are allowed. - The agent that owns this multi-agent streaming event. + - `read_only: Optional[bool]` - - `agent_name: str` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The canonical name of the agent that produced this item. + - `tool_names: Optional[List[str]]` - - `class BetaResponseAudioTranscriptDoneEvent: …` + List of allowed tool names. - Emitted when the full audio transcript is completed. + - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` - - `sequence_number: int` + A filter object to specify which tools are allowed. - The sequence number of this event. + - `read_only: Optional[bool]` - - `type: Literal["response.audio.transcript.done"]` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The type of the event. Always `response.audio.transcript.done`. + - `tool_names: Optional[List[str]]` - - `"response.audio.transcript.done"` + List of allowed tool names. - - `agent: Optional[Agent]` + - `Literal["always", "never"]` - The agent that owns this multi-agent streaming event. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `agent_name: str` + - `"always"` - The canonical name of the agent that produced this item. + - `"never"` - - `class BetaResponseCodeInterpreterCallCodeDeltaEvent: …` + - `server_description: Optional[str]` - Emitted when a partial code snippet is streamed by the code interpreter. + Optional description of the MCP server, used to provide more context. - - `delta: str` + - `server_url: Optional[str]` - The partial code snippet being streamed by the code interpreter. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `item_id: str` + - `tunnel_id: Optional[str]` - The unique identifier of the code interpreter tool call item. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `output_index: int` + - `class CodeInterpreter: …` - The index of the output item in the response for which the code is being streamed. + A tool that runs Python code to help generate a response to a prompt. - - `sequence_number: int` + - `container: CodeInterpreterContainer` - The sequence number of this event, used to order streaming events. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `type: Literal["response.code_interpreter_call_code.delta"]` + - `str` - The type of the event. Always `response.code_interpreter_call_code.delta`. + The container ID. - - `"response.code_interpreter_call_code.delta"` + - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` - - `agent: Optional[Agent]` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The agent that owns this multi-agent streaming event. + - `type: Literal["auto"]` - - `agent_name: str` + Always `auto`. - The canonical name of the agent that produced this item. + - `"auto"` - - `class BetaResponseCodeInterpreterCallCodeDoneEvent: …` + - `file_ids: Optional[List[str]]` - Emitted when the code snippet is finalized by the code interpreter. + An optional list of uploaded files to make available to your code. - - `code: str` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - The final code snippet output by the code interpreter. + The memory limit for the code interpreter container. - - `item_id: str` + - `"1g"` - The unique identifier of the code interpreter tool call item. + - `"4g"` - - `output_index: int` + - `"16g"` - The index of the output item in the response for which the code is finalized. + - `"64g"` - - `sequence_number: int` + - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` - The sequence number of this event, used to order streaming events. + Network access policy for the container. - - `type: Literal["response.code_interpreter_call_code.done"]` + - `class BetaContainerNetworkPolicyDisabled: …` - The type of the event. Always `response.code_interpreter_call_code.done`. + - `type: Literal["disabled"]` - - `"response.code_interpreter_call_code.done"` + Disable outbound network access. Always `disabled`. - - `agent: Optional[Agent]` + - `"disabled"` - The agent that owns this multi-agent streaming event. + - `class BetaContainerNetworkPolicyAllowlist: …` - - `agent_name: str` + - `allowed_domains: List[str]` - The canonical name of the agent that produced this item. + A list of allowed domains when type is `allowlist`. - - `class BetaResponseCodeInterpreterCallCompletedEvent: …` + - `type: Literal["allowlist"]` - Emitted when the code interpreter call is completed. + Allow outbound network access only to specified domains. Always `allowlist`. - - `item_id: str` + - `"allowlist"` - The unique identifier of the code interpreter tool call item. + - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` - - `output_index: int` + Optional domain-scoped secrets for allowlisted domains. - The index of the output item in the response for which the code interpreter call is completed. + - `domain: str` - - `sequence_number: int` + The domain associated with the secret. - The sequence number of this event, used to order streaming events. + - `name: str` - - `type: Literal["response.code_interpreter_call.completed"]` + The name of the secret to inject for the domain. - The type of the event. Always `response.code_interpreter_call.completed`. + - `value: str` - - `"response.code_interpreter_call.completed"` + The secret value to inject for the domain. - - `agent: Optional[Agent]` + - `type: Literal["code_interpreter"]` - The agent that owns this multi-agent streaming event. + The type of the code interpreter tool. Always `code_interpreter`. - - `agent_name: str` + - `"code_interpreter"` - The canonical name of the agent that produced this item. + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `class BetaResponseCodeInterpreterCallInProgressEvent: …` + The tool invocation context(s). - Emitted when a code interpreter call is in progress. + - `"direct"` - - `item_id: str` + - `"programmatic"` - The unique identifier of the code interpreter tool call item. + - `class ProgrammaticToolCalling: …` - - `output_index: int` + - `type: Literal["programmatic_tool_calling"]` - The index of the output item in the response for which the code interpreter call is in progress. + The type of the tool. Always `programmatic_tool_calling`. - - `sequence_number: int` + - `"programmatic_tool_calling"` - The sequence number of this event, used to order streaming events. + - `class ImageGeneration: …` - - `type: Literal["response.code_interpreter_call.in_progress"]` + A tool that generates images using the GPT image models. - The type of the event. Always `response.code_interpreter_call.in_progress`. + - `type: Literal["image_generation"]` - - `"response.code_interpreter_call.in_progress"` + The type of the image generation tool. Always `image_generation`. - - `agent: Optional[Agent]` + - `"image_generation"` - The agent that owns this multi-agent streaming event. + - `action: Optional[Literal["generate", "edit", "auto"]]` - - `agent_name: str` + Whether to generate a new image or edit an existing image. Default: `auto`. - The canonical name of the agent that produced this item. + - `"generate"` - - `class BetaResponseCodeInterpreterCallInterpretingEvent: …` + - `"edit"` - Emitted when the code interpreter is actively interpreting the code snippet. + - `"auto"` - - `item_id: str` + - `background: Optional[Literal["transparent", "opaque", "auto"]]` - The unique identifier of the code interpreter tool call item. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `output_index: int` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - The index of the output item in the response for which the code interpreter is interpreting code. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `sequence_number: int` + - `"transparent"` - The sequence number of this event, used to order streaming events. + - `"opaque"` - - `type: Literal["response.code_interpreter_call.interpreting"]` + - `"auto"` - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `input_fidelity: Optional[Literal["high", "low"]]` - - `"response.code_interpreter_call.interpreting"` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `agent: Optional[Agent]` + - `"high"` - The agent that owns this multi-agent streaming event. + - `"low"` - - `agent_name: str` + - `input_image_mask: Optional[ImageGenerationInputImageMask]` - The canonical name of the agent that produced this item. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `class BetaResponseCompletedEvent: …` + - `file_id: Optional[str]` - Emitted when the model response is complete. + File ID for the mask image. - - `response: BetaResponse` + - `image_url: Optional[str]` - Properties of the completed response. + Base64-encoded mask image. - - `id: str` + - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` - Unique identifier for this Response. + The image generation model to use. Default: `gpt-image-1`. - - `created_at: float` + - `str` - Unix timestamp (in seconds) of when this Response was created. + - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` - - `error: Optional[BetaResponseError]` + The image generation model to use. Default: `gpt-image-1`. - An error object returned when the model fails to generate a Response. + - `"gpt-image-1"` - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt", 16 more]` + - `"gpt-image-1-mini"` - The error code for the response. + - `"gpt-image-2"` - - `"server_error"` + - `"gpt-image-2-2026-04-21"` - - `"rate_limit_exceeded"` + - `"gpt-image-1.5"` - - `"invalid_prompt"` + - `"chatgpt-image-latest"` - - `"bio_policy"` + - `moderation: Optional[Literal["auto", "low"]]` - - `"vector_store_timeout"` + Moderation level for the generated image. Default: `auto`. - - `"invalid_image"` + - `"auto"` - - `"invalid_image_format"` + - `"low"` - - `"invalid_base64_image"` + - `output_compression: Optional[int]` - - `"invalid_image_url"` + Compression level for the output image. Default: 100. - - `"image_too_large"` + - `output_format: Optional[Literal["png", "webp", "jpeg"]]` - - `"image_too_small"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"image_parse_error"` + - `"png"` - - `"image_content_policy_violation"` + - `"webp"` - - `"invalid_image_mode"` + - `"jpeg"` - - `"image_file_too_large"` + - `partial_images: Optional[int]` - - `"unsupported_image_media_type"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"empty_image_file"` + - `quality: Optional[Literal["low", "medium", "high", "auto"]]` - - `"failed_to_download_image"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"image_file_not_found"` + - `"low"` - - `message: str` + - `"medium"` - A human-readable description of the error. + - `"high"` - - `incomplete_details: Optional[IncompleteDetails]` + - `"auto"` - Details about why the response is incomplete. + - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` - - `reason: Optional[Literal["max_output_tokens", "content_filter"]]` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The reason why the response is incomplete. + - `str` - - `"max_output_tokens"` + - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` - - `"content_filter"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `instructions: Union[str, List[BetaResponseInputItem], null]` + - `"1024x1024"` - A system (or developer) message inserted into the model's context. + - `"1024x1536"` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `"1536x1024"` - - `str` + - `"auto"` - A text input to the model, equivalent to a text input with the - `developer` role. + - `class LocalShell: …` - - `List[BetaResponseInputItem]` + A tool that allows the model to execute shell commands in a local environment. - A list of one or many input items to the model, containing - different content types. + - `type: Literal["local_shell"]` - - `class BetaEasyInputMessage: …` + The type of the local shell tool. Always `local_shell`. - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `"local_shell"` - - `content: Union[str, BetaResponseInputMessageContentList]` + - `class BetaFunctionShellTool: …` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + A tool that allows the model to execute shell commands. - - `str` + - `type: Literal["shell"]` - A text input to the model. + The type of the shell tool. Always `shell`. - - `List[BetaResponseInputContent]` + - `"shell"` - - `class BetaResponseInputText: …` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - A text input to the model. + The tool invocation context(s). - - `text: str` + - `"direct"` - The text input to the model. + - `"programmatic"` - - `type: Literal["input_text"]` + - `environment: Optional[Environment]` - The type of the input item. Always `input_text`. + - `class BetaContainerAuto: …` - - `"input_text"` + - `type: Literal["container_auto"]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + Automatically creates a container for this request - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"container_auto"` - - `mode: Literal["explicit"]` + - `file_ids: Optional[List[str]]` - The breakpoint mode. Always `explicit`. + An optional list of uploaded files to make available to your code. - - `"explicit"` + - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` - - `class BetaResponseInputImage: …` + The memory limit for the container. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"1g"` - - `detail: Literal["low", "high", "auto", "original"]` + - `"4g"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"16g"` - - `"low"` + - `"64g"` - - `"high"` + - `network_policy: Optional[NetworkPolicy]` - - `"auto"` + Network access policy for the container. - - `"original"` + - `class BetaContainerNetworkPolicyDisabled: …` - - `type: Literal["input_image"]` + - `class BetaContainerNetworkPolicyAllowlist: …` - The type of the input item. Always `input_image`. + - `skills: Optional[List[Skill]]` - - `"input_image"` + An optional list of skills referenced by id or inline data. - - `file_id: Optional[str]` + - `class BetaSkillReference: …` - The ID of the file to be sent to the model. + - `skill_id: str` - - `image_url: Optional[str]` + The ID of the referenced skill. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: Literal["skill_reference"]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + References a skill created with the /v1/skills endpoint. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"skill_reference"` - - `mode: Literal["explicit"]` + - `version: Optional[str]` - The breakpoint mode. Always `explicit`. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `"explicit"` + - `class BetaInlineSkill: …` - - `class BetaResponseInputFile: …` + - `description: str` - A file input to the model. + The description of the skill. - - `type: Literal["input_file"]` + - `name: str` - The type of the input item. Always `input_file`. + The name of the skill. - - `"input_file"` + - `source: BetaInlineSkillSource` - - `detail: Optional[Literal["auto", "low", "high"]]` + Inline skill payload - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `data: str` - - `"auto"` + Base64-encoded skill zip bundle. - - `"low"` + - `media_type: Literal["application/zip"]` - - `"high"` + The media type of the inline skill payload. Must be `application/zip`. - - `file_data: Optional[str]` + - `"application/zip"` - The content of the file to be sent to the model. + - `type: Literal["base64"]` - - `file_id: Optional[str]` + The type of the inline skill source. Must be `base64`. - The ID of the file to be sent to the model. + - `"base64"` - - `file_url: Optional[str]` + - `type: Literal["inline"]` - The URL of the file to be sent to the model. + Defines an inline skill for this request. - - `filename: Optional[str]` + - `"inline"` - The name of the file to be sent to the model. + - `class BetaLocalEnvironment: …` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `type: Literal["local"]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Use a local computer environment. - - `mode: Literal["explicit"]` + - `"local"` - The breakpoint mode. Always `explicit`. + - `skills: Optional[List[BetaLocalSkill]]` - - `"explicit"` + An optional list of skills. - - `role: Literal["user", "assistant", "system", "developer"]` + - `description: str` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The description of the skill. - - `"user"` + - `name: str` - - `"assistant"` + The name of the skill. - - `"system"` + - `path: str` - - `"developer"` + The path to the directory containing the skill. - - `phase: Optional[Literal["commentary"]]` + - `class BetaContainerReference: …` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `container_id: str` - - `"commentary"` + The ID of the referenced container. - - `type: Optional[Literal["message"]]` + - `type: Literal["container_reference"]` - The type of the message input. Always `message`. + References a container created with the /v1/containers endpoint - - `"message"` + - `"container_reference"` - - `class Message: …` + - `class BetaCustomTool: …` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `content: BetaResponseInputMessageContentList` + - `name: str` - A list of one or many input items to the model, containing different content - types. + The name of the custom tool, used to identify it in tool calls. - - `class BetaResponseInputText: …` + - `type: Literal["custom"]` - A text input to the model. + The type of the custom tool. Always `custom`. - - `class BetaResponseInputImage: …` + - `"custom"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `class BetaResponseInputFile: …` + The tool invocation context(s). - A file input to the model. + - `"direct"` - - `role: Literal["user", "system", "developer"]` + - `"programmatic"` - The role of the message input. One of `user`, `system`, or `developer`. + - `defer_loading: Optional[bool]` - - `"user"` + Whether this tool should be deferred and discovered via tool search. - - `"system"` + - `description: Optional[str]` - - `"developer"` + Optional description of the custom tool, used to provide more context. - - `agent: Optional[MessageAgent]` + - `format: Optional[Format]` - The agent that produced this item. + The input format for the custom tool. Default is unconstrained text. - - `agent_name: str` + - `class FormatText: …` - The canonical name of the agent that produced this item. + Unconstrained free-form text. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `type: Literal["text"]` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Unconstrained text format. Always `text`. - - `"in_progress"` + - `"text"` - - `"completed"` + - `class FormatGrammar: …` - - `"incomplete"` + A grammar defined by the user. - - `type: Optional[Literal["message"]]` + - `definition: str` - The type of the message input. Always set to `message`. + The grammar definition. - - `"message"` + - `syntax: Literal["lark", "regex"]` - - `class BetaResponseOutputMessage: …` + The syntax of the grammar definition. One of `lark` or `regex`. - An output message from the model. + - `"lark"` - - `id: str` + - `"regex"` - The unique ID of the output message. + - `type: Literal["grammar"]` - - `content: List[Content]` + Grammar format. Always `grammar`. - The content of the output message. + - `"grammar"` - - `class BetaResponseOutputText: …` + - `class BetaNamespaceTool: …` - A text output from the model. + Groups function/custom tools under a shared namespace. - - `annotations: List[Annotation]` + - `description: str` - The annotations of the text output. + A description of the namespace shown to the model. - - `class AnnotationFileCitation: …` + - `name: str` - A citation to a file. + The namespace name used in tool calls (for example, `crm`). - - `file_id: str` + - `tools: List[Tool]` - The ID of the file. + The function/custom tools available inside this namespace. - - `filename: str` + - `class ToolFunction: …` - The filename of the file cited. + - `name: str` - - `index: int` + - `type: Literal["function"]` - The index of the file in the list of files. + - `"function"` - - `type: Literal["file_citation"]` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - The type of the file citation. Always `file_citation`. + The tool invocation context(s). - - `"file_citation"` + - `"direct"` - - `class AnnotationURLCitation: …` + - `"programmatic"` - A citation for a web resource used to generate a model response. + - `defer_loading: Optional[bool]` - - `end_index: int` + Whether this function should be deferred and discovered via tool search. - The index of the last character of the URL citation in the message. + - `description: Optional[str]` - - `start_index: int` + - `output_schema: Optional[Dict[str, object]]` - The index of the first character of the URL citation in the message. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `title: str` + - `parameters: Optional[object]` - The title of the web resource. + - `strict: Optional[bool]` - - `type: Literal["url_citation"]` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - The type of the URL citation. Always `url_citation`. + - `class BetaCustomTool: …` - - `"url_citation"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `url: str` + - `type: Literal["namespace"]` - The URL of the web resource. + The type of the tool. Always `namespace`. - - `class AnnotationContainerFileCitation: …` + - `"namespace"` - A citation for a container file used to generate a model response. + - `class BetaToolSearchTool: …` - - `container_id: str` + Hosted or BYOT tool search configuration for deferred tools. - The ID of the container file. + - `type: Literal["tool_search"]` - - `end_index: int` + The type of the tool. Always `tool_search`. - The index of the last character of the container file citation in the message. + - `"tool_search"` - - `file_id: str` + - `description: Optional[str]` - The ID of the file. + Description shown to the model for a client-executed tool search tool. - - `filename: str` + - `execution: Optional[Literal["server", "client"]]` - The filename of the container file cited. + Whether tool search is executed by the server or by the client. - - `start_index: int` + - `"server"` - The index of the first character of the container file citation in the message. + - `"client"` - - `type: Literal["container_file_citation"]` + - `parameters: Optional[object]` - The type of the container file citation. Always `container_file_citation`. + Parameter schema for a client-executed tool search tool. - - `"container_file_citation"` + - `class BetaWebSearchPreviewTool: …` - - `class AnnotationFilePath: …` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - A path to a file. + - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` - - `file_id: str` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The ID of the file. + - `"web_search_preview"` - - `index: int` + - `"web_search_preview_2025_03_11"` - The index of the file in the list of files. + - `search_content_types: Optional[List[Literal["text", "image"]]]` - - `type: Literal["file_path"]` + - `"text"` - The type of the file path. Always `file_path`. + - `"image"` - - `"file_path"` + - `search_context_size: Optional[Literal["low", "medium", "high"]]` - - `text: str` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The text output from the model. + - `"low"` - - `type: Literal["output_text"]` + - `"medium"` - The type of the output text. Always `output_text`. + - `"high"` - - `"output_text"` + - `user_location: Optional[UserLocation]` - - `logprobs: Optional[List[Logprob]]` + The user's location. - - `token: str` + - `type: Literal["approximate"]` - - `bytes: List[int]` + The type of location approximation. Always `approximate`. - - `logprob: float` + - `"approximate"` - - `top_logprobs: List[LogprobTopLogprob]` + - `city: Optional[str]` - - `token: str` + Free text input for the city of the user, e.g. `San Francisco`. - - `bytes: List[int]` + - `country: Optional[str]` - - `logprob: float` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `class BetaResponseOutputRefusal: …` + - `region: Optional[str]` - A refusal from the model. + Free text input for the region of the user, e.g. `California`. - - `refusal: str` + - `timezone: Optional[str]` - The refusal explanation from the model. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `type: Literal["refusal"]` + - `class BetaApplyPatchTool: …` - The type of the refusal. Always `refusal`. + Allows the assistant to create, delete, or update files using unified diffs. - - `"refusal"` + - `type: Literal["apply_patch"]` - - `role: Literal["assistant"]` + The type of the tool. Always `apply_patch`. - The role of the output message. Always `assistant`. + - `"apply_patch"` - - `"assistant"` + - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` - - `status: Literal["in_progress", "completed", "incomplete"]` + The tool invocation context(s). - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"direct"` - - `"in_progress"` + - `"programmatic"` - - `"completed"` + - `type: Literal["tool_search_output"]` - - `"incomplete"` + The item type. Always `tool_search_output`. - - `type: Literal["message"]` + - `"tool_search_output"` - The type of the output message. Always `message`. + - `id: Optional[str]` - - `"message"` + The unique ID of this tool search output. - `agent: Optional[Agent]` @@ -143467,434 +155003,417 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `phase: Optional[Literal["commentary"]]` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - - `"commentary"` - - - `class BetaResponseFileSearchToolCall: …` + - `call_id: Optional[str]` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + The unique ID of the tool search call generated by the model. - - `id: str` + - `execution: Optional[Literal["server", "client"]]` - The unique ID of the file search tool call. + Whether tool search was executed by the server or by the client. - - `queries: List[str]` + - `"server"` - The queries used to search for files. + - `"client"` - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The status of the tool search output. - `"in_progress"` - - `"searching"` - - `"completed"` - `"incomplete"` - - `"failed"` - - - `type: Literal["file_search_call"]` + - `class AdditionalTools: …` - The type of the file search tool call. Always `file_search_call`. + - `role: Literal["developer"]` - - `"file_search_call"` + The role that provided the additional tools. Only `developer` is supported. - - `agent: Optional[Agent]` + - `"developer"` - The agent that produced this item. + - `tools: List[BetaTool]` - - `agent_name: str` + A list of additional tools made available at this item. - The canonical name of the agent that produced this item. + - `class BetaFunctionTool: …` - - `results: Optional[List[Result]]` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The results of the file search tool call. + - `class BetaFileSearchTool: …` - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - 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, booleans, or numbers. + - `class BetaComputerTool: …` - - `str` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `float` + - `class BetaComputerUsePreviewTool: …` - - `bool` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `file_id: Optional[str]` + - `class BetaWebSearchTool: …` - The unique ID of the file. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `filename: Optional[str]` + - `class Mcp: …` - The name of the file. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `score: Optional[float]` + - `class CodeInterpreter: …` - The relevance score of the file - a value between 0 and 1. + A tool that runs Python code to help generate a response to a prompt. - - `text: Optional[str]` + - `class ProgrammaticToolCalling: …` - The text that was retrieved from the file. + - `class ImageGeneration: …` - - `class BetaResponseComputerToolCall: …` + A tool that generates images using the GPT image models. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `class LocalShell: …` - - `id: str` + A tool that allows the model to execute shell commands in a local environment. - The unique ID of the computer call. + - `class BetaFunctionShellTool: …` - - `call_id: str` + A tool that allows the model to execute shell commands. - An identifier used when responding to the tool call with output. + - `class BetaCustomTool: …` - - `pending_safety_checks: List[PendingSafetyCheck]` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The pending safety checks for the computer call. + - `class BetaNamespaceTool: …` - - `id: str` + Groups function/custom tools under a shared namespace. - The ID of the pending safety check. + - `class BetaToolSearchTool: …` - - `code: Optional[str]` + Hosted or BYOT tool search configuration for deferred tools. - The type of the pending safety check. + - `class BetaWebSearchPreviewTool: …` - - `message: Optional[str]` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Details about the pending safety check. + - `class BetaApplyPatchTool: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + Allows the assistant to create, delete, or update files using unified diffs. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: Literal["additional_tools"]` - - `"in_progress"` + The item type. Always `additional_tools`. - - `"completed"` + - `"additional_tools"` - - `"incomplete"` + - `id: Optional[str]` - - `type: Literal["computer_call"]` + The unique ID of this additional tools item. - The type of the computer call. Always `computer_call`. + - `agent: Optional[AdditionalToolsAgent]` - - `"computer_call"` + The agent that produced this item. - - `action: Optional[BetaComputerAction]` + - `agent_name: str` - A click action. + The canonical name of the agent that produced this item. - - `class Click: …` + - `class BetaResponseReasoningItem: …` - A click action. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `button: Literal["left", "right", "wheel", 2 more]` + - `id: str` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The unique identifier of the reasoning content. - - `"left"` + - `summary: List[Summary]` - - `"right"` + Reasoning summary content. - - `"wheel"` + - `text: str` - - `"back"` + A summary of the reasoning output from the model so far. - - `"forward"` + - `type: Literal["summary_text"]` - - `type: Literal["click"]` + The type of the object. Always `summary_text`. - Specifies the event type. For a click action, this property is always `click`. + - `"summary_text"` - - `"click"` + - `type: Literal["reasoning"]` - - `x: int` + The type of the object. Always `reasoning`. - The x-coordinate where the click occurred. + - `"reasoning"` - - `y: int` + - `agent: Optional[Agent]` - The y-coordinate where the click occurred. + The agent that produced this item. - - `keys: Optional[List[str]]` + - `agent_name: str` - The keys being held while clicking. + The canonical name of the agent that produced this item. - - `class DoubleClick: …` + - `content: Optional[List[Content]]` - A double click action. + Reasoning text content. - - `keys: Optional[List[str]]` + - `text: str` - The keys being held while double-clicking. + The reasoning text from the model. - - `type: Literal["double_click"]` + - `type: Literal["reasoning_text"]` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The type of the reasoning text. Always `reasoning_text`. - - `"double_click"` + - `"reasoning_text"` - - `x: int` + - `encrypted_content: Optional[str]` - The x-coordinate where the double click occurred. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `y: int` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The y-coordinate where the double click occurred. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `class Drag: …` + - `"in_progress"` - A drag action. + - `"completed"` - - `path: List[DragPath]` + - `"incomplete"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `class BetaResponseCompactionItemParam: …` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `x: int` + - `encrypted_content: str` - The x-coordinate. + The encrypted content of the compaction summary. - - `y: int` + - `type: Literal["compaction"]` - The y-coordinate. + The type of the item. Always `compaction`. - - `type: Literal["drag"]` + - `"compaction"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `id: Optional[str]` - - `"drag"` + The ID of the compaction item. - - `keys: Optional[List[str]]` + - `agent: Optional[Agent]` - The keys being held while dragging the mouse. + The agent that produced this item. - - `class Keypress: …` + - `agent_name: str` - A collection of keypresses the model would like to perform. + The canonical name of the agent that produced this item. - - `keys: List[str]` + - `class ImageGenerationCall: …` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + An image generation request made by the model. - - `type: Literal["keypress"]` + - `id: str` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The unique ID of the image generation call. - - `"keypress"` + - `result: Optional[str]` - - `class Move: …` + The generated image encoded in base64. - A mouse move action. + - `status: Literal["in_progress", "completed", "generating", "failed"]` - - `type: Literal["move"]` + The status of the image generation call. - Specifies the event type. For a move action, this property is always set to `move`. + - `"in_progress"` - - `"move"` + - `"completed"` - - `x: int` + - `"generating"` - The x-coordinate to move to. + - `"failed"` - - `y: int` + - `type: Literal["image_generation_call"]` - The y-coordinate to move to. + The type of the image generation call. Always `image_generation_call`. - - `keys: Optional[List[str]]` + - `"image_generation_call"` - The keys being held while moving the mouse. + - `agent: Optional[ImageGenerationCallAgent]` - - `class Screenshot: …` + The agent that produced this item. - A screenshot action. + - `agent_name: str` - - `type: Literal["screenshot"]` + The canonical name of the agent that produced this item. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `class BetaResponseCodeInterpreterToolCall: …` - - `"screenshot"` + A tool call to run code. - - `class Scroll: …` + - `id: str` - A scroll action. + The unique ID of the code interpreter tool call. - - `scroll_x: int` + - `code: Optional[str]` - The horizontal scroll distance. + The code to run, or null if not available. - - `scroll_y: int` + - `container_id: str` - The vertical scroll distance. + The ID of the container used to run the code. - - `type: Literal["scroll"]` + - `outputs: Optional[List[Output]]` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"scroll"` + - `class OutputLogs: …` - - `x: int` + The logs output from the code interpreter. - The x-coordinate where the scroll occurred. + - `logs: str` - - `y: int` + The logs output from the code interpreter. - The y-coordinate where the scroll occurred. + - `type: Literal["logs"]` - - `keys: Optional[List[str]]` + The type of the output. Always `logs`. - The keys being held while scrolling. + - `"logs"` - - `class Type: …` + - `class OutputImage: …` - An action to type in text. + The image output from the code interpreter. - - `text: str` + - `type: Literal["image"]` - The text to type. + The type of the output. Always `image`. - - `type: Literal["type"]` + - `"image"` - Specifies the event type. For a type action, this property is always set to `type`. + - `url: str` - - `"type"` + The URL of the image output from the code interpreter. - - `class Wait: …` + - `status: Literal["in_progress", "completed", "incomplete", 2 more]` - A wait action. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `type: Literal["wait"]` + - `"in_progress"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"completed"` - - `"wait"` + - `"incomplete"` - - `actions: Optional[BetaComputerActionList]` + - `"interpreting"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"failed"` - - `class Click: …` + - `type: Literal["code_interpreter_call"]` - A click action. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `class DoubleClick: …` + - `"code_interpreter_call"` - A double click action. + - `agent: Optional[Agent]` - - `class Drag: …` + The agent that produced this item. - A drag action. + - `agent_name: str` - - `class Keypress: …` + The canonical name of the agent that produced this item. - A collection of keypresses the model would like to perform. + - `class LocalShellCall: …` - - `class Move: …` + A tool call to run a command on the local shell. - A mouse move action. + - `id: str` - - `class Screenshot: …` + The unique ID of the local shell call. - A screenshot action. + - `action: LocalShellCallAction` - - `class Scroll: …` + Execute a shell command on the server. - A scroll action. + - `command: List[str]` - - `class Type: …` + The command to run. - An action to type in text. + - `env: Dict[str, str]` - - `class Wait: …` + Environment variables to set for the command. - A wait action. + - `type: Literal["exec"]` - - `agent: Optional[Agent]` + The type of the local shell action. Always `exec`. - The agent that produced this item. + - `"exec"` - - `agent_name: str` + - `timeout_ms: Optional[int]` - The canonical name of the agent that produced this item. + Optional timeout in milliseconds for the command. - - `class ComputerCallOutput: …` + - `user: Optional[str]` - The output of a computer tool call. + Optional user to run the command as. - - `call_id: str` + - `working_directory: Optional[str]` - The ID of the computer tool call that produced the output. + Optional working directory to run the command in. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `call_id: str` - A computer screenshot image used with the computer use tool. + The unique ID of the local shell tool call generated by the model. - - `type: Literal["computer_screenshot"]` + - `status: Literal["in_progress", "completed", "incomplete"]` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The status of the local shell call. - - `"computer_screenshot"` + - `"in_progress"` - - `file_id: Optional[str]` + - `"completed"` - The identifier of an uploaded file that contains the screenshot. + - `"incomplete"` - - `image_url: Optional[str]` + - `type: Literal["local_shell_call"]` - The URL of the screenshot image. + The type of the local shell call. Always `local_shell_call`. - - `type: Literal["computer_call_output"]` + - `"local_shell_call"` - The type of the computer tool call output. Always `computer_call_output`. + - `agent: Optional[LocalShellCallAgent]` - - `"computer_call_output"` + The agent that produced this item. - - `id: Optional[str]` + - `agent_name: str` - The ID of the computer tool call output. + The canonical name of the agent that produced this item. - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + - `class LocalShellCallOutput: …` - The safety checks reported by the API that have been acknowledged by the developer. + The output of a local shell tool call. - `id: str` - The ID of the pending safety check. + The unique ID of the local shell tool call generated by the model. - - `code: Optional[str]` + - `output: str` - The type of the pending safety check. + A JSON string of the output of the local shell tool call. - - `message: Optional[str]` + - `type: Literal["local_shell_call_output"]` - Details about the pending safety check. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `agent: Optional[ComputerCallOutputAgent]` + - `"local_shell_call_output"` + + - `agent: Optional[LocalShellCallOutputAgent]` The agent that produced this item. @@ -143904,7 +155423,7 @@ print(compacted_response) - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -143912,138 +155431,149 @@ print(compacted_response) - `"incomplete"` - - `class BetaResponseFunctionWebSearch: …` - - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `class ShellCall: …` - - `id: str` + A tool representing a request to execute one or more shell commands. - The unique ID of the web search tool call. + - `action: ShellCallAction` - - `action: Action` + The shell commands and limits that describe how to run the tool call. - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `commands: List[str]` - - `class ActionSearch: …` + Ordered shell commands for the execution environment to run. - Action type "search" - Performs a web search query. + - `max_output_length: Optional[int]` - - `type: Literal["search"]` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - The action type. + - `timeout_ms: Optional[int]` - - `"search"` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `queries: Optional[List[str]]` + - `call_id: str` - The search queries. + The unique ID of the shell tool call generated by the model. - - `query: Optional[str]` + - `type: Literal["shell_call"]` - The search query. + The type of the item. Always `shell_call`. - - `sources: Optional[List[ActionSearchSource]]` + - `"shell_call"` - The sources used in the search. + - `id: Optional[str]` - - `type: Literal["url"]` + The unique ID of the shell tool call. Populated when this item is returned via API. - The type of source. Always `url`. + - `agent: Optional[ShellCallAgent]` - - `"url"` + The agent that produced this item. - - `url: str` + - `agent_name: str` - The URL of the source. + The canonical name of the agent that produced this item. - - `class ActionOpenPage: …` + - `caller: Optional[ShellCallCaller]` - Action type "open_page" - Opens a specific URL from search results. + The execution context that produced this tool call. - - `type: Literal["open_page"]` + - `class ShellCallCallerDirect: …` - The action type. + - `type: Literal["direct"]` - - `"open_page"` + The caller type. Always `direct`. - - `url: Optional[str]` + - `"direct"` - The URL opened by the model. + - `class ShellCallCallerProgram: …` - - `class ActionFindInPage: …` + - `caller_id: str` - Action type "find_in_page": Searches for a pattern within a loaded page. + The call ID of the program item that produced this tool call. - - `pattern: str` + - `type: Literal["program"]` - The pattern or text to search for within the page. + The caller type. Always `program`. - - `type: Literal["find_in_page"]` + - `"program"` - The action type. + - `environment: Optional[ShellCallEnvironment]` - - `"find_in_page"` + The environment to execute the shell commands in. - - `url: str` + - `class BetaLocalEnvironment: …` - The URL of the page searched for the pattern. + - `class BetaContainerReference: …` - - `status: Literal["in_progress", "searching", "completed", "failed"]` + - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the web search tool call. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` - - `"searching"` - - `"completed"` - - `"failed"` + - `"incomplete"` - - `type: Literal["web_search_call"]` + - `class ShellCallOutput: …` - The type of the web search tool call. Always `web_search_call`. + The streamed output items emitted by a shell tool call. - - `"web_search_call"` + - `call_id: str` - - `agent: Optional[Agent]` + The unique ID of the shell tool call generated by the model. - The agent that produced this item. + - `output: List[BetaResponseFunctionShellCallOutputContent]` - - `agent_name: str` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The canonical name of the agent that produced this item. + - `outcome: Outcome` - - `class BetaResponseFunctionToolCall: …` + The exit or timeout outcome associated with this shell call. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `class OutcomeTimeout: …` - - `arguments: str` + Indicates that the shell call exceeded its configured time limit. - A JSON string of the arguments to pass to the function. + - `type: Literal["timeout"]` - - `call_id: str` + The outcome type. Always `timeout`. - The unique ID of the function tool call generated by the model. + - `"timeout"` - - `name: str` + - `class OutcomeExit: …` - The name of the function to run. + Indicates that the shell commands finished and returned an exit code. - - `type: Literal["function_call"]` + - `exit_code: int` - The type of the function tool call. Always `function_call`. + The exit code returned by the shell process. - - `"function_call"` + - `type: Literal["exit"]` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: str` + + Captured stderr output for the shell call. + + - `stdout: str` + + Captured stdout output for the shell call. + + - `type: Literal["shell_call_output"]` + + The type of the item. Always `shell_call_output`. + + - `"shell_call_output"` - `id: Optional[str]` - The unique ID of the function tool call. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `agent: Optional[Agent]` + - `agent: Optional[ShellCallOutputAgent]` The agent that produced this item. @@ -144051,17 +155581,19 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[Caller]` + - `caller: Optional[ShellCallOutputCaller]` The execution context that produced this tool call. - - `class CallerDirect: …` + - `class ShellCallOutputCallerDirect: …` - `type: Literal["direct"]` + The caller type. Always `direct`. + - `"direct"` - - `class CallerProgram: …` + - `class ShellCallOutputCallerProgram: …` - `caller_id: str` @@ -144069,16 +155601,17 @@ print(compacted_response) - `type: Literal["program"]` + The caller type. Always `program`. + - `"program"` - - `namespace: Optional[str]` + - `max_output_length: Optional[int]` - The namespace of the function to run. + The maximum number of UTF-8 characters captured for this shell call's combined output. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the shell call output. - `"in_progress"` @@ -144086,145 +155619,145 @@ print(compacted_response) - `"incomplete"` - - `class FunctionCallOutput: …` + - `class ApplyPatchCall: …` - The output of a function tool call. + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: str` - The unique ID of the function tool call generated by the model. + The unique ID of the apply patch tool call generated by the model. - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + - `operation: ApplyPatchCallOperation` - Text, image, or file output of the function tool call. + The specific create, delete, or update instruction for the apply_patch tool call. - - `str` + - `class ApplyPatchCallOperationCreateFile: …` - A JSON string of the output of the function tool call. + Instruction for creating a new file via the apply_patch tool. - - `List[BetaResponseFunctionCallOutputItem]` + - `diff: str` - - `class BetaResponseInputTextContent: …` + Unified diff content to apply when creating the file. - A text input to the model. + - `path: str` - - `text: str` + Path of the file to create relative to the workspace root. - The text input to the model. + - `type: Literal["create_file"]` - - `type: Literal["input_text"]` + The operation type. Always `create_file`. - The type of the input item. Always `input_text`. + - `"create_file"` - - `"input_text"` + - `class ApplyPatchCallOperationDeleteFile: …` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + Instruction for deleting an existing file via the apply_patch tool. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `path: str` - - `mode: Literal["explicit"]` + Path of the file to delete relative to the workspace root. - The breakpoint mode. Always `explicit`. + - `type: Literal["delete_file"]` - - `"explicit"` + The operation type. Always `delete_file`. - - `class BetaResponseInputImageContent: …` + - `"delete_file"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `class ApplyPatchCallOperationUpdateFile: …` - - `type: Literal["input_image"]` + Instruction for updating an existing file via the apply_patch tool. - The type of the input item. Always `input_image`. + - `diff: str` - - `"input_image"` + Unified diff content to apply to the existing file. - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + - `path: str` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Path of the file to update relative to the workspace root. - - `"low"` + - `type: Literal["update_file"]` - - `"high"` + The operation type. Always `update_file`. - - `"auto"` + - `"update_file"` - - `"original"` + - `status: Literal["in_progress", "completed"]` - - `file_id: Optional[str]` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The ID of the file to be sent to the model. + - `"in_progress"` - - `image_url: Optional[str]` + - `"completed"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: Literal["apply_patch_call"]` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The type of the item. Always `apply_patch_call`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"apply_patch_call"` - - `mode: Literal["explicit"]` + - `id: Optional[str]` - The breakpoint mode. Always `explicit`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"explicit"` + - `agent: Optional[ApplyPatchCallAgent]` - - `class BetaResponseInputFileContent: …` + The agent that produced this item. - A file input to the model. + - `agent_name: str` - - `type: Literal["input_file"]` + The canonical name of the agent that produced this item. - The type of the input item. Always `input_file`. + - `caller: Optional[ApplyPatchCallCaller]` - - `"input_file"` + The execution context that produced this tool call. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `class ApplyPatchCallCallerDirect: …` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `type: Literal["direct"]` - - `"auto"` + The caller type. Always `direct`. - - `"low"` + - `"direct"` - - `"high"` + - `class ApplyPatchCallCallerProgram: …` - - `file_data: Optional[str]` + - `caller_id: str` - The base64-encoded data of the file to be sent to the model. + The call ID of the program item that produced this tool call. - - `file_id: Optional[str]` + - `type: Literal["program"]` - The ID of the file to be sent to the model. + The caller type. Always `program`. - - `file_url: Optional[str]` + - `"program"` - The URL of the file to be sent to the model. + - `class ApplyPatchCallOutput: …` - - `filename: Optional[str]` + The streamed output emitted by an apply patch tool call. - The name of the file to be sent to the model. + - `call_id: str` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The unique ID of the apply patch tool call generated by the model. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `status: Literal["completed", "failed"]` - - `mode: Literal["explicit"]` + The status of the apply patch tool call output. One of `completed` or `failed`. - The breakpoint mode. Always `explicit`. + - `"completed"` - - `"explicit"` + - `"failed"` - - `type: Literal["function_call_output"]` + - `type: Literal["apply_patch_call_output"]` - The type of the function tool call output. Always `function_call_output`. + The type of the item. Always `apply_patch_call_output`. - - `"function_call_output"` + - `"apply_patch_call_output"` - `id: Optional[str]` - The unique ID of the function tool call output. Populated when this item is returned via API. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `agent: Optional[FunctionCallOutputAgent]` + - `agent: Optional[ApplyPatchCallOutputAgent]` The agent that produced this item. @@ -144232,11 +155765,11 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `caller: Optional[FunctionCallOutputCaller]` + - `caller: Optional[ApplyPatchCallOutputCaller]` The execution context that produced this tool call. - - `class FunctionCallOutputCallerDirect: …` + - `class ApplyPatchCallOutputCallerDirect: …` - `type: Literal["direct"]` @@ -144244,7 +155777,7 @@ print(compacted_response) - `"direct"` - - `class FunctionCallOutputCallerProgram: …` + - `class ApplyPatchCallOutputCallerProgram: …` - `caller_id: str` @@ -144256,65 +155789,49 @@ print(compacted_response) - `"program"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `class AgentMessage: …` - - A message routed between agents. - - - `author: str` - - The sending agent identity. + - `output: Optional[str]` - - `content: List[AgentMessageContent]` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - Plaintext, image, or encrypted content sent between agents. + - `class McpListTools: …` - - `class BetaResponseInputTextContent: …` + A list of tools available on an MCP server. - A text input to the model. + - `id: str` - - `class BetaResponseInputImageContent: …` + The unique ID of the list. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `server_label: str` - - `class AgentMessageContentEncryptedContent: …` + The label of the MCP server. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `tools: List[McpListToolsTool]` - - `encrypted_content: str` + The tools available on the server. - Opaque encrypted content. + - `input_schema: object` - - `type: Literal["encrypted_content"]` + The JSON schema describing the tool's input. - The type of the input item. Always `encrypted_content`. + - `name: str` - - `"encrypted_content"` + The name of the tool. - - `recipient: str` + - `annotations: Optional[object]` - The destination agent identity. + Additional annotations about the tool. - - `type: Literal["agent_message"]` + - `description: Optional[str]` - The item type. Always `agent_message`. + The description of the tool. - - `"agent_message"` + - `type: Literal["mcp_list_tools"]` - - `id: Optional[str]` + The type of the item. Always `mcp_list_tools`. - The unique ID of this agent message item. + - `"mcp_list_tools"` - - `agent: Optional[AgentMessageAgent]` + - `agent: Optional[McpListToolsAgent]` The agent that produced this item. @@ -144322,173 +155839,105 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class MultiAgentCall: …` - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - The multi-agent action that was executed. - - - `"spawn_agent"` + - `error: Optional[str]` - - `"interrupt_agent"` + Error message if the server could not list tools. - - `"list_agents"` + - `class McpApprovalRequest: …` - - `"send_message"` + A request for human approval of a tool invocation. - - `"followup_task"` + - `id: str` - - `"wait_agent"` + The unique ID of the approval request. - `arguments: str` - The action arguments as a JSON string. - - - `call_id: str` - - The unique ID linking this call to its output. - - - `type: Literal["multi_agent_call"]` - - The item type. Always `multi_agent_call`. - - - `"multi_agent_call"` - - - `id: Optional[str]` - - The unique ID of this multi-agent call. - - - `agent: Optional[MultiAgentCallAgent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `class MultiAgentCallOutput: …` - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `call_id: str` - - The unique ID of the multi-agent call. - - - `output: List[MultiAgentCallOutputOutput]` - - Text output returned by the multi-agent action. - - - `text: str` - - The text content. - - - `type: Literal["output_text"]` - - The content type. Always `output_text`. - - - `"output_text"` - - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` - - Citations associated with the text content. + A JSON string of arguments for the tool. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + - `name: str` - - `file_id: str` + The name of the tool to run. - The ID of the file. + - `server_label: str` - - `filename: str` + The label of the MCP server making the request. - The filename of the file cited. + - `type: Literal["mcp_approval_request"]` - - `index: int` + The type of the item. Always `mcp_approval_request`. - The index of the file in the list of files. + - `"mcp_approval_request"` - - `type: Literal["file_citation"]` + - `agent: Optional[McpApprovalRequestAgent]` - The citation type. Always `file_citation`. + The agent that produced this item. - - `"file_citation"` + - `agent_name: str` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + The canonical name of the agent that produced this item. - - `end_index: int` + - `class McpApprovalResponse: …` - The index of the last character of the citation in the message. + A response to an MCP approval request. - - `start_index: int` + - `approval_request_id: str` - The index of the first character of the citation in the message. + The ID of the approval request being answered. - - `title: str` + - `approve: bool` - The title of the cited resource. + Whether the request was approved. - - `type: Literal["url_citation"]` + - `type: Literal["mcp_approval_response"]` - The citation type. Always `url_citation`. + The type of the item. Always `mcp_approval_response`. - - `"url_citation"` + - `"mcp_approval_response"` - - `url: str` + - `id: Optional[str]` - The URL of the cited resource. + The unique ID of the approval response - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `agent: Optional[McpApprovalResponseAgent]` - - `container_id: str` + The agent that produced this item. - The ID of the container. + - `agent_name: str` - - `end_index: int` + The canonical name of the agent that produced this item. - The index of the last character of the citation in the message. + - `reason: Optional[str]` - - `file_id: str` + Optional reason for the decision. - The ID of the container file. + - `class McpCall: …` - - `filename: str` + An invocation of a tool on an MCP server. - The filename of the container file cited. + - `id: str` - - `start_index: int` + The unique ID of the tool call. - The index of the first character of the citation in the message. + - `arguments: str` - - `type: Literal["container_file_citation"]` + A JSON string of the arguments passed to the tool. - The citation type. Always `container_file_citation`. + - `name: str` - - `"container_file_citation"` + The name of the tool that was run. - - `type: Literal["multi_agent_call_output"]` + - `server_label: str` - The item type. Always `multi_agent_call_output`. + The label of the MCP server running the tool. - - `"multi_agent_call_output"` + - `type: Literal["mcp_call"]` - - `id: Optional[str]` + The type of the item. Always `mcp_call`. - The unique ID of this multi-agent call output. + - `"mcp_call"` - - `agent: Optional[MultiAgentCallOutputAgent]` + - `agent: Optional[McpCallAgent]` The agent that produced this item. @@ -144496,335 +155945,334 @@ print(compacted_response) The canonical name of the agent that produced this item. - - `class ToolSearchCall: …` + - `approval_request_id: Optional[str]` - - `arguments: object` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The arguments supplied to the tool search call. + - `error: Optional[str]` - - `type: Literal["tool_search_call"]` + The error from the tool call, if any. - The item type. Always `tool_search_call`. + - `output: Optional[str]` - - `"tool_search_call"` + The output from the tool call. - - `id: Optional[str]` + - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` - The unique ID of this tool search call. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `agent: Optional[ToolSearchCallAgent]` + - `"in_progress"` - The agent that produced this item. + - `"completed"` - - `agent_name: str` + - `"incomplete"` - The canonical name of the agent that produced this item. + - `"calling"` - - `call_id: Optional[str]` + - `"failed"` - The unique ID of the tool search call generated by the model. + - `class BetaResponseCustomToolCallOutput: …` - - `execution: Optional[Literal["server", "client"]]` + The output of a custom tool call from your code, being sent back to the model. - Whether tool search was executed by the server or by the client. + - `call_id: str` - - `"server"` + The call ID, used to map this custom tool call output to a custom tool call. - - `"client"` + - `output: Union[str, List[OutputOutputContentList]]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The status of the tool search call. + - `str` - - `"in_progress"` + A string of the output of the custom tool call. - - `"completed"` + - `List[OutputOutputContentList]` - - `"incomplete"` + Text, image, or file output of the custom tool call. - - `class BetaResponseToolSearchOutputItemParam: …` + - `class BetaResponseInputText: …` - - `tools: List[BetaTool]` + A text input to the model. - The loaded tool definitions returned by the tool search output. + - `class BetaResponseInputImage: …` - - `class BetaFunctionTool: …` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class BetaResponseInputFile: …` - - `name: str` + A file input to the model. - The name of the function to call. + - `type: Literal["custom_tool_call_output"]` - - `parameters: Optional[Dict[str, object]]` + The type of the custom tool call output. Always `custom_tool_call_output`. - A JSON schema object describing the parameters of the function. + - `"custom_tool_call_output"` - - `strict: Optional[bool]` + - `id: Optional[str]` - Whether strict parameter validation is enforced for this function tool. + The unique ID of the custom tool call output in the OpenAI platform. - - `type: Literal["function"]` + - `agent: Optional[Agent]` - The type of the function tool. Always `function`. + The agent that produced this item. - - `"function"` + - `agent_name: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `caller: Optional[Caller]` - - `"direct"` + The execution context that produced this tool call. - - `"programmatic"` + - `class CallerDirect: …` - - `defer_loading: Optional[bool]` + - `type: Literal["direct"]` - Whether this function is deferred and loaded via tool search. + The caller type. Always `direct`. - - `description: Optional[str]` + - `"direct"` - A description of the function. Used by the model to determine whether or not to call the function. + - `class CallerProgram: …` - - `output_schema: Optional[Dict[str, object]]` + - `caller_id: str` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The call ID of the program item that produced this tool call. - - `class BetaFileSearchTool: …` + - `type: Literal["program"]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The caller type. Always `program`. - - `type: Literal["file_search"]` + - `"program"` - The type of the file search tool. Always `file_search`. + - `class BetaResponseCustomToolCall: …` - - `"file_search"` + A call to a custom tool created by the model. - - `vector_store_ids: List[str]` + - `call_id: str` - The IDs of the vector stores to search. + An identifier used to map this custom tool call to a tool call output. - - `filters: Optional[Filters]` + - `input: str` - A filter to apply. + The input for the custom tool call generated by the model. - - `class FiltersComparisonFilter: …` + - `name: str` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The name of the custom tool being called. - - `key: str` + - `type: Literal["custom_tool_call"]` - The key to compare against the value. + The type of the custom tool call. Always `custom_tool_call`. - - `type: Literal["eq", "ne", "gt", 5 more]` + - `"custom_tool_call"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `id: Optional[str]` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The unique ID of the custom tool call in the OpenAI platform. - - `"eq"` + - `agent: Optional[Agent]` - - `"ne"` + The agent that produced this item. - - `"gt"` + - `agent_name: str` - - `"gte"` + The canonical name of the agent that produced this item. - - `"lt"` + - `caller: Optional[Caller]` - - `"lte"` + The execution context that produced this tool call. - - `"in"` + - `class CallerDirect: …` - - `"nin"` + - `type: Literal["direct"]` - - `value: Union[str, float, bool, List[object]]` + - `"direct"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `class CallerProgram: …` - - `str` + - `caller_id: str` - - `float` + The call ID of the program item that produced this tool call. - - `bool` + - `type: Literal["program"]` - - `List[object]` + - `"program"` - - `class FiltersCompoundFilter: …` + - `namespace: Optional[str]` - Combine multiple filters using `and` or `or`. + The namespace of the custom tool being called. - - `filters: List[FiltersCompoundFilterFilter]` + - `class CompactionTrigger: …` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Compacts the current context. Must be the final input item. - - `class FiltersCompoundFilterFilterComparisonFilter: …` + - `type: Literal["compaction_trigger"]` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The type of the item. Always `compaction_trigger`. - - `key: str` + - `"compaction_trigger"` - The key to compare against the value. + - `agent: Optional[CompactionTriggerAgent]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The agent that produced this item. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `agent_name: str` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The canonical name of the agent that produced this item. - - `"eq"` + - `class ItemReference: …` - - `"ne"` + An internal identifier for an item to reference. - - `"gt"` + - `id: str` - - `"gte"` + The ID of the item to reference. - - `"lt"` + - `agent: Optional[ItemReferenceAgent]` - - `"lte"` + The agent that produced this item. - - `"in"` + - `agent_name: str` - - `"nin"` + The canonical name of the agent that produced this item. - - `value: Union[str, float, bool, List[object]]` + - `type: Optional[Literal["item_reference"]]` - The value to compare against the attribute key; supports string, number, or boolean types. + The type of item to reference. Always `item_reference`. - - `str` + - `"item_reference"` - - `float` + - `class Program: …` - - `bool` + - `id: str` - - `List[object]` + The unique ID of this program item. - - `object` + - `call_id: str` - - `type: Literal["and", "or"]` + The stable call ID of the program item. - Type of operation: `and` or `or`. + - `code: str` - - `"and"` + The JavaScript source executed by programmatic tool calling. - - `"or"` + - `fingerprint: str` - - `max_num_results: Optional[int]` + Opaque program replay fingerprint that must be round-tripped. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `type: Literal["program"]` - - `ranking_options: Optional[RankingOptions]` + The item type. Always `program`. - Ranking options for search. + - `"program"` - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + - `agent: Optional[ProgramAgent]` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The agent that produced this item. - - `embedding_weight: float` + - `agent_name: str` - The weight of the embedding in the reciprocal ranking fusion. + The canonical name of the agent that produced this item. - - `text_weight: float` + - `class ProgramOutput: …` - The weight of the text in the reciprocal ranking fusion. + - `id: str` - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + The unique ID of this program output item. - The ranker to use for the file search. + - `call_id: str` - - `"auto"` + The call ID of the program item. - - `"default-2024-11-15"` + - `result: str` - - `score_threshold: Optional[float]` + The result produced by the program item. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `status: Literal["completed", "incomplete"]` - - `class BetaComputerTool: …` + The terminal status of the program output. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"completed"` - - `type: Literal["computer"]` + - `"incomplete"` - The type of the computer tool. Always `computer`. + - `type: Literal["program_output"]` - - `"computer"` + The item type. Always `program_output`. - - `class BetaComputerUsePreviewTool: …` + - `"program_output"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent: Optional[ProgramOutputAgent]` - - `display_height: int` + The agent that produced this item. - The height of the computer display. + - `agent_name: str` - - `display_width: int` + The canonical name of the agent that produced this item. - The width of the computer display. +- `instructions: Optional[str]` - - `environment: Literal["windows", "mac", "linux", 2 more]` + A system (or developer) message inserted into the model's context. + When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. - The type of computer environment to control. +- `model: Optional[str]` - - `"windows"` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - - `"mac"` +- `parallel_tool_calls: Optional[bool]` - - `"linux"` + Whether to allow the model to run tool calls in parallel. - - `"ubuntu"` +- `personality: Optional[Union[str, Literal["friendly", "pragmatic"]]]` - - `"browser"` + A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. - - `type: Literal["computer_use_preview"]` + - `str` - The type of the computer use tool. Always `computer_use_preview`. + - `Literal["friendly", "pragmatic"]` - - `"computer_use_preview"` + A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. - - `class BetaWebSearchTool: …` + - `"friendly"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"pragmatic"` - - `type: Literal["web_search", "web_search_2025_08_26"]` +- `previous_response_id: Optional[str]` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `"web_search"` +- `reasoning: Optional[Reasoning]` - - `"web_search_2025_08_26"` + **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `filters: Optional[Filters]` + - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` - Filters for the search. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `allowed_domains: Optional[List[str]]` + - `"auto"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"current_turn"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"all_turns"` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. + + - `"none"` + + - `"minimal"` - `"low"` @@ -144832,4439 +156280,5089 @@ print(compacted_response) - `"high"` - - `user_location: Optional[UserLocation]` + - `"xhigh"` - The approximate location of the user. + - `"max"` - - `city: Optional[str]` + - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` - Free text input for the city of the user, e.g. `San Francisco`. + **Deprecated:** use `summary` instead. - - `country: Optional[str]` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"auto"` - - `region: Optional[str]` + - `"concise"` - Free text input for the region of the user, e.g. `California`. + - `"detailed"` - - `timezone: Optional[str]` + - `mode: Optional[Union[str, Literal["standard", "pro"]]]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Controls the reasoning execution mode for the request. - - `type: Optional[Literal["approximate"]]` + When returned on a response, this is the effective execution mode. - The type of location approximation. Always `approximate`. + - `str` - - `"approximate"` + - `Literal["standard", "pro"]` - - `class Mcp: …` + Controls the reasoning execution mode for the request. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + When returned on a response, this is the effective execution mode. - - `server_label: str` + - `"standard"` - A label for this MCP server, used to identify it in tool calls. + - `"pro"` - - `type: Literal["mcp"]` + - `summary: Optional[Literal["auto", "concise", "detailed"]]` - The type of the MCP tool. Always `mcp`. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `"mcp"` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"auto"` - The tool invocation context(s). + - `"concise"` - - `"direct"` + - `"detailed"` - - `"programmatic"` +- `text: Optional[Text]` - - `allowed_tools: Optional[McpAllowedTools]` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - List of allowed tool names or a filter object. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `List[str]` + - `format: Optional[BetaResponseFormatTextConfigParam]` - A string array of allowed tool names + An object specifying the format that the model must output. - - `class McpAllowedToolsMcpToolFilter: …` + Configuring `{ "type": "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). - A filter object to specify which tools are allowed. + The default format is `{ "type": "text" }` with no additional options. - - `read_only: Optional[bool]` + **Not recommended for gpt-4o and newer models:** - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `tool_names: Optional[List[str]]` + - `class Text: …` - List of allowed tool names. + Default response format. Used to generate text responses. - - `authorization: Optional[str]` + - `type: Literal["text"]` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The type of response format being defined. Always `text`. - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + - `"text"` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `class BetaResponseFormatTextJSONSchemaConfig: …` - Currently supported `connector_id` values are: + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `name: str` - - `"connector_dropbox"` + 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. - - `"connector_gmail"` + - `schema: Dict[str, object]` - - `"connector_googlecalendar"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"connector_googledrive"` + - `type: Literal["json_schema"]` - - `"connector_microsoftteams"` + The type of response format being defined. Always `json_schema`. - - `"connector_outlookcalendar"` + - `"json_schema"` - - `"connector_outlookemail"` + - `description: Optional[str]` - - `"connector_sharepoint"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `defer_loading: Optional[bool]` + - `strict: Optional[bool]` - Whether this MCP tool is deferred and discovered via tool search. + 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). - - `headers: Optional[Dict[str, str]]` + - `class JSONObject: …` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + 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. - - `require_approval: Optional[McpRequireApproval]` + - `type: Literal["json_object"]` - Specify which of the MCP server's tools require approval. + The type of response format being defined. Always `json_object`. - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `"json_object"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `verbosity: Optional[Literal["low", "medium", "high"]]` - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - A filter object to specify which tools are allowed. + - `"low"` - - `read_only: Optional[bool]` + - `"medium"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"high"` - - `tool_names: Optional[List[str]]` +- `tool_choice: Optional[ToolChoice]` - List of allowed tool names. + Controls which tool the model should use, if any. - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + - `Literal["none", "auto", "required"]` - A filter object to specify which tools are allowed. + - `"none"` - - `read_only: Optional[bool]` + - `"auto"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"required"` - - `tool_names: Optional[List[str]]` + - `class BetaToolChoiceAllowed: …` - List of allowed tool names. + Constrains the tools available to the model to a pre-defined set. - - `Literal["always", "never"]` + - `mode: Literal["auto", "required"]` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + Constrains the tools available to the model to a pre-defined set. - - `"always"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `"never"` + `required` requires the model to call one or more of the allowed tools. - - `server_description: Optional[str]` + - `"auto"` - Optional description of the MCP server, used to provide more context. + - `"required"` - - `server_url: Optional[str]` + - `tools: List[Dict[str, object]]` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + A list of tool definitions that the model should be allowed to call. - - `tunnel_id: Optional[str]` + For the Responses API, the list of tool definitions might look like: - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `class CodeInterpreter: …` + - `type: Literal["allowed_tools"]` - A tool that runs Python code to help generate a response to a prompt. + Allowed tool configuration type. Always `allowed_tools`. - - `container: CodeInterpreterContainer` + - `"allowed_tools"` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `class BetaToolChoiceTypes: …` - - `str` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - The container ID. + - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Allowed values are: - - `type: Literal["auto"]` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - Always `auto`. + - `"file_search"` - - `"auto"` + - `"web_search_preview"` - - `file_ids: Optional[List[str]]` + - `"computer"` - An optional list of uploaded files to make available to your code. + - `"computer_use_preview"` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `"computer_use"` - The memory limit for the code interpreter container. + - `"web_search_preview_2025_03_11"` - - `"1g"` + - `"image_generation"` - - `"4g"` + - `"code_interpreter"` - - `"16g"` + - `class BetaToolChoiceFunction: …` - - `"64g"` + Use this option to force the model to call a specific function. - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `name: str` - Network access policy for the container. + The name of the function to call. - - `class BetaContainerNetworkPolicyDisabled: …` + - `type: Literal["function"]` - - `type: Literal["disabled"]` + For function calling, the type is always `function`. - Disable outbound network access. Always `disabled`. + - `"function"` - - `"disabled"` + - `class BetaToolChoiceMcp: …` - - `class BetaContainerNetworkPolicyAllowlist: …` + Use this option to force the model to call a specific tool on a remote MCP server. - - `allowed_domains: List[str]` + - `server_label: str` - A list of allowed domains when type is `allowlist`. + The label of the MCP server to use. - - `type: Literal["allowlist"]` + - `type: Literal["mcp"]` - Allow outbound network access only to specified domains. Always `allowlist`. + For MCP tools, the type is always `mcp`. - - `"allowlist"` + - `"mcp"` - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `name: Optional[str]` - Optional domain-scoped secrets for allowlisted domains. + The name of the tool to call on the server. - - `domain: str` + - `class BetaToolChoiceCustom: …` - The domain associated with the secret. + Use this option to force the model to call a specific custom tool. - `name: str` - The name of the secret to inject for the domain. - - - `value: str` + The name of the custom tool to call. - The secret value to inject for the domain. + - `type: Literal["custom"]` - - `type: Literal["code_interpreter"]` + For custom tool calling, the type is always `custom`. - The type of the code interpreter tool. Always `code_interpreter`. + - `"custom"` - - `"code_interpreter"` + - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["programmatic_tool_calling"]` - The tool invocation context(s). + The tool to call. Always `programmatic_tool_calling`. - - `"direct"` + - `"programmatic_tool_calling"` - - `"programmatic"` + - `class BetaToolChoiceApplyPatch: …` - - `class ProgrammaticToolCalling: …` + Forces the model to call the apply_patch tool when executing a tool call. - - `type: Literal["programmatic_tool_calling"]` + - `type: Literal["apply_patch"]` - The type of the tool. Always `programmatic_tool_calling`. + The tool to call. Always `apply_patch`. - - `"programmatic_tool_calling"` + - `"apply_patch"` - - `class ImageGeneration: …` + - `class BetaToolChoiceShell: …` - A tool that generates images using the GPT image models. + Forces the model to call the shell tool when a tool call is required. - - `type: Literal["image_generation"]` + - `type: Literal["shell"]` - The type of the image generation tool. Always `image_generation`. + The tool to call. Always `shell`. - - `"image_generation"` + - `"shell"` - - `action: Optional[Literal["generate", "edit", "auto"]]` +- `tools: Optional[Iterable[BetaToolParam]]` - Whether to generate a new image or edit an existing image. Default: `auto`. + An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. - - `"generate"` + - `class BetaFunctionTool: …` - - `"edit"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"auto"` + - `class BetaFileSearchTool: …` - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `class BetaComputerTool: …` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `class BetaComputerUsePreviewTool: …` - - `"transparent"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"opaque"` + - `class BetaWebSearchTool: …` - - `"auto"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `input_fidelity: Optional[Literal["high", "low"]]` + - `class Mcp: …` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"high"` + - `class CodeInterpreter: …` - - `"low"` + A tool that runs Python code to help generate a response to a prompt. - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + - `class ProgrammaticToolCalling: …` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `class ImageGeneration: …` - - `file_id: Optional[str]` + A tool that generates images using the GPT image models. - File ID for the mask image. + - `class LocalShell: …` - - `image_url: Optional[str]` + A tool that allows the model to execute shell commands in a local environment. - Base64-encoded mask image. + - `class BetaFunctionShellTool: …` - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + A tool that allows the model to execute shell commands. - The image generation model to use. Default: `gpt-image-1`. + - `class BetaCustomTool: …` - - `str` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `class BetaNamespaceTool: …` - The image generation model to use. Default: `gpt-image-1`. + Groups function/custom tools under a shared namespace. - - `"gpt-image-1"` + - `class BetaToolSearchTool: …` - - `"gpt-image-1-mini"` + Hosted or BYOT tool search configuration for deferred tools. - - `"gpt-image-2"` + - `class BetaWebSearchPreviewTool: …` - - `"gpt-image-2-2026-04-21"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"gpt-image-1.5"` + - `class BetaApplyPatchTool: …` - - `"chatgpt-image-latest"` + Allows the assistant to create, delete, or update files using unified diffs. - - `moderation: Optional[Literal["auto", "low"]]` +- `truncation: Optional[Literal["auto", "disabled"]]` - Moderation level for the generated image. Default: `auto`. + The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error. - `"auto"` - - `"low"` + - `"disabled"` - - `output_compression: Optional[int]` +- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` - Compression level for the output image. Default: 100. + - `"responses_multi_agent=v1"` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` +### Returns - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. +- `class InputTokenCountResponse: …` - - `"png"` + - `input_tokens: int` - - `"webp"` + - `object: Literal["response.input_tokens"]` - - `"jpeg"` + - `"response.input_tokens"` - - `partial_images: Optional[int]` +### Example - Number of partial images to generate in streaming mode, from 0 (default value) to 3. +```python +import os +from openai import OpenAI - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +response = client.beta.responses.input_tokens.count() +print(response.input_tokens) +``` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. +#### Response - - `"low"` +```json +{ + "input_tokens": 123, + "object": "response.input_tokens" +} +``` - - `"medium"` +### Example - - `"high"` +```python +from openai import OpenAI - - `"auto"` +client = OpenAI() - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` +response = client.responses.input_tokens.count( + model="gpt-5", + input="Tell me a joke." +) +print(response.input_tokens) +``` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. +#### Response - - `str` +```json +{ + "object": "response.input_tokens", + "input_tokens": 11 +} +``` - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` +## Domain Types - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. +### Input Token Count Response - - `"1024x1024"` +- `class InputTokenCountResponse: …` - - `"1024x1536"` + - `input_tokens: int` - - `"1536x1024"` + - `object: Literal["response.input_tokens"]` - - `"auto"` + - `"response.input_tokens"` - - `class LocalShell: …` +# ChatKit - A tool that allows the model to execute shell commands in a local environment. +## Domain Types - - `type: Literal["local_shell"]` +### ChatKit Workflow - The type of the local shell tool. Always `local_shell`. +- `class ChatKitWorkflow: …` - - `"local_shell"` + Workflow metadata and state returned for the session. - - `class BetaFunctionShellTool: …` + - `id: str` - A tool that allows the model to execute shell commands. + Identifier of the workflow backing the session. - - `type: Literal["shell"]` + - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` - The type of the shell tool. Always `shell`. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `"shell"` + - `str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `bool` - The tool invocation context(s). + - `float` - - `"direct"` + - `tracing: Tracing` - - `"programmatic"` + Tracing settings applied to the workflow. - - `environment: Optional[Environment]` + - `enabled: bool` - - `class BetaContainerAuto: …` + Indicates whether tracing is enabled. - - `type: Literal["container_auto"]` + - `version: Optional[str]` - Automatically creates a container for this request + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `"container_auto"` +# Sessions - - `file_ids: Optional[List[str]]` +## Cancel chat session - An optional list of uploaded files to make available to your code. +`beta.chatkit.sessions.cancel(strsession_id) -> ChatSession` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` +**post** `/chatkit/sessions/{session_id}/cancel` - The memory limit for the container. +Cancel an active ChatKit session and return its most recent metadata. - - `"1g"` +Cancelling prevents new requests from using the issued client secret. - - `"4g"` +### Parameters - - `"16g"` +- `session_id: str` - - `"64g"` +### Returns - - `network_policy: Optional[NetworkPolicy]` +- `class ChatSession: …` - Network access policy for the container. + Represents a ChatKit session and its resolved configuration. - - `class BetaContainerNetworkPolicyDisabled: …` + - `id: str` - - `class BetaContainerNetworkPolicyAllowlist: …` + Identifier for the ChatKit session. - - `skills: Optional[List[Skill]]` + - `chatkit_configuration: ChatSessionChatKitConfiguration` - An optional list of skills referenced by id or inline data. + Resolved ChatKit feature configuration for the session. - - `class BetaSkillReference: …` + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - - `skill_id: str` + Automatic thread titling preferences. - The ID of the referenced skill. + - `enabled: bool` - - `type: Literal["skill_reference"]` + Whether automatic thread titling is enabled. - References a skill created with the /v1/skills endpoint. + - `file_upload: ChatSessionFileUpload` - - `"skill_reference"` + Upload settings for the session. - - `version: Optional[str]` + - `enabled: bool` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + Indicates if uploads are enabled for the session. - - `class BetaInlineSkill: …` + - `max_file_size: Optional[int]` - - `description: str` + Maximum upload size in megabytes. - The description of the skill. + - `max_files: Optional[int]` - - `name: str` + Maximum number of uploads allowed during the session. - The name of the skill. + - `history: ChatSessionHistory` - - `source: BetaInlineSkillSource` + History retention configuration. - Inline skill payload + - `enabled: bool` - - `data: str` + Indicates if chat history is persisted for the session. - Base64-encoded skill zip bundle. + - `recent_threads: Optional[int]` - - `media_type: Literal["application/zip"]` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - The media type of the inline skill payload. Must be `application/zip`. + - `client_secret: str` - - `"application/zip"` + Ephemeral client secret that authenticates session requests. - - `type: Literal["base64"]` + - `expires_at: int` - The type of the inline skill source. Must be `base64`. + Unix timestamp (in seconds) for when the session expires. + + - `max_requests_per_1_minute: int` + + Convenience copy of the per-minute request limit. + + - `object: Literal["chatkit.session"]` + + Type discriminator that is always `chatkit.session`. - - `"base64"` + - `"chatkit.session"` - - `type: Literal["inline"]` + - `rate_limits: ChatSessionRateLimits` - Defines an inline skill for this request. + Resolved rate limit values. - - `"inline"` + - `max_requests_per_1_minute: int` - - `class BetaLocalEnvironment: …` + Maximum allowed requests per one-minute window. - - `type: Literal["local"]` + - `status: ChatSessionStatus` - Use a local computer environment. + Current lifecycle state of the session. - - `"local"` + - `"active"` - - `skills: Optional[List[BetaLocalSkill]]` + - `"expired"` - An optional list of skills. + - `"cancelled"` - - `description: str` + - `user: str` - The description of the skill. + User identifier associated with the session. - - `name: str` + - `workflow: ChatKitWorkflow` - The name of the skill. + Workflow metadata for the session. - - `path: str` + - `id: str` - The path to the directory containing the skill. + Identifier of the workflow backing the session. - - `class BetaContainerReference: …` + - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` - - `container_id: str` + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - The ID of the referenced container. + - `str` - - `type: Literal["container_reference"]` + - `bool` - References a container created with the /v1/containers endpoint + - `float` - - `"container_reference"` + - `tracing: Tracing` - - `class BetaCustomTool: …` + Tracing settings applied to the workflow. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `enabled: bool` - - `name: str` + Indicates whether tracing is enabled. - The name of the custom tool, used to identify it in tool calls. + - `version: Optional[str]` - - `type: Literal["custom"]` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - The type of the custom tool. Always `custom`. +### Example - - `"custom"` +```python +import os +from openai import OpenAI - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +chat_session = client.beta.chatkit.sessions.cancel( + "cksess_123", +) +print(chat_session.id) +``` - The tool invocation context(s). +#### Response - - `"direct"` +```json +{ + "id": "id", + "chatkit_configuration": { + "automatic_thread_titling": { + "enabled": true + }, + "file_upload": { + "enabled": true, + "max_file_size": 0, + "max_files": 0 + }, + "history": { + "enabled": true, + "recent_threads": 0 + } + }, + "client_secret": "client_secret", + "expires_at": 0, + "max_requests_per_1_minute": 0, + "object": "chatkit.session", + "rate_limits": { + "max_requests_per_1_minute": 0 + }, + "status": "active", + "user": "user", + "workflow": { + "id": "id", + "state_variables": { + "foo": "string" + }, + "tracing": { + "enabled": true + }, + "version": "version" + } +} +``` - - `"programmatic"` +### Example - - `defer_loading: Optional[bool]` +```python +from openai import OpenAI - Whether this tool should be deferred and discovered via tool search. +client = OpenAI() +chat_session = client.beta.chatkit.sessions.cancel( + "cksess_123", +) +print(chat_session.id) +``` - - `description: Optional[str]` +#### Response - Optional description of the custom tool, used to provide more context. +```json +{ + "id": "cksess_123", + "object": "chatkit.session", + "workflow": { + "id": "workflow_alpha", + "version": "1" + }, + "scope": { + "customer_id": "cust_456" + }, + "max_requests_per_1_minute": 30, + "ttl_seconds": 900, + "status": "cancelled", + "cancelled_at": 1712345678 +} +``` - - `format: Optional[Format]` +## Create ChatKit session - The input format for the custom tool. Default is unconstrained text. +`beta.chatkit.sessions.create(SessionCreateParams**kwargs) -> ChatSession` - - `class FormatText: …` +**post** `/chatkit/sessions` - Unconstrained free-form text. +Create a ChatKit session. - - `type: Literal["text"]` +### Parameters - Unconstrained text format. Always `text`. +- `user: str` - - `"text"` + A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. - - `class FormatGrammar: …` +- `workflow: ChatSessionWorkflowParam` - A grammar defined by the user. + Workflow that powers the session. - - `definition: str` + - `id: str` - The grammar definition. + Identifier for the workflow invoked by the session. - - `syntax: Literal["lark", "regex"]` + - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` - The syntax of the grammar definition. One of `lark` or `regex`. + State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. - - `"lark"` + - `str` - - `"regex"` + - `bool` - - `type: Literal["grammar"]` + - `float` - Grammar format. Always `grammar`. + - `tracing: Optional[Tracing]` - - `"grammar"` + Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - - `class BetaNamespaceTool: …` + - `enabled: Optional[bool]` - Groups function/custom tools under a shared namespace. + Whether tracing is enabled during the session. Defaults to true. - - `description: str` + - `version: Optional[str]` - A description of the namespace shown to the model. + Specific workflow version to run. Defaults to the latest deployed version. - - `name: str` +- `chatkit_configuration: Optional[ChatSessionChatKitConfigurationParam]` - The namespace name used in tool calls (for example, `crm`). + Optional overrides for ChatKit runtime configuration features - - `tools: List[Tool]` + - `automatic_thread_titling: Optional[AutomaticThreadTitling]` - The function/custom tools available inside this namespace. + Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - - `class ToolFunction: …` + - `enabled: Optional[bool]` - - `name: str` + Enable automatic thread title generation. Defaults to true. - - `type: Literal["function"]` + - `file_upload: Optional[FileUpload]` - - `"function"` + Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `enabled: Optional[bool]` - The tool invocation context(s). + Enable uploads for this session. Defaults to false. - - `"direct"` + - `max_file_size: Optional[int]` - - `"programmatic"` + Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - - `defer_loading: Optional[bool]` + - `max_files: Optional[int]` - Whether this function should be deferred and discovered via tool search. + Maximum number of files that can be uploaded to the session. Defaults to 10. - - `description: Optional[str]` + - `history: Optional[History]` - - `output_schema: Optional[Dict[str, object]]` + Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `enabled: Optional[bool]` - - `parameters: Optional[object]` + Enables chat users to access previous ChatKit threads. Defaults to true. - - `strict: Optional[bool]` + - `recent_threads: Optional[int]` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. - - `class BetaCustomTool: …` +- `expires_after: Optional[ChatSessionExpiresAfterParam]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. - - `type: Literal["namespace"]` + - `anchor: Literal["created_at"]` - The type of the tool. Always `namespace`. + Base timestamp used to calculate expiration. Currently fixed to `created_at`. - - `"namespace"` + - `"created_at"` - - `class BetaToolSearchTool: …` + - `seconds: int` - Hosted or BYOT tool search configuration for deferred tools. + Number of seconds after the anchor when the session expires. - - `type: Literal["tool_search"]` +- `rate_limits: Optional[ChatSessionRateLimitsParam]` - The type of the tool. Always `tool_search`. + Optional override for per-minute request limits. When omitted, defaults to 10. - - `"tool_search"` + - `max_requests_per_1_minute: Optional[int]` - - `description: Optional[str]` + Maximum number of requests allowed per minute for the session. Defaults to 10. - Description shown to the model for a client-executed tool search tool. +### Returns - - `execution: Optional[Literal["server", "client"]]` +- `class ChatSession: …` - Whether tool search is executed by the server or by the client. + Represents a ChatKit session and its resolved configuration. - - `"server"` + - `id: str` - - `"client"` + Identifier for the ChatKit session. - - `parameters: Optional[object]` + - `chatkit_configuration: ChatSessionChatKitConfiguration` - Parameter schema for a client-executed tool search tool. + Resolved ChatKit feature configuration for the session. - - `class BetaWebSearchPreviewTool: …` + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Automatic thread titling preferences. - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + - `enabled: bool` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + Whether automatic thread titling is enabled. - - `"web_search_preview"` + - `file_upload: ChatSessionFileUpload` - - `"web_search_preview_2025_03_11"` + Upload settings for the session. - - `search_content_types: Optional[List[Literal["text", "image"]]]` + - `enabled: bool` - - `"text"` + Indicates if uploads are enabled for the session. - - `"image"` + - `max_file_size: Optional[int]` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + Maximum upload size in megabytes. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `max_files: Optional[int]` - - `"low"` + Maximum number of uploads allowed during the session. - - `"medium"` + - `history: ChatSessionHistory` - - `"high"` + History retention configuration. - - `user_location: Optional[UserLocation]` + - `enabled: bool` - The user's location. + Indicates if chat history is persisted for the session. - - `type: Literal["approximate"]` + - `recent_threads: Optional[int]` - The type of location approximation. Always `approximate`. + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `"approximate"` + - `client_secret: str` - - `city: Optional[str]` + Ephemeral client secret that authenticates session requests. - Free text input for the city of the user, e.g. `San Francisco`. + - `expires_at: int` - - `country: Optional[str]` + Unix timestamp (in seconds) for when the session expires. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `max_requests_per_1_minute: int` - - `region: Optional[str]` + Convenience copy of the per-minute request limit. - Free text input for the region of the user, e.g. `California`. + - `object: Literal["chatkit.session"]` - - `timezone: Optional[str]` + Type discriminator that is always `chatkit.session`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"chatkit.session"` - - `class BetaApplyPatchTool: …` + - `rate_limits: ChatSessionRateLimits` - Allows the assistant to create, delete, or update files using unified diffs. + Resolved rate limit values. - - `type: Literal["apply_patch"]` + - `max_requests_per_1_minute: int` - The type of the tool. Always `apply_patch`. + Maximum allowed requests per one-minute window. - - `"apply_patch"` + - `status: ChatSessionStatus` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + Current lifecycle state of the session. - The tool invocation context(s). + - `"active"` - - `"direct"` + - `"expired"` - - `"programmatic"` + - `"cancelled"` - - `type: Literal["tool_search_output"]` + - `user: str` - The item type. Always `tool_search_output`. + User identifier associated with the session. - - `"tool_search_output"` + - `workflow: ChatKitWorkflow` - - `id: Optional[str]` + Workflow metadata for the session. - The unique ID of this tool search output. + - `id: str` - - `agent: Optional[Agent]` + Identifier of the workflow backing the session. - The agent that produced this item. + - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` - - `agent_name: str` + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - The canonical name of the agent that produced this item. + - `str` - - `call_id: Optional[str]` + - `bool` - The unique ID of the tool search call generated by the model. + - `float` - - `execution: Optional[Literal["server", "client"]]` + - `tracing: Tracing` - Whether tool search was executed by the server or by the client. + Tracing settings applied to the workflow. - - `"server"` + - `enabled: bool` - - `"client"` + Indicates whether tracing is enabled. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `version: Optional[str]` - The status of the tool search output. + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `"in_progress"` +### Example - - `"completed"` +```python +import os +from openai import OpenAI - - `"incomplete"` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +chat_session = client.beta.chatkit.sessions.create( + user="x", + workflow={ + "id": "id" + }, +) +print(chat_session.id) +``` - - `class AdditionalTools: …` +#### Response - - `role: Literal["developer"]` +```json +{ + "id": "id", + "chatkit_configuration": { + "automatic_thread_titling": { + "enabled": true + }, + "file_upload": { + "enabled": true, + "max_file_size": 0, + "max_files": 0 + }, + "history": { + "enabled": true, + "recent_threads": 0 + } + }, + "client_secret": "client_secret", + "expires_at": 0, + "max_requests_per_1_minute": 0, + "object": "chatkit.session", + "rate_limits": { + "max_requests_per_1_minute": 0 + }, + "status": "active", + "user": "user", + "workflow": { + "id": "id", + "state_variables": { + "foo": "string" + }, + "tracing": { + "enabled": true + }, + "version": "version" + } +} +``` - The role that provided the additional tools. Only `developer` is supported. +### Example - - `"developer"` +```python +from openai import OpenAI - - `tools: List[BetaTool]` +client = OpenAI() +chat_session = client.beta.chatkit.sessions.create( + user="user", + workflow={ + "id": "id" + }, +) +print(chat_session.id) +``` - A list of additional tools made available at this item. +#### Response - - `class BetaFunctionTool: …` +```json +{ + "client_secret": "chatkit_token_123", + "expires_at": 1735689600, + "workflow": { + "id": "workflow_alpha", + "version": "2024-10-01" + }, + "scope": { + "project": "alpha", + "environment": "staging" + }, + "max_requests_per_1_minute": 60, + "max_requests_per_session": 500, + "status": "active" +} +``` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). +# Threads - - `class BetaFileSearchTool: …` +## List ChatKit thread items - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). +`beta.chatkit.threads.list_items(strthread_id, ThreadListItemsParams**kwargs) -> SyncConversationCursorPage[Data]` - - `class BetaComputerTool: …` +**get** `/chatkit/threads/{thread_id}/items` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +List items that belong to a ChatKit thread. - - `class BetaComputerUsePreviewTool: …` +### Parameters - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +- `thread_id: str` - - `class BetaWebSearchTool: …` +- `after: Optional[str]` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + List items created after this thread item ID. Defaults to null for the first page. - - `class Mcp: …` +- `before: Optional[str]` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + List items created before this thread item ID. Defaults to null for the newest results. - - `class CodeInterpreter: …` +- `limit: Optional[int]` - A tool that runs Python code to help generate a response to a prompt. + Maximum number of thread items to return. Defaults to 20. - - `class ProgrammaticToolCalling: …` +- `order: Optional[Literal["asc", "desc"]]` - - `class ImageGeneration: …` + Sort order for results by creation time. Defaults to `desc`. - A tool that generates images using the GPT image models. + - `"asc"` - - `class LocalShell: …` + - `"desc"` - A tool that allows the model to execute shell commands in a local environment. +### Returns - - `class BetaFunctionShellTool: …` +- `Data` - A tool that allows the model to execute shell commands. + - `class ChatKitThreadUserMessageItem: …` - - `class BetaCustomTool: …` + User-authored messages within a thread. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `id: str` - - `class BetaNamespaceTool: …` + Identifier of the thread item. - Groups function/custom tools under a shared namespace. + - `attachments: List[ChatKitAttachment]` - - `class BetaToolSearchTool: …` + Attachments associated with the user message. Defaults to an empty list. - Hosted or BYOT tool search configuration for deferred tools. + - `id: str` - - `class BetaWebSearchPreviewTool: …` + Identifier for the attachment. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `mime_type: str` - - `class BetaApplyPatchTool: …` + MIME type of the attachment. - Allows the assistant to create, delete, or update files using unified diffs. + - `name: str` - - `type: Literal["additional_tools"]` + Original display name for the attachment. - The item type. Always `additional_tools`. + - `preview_url: Optional[str]` - - `"additional_tools"` + Preview URL for rendering the attachment inline. - - `id: Optional[str]` + - `type: Literal["image", "file"]` - The unique ID of this additional tools item. + Attachment discriminator. - - `agent: Optional[AdditionalToolsAgent]` + - `"image"` - The agent that produced this item. + - `"file"` - - `agent_name: str` + - `content: List[Content]` - The canonical name of the agent that produced this item. + Ordered content elements supplied by the user. - - `class BetaResponseReasoningItem: …` + - `class ContentInputText: …` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + Text block that a user contributed to the thread. - - `id: str` + - `text: str` - The unique identifier of the reasoning content. + Plain-text content supplied by the user. - - `summary: List[Summary]` + - `type: Literal["input_text"]` - Reasoning summary content. + Type discriminator that is always `input_text`. - - `text: str` + - `"input_text"` - A summary of the reasoning output from the model so far. + - `class ContentQuotedText: …` - - `type: Literal["summary_text"]` + Quoted snippet that the user referenced in their message. - The type of the object. Always `summary_text`. + - `text: str` - - `"summary_text"` + Quoted text content. - - `type: Literal["reasoning"]` + - `type: Literal["quoted_text"]` - The type of the object. Always `reasoning`. + Type discriminator that is always `quoted_text`. - - `"reasoning"` + - `"quoted_text"` - - `agent: Optional[Agent]` + - `created_at: int` - The agent that produced this item. + Unix timestamp (in seconds) for when the item was created. - - `agent_name: str` + - `inference_options: Optional[InferenceOptions]` - The canonical name of the agent that produced this item. + Inference overrides applied to the message. Defaults to null when unset. - - `content: Optional[List[Content]]` + - `model: Optional[str]` - Reasoning text content. + Model name that generated the response. Defaults to null when using the session default. - - `text: str` + - `tool_choice: Optional[InferenceOptionsToolChoice]` - The reasoning text from the model. + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - - `type: Literal["reasoning_text"]` + - `id: str` - The type of the reasoning text. Always `reasoning_text`. + Identifier of the requested tool. - - `"reasoning_text"` + - `object: Literal["chatkit.thread_item"]` - - `encrypted_content: Optional[str]` + Type discriminator that is always `chatkit.thread_item`. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"chatkit.thread_item"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `thread_id: str` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Identifier of the parent thread. - - `"in_progress"` + - `type: Literal["chatkit.user_message"]` - - `"completed"` + - `"chatkit.user_message"` - - `"incomplete"` + - `class ChatKitThreadAssistantMessageItem: …` - - `class BetaResponseCompactionItemParam: …` + Assistant-authored message within a thread. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `id: str` - - `encrypted_content: str` + Identifier of the thread item. - The encrypted content of the compaction summary. + - `content: List[ChatKitResponseOutputText]` - - `type: Literal["compaction"]` + Ordered assistant response segments. - The type of the item. Always `compaction`. + - `annotations: List[Annotation]` - - `"compaction"` + Ordered list of annotations attached to the response text. - - `id: Optional[str]` + - `class AnnotationFile: …` - The ID of the compaction item. + Annotation that references an uploaded file. - - `agent: Optional[Agent]` + - `source: AnnotationFileSource` - The agent that produced this item. + File attachment referenced by the annotation. - - `agent_name: str` + - `filename: str` - The canonical name of the agent that produced this item. + Filename referenced by the annotation. - - `class ImageGenerationCall: …` + - `type: Literal["file"]` - An image generation request made by the model. + Type discriminator that is always `file`. - - `id: str` + - `"file"` - The unique ID of the image generation call. + - `type: Literal["file"]` - - `result: Optional[str]` + Type discriminator that is always `file` for this annotation. - The generated image encoded in base64. + - `"file"` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `class AnnotationURL: …` - The status of the image generation call. + Annotation that references a URL. - - `"in_progress"` + - `source: AnnotationURLSource` - - `"completed"` + URL referenced by the annotation. - - `"generating"` + - `type: Literal["url"]` - - `"failed"` + Type discriminator that is always `url`. - - `type: Literal["image_generation_call"]` + - `"url"` - The type of the image generation call. Always `image_generation_call`. + - `url: str` - - `"image_generation_call"` + URL referenced by the annotation. - - `agent: Optional[ImageGenerationCallAgent]` + - `type: Literal["url"]` - The agent that produced this item. + Type discriminator that is always `url` for this annotation. - - `agent_name: str` + - `"url"` - The canonical name of the agent that produced this item. + - `text: str` - - `class BetaResponseCodeInterpreterToolCall: …` + Assistant generated text. - A tool call to run code. + - `type: Literal["output_text"]` - - `id: str` + Type discriminator that is always `output_text`. - The unique ID of the code interpreter tool call. + - `"output_text"` - - `code: Optional[str]` + - `created_at: int` - The code to run, or null if not available. + Unix timestamp (in seconds) for when the item was created. - - `container_id: str` + - `object: Literal["chatkit.thread_item"]` - The ID of the container used to run the code. + Type discriminator that is always `chatkit.thread_item`. - - `outputs: Optional[List[Output]]` + - `"chatkit.thread_item"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `thread_id: str` - - `class OutputLogs: …` + Identifier of the parent thread. - The logs output from the code interpreter. + - `type: Literal["chatkit.assistant_message"]` - - `logs: str` + Type discriminator that is always `chatkit.assistant_message`. - The logs output from the code interpreter. + - `"chatkit.assistant_message"` - - `type: Literal["logs"]` + - `class ChatKitWidgetItem: …` - The type of the output. Always `logs`. + Thread item that renders a widget payload. - - `"logs"` + - `id: str` - - `class OutputImage: …` + Identifier of the thread item. - The image output from the code interpreter. + - `created_at: int` - - `type: Literal["image"]` + Unix timestamp (in seconds) for when the item was created. - The type of the output. Always `image`. + - `object: Literal["chatkit.thread_item"]` - - `"image"` + Type discriminator that is always `chatkit.thread_item`. - - `url: str` + - `"chatkit.thread_item"` - The URL of the image output from the code interpreter. + - `thread_id: str` - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + Identifier of the parent thread. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `type: Literal["chatkit.widget"]` - - `"in_progress"` + Type discriminator that is always `chatkit.widget`. - - `"completed"` + - `"chatkit.widget"` - - `"incomplete"` + - `widget: str` - - `"interpreting"` + Serialized widget payload rendered in the UI. - - `"failed"` + - `class DataChatKitClientToolCall: …` - - `type: Literal["code_interpreter_call"]` + Record of a client side tool invocation initiated by the assistant. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `id: str` - - `"code_interpreter_call"` + Identifier of the thread item. - - `agent: Optional[Agent]` + - `arguments: str` - The agent that produced this item. + JSON-encoded arguments that were sent to the tool. - - `agent_name: str` + - `call_id: str` - The canonical name of the agent that produced this item. + Identifier for the client tool call. - - `class LocalShellCall: …` + - `created_at: int` - A tool call to run a command on the local shell. + Unix timestamp (in seconds) for when the item was created. - - `id: str` + - `name: str` - The unique ID of the local shell call. + Tool name that was invoked. - - `action: LocalShellCallAction` + - `object: Literal["chatkit.thread_item"]` - Execute a shell command on the server. + Type discriminator that is always `chatkit.thread_item`. - - `command: List[str]` + - `"chatkit.thread_item"` - The command to run. + - `output: Optional[str]` - - `env: Dict[str, str]` + JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - Environment variables to set for the command. + - `status: Literal["in_progress", "completed"]` - - `type: Literal["exec"]` + Execution status for the tool call. - The type of the local shell action. Always `exec`. + - `"in_progress"` - - `"exec"` + - `"completed"` - - `timeout_ms: Optional[int]` + - `thread_id: str` - Optional timeout in milliseconds for the command. + Identifier of the parent thread. - - `user: Optional[str]` + - `type: Literal["chatkit.client_tool_call"]` - Optional user to run the command as. + Type discriminator that is always `chatkit.client_tool_call`. - - `working_directory: Optional[str]` + - `"chatkit.client_tool_call"` - Optional working directory to run the command in. + - `class DataChatKitTask: …` - - `call_id: str` + Task emitted by the workflow to show progress and status updates. - The unique ID of the local shell tool call generated by the model. + - `id: str` - - `status: Literal["in_progress", "completed", "incomplete"]` + Identifier of the thread item. - The status of the local shell call. + - `created_at: int` - - `"in_progress"` + Unix timestamp (in seconds) for when the item was created. - - `"completed"` + - `heading: Optional[str]` - - `"incomplete"` + Optional heading for the task. Defaults to null when not provided. - - `type: Literal["local_shell_call"]` + - `object: Literal["chatkit.thread_item"]` - The type of the local shell call. Always `local_shell_call`. + Type discriminator that is always `chatkit.thread_item`. - - `"local_shell_call"` + - `"chatkit.thread_item"` - - `agent: Optional[LocalShellCallAgent]` + - `summary: Optional[str]` - The agent that produced this item. + Optional summary that describes the task. Defaults to null when omitted. - - `agent_name: str` + - `task_type: Literal["custom", "thought"]` - The canonical name of the agent that produced this item. + Subtype for the task. - - `class LocalShellCallOutput: …` + - `"custom"` - The output of a local shell tool call. + - `"thought"` - - `id: str` + - `thread_id: str` - The unique ID of the local shell tool call generated by the model. + Identifier of the parent thread. - - `output: str` + - `type: Literal["chatkit.task"]` - A JSON string of the output of the local shell tool call. + Type discriminator that is always `chatkit.task`. - - `type: Literal["local_shell_call_output"]` + - `"chatkit.task"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `class DataChatKitTaskGroup: …` - - `"local_shell_call_output"` + Collection of workflow tasks grouped together in the thread. - - `agent: Optional[LocalShellCallOutputAgent]` + - `id: str` - The agent that produced this item. + Identifier of the thread item. - - `agent_name: str` + - `created_at: int` - The canonical name of the agent that produced this item. + Unix timestamp (in seconds) for when the item was created. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `object: Literal["chatkit.thread_item"]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Type discriminator that is always `chatkit.thread_item`. - - `"in_progress"` + - `"chatkit.thread_item"` - - `"completed"` + - `tasks: List[DataChatKitTaskGroupTask]` - - `"incomplete"` + Tasks included in the group. - - `class ShellCall: …` + - `heading: Optional[str]` - A tool representing a request to execute one or more shell commands. + Optional heading for the grouped task. Defaults to null when not provided. - - `action: ShellCallAction` + - `summary: Optional[str]` - The shell commands and limits that describe how to run the tool call. + Optional summary that describes the grouped task. Defaults to null when omitted. - - `commands: List[str]` + - `type: Literal["custom", "thought"]` - Ordered shell commands for the execution environment to run. + Subtype for the grouped task. - - `max_output_length: Optional[int]` + - `"custom"` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `"thought"` - - `timeout_ms: Optional[int]` + - `thread_id: str` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Identifier of the parent thread. - - `call_id: str` + - `type: Literal["chatkit.task_group"]` - The unique ID of the shell tool call generated by the model. + Type discriminator that is always `chatkit.task_group`. - - `type: Literal["shell_call"]` + - `"chatkit.task_group"` - The type of the item. Always `shell_call`. +### Example - - `"shell_call"` +```python +import os +from openai import OpenAI - - `id: Optional[str]` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +page = client.beta.chatkit.threads.list_items( + thread_id="cthr_123", +) +page = page.data[0] +print(page) +``` - The unique ID of the shell tool call. Populated when this item is returned via API. +#### Response - - `agent: Optional[ShellCallAgent]` +```json +{ + "data": [ + { + "id": "id", + "attachments": [ + { + "id": "id", + "mime_type": "mime_type", + "name": "name", + "preview_url": "https://example.com", + "type": "image" + } + ], + "content": [ + { + "text": "text", + "type": "input_text" + } + ], + "created_at": 0, + "inference_options": { + "model": "model", + "tool_choice": { + "id": "id" + } + }, + "object": "chatkit.thread_item", + "thread_id": "thread_id", + "type": "chatkit.user_message" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - The agent that produced this item. +### Example - - `agent_name: str` +```python +from openai import OpenAI - The canonical name of the agent that produced this item. +client = OpenAI() +page = client.beta.chatkit.threads.list_items( + thread_id="cthr_123", +) +page = page.data[0] +print(page) +``` - - `caller: Optional[ShellCallCaller]` +#### Response - The execution context that produced this tool call. +```json +{ + "data": [ + { + "id": "cthi_user_001", + "object": "chatkit.thread_item", + "type": "user_message", + "content": [ + { + "type": "input_text", + "text": "I need help debugging an onboarding issue." + } + ], + "attachments": [] + }, + { + "id": "cthi_assistant_002", + "object": "chatkit.thread_item", + "type": "assistant_message", + "content": [ + { + "type": "output_text", + "text": "Let's start by confirming the workflow version you deployed." + } + ] + } + ], + "has_more": false, + "object": "list" +} +``` - - `class ShellCallCallerDirect: …` +## Retrieve ChatKit thread - - `type: Literal["direct"]` +`beta.chatkit.threads.retrieve(strthread_id) -> ChatKitThread` - The caller type. Always `direct`. +**get** `/chatkit/threads/{thread_id}` - - `"direct"` +Retrieve a ChatKit thread by its identifier. - - `class ShellCallCallerProgram: …` +### Parameters - - `caller_id: str` +- `thread_id: str` - The call ID of the program item that produced this tool call. +### Returns - - `type: Literal["program"]` +- `class ChatKitThread: …` - The caller type. Always `program`. + Represents a ChatKit thread and its current status. - - `"program"` + - `id: str` - - `environment: Optional[ShellCallEnvironment]` + Identifier of the thread. - The environment to execute the shell commands in. + - `created_at: int` - - `class BetaLocalEnvironment: …` + Unix timestamp (in seconds) for when the thread was created. - - `class BetaContainerReference: …` + - `object: Literal["chatkit.thread"]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + Type discriminator that is always `chatkit.thread`. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"chatkit.thread"` - - `"in_progress"` + - `status: Status` - - `"completed"` + Current status for the thread. Defaults to `active` for newly created threads. - - `"incomplete"` + - `class StatusActive: …` - - `class ShellCallOutput: …` + Indicates that a thread is active. - The streamed output items emitted by a shell tool call. + - `type: Literal["active"]` - - `call_id: str` + Status discriminator that is always `active`. - The unique ID of the shell tool call generated by the model. + - `"active"` - - `output: List[BetaResponseFunctionShellCallOutputContent]` + - `class StatusLocked: …` - Captured chunks of stdout and stderr output, along with their associated outcomes. + Indicates that a thread is locked and cannot accept new input. - - `outcome: Outcome` + - `reason: Optional[str]` - The exit or timeout outcome associated with this shell call. + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `class OutcomeTimeout: …` + - `type: Literal["locked"]` - Indicates that the shell call exceeded its configured time limit. + Status discriminator that is always `locked`. - - `type: Literal["timeout"]` + - `"locked"` - The outcome type. Always `timeout`. + - `class StatusClosed: …` - - `"timeout"` + Indicates that a thread has been closed. - - `class OutcomeExit: …` + - `reason: Optional[str]` - Indicates that the shell commands finished and returned an exit code. + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `exit_code: int` + - `type: Literal["closed"]` - The exit code returned by the shell process. + Status discriminator that is always `closed`. - - `type: Literal["exit"]` + - `"closed"` - The outcome type. Always `exit`. + - `title: Optional[str]` - - `"exit"` + Optional human-readable title for the thread. Defaults to null when no title has been generated. - - `stderr: str` + - `user: str` - Captured stderr output for the shell call. + Free-form string that identifies your end user who owns the thread. - - `stdout: str` +### Example - Captured stdout output for the shell call. +```python +import os +from openai import OpenAI - - `type: Literal["shell_call_output"]` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +chatkit_thread = client.beta.chatkit.threads.retrieve( + "cthr_123", +) +print(chatkit_thread.id) +``` - The type of the item. Always `shell_call_output`. +#### Response - - `"shell_call_output"` +```json +{ + "id": "cthr_def456", + "created_at": 1712345600, + "object": "chatkit.thread", + "status": { + "type": "active" + }, + "title": "Demo feedback", + "user": "user_456" +} +``` - - `id: Optional[str]` +### Example - The unique ID of the shell tool call output. Populated when this item is returned via API. +```python +from openai import OpenAI - - `agent: Optional[ShellCallOutputAgent]` +client = OpenAI() +chatkit_thread = client.beta.chatkit.threads.retrieve( + "cthr_123", +) +print(chatkit_thread.id) +``` - The agent that produced this item. +#### Response - - `agent_name: str` +```json +{ + "id": "cthr_abc123", + "object": "chatkit.thread", + "title": "Customer escalation", + "items": { + "data": [ + { + "id": "cthi_user_001", + "object": "chatkit.thread_item", + "type": "user_message", + "content": [ + { + "type": "input_text", + "text": "I need help debugging an onboarding issue." + } + ], + "attachments": [] + }, + { + "id": "cthi_assistant_002", + "object": "chatkit.thread_item", + "type": "assistant_message", + "content": [ + { + "type": "output_text", + "text": "Let's start by confirming the workflow version you deployed." + } + ] + } + ], + "has_more": false + } +} +``` - The canonical name of the agent that produced this item. +## Delete ChatKit thread - - `caller: Optional[ShellCallOutputCaller]` +`beta.chatkit.threads.delete(strthread_id) -> ThreadDeleteResponse` - The execution context that produced this tool call. +**delete** `/chatkit/threads/{thread_id}` - - `class ShellCallOutputCallerDirect: …` +Delete a ChatKit thread along with its items and stored attachments. - - `type: Literal["direct"]` +### Parameters - The caller type. Always `direct`. +- `thread_id: str` - - `"direct"` +### Returns - - `class ShellCallOutputCallerProgram: …` +- `class ThreadDeleteResponse: …` - - `caller_id: str` + Confirmation payload returned after deleting a thread. - The call ID of the program item that produced this tool call. + - `id: str` - - `type: Literal["program"]` + Identifier of the deleted thread. - The caller type. Always `program`. + - `deleted: bool` - - `"program"` + Indicates that the thread has been deleted. - - `max_output_length: Optional[int]` + - `object: Literal["chatkit.thread.deleted"]` - The maximum number of UTF-8 characters captured for this shell call's combined output. + Type discriminator that is always `chatkit.thread.deleted`. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"chatkit.thread.deleted"` - The status of the shell call output. +### Example - - `"in_progress"` +```python +import os +from openai import OpenAI - - `"completed"` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +thread = client.beta.chatkit.threads.delete( + "cthr_123", +) +print(thread.id) +``` - - `"incomplete"` +#### Response - - `class ApplyPatchCall: …` +```json +{ + "id": "id", + "deleted": true, + "object": "chatkit.thread.deleted" +} +``` - A tool call representing a request to create, delete, or update files using diff patches. +### Example - - `call_id: str` +```python +from openai import OpenAI - The unique ID of the apply patch tool call generated by the model. +client = OpenAI() +thread = client.beta.chat_kit.threads.delete( + "cthr_123", +) +print(thread.id) +``` - - `operation: ApplyPatchCallOperation` +## List ChatKit threads - The specific create, delete, or update instruction for the apply_patch tool call. +`beta.chatkit.threads.list(ThreadListParams**kwargs) -> SyncConversationCursorPage[ChatKitThread]` - - `class ApplyPatchCallOperationCreateFile: …` +**get** `/chatkit/threads` - Instruction for creating a new file via the apply_patch tool. +List ChatKit threads with optional pagination and user filters. - - `diff: str` +### Parameters - Unified diff content to apply when creating the file. +- `after: Optional[str]` - - `path: str` + List items created after this thread item ID. Defaults to null for the first page. - Path of the file to create relative to the workspace root. +- `before: Optional[str]` - - `type: Literal["create_file"]` + List items created before this thread item ID. Defaults to null for the newest results. - The operation type. Always `create_file`. +- `limit: Optional[int]` - - `"create_file"` + Maximum number of thread items to return. Defaults to 20. - - `class ApplyPatchCallOperationDeleteFile: …` +- `order: Optional[Literal["asc", "desc"]]` - Instruction for deleting an existing file via the apply_patch tool. + Sort order for results by creation time. Defaults to `desc`. - - `path: str` + - `"asc"` - Path of the file to delete relative to the workspace root. + - `"desc"` - - `type: Literal["delete_file"]` +- `user: Optional[str]` - The operation type. Always `delete_file`. + Filter threads that belong to this user identifier. Defaults to null to return all users. - - `"delete_file"` +### Returns - - `class ApplyPatchCallOperationUpdateFile: …` +- `class ChatKitThread: …` - Instruction for updating an existing file via the apply_patch tool. + Represents a ChatKit thread and its current status. - - `diff: str` + - `id: str` - Unified diff content to apply to the existing file. + Identifier of the thread. - - `path: str` + - `created_at: int` - Path of the file to update relative to the workspace root. + Unix timestamp (in seconds) for when the thread was created. - - `type: Literal["update_file"]` + - `object: Literal["chatkit.thread"]` - The operation type. Always `update_file`. + Type discriminator that is always `chatkit.thread`. - - `"update_file"` + - `"chatkit.thread"` - - `status: Literal["in_progress", "completed"]` + - `status: Status` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Current status for the thread. Defaults to `active` for newly created threads. - - `"in_progress"` + - `class StatusActive: …` - - `"completed"` + Indicates that a thread is active. - - `type: Literal["apply_patch_call"]` + - `type: Literal["active"]` - The type of the item. Always `apply_patch_call`. + Status discriminator that is always `active`. - - `"apply_patch_call"` + - `"active"` - - `id: Optional[str]` + - `class StatusLocked: …` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Indicates that a thread is locked and cannot accept new input. - - `agent: Optional[ApplyPatchCallAgent]` + - `reason: Optional[str]` - The agent that produced this item. + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `agent_name: str` + - `type: Literal["locked"]` - The canonical name of the agent that produced this item. + Status discriminator that is always `locked`. - - `caller: Optional[ApplyPatchCallCaller]` + - `"locked"` - The execution context that produced this tool call. + - `class StatusClosed: …` - - `class ApplyPatchCallCallerDirect: …` + Indicates that a thread has been closed. - - `type: Literal["direct"]` + - `reason: Optional[str]` - The caller type. Always `direct`. + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `"direct"` + - `type: Literal["closed"]` - - `class ApplyPatchCallCallerProgram: …` + Status discriminator that is always `closed`. - - `caller_id: str` + - `"closed"` - The call ID of the program item that produced this tool call. + - `title: Optional[str]` - - `type: Literal["program"]` + Optional human-readable title for the thread. Defaults to null when no title has been generated. - The caller type. Always `program`. + - `user: str` - - `"program"` + Free-form string that identifies your end user who owns the thread. - - `class ApplyPatchCallOutput: …` +### Example - The streamed output emitted by an apply patch tool call. +```python +import os +from openai import OpenAI - - `call_id: str` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +page = client.beta.chatkit.threads.list() +page = page.data[0] +print(page.id) +``` - The unique ID of the apply patch tool call generated by the model. +#### Response - - `status: Literal["completed", "failed"]` +```json +{ + "data": [ + { + "id": "cthr_def456", + "created_at": 1712345600, + "object": "chatkit.thread", + "status": { + "type": "active" + }, + "title": "Demo feedback", + "user": "user_456" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - The status of the apply patch tool call output. One of `completed` or `failed`. +### Example - - `"completed"` +```python +from openai import OpenAI - - `"failed"` +client = OpenAI() +page = client.beta.chatkit.threads.list() +page = page.data[0] +print(page.id) +``` - - `type: Literal["apply_patch_call_output"]` +#### Response - The type of the item. Always `apply_patch_call_output`. +```json +{ + "data": [ + { + "id": "cthr_abc123", + "object": "chatkit.thread", + "title": "Customer escalation" + }, + { + "id": "cthr_def456", + "object": "chatkit.thread", + "title": "Demo feedback" + } + ], + "has_more": false, + "object": "list" +} +``` - - `"apply_patch_call_output"` +## Domain Types - - `id: Optional[str]` +### Chat Session - The unique ID of the apply patch tool call output. Populated when this item is returned via API. +- `class ChatSession: …` - - `agent: Optional[ApplyPatchCallOutputAgent]` + Represents a ChatKit session and its resolved configuration. - The agent that produced this item. + - `id: str` - - `agent_name: str` + Identifier for the ChatKit session. - The canonical name of the agent that produced this item. + - `chatkit_configuration: ChatSessionChatKitConfiguration` - - `caller: Optional[ApplyPatchCallOutputCaller]` + Resolved ChatKit feature configuration for the session. - The execution context that produced this tool call. + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - - `class ApplyPatchCallOutputCallerDirect: …` + Automatic thread titling preferences. - - `type: Literal["direct"]` + - `enabled: bool` - The caller type. Always `direct`. + Whether automatic thread titling is enabled. - - `"direct"` + - `file_upload: ChatSessionFileUpload` - - `class ApplyPatchCallOutputCallerProgram: …` + Upload settings for the session. - - `caller_id: str` + - `enabled: bool` - The call ID of the program item that produced this tool call. + Indicates if uploads are enabled for the session. - - `type: Literal["program"]` + - `max_file_size: Optional[int]` - The caller type. Always `program`. + Maximum upload size in megabytes. - - `"program"` + - `max_files: Optional[int]` - - `output: Optional[str]` + Maximum number of uploads allowed during the session. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `history: ChatSessionHistory` - - `class McpListTools: …` + History retention configuration. - A list of tools available on an MCP server. + - `enabled: bool` - - `id: str` + Indicates if chat history is persisted for the session. - The unique ID of the list. + - `recent_threads: Optional[int]` - - `server_label: str` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - The label of the MCP server. + - `client_secret: str` - - `tools: List[McpListToolsTool]` + Ephemeral client secret that authenticates session requests. - The tools available on the server. + - `expires_at: int` - - `input_schema: object` + Unix timestamp (in seconds) for when the session expires. - The JSON schema describing the tool's input. + - `max_requests_per_1_minute: int` - - `name: str` + Convenience copy of the per-minute request limit. - The name of the tool. + - `object: Literal["chatkit.session"]` - - `annotations: Optional[object]` + Type discriminator that is always `chatkit.session`. - Additional annotations about the tool. + - `"chatkit.session"` - - `description: Optional[str]` + - `rate_limits: ChatSessionRateLimits` - The description of the tool. + Resolved rate limit values. - - `type: Literal["mcp_list_tools"]` + - `max_requests_per_1_minute: int` - The type of the item. Always `mcp_list_tools`. + Maximum allowed requests per one-minute window. - - `"mcp_list_tools"` + - `status: ChatSessionStatus` - - `agent: Optional[McpListToolsAgent]` + Current lifecycle state of the session. - The agent that produced this item. + - `"active"` - - `agent_name: str` + - `"expired"` - The canonical name of the agent that produced this item. + - `"cancelled"` - - `error: Optional[str]` + - `user: str` - Error message if the server could not list tools. + User identifier associated with the session. - - `class McpApprovalRequest: …` + - `workflow: ChatKitWorkflow` - A request for human approval of a tool invocation. + Workflow metadata for the session. - `id: str` - The unique ID of the approval request. + Identifier of the workflow backing the session. - - `arguments: str` + - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` - A JSON string of arguments for the tool. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `name: str` + - `str` - The name of the tool to run. + - `bool` - - `server_label: str` + - `float` - The label of the MCP server making the request. + - `tracing: Tracing` - - `type: Literal["mcp_approval_request"]` + Tracing settings applied to the workflow. - The type of the item. Always `mcp_approval_request`. + - `enabled: bool` - - `"mcp_approval_request"` + Indicates whether tracing is enabled. - - `agent: Optional[McpApprovalRequestAgent]` + - `version: Optional[str]` - The agent that produced this item. + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `agent_name: str` +### Chat Session Automatic Thread Titling - The canonical name of the agent that produced this item. +- `class ChatSessionAutomaticThreadTitling: …` - - `class McpApprovalResponse: …` + Automatic thread title preferences for the session. - A response to an MCP approval request. + - `enabled: bool` - - `approval_request_id: str` + Whether automatic thread titling is enabled. - The ID of the approval request being answered. +### Chat Session ChatKit Configuration - - `approve: bool` +- `class ChatSessionChatKitConfiguration: …` - Whether the request was approved. + ChatKit configuration for the session. - - `type: Literal["mcp_approval_response"]` + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - The type of the item. Always `mcp_approval_response`. + Automatic thread titling preferences. - - `"mcp_approval_response"` + - `enabled: bool` - - `id: Optional[str]` + Whether automatic thread titling is enabled. - The unique ID of the approval response + - `file_upload: ChatSessionFileUpload` - - `agent: Optional[McpApprovalResponseAgent]` + Upload settings for the session. - The agent that produced this item. + - `enabled: bool` - - `agent_name: str` + Indicates if uploads are enabled for the session. - The canonical name of the agent that produced this item. + - `max_file_size: Optional[int]` - - `reason: Optional[str]` + Maximum upload size in megabytes. - Optional reason for the decision. + - `max_files: Optional[int]` - - `class McpCall: …` + Maximum number of uploads allowed during the session. - An invocation of a tool on an MCP server. + - `history: ChatSessionHistory` - - `id: str` + History retention configuration. - The unique ID of the tool call. + - `enabled: bool` - - `arguments: str` + Indicates if chat history is persisted for the session. - A JSON string of the arguments passed to the tool. + - `recent_threads: Optional[int]` - - `name: str` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - The name of the tool that was run. +### Chat Session ChatKit Configuration Param - - `server_label: str` +- `class ChatSessionChatKitConfigurationParam: …` - The label of the MCP server running the tool. + Optional per-session configuration settings for ChatKit behavior. - - `type: Literal["mcp_call"]` + - `automatic_thread_titling: Optional[AutomaticThreadTitling]` - The type of the item. Always `mcp_call`. + Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - - `"mcp_call"` + - `enabled: Optional[bool]` - - `agent: Optional[McpCallAgent]` + Enable automatic thread title generation. Defaults to true. - The agent that produced this item. + - `file_upload: Optional[FileUpload]` - - `agent_name: str` + Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - The canonical name of the agent that produced this item. + - `enabled: Optional[bool]` - - `approval_request_id: Optional[str]` + Enable uploads for this session. Defaults to false. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `max_file_size: Optional[int]` - - `error: Optional[str]` + Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - The error from the tool call, if any. + - `max_files: Optional[int]` - - `output: Optional[str]` + Maximum number of files that can be uploaded to the session. Defaults to 10. - The output from the tool call. + - `history: Optional[History]` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `enabled: Optional[bool]` - - `"in_progress"` + Enables chat users to access previous ChatKit threads. Defaults to true. - - `"completed"` + - `recent_threads: Optional[int]` - - `"incomplete"` + Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. - - `"calling"` +### Chat Session Expires After Param - - `"failed"` +- `class ChatSessionExpiresAfterParam: …` - - `class BetaResponseCustomToolCallOutput: …` + Controls when the session expires relative to an anchor timestamp. - The output of a custom tool call from your code, being sent back to the model. + - `anchor: Literal["created_at"]` - - `call_id: str` + Base timestamp used to calculate expiration. Currently fixed to `created_at`. - The call ID, used to map this custom tool call output to a custom tool call. + - `"created_at"` - - `output: Union[str, List[OutputOutputContentList]]` + - `seconds: int` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Number of seconds after the anchor when the session expires. - - `str` +### Chat Session File Upload - A string of the output of the custom tool call. +- `class ChatSessionFileUpload: …` - - `List[OutputOutputContentList]` + Upload permissions and limits applied to the session. - Text, image, or file output of the custom tool call. + - `enabled: bool` - - `class BetaResponseInputText: …` + Indicates if uploads are enabled for the session. - A text input to the model. + - `max_file_size: Optional[int]` - - `class BetaResponseInputImage: …` + Maximum upload size in megabytes. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `max_files: Optional[int]` - - `class BetaResponseInputFile: …` + Maximum number of uploads allowed during the session. - A file input to the model. +### Chat Session History - - `type: Literal["custom_tool_call_output"]` +- `class ChatSessionHistory: …` - The type of the custom tool call output. Always `custom_tool_call_output`. + History retention preferences returned for the session. - - `"custom_tool_call_output"` + - `enabled: bool` - - `id: Optional[str]` + Indicates if chat history is persisted for the session. - The unique ID of the custom tool call output in the OpenAI platform. + - `recent_threads: Optional[int]` - - `agent: Optional[Agent]` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - The agent that produced this item. +### Chat Session Rate Limits - - `agent_name: str` +- `class ChatSessionRateLimits: …` - The canonical name of the agent that produced this item. + Active per-minute request limit for the session. - - `caller: Optional[Caller]` + - `max_requests_per_1_minute: int` - The execution context that produced this tool call. + Maximum allowed requests per one-minute window. - - `class CallerDirect: …` +### Chat Session Rate Limits Param - - `type: Literal["direct"]` +- `class ChatSessionRateLimitsParam: …` - The caller type. Always `direct`. + Controls request rate limits for the session. - - `"direct"` + - `max_requests_per_1_minute: Optional[int]` - - `class CallerProgram: …` + Maximum number of requests allowed per minute for the session. Defaults to 10. - - `caller_id: str` +### Chat Session Status - The call ID of the program item that produced this tool call. +- `Literal["active", "expired", "cancelled"]` - - `type: Literal["program"]` + - `"active"` - The caller type. Always `program`. + - `"expired"` - - `"program"` + - `"cancelled"` - - `class BetaResponseCustomToolCall: …` +### Chat Session Workflow Param - A call to a custom tool created by the model. +- `class ChatSessionWorkflowParam: …` - - `call_id: str` + Workflow reference and overrides applied to the chat session. - An identifier used to map this custom tool call to a tool call output. + - `id: str` - - `input: str` + Identifier for the workflow invoked by the session. - The input for the custom tool call generated by the model. + - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` - - `name: str` + State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. - The name of the custom tool being called. + - `str` - - `type: Literal["custom_tool_call"]` + - `bool` - The type of the custom tool call. Always `custom_tool_call`. + - `float` - - `"custom_tool_call"` + - `tracing: Optional[Tracing]` - - `id: Optional[str]` + Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - The unique ID of the custom tool call in the OpenAI platform. + - `enabled: Optional[bool]` - - `agent: Optional[Agent]` + Whether tracing is enabled during the session. Defaults to true. - The agent that produced this item. + - `version: Optional[str]` - - `agent_name: str` + Specific workflow version to run. Defaults to the latest deployed version. - The canonical name of the agent that produced this item. +### ChatKit Attachment - - `caller: Optional[Caller]` +- `class ChatKitAttachment: …` - The execution context that produced this tool call. + Attachment metadata included on thread items. - - `class CallerDirect: …` + - `id: str` - - `type: Literal["direct"]` + Identifier for the attachment. - - `"direct"` + - `mime_type: str` - - `class CallerProgram: …` + MIME type of the attachment. - - `caller_id: str` + - `name: str` - The call ID of the program item that produced this tool call. + Original display name for the attachment. - - `type: Literal["program"]` + - `preview_url: Optional[str]` - - `"program"` + Preview URL for rendering the attachment inline. - - `namespace: Optional[str]` + - `type: Literal["image", "file"]` - The namespace of the custom tool being called. + Attachment discriminator. - - `class CompactionTrigger: …` + - `"image"` - Compacts the current context. Must be the final input item. + - `"file"` - - `type: Literal["compaction_trigger"]` +### ChatKit Response Output Text - The type of the item. Always `compaction_trigger`. +- `class ChatKitResponseOutputText: …` - - `"compaction_trigger"` + Assistant response text accompanied by optional annotations. - - `agent: Optional[CompactionTriggerAgent]` + - `annotations: List[Annotation]` - The agent that produced this item. + Ordered list of annotations attached to the response text. - - `agent_name: str` + - `class AnnotationFile: …` - The canonical name of the agent that produced this item. + Annotation that references an uploaded file. - - `class ItemReference: …` + - `source: AnnotationFileSource` - An internal identifier for an item to reference. + File attachment referenced by the annotation. - - `id: str` + - `filename: str` - The ID of the item to reference. + Filename referenced by the annotation. - - `agent: Optional[ItemReferenceAgent]` + - `type: Literal["file"]` - The agent that produced this item. + Type discriminator that is always `file`. - - `agent_name: str` + - `"file"` - The canonical name of the agent that produced this item. + - `type: Literal["file"]` - - `type: Optional[Literal["item_reference"]]` + Type discriminator that is always `file` for this annotation. - The type of item to reference. Always `item_reference`. + - `"file"` - - `"item_reference"` + - `class AnnotationURL: …` - - `class Program: …` + Annotation that references a URL. - - `id: str` + - `source: AnnotationURLSource` - The unique ID of this program item. + URL referenced by the annotation. - - `call_id: str` + - `type: Literal["url"]` - The stable call ID of the program item. + Type discriminator that is always `url`. - - `code: str` + - `"url"` - The JavaScript source executed by programmatic tool calling. + - `url: str` - - `fingerprint: str` + URL referenced by the annotation. - Opaque program replay fingerprint that must be round-tripped. + - `type: Literal["url"]` - - `type: Literal["program"]` + Type discriminator that is always `url` for this annotation. - The item type. Always `program`. + - `"url"` - - `"program"` + - `text: str` - - `agent: Optional[ProgramAgent]` + Assistant generated text. - The agent that produced this item. + - `type: Literal["output_text"]` - - `agent_name: str` + Type discriminator that is always `output_text`. - The canonical name of the agent that produced this item. + - `"output_text"` - - `class ProgramOutput: …` +### ChatKit Thread + +- `class ChatKitThread: …` + + Represents a ChatKit thread and its current status. - `id: str` - The unique ID of this program output item. + Identifier of the thread. - - `call_id: str` + - `created_at: int` - The call ID of the program item. + Unix timestamp (in seconds) for when the thread was created. - - `result: str` + - `object: Literal["chatkit.thread"]` - The result produced by the program item. + Type discriminator that is always `chatkit.thread`. - - `status: Literal["completed", "incomplete"]` + - `"chatkit.thread"` - The terminal status of the program output. + - `status: Status` - - `"completed"` + Current status for the thread. Defaults to `active` for newly created threads. - - `"incomplete"` + - `class StatusActive: …` - - `type: Literal["program_output"]` + Indicates that a thread is active. - The item type. Always `program_output`. + - `type: Literal["active"]` - - `"program_output"` + Status discriminator that is always `active`. - - `agent: Optional[ProgramOutputAgent]` + - `"active"` - The agent that produced this item. + - `class StatusLocked: …` - - `agent_name: str` + Indicates that a thread is locked and cannot accept new input. - The canonical name of the agent that produced this item. + - `reason: Optional[str]` - - `metadata: Optional[Dict[str, str]]` + Reason that the thread was locked. Defaults to null when no reason is recorded. - 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. + - `type: Literal["locked"]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Status discriminator that is always `locked`. - - `model: Union[Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more], str]` + - `"locked"` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `class StatusClosed: …` - - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 92 more]` + Indicates that a thread has been closed. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `reason: Optional[str]` - - `"gpt-5.6-sol"` + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `"gpt-5.6-terra"` + - `type: Literal["closed"]` - - `"gpt-5.6-luna"` + Status discriminator that is always `closed`. - - `"gpt-5.4"` + - `"closed"` - - `"gpt-5.4-mini"` + - `title: Optional[str]` - - `"gpt-5.4-nano"` + Optional human-readable title for the thread. Defaults to null when no title has been generated. - - `"gpt-5.4-mini-2026-03-17"` + - `user: str` - - `"gpt-5.4-nano-2026-03-17"` + Free-form string that identifies your end user who owns the thread. - - `"gpt-5.3-chat-latest"` +### ChatKit Thread Assistant Message Item - - `"gpt-5.2"` +- `class ChatKitThreadAssistantMessageItem: …` - - `"gpt-5.2-2025-12-11"` + Assistant-authored message within a thread. - - `"gpt-5.2-chat-latest"` + - `id: str` - - `"gpt-5.2-pro"` + Identifier of the thread item. - - `"gpt-5.2-pro-2025-12-11"` + - `content: List[ChatKitResponseOutputText]` - - `"gpt-5.1"` + Ordered assistant response segments. - - `"gpt-5.1-2025-11-13"` + - `annotations: List[Annotation]` - - `"gpt-5.1-codex"` + Ordered list of annotations attached to the response text. - - `"gpt-5.1-mini"` + - `class AnnotationFile: …` - - `"gpt-5.1-chat-latest"` + Annotation that references an uploaded file. - - `"gpt-5"` + - `source: AnnotationFileSource` - - `"gpt-5-mini"` + File attachment referenced by the annotation. - - `"gpt-5-nano"` + - `filename: str` - - `"gpt-5-2025-08-07"` + Filename referenced by the annotation. - - `"gpt-5-mini-2025-08-07"` + - `type: Literal["file"]` - - `"gpt-5-nano-2025-08-07"` + Type discriminator that is always `file`. - - `"gpt-5-chat-latest"` + - `"file"` - - `"gpt-4.1"` + - `type: Literal["file"]` - - `"gpt-4.1-mini"` + Type discriminator that is always `file` for this annotation. - - `"gpt-4.1-nano"` + - `"file"` - - `"gpt-4.1-2025-04-14"` + - `class AnnotationURL: …` - - `"gpt-4.1-mini-2025-04-14"` + Annotation that references a URL. - - `"gpt-4.1-nano-2025-04-14"` + - `source: AnnotationURLSource` - - `"o4-mini"` + URL referenced by the annotation. - - `"o4-mini-2025-04-16"` + - `type: Literal["url"]` - - `"o3"` + Type discriminator that is always `url`. - - `"o3-2025-04-16"` + - `"url"` - - `"o3-mini"` + - `url: str` - - `"o3-mini-2025-01-31"` + URL referenced by the annotation. - - `"o1"` + - `type: Literal["url"]` - - `"o1-2024-12-17"` + Type discriminator that is always `url` for this annotation. - - `"o1-preview"` + - `"url"` - - `"o1-preview-2024-09-12"` + - `text: str` - - `"o1-mini"` + Assistant generated text. - - `"o1-mini-2024-09-12"` + - `type: Literal["output_text"]` - - `"gpt-4o"` + Type discriminator that is always `output_text`. - - `"gpt-4o-2024-11-20"` + - `"output_text"` - - `"gpt-4o-2024-08-06"` + - `created_at: int` - - `"gpt-4o-2024-05-13"` + Unix timestamp (in seconds) for when the item was created. - - `"gpt-4o-audio-preview"` + - `object: Literal["chatkit.thread_item"]` - - `"gpt-4o-audio-preview-2024-10-01"` + Type discriminator that is always `chatkit.thread_item`. - - `"gpt-4o-audio-preview-2024-12-17"` + - `"chatkit.thread_item"` - - `"gpt-4o-audio-preview-2025-06-03"` + - `thread_id: str` - - `"gpt-4o-mini-audio-preview"` + Identifier of the parent thread. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `type: Literal["chatkit.assistant_message"]` - - `"gpt-4o-search-preview"` + Type discriminator that is always `chatkit.assistant_message`. - - `"gpt-4o-mini-search-preview"` + - `"chatkit.assistant_message"` - - `"gpt-4o-search-preview-2025-03-11"` +### ChatKit Thread Item List - - `"gpt-4o-mini-search-preview-2025-03-11"` +- `class ChatKitThreadItemList: …` - - `"chatgpt-4o-latest"` + A paginated list of thread items rendered for the ChatKit API. - - `"codex-mini-latest"` + - `data: List[Data]` - - `"gpt-4o-mini"` + A list of items - - `"gpt-4o-mini-2024-07-18"` + - `class ChatKitThreadUserMessageItem: …` - - `"gpt-4-turbo"` + User-authored messages within a thread. - - `"gpt-4-turbo-2024-04-09"` + - `id: str` - - `"gpt-4-0125-preview"` + Identifier of the thread item. - - `"gpt-4-turbo-preview"` + - `attachments: List[ChatKitAttachment]` - - `"gpt-4-1106-preview"` + Attachments associated with the user message. Defaults to an empty list. - - `"gpt-4-vision-preview"` + - `id: str` - - `"gpt-4"` + Identifier for the attachment. - - `"gpt-4-0314"` + - `mime_type: str` - - `"gpt-4-0613"` + MIME type of the attachment. - - `"gpt-4-32k"` + - `name: str` - - `"gpt-4-32k-0314"` + Original display name for the attachment. - - `"gpt-4-32k-0613"` + - `preview_url: Optional[str]` - - `"gpt-3.5-turbo"` + Preview URL for rendering the attachment inline. - - `"gpt-3.5-turbo-16k"` + - `type: Literal["image", "file"]` - - `"gpt-3.5-turbo-0301"` + Attachment discriminator. - - `"gpt-3.5-turbo-0613"` + - `"image"` - - `"gpt-3.5-turbo-1106"` + - `"file"` - - `"gpt-3.5-turbo-0125"` + - `content: List[Content]` - - `"gpt-3.5-turbo-16k-0613"` + Ordered content elements supplied by the user. - - `"o1-pro"` + - `class ContentInputText: …` - - `"o1-pro-2025-03-19"` + Text block that a user contributed to the thread. - - `"o3-pro"` + - `text: str` - - `"o3-pro-2025-06-10"` + Plain-text content supplied by the user. - - `"o3-deep-research"` + - `type: Literal["input_text"]` - - `"o3-deep-research-2025-06-26"` + Type discriminator that is always `input_text`. - - `"o4-mini-deep-research"` + - `"input_text"` - - `"o4-mini-deep-research-2025-06-26"` + - `class ContentQuotedText: …` + + Quoted snippet that the user referenced in their message. - - `"computer-use-preview"` + - `text: str` - - `"computer-use-preview-2025-03-11"` + Quoted text content. - - `"gpt-5-codex"` + - `type: Literal["quoted_text"]` - - `"gpt-5-pro"` + Type discriminator that is always `quoted_text`. - - `"gpt-5-pro-2025-10-06"` + - `"quoted_text"` - - `"gpt-5.1-codex-max"` + - `created_at: int` - - `str` + Unix timestamp (in seconds) for when the item was created. - - `object: Literal["response"]` + - `inference_options: Optional[InferenceOptions]` - The object type of this resource - always set to `response`. + Inference overrides applied to the message. Defaults to null when unset. - - `"response"` + - `model: Optional[str]` - - `output: List[BetaResponseOutputItem]` + Model name that generated the response. Defaults to null when using the session default. - An array of content items generated by the model. + - `tool_choice: Optional[InferenceOptionsToolChoice]` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - - `class BetaResponseOutputMessage: …` + - `id: str` - An output message from the model. + Identifier of the requested tool. - - `class BetaResponseFileSearchToolCall: …` + - `object: Literal["chatkit.thread_item"]` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + Type discriminator that is always `chatkit.thread_item`. - - `class BetaResponseFunctionToolCall: …` + - `"chatkit.thread_item"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `thread_id: str` - - `class BetaResponseFunctionToolCallOutputItem: …` + Identifier of the parent thread. - - `id: str` + - `type: Literal["chatkit.user_message"]` - The unique ID of the function call tool output. + - `"chatkit.user_message"` - - `call_id: str` + - `class ChatKitThreadAssistantMessageItem: …` - The unique ID of the function tool call generated by the model. + Assistant-authored message within a thread. - - `output: Union[str, List[OutputOutputContentList]]` + - `id: str` - The output from the function call generated by your code. - Can be a string or an list of output content. + Identifier of the thread item. - - `str` + - `content: List[ChatKitResponseOutputText]` - A string of the output of the function call. + Ordered assistant response segments. - - `List[OutputOutputContentList]` + - `annotations: List[Annotation]` - Text, image, or file output of the function call. + Ordered list of annotations attached to the response text. - - `class BetaResponseInputText: …` + - `class AnnotationFile: …` - A text input to the model. + Annotation that references an uploaded file. - - `class BetaResponseInputImage: …` + - `source: AnnotationFileSource` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + File attachment referenced by the annotation. - - `class BetaResponseInputFile: …` + - `filename: str` - A file input to the model. + Filename referenced by the annotation. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `type: Literal["file"]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Type discriminator that is always `file`. - - `"in_progress"` + - `"file"` - - `"completed"` + - `type: Literal["file"]` - - `"incomplete"` + Type discriminator that is always `file` for this annotation. - - `type: Literal["function_call_output"]` + - `"file"` - The type of the function tool call output. Always `function_call_output`. + - `class AnnotationURL: …` - - `"function_call_output"` + Annotation that references a URL. - - `agent: Optional[Agent]` + - `source: AnnotationURLSource` - The agent that produced this item. + URL referenced by the annotation. - - `agent_name: str` + - `type: Literal["url"]` - The canonical name of the agent that produced this item. + Type discriminator that is always `url`. - - `caller: Optional[Caller]` + - `"url"` - The execution context that produced this tool call. + - `url: str` - - `class CallerDirect: …` + URL referenced by the annotation. - - `type: Literal["direct"]` + - `type: Literal["url"]` - The caller type. Always `direct`. + Type discriminator that is always `url` for this annotation. - - `"direct"` + - `"url"` - - `class CallerProgram: …` + - `text: str` - - `caller_id: str` + Assistant generated text. - The call ID of the program item that produced this tool call. + - `type: Literal["output_text"]` - - `type: Literal["program"]` + Type discriminator that is always `output_text`. - The caller type. Always `program`. + - `"output_text"` - - `"program"` + - `created_at: int` - - `created_by: Optional[str]` + Unix timestamp (in seconds) for when the item was created. - The identifier of the actor that created the item. + - `object: Literal["chatkit.thread_item"]` - - `class AgentMessage: …` + Type discriminator that is always `chatkit.thread_item`. - - `id: str` + - `"chatkit.thread_item"` - The unique ID of the agent message. + - `thread_id: str` - - `author: str` + Identifier of the parent thread. - The sending agent identity. + - `type: Literal["chatkit.assistant_message"]` - - `content: List[AgentMessageContent]` + Type discriminator that is always `chatkit.assistant_message`. - Encrypted content sent between agents. + - `"chatkit.assistant_message"` - - `class BetaResponseInputText: …` + - `class ChatKitWidgetItem: …` - A text input to the model. + Thread item that renders a widget payload. - - `class BetaResponseOutputText: …` + - `id: str` - A text output from the model. + Identifier of the thread item. - - `class AgentMessageContentText: …` + - `created_at: int` - A text content. + Unix timestamp (in seconds) for when the item was created. - - `text: str` + - `object: Literal["chatkit.thread_item"]` - - `type: Literal["text"]` + Type discriminator that is always `chatkit.thread_item`. - - `"text"` + - `"chatkit.thread_item"` - - `class AgentMessageContentSummaryText: …` + - `thread_id: str` - A summary text from the model. + Identifier of the parent thread. - - `text: str` + - `type: Literal["chatkit.widget"]` - A summary of the reasoning output from the model so far. + Type discriminator that is always `chatkit.widget`. - - `type: Literal["summary_text"]` + - `"chatkit.widget"` - The type of the object. Always `summary_text`. + - `widget: str` - - `"summary_text"` + Serialized widget payload rendered in the UI. - - `class AgentMessageContentReasoningText: …` + - `class DataChatKitClientToolCall: …` - Reasoning text from the model. + Record of a client side tool invocation initiated by the assistant. - - `text: str` + - `id: str` - The reasoning text from the model. + Identifier of the thread item. - - `type: Literal["reasoning_text"]` + - `arguments: str` - The type of the reasoning text. Always `reasoning_text`. + JSON-encoded arguments that were sent to the tool. - - `"reasoning_text"` + - `call_id: str` - - `class BetaResponseOutputRefusal: …` + Identifier for the client tool call. - A refusal from the model. + - `created_at: int` - - `class BetaResponseInputImage: …` + Unix timestamp (in seconds) for when the item was created. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `name: str` - - `class AgentMessageContentComputerScreenshot: …` + Tool name that was invoked. - A screenshot of a computer. + - `object: Literal["chatkit.thread_item"]` - - `detail: Literal["low", "high", "auto", "original"]` + Type discriminator that is always `chatkit.thread_item`. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"chatkit.thread_item"` - - `"low"` + - `output: Optional[str]` - - `"high"` + JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - - `"auto"` + - `status: Literal["in_progress", "completed"]` - - `"original"` + Execution status for the tool call. - - `file_id: Optional[str]` + - `"in_progress"` - The identifier of an uploaded file that contains the screenshot. + - `"completed"` - - `image_url: Optional[str]` + - `thread_id: str` - The URL of the screenshot image. + Identifier of the parent thread. - - `type: Literal["computer_screenshot"]` + - `type: Literal["chatkit.client_tool_call"]` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Type discriminator that is always `chatkit.client_tool_call`. - - `"computer_screenshot"` + - `"chatkit.client_tool_call"` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `class DataChatKitTask: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Task emitted by the workflow to show progress and status updates. - - `mode: Literal["explicit"]` + - `id: str` - The breakpoint mode. Always `explicit`. + Identifier of the thread item. - - `"explicit"` + - `created_at: int` - - `class BetaResponseInputFile: …` + Unix timestamp (in seconds) for when the item was created. - A file input to the model. + - `heading: Optional[str]` - - `class AgentMessageContentEncryptedContent: …` + Optional heading for the task. Defaults to null when not provided. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `object: Literal["chatkit.thread_item"]` - - `encrypted_content: str` + Type discriminator that is always `chatkit.thread_item`. - Opaque encrypted content. + - `"chatkit.thread_item"` - - `type: Literal["encrypted_content"]` + - `summary: Optional[str]` - The type of the input item. Always `encrypted_content`. + Optional summary that describes the task. Defaults to null when omitted. - - `"encrypted_content"` + - `task_type: Literal["custom", "thought"]` - - `recipient: str` + Subtype for the task. - The destination agent identity. + - `"custom"` - - `type: Literal["agent_message"]` + - `"thought"` - The type of the item. Always `agent_message`. + - `thread_id: str` - - `"agent_message"` + Identifier of the parent thread. - - `agent: Optional[AgentMessageAgent]` + - `type: Literal["chatkit.task"]` - The agent that produced this item. + Type discriminator that is always `chatkit.task`. - - `agent_name: str` + - `"chatkit.task"` - The canonical name of the agent that produced this item. + - `class DataChatKitTaskGroup: …` - - `class MultiAgentCall: …` + Collection of workflow tasks grouped together in the thread. - `id: str` - The unique ID of the multi-agent call item. - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + Identifier of the thread item. - The multi-agent action to execute. + - `created_at: int` - - `"spawn_agent"` + Unix timestamp (in seconds) for when the item was created. - - `"interrupt_agent"` + - `object: Literal["chatkit.thread_item"]` - - `"list_agents"` + Type discriminator that is always `chatkit.thread_item`. - - `"send_message"` + - `"chatkit.thread_item"` - - `"followup_task"` + - `tasks: List[DataChatKitTaskGroupTask]` - - `"wait_agent"` + Tasks included in the group. - - `arguments: str` + - `heading: Optional[str]` - The JSON string of arguments generated for the action. + Optional heading for the grouped task. Defaults to null when not provided. - - `call_id: str` + - `summary: Optional[str]` - The unique ID linking this call to its output. + Optional summary that describes the grouped task. Defaults to null when omitted. - - `type: Literal["multi_agent_call"]` + - `type: Literal["custom", "thought"]` - The type of the multi-agent call. Always `multi_agent_call`. + Subtype for the grouped task. - - `"multi_agent_call"` + - `"custom"` - - `agent: Optional[MultiAgentCallAgent]` + - `"thought"` - The agent that produced this item. + - `thread_id: str` - - `agent_name: str` + Identifier of the parent thread. - The canonical name of the agent that produced this item. + - `type: Literal["chatkit.task_group"]` - - `class MultiAgentCallOutput: …` + Type discriminator that is always `chatkit.task_group`. - - `id: str` + - `"chatkit.task_group"` - The unique ID of the multi-agent call output item. + - `first_id: Optional[str]` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The ID of the first item in the list. - The multi-agent action that produced this result. + - `has_more: bool` - - `"spawn_agent"` + Whether there are more items available. - - `"interrupt_agent"` + - `last_id: Optional[str]` - - `"list_agents"` + The ID of the last item in the list. - - `"send_message"` + - `object: Literal["list"]` - - `"followup_task"` + The type of object returned, must be `list`. - - `"wait_agent"` + - `"list"` - - `call_id: str` +### ChatKit Thread User Message Item - The unique ID of the multi-agent call. +- `class ChatKitThreadUserMessageItem: …` - - `output: List[BetaResponseOutputText]` + User-authored messages within a thread. - Text output returned by the multi-agent action. + - `id: str` - - `annotations: List[Annotation]` + Identifier of the thread item. - The annotations of the text output. + - `attachments: List[ChatKitAttachment]` - - `text: str` + Attachments associated with the user message. Defaults to an empty list. - The text output from the model. + - `id: str` - - `type: Literal["output_text"]` + Identifier for the attachment. - The type of the output text. Always `output_text`. + - `mime_type: str` - - `logprobs: Optional[List[Logprob]]` + MIME type of the attachment. - - `type: Literal["multi_agent_call_output"]` + - `name: str` - The type of the multi-agent result. Always `multi_agent_call_output`. + Original display name for the attachment. - - `"multi_agent_call_output"` + - `preview_url: Optional[str]` - - `agent: Optional[MultiAgentCallOutputAgent]` + Preview URL for rendering the attachment inline. - The agent that produced this item. + - `type: Literal["image", "file"]` - - `agent_name: str` + Attachment discriminator. - The canonical name of the agent that produced this item. + - `"image"` - - `class BetaResponseFunctionWebSearch: …` + - `"file"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `content: List[Content]` - - `class BetaResponseComputerToolCall: …` + Ordered content elements supplied by the user. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `class ContentInputText: …` - - `class BetaResponseComputerToolCallOutputItem: …` + Text block that a user contributed to the thread. - - `id: str` + - `text: str` - The unique ID of the computer call tool output. + Plain-text content supplied by the user. - - `call_id: str` + - `type: Literal["input_text"]` - The ID of the computer tool call that produced the output. + Type discriminator that is always `input_text`. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"input_text"` - A computer screenshot image used with the computer use tool. + - `class ContentQuotedText: …` - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + Quoted snippet that the user referenced in their message. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `text: str` - - `"completed"` + Quoted text content. - - `"incomplete"` + - `type: Literal["quoted_text"]` - - `"failed"` + Type discriminator that is always `quoted_text`. - - `"in_progress"` + - `"quoted_text"` - - `type: Literal["computer_call_output"]` + - `created_at: int` - The type of the computer tool call output. Always `computer_call_output`. + Unix timestamp (in seconds) for when the item was created. - - `"computer_call_output"` + - `inference_options: Optional[InferenceOptions]` - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + Inference overrides applied to the message. Defaults to null when unset. - The safety checks reported by the API that have been acknowledged by the - developer. + - `model: Optional[str]` - - `id: str` + Model name that generated the response. Defaults to null when using the session default. - The ID of the pending safety check. + - `tool_choice: Optional[InferenceOptionsToolChoice]` - - `code: Optional[str]` + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - The type of the pending safety check. + - `id: str` - - `message: Optional[str]` + Identifier of the requested tool. - Details about the pending safety check. + - `object: Literal["chatkit.thread_item"]` - - `agent: Optional[Agent]` + Type discriminator that is always `chatkit.thread_item`. - The agent that produced this item. + - `"chatkit.thread_item"` - - `agent_name: str` + - `thread_id: str` - The canonical name of the agent that produced this item. + Identifier of the parent thread. - - `created_by: Optional[str]` + - `type: Literal["chatkit.user_message"]` - The identifier of the actor that created the item. + - `"chatkit.user_message"` - - `class BetaResponseReasoningItem: …` +### ChatKit Widget Item - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). +- `class ChatKitWidgetItem: …` - - `class Program: …` + Thread item that renders a widget payload. - `id: str` - The unique ID of the program item. + Identifier of the thread item. - - `call_id: str` + - `created_at: int` - The stable call ID of the program item. + Unix timestamp (in seconds) for when the item was created. - - `code: str` + - `object: Literal["chatkit.thread_item"]` - The JavaScript source executed by programmatic tool calling. + Type discriminator that is always `chatkit.thread_item`. - - `fingerprint: str` + - `"chatkit.thread_item"` - Opaque program replay fingerprint that must be round-tripped. + - `thread_id: str` - - `type: Literal["program"]` + Identifier of the parent thread. - The type of the item. Always `program`. + - `type: Literal["chatkit.widget"]` - - `"program"` + Type discriminator that is always `chatkit.widget`. - - `agent: Optional[ProgramAgent]` + - `"chatkit.widget"` - The agent that produced this item. + - `widget: str` - - `agent_name: str` + Serialized widget payload rendered in the UI. - The canonical name of the agent that produced this item. +### Thread Delete Response - - `class ProgramOutput: …` +- `class ThreadDeleteResponse: …` + + Confirmation payload returned after deleting a thread. - `id: str` - The unique ID of the program output item. + Identifier of the deleted thread. - - `call_id: str` + - `deleted: bool` - The call ID of the program item. + Indicates that the thread has been deleted. - - `result: str` + - `object: Literal["chatkit.thread.deleted"]` - The result produced by the program item. + Type discriminator that is always `chatkit.thread.deleted`. - - `status: Literal["completed", "incomplete"]` + - `"chatkit.thread.deleted"` - The terminal status of the program output item. +# Assistants - - `"completed"` +## List assistants - - `"incomplete"` +`beta.assistants.list(AssistantListParams**kwargs) -> SyncCursorPage[Assistant]` - - `type: Literal["program_output"]` +**get** `/assistants` - The type of the item. Always `program_output`. +Returns a list of assistants. - - `"program_output"` +### Parameters - - `agent: Optional[ProgramOutputAgent]` +- `after: Optional[str]` - The agent that produced this item. + 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. - - `agent_name: str` +- `before: Optional[str]` - The canonical name of the agent that produced this item. + 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. - - `class BetaResponseToolSearchCall: …` +- `limit: Optional[int]` - - `id: str` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - The unique ID of the tool search call item. +- `order: Optional[Literal["asc", "desc"]]` - - `arguments: object` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - Arguments used for the tool search call. + - `"asc"` - - `call_id: Optional[str]` + - `"desc"` - The unique ID of the tool search call generated by the model. +### Returns - - `execution: Literal["server", "client"]` +- `class Assistant: …` - Whether tool search was executed by the server or by the client. + Represents an `assistant` that can call the model and use tools. - - `"server"` + - `id: str` - - `"client"` + The identifier, which can be referenced in API endpoints. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `created_at: int` - The status of the tool search call item that was recorded. + The Unix timestamp (in seconds) for when the assistant was created. - - `"in_progress"` + - `description: Optional[str]` - - `"completed"` + The description of the assistant. The maximum length is 512 characters. - - `"incomplete"` + - `instructions: Optional[str]` - - `type: Literal["tool_search_call"]` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - The type of the item. Always `tool_search_call`. + - `metadata: Optional[Metadata]` - - `"tool_search_call"` + 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. - - `agent: Optional[Agent]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The agent that produced this item. + - `model: str` - - `agent_name: 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. - The canonical name of the agent that produced this item. + - `name: Optional[str]` - - `created_by: Optional[str]` + The name of the assistant. The maximum length is 256 characters. - The identifier of the actor that created the item. + - `object: Literal["assistant"]` - - `class BetaResponseToolSearchOutputItem: …` + The object type, which is always `assistant`. - - `id: str` + - `"assistant"` - The unique ID of the tool search output item. + - `tools: List[AssistantTool]` - - `call_id: Optional[str]` + 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`. - The unique ID of the tool search call generated by the model. + - `class CodeInterpreterTool: …` - - `execution: Literal["server", "client"]` + - `type: Literal["code_interpreter"]` - Whether tool search was executed by the server or by the client. + The type of tool being defined: `code_interpreter` - - `"server"` + - `"code_interpreter"` - - `"client"` + - `class FileSearchTool: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `type: Literal["file_search"]` - The status of the tool search output item that was recorded. + The type of tool being defined: `file_search` - - `"in_progress"` + - `"file_search"` - - `"completed"` + - `file_search: Optional[FileSearch]` - - `"incomplete"` + Overrides for the file search tool. - - `tools: List[BetaTool]` + - `max_num_results: Optional[int]` - The loaded tool definitions returned by tool search. + 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. - - `class BetaFunctionTool: …` + 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. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `ranking_options: Optional[FileSearchRankingOptions]` - - `class BetaFileSearchTool: …` + 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. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `class BetaComputerTool: …` + - `score_threshold: float` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `class BetaComputerUsePreviewTool: …` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `class BetaWebSearchTool: …` + - `"auto"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"default_2024_08_21"` - - `class Mcp: …` + - `class FunctionTool: …` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `function: FunctionDefinition` - - `class CodeInterpreter: …` + - `name: str` - A tool that runs Python code to help generate a response to a prompt. + 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. - - `class ProgrammaticToolCalling: …` + - `description: Optional[str]` - - `class ImageGeneration: …` + A description of what the function does, used by the model to choose when and how to call the function. - A tool that generates images using the GPT image models. + - `parameters: Optional[FunctionParameters]` - - `class LocalShell: …` + 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. - A tool that allows the model to execute shell commands in a local environment. + Omitting `parameters` defines a function with an empty parameter list. - - `class BetaFunctionShellTool: …` + - `strict: Optional[bool]` - A tool that allows the model to execute shell commands. + 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). - - `class BetaCustomTool: …` + - `type: Literal["function"]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The type of tool being defined: `function` - - `class BetaNamespaceTool: …` + - `"function"` - Groups function/custom tools under a shared namespace. + - `response_format: Optional[AssistantResponseFormatOption]` - - `class BetaToolSearchTool: …` + 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`. - Hosted or BYOT tool search configuration for deferred tools. + 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). - - `class BetaWebSearchPreviewTool: …` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + **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. - - `class BetaApplyPatchTool: …` + - `Literal["auto"]` - Allows the assistant to create, delete, or update files using unified diffs. + `auto` is the default value - - `type: Literal["tool_search_output"]` + - `"auto"` - The type of the item. Always `tool_search_output`. + - `class ResponseFormatText: …` - - `"tool_search_output"` + Default response format. Used to generate text responses. - - `agent: Optional[Agent]` + - `type: Literal["text"]` - The agent that produced this item. + The type of response format being defined. Always `text`. - - `agent_name: str` + - `"text"` - The canonical name of the agent that produced this item. + - `class ResponseFormatJSONObject: …` - - `created_by: Optional[str]` + 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. - The identifier of the actor that created the item. + - `type: Literal["json_object"]` - - `class AdditionalTools: …` + The type of response format being defined. Always `json_object`. - - `id: str` + - `"json_object"` - The unique ID of the additional tools item. + - `class ResponseFormatJSONSchema: …` - - `role: Literal["unknown", "user", "assistant", 5 more]` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The role that provided the additional tools. + - `json_schema: JSONSchema` - - `"unknown"` + Structured Outputs configuration options, including a JSON Schema. - - `"user"` + - `name: str` - - `"assistant"` + 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. - - `"system"` + - `description: Optional[str]` - - `"critic"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"discriminator"` + - `schema: Optional[Dict[str, object]]` - - `"developer"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"tool"` + - `strict: Optional[bool]` - - `tools: List[BetaTool]` + 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). - The additional tool definitions made available at this item. + - `type: Literal["json_schema"]` - - `class BetaFunctionTool: …` + The type of response format being defined. Always `json_schema`. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `"json_schema"` - - `class BetaFileSearchTool: …` + - `temperature: Optional[float]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + 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. - - `class BetaComputerTool: …` + - `tool_resources: Optional[ToolResources]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + 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. - - `class BetaComputerUsePreviewTool: …` + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `file_ids: Optional[List[str]]` - - `class BetaWebSearchTool: …` + 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. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `file_search: Optional[ToolResourcesFileSearch]` - - `class Mcp: …` + - `vector_store_ids: Optional[List[str]]` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + 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. - - `class CodeInterpreter: …` + - `top_p: Optional[float]` - A tool that runs Python code to help generate a response to a prompt. + 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. - - `class ProgrammaticToolCalling: …` + We generally recommend altering this or temperature but not both. - - `class ImageGeneration: …` +### Example - A tool that generates images using the GPT image models. +```python +import os +from openai import OpenAI - - `class LocalShell: …` +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) +``` - A tool that allows the model to execute shell commands in a local environment. +#### Response - - `class BetaFunctionShellTool: …` +```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" +} +``` - A tool that allows the model to execute shell commands. +### Example - - `class BetaCustomTool: …` +```python +from openai import OpenAI +client = OpenAI() - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) +my_assistants = client.beta.assistants.list( + order="desc", + limit="20", +) +print(my_assistants.data) +``` - - `class BetaNamespaceTool: …` +#### Response - Groups function/custom tools under a shared namespace. +```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 +} +``` - - `class BetaToolSearchTool: …` +## Create assistant - Hosted or BYOT tool search configuration for deferred tools. +`beta.assistants.create(AssistantCreateParams**kwargs) -> Assistant` - - `class BetaWebSearchPreviewTool: …` +**post** `/assistants` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). +Create an assistant with a model and instructions. - - `class BetaApplyPatchTool: …` +### Parameters - Allows the assistant to create, delete, or update files using unified diffs. +- `model: Union[str, ChatModel]` - - `type: Literal["additional_tools"]` + 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. - The type of the item. Always `additional_tools`. + - `str` - - `"additional_tools"` + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 78 more]` - - `agent: Optional[AdditionalToolsAgent]` + - `"gpt-5.6-sol"` - The agent that produced this item. + - `"gpt-5.6-terra"` - - `agent_name: str` + - `"gpt-5.6-luna"` - The canonical name of the agent that produced this item. + - `"gpt-5.4"` - - `class BetaResponseCompactionItem: …` + - `"gpt-5.4-mini"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"gpt-5.4-nano"` - - `id: str` + - `"gpt-5.4-mini-2026-03-17"` - The unique ID of the compaction item. + - `"gpt-5.4-nano-2026-03-17"` - - `encrypted_content: str` + - `"gpt-5.3-chat-latest"` - The encrypted content that was produced by compaction. + - `"gpt-5.2"` - - `type: Literal["compaction"]` + - `"gpt-5.2-2025-12-11"` - The type of the item. Always `compaction`. + - `"gpt-5.2-chat-latest"` - - `"compaction"` + - `"gpt-5.2-pro"` - - `agent: Optional[Agent]` + - `"gpt-5.2-pro-2025-12-11"` - The agent that produced this item. + - `"gpt-5.1"` - - `agent_name: str` + - `"gpt-5.1-2025-11-13"` - The canonical name of the agent that produced this item. + - `"gpt-5.1-codex"` - - `created_by: Optional[str]` + - `"gpt-5.1-mini"` - The identifier of the actor that created the item. + - `"gpt-5.1-chat-latest"` - - `class ImageGenerationCall: …` + - `"gpt-5"` - An image generation request made by the model. + - `"gpt-5-mini"` - - `id: str` + - `"gpt-5-nano"` - The unique ID of the image generation call. + - `"gpt-5-2025-08-07"` - - `result: Optional[str]` + - `"gpt-5-mini-2025-08-07"` - The generated image encoded in base64. + - `"gpt-5-nano-2025-08-07"` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + - `"gpt-5-chat-latest"` - The status of the image generation call. + - `"gpt-4.1"` - - `"in_progress"` + - `"gpt-4.1-mini"` - - `"completed"` + - `"gpt-4.1-nano"` - - `"generating"` + - `"gpt-4.1-2025-04-14"` - - `"failed"` + - `"gpt-4.1-mini-2025-04-14"` - - `type: Literal["image_generation_call"]` + - `"gpt-4.1-nano-2025-04-14"` - The type of the image generation call. Always `image_generation_call`. + - `"o4-mini"` - - `"image_generation_call"` + - `"o4-mini-2025-04-16"` - - `agent: Optional[ImageGenerationCallAgent]` + - `"o3"` - The agent that produced this item. + - `"o3-2025-04-16"` - - `agent_name: str` + - `"o3-mini"` - The canonical name of the agent that produced this item. + - `"o3-mini-2025-01-31"` - - `class BetaResponseCodeInterpreterToolCall: …` + - `"o1"` - A tool call to run code. + - `"o1-2024-12-17"` - - `class LocalShellCall: …` + - `"o1-preview"` - A tool call to run a command on the local shell. + - `"o1-preview-2024-09-12"` - - `id: str` + - `"o1-mini"` - The unique ID of the local shell call. + - `"o1-mini-2024-09-12"` - - `action: LocalShellCallAction` + - `"gpt-4o"` - Execute a shell command on the server. + - `"gpt-4o-2024-11-20"` - - `command: List[str]` + - `"gpt-4o-2024-08-06"` - The command to run. + - `"gpt-4o-2024-05-13"` - - `env: Dict[str, str]` + - `"gpt-4o-audio-preview"` - Environment variables to set for the command. + - `"gpt-4o-audio-preview-2024-10-01"` - - `type: Literal["exec"]` + - `"gpt-4o-audio-preview-2024-12-17"` - The type of the local shell action. Always `exec`. + - `"gpt-4o-audio-preview-2025-06-03"` - - `"exec"` + - `"gpt-4o-mini-audio-preview"` - - `timeout_ms: Optional[int]` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - Optional timeout in milliseconds for the command. + - `"gpt-4o-search-preview"` - - `user: Optional[str]` + - `"gpt-4o-mini-search-preview"` - Optional user to run the command as. + - `"gpt-4o-search-preview-2025-03-11"` - - `working_directory: Optional[str]` + - `"gpt-4o-mini-search-preview-2025-03-11"` - Optional working directory to run the command in. + - `"chatgpt-4o-latest"` - - `call_id: str` + - `"codex-mini-latest"` - The unique ID of the local shell tool call generated by the model. + - `"gpt-4o-mini"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"gpt-4o-mini-2024-07-18"` - The status of the local shell call. + - `"gpt-4-turbo"` - - `"in_progress"` + - `"gpt-4-turbo-2024-04-09"` - - `"completed"` + - `"gpt-4-0125-preview"` - - `"incomplete"` + - `"gpt-4-turbo-preview"` - - `type: Literal["local_shell_call"]` + - `"gpt-4-1106-preview"` - The type of the local shell call. Always `local_shell_call`. + - `"gpt-4-vision-preview"` - - `"local_shell_call"` + - `"gpt-4"` - - `agent: Optional[LocalShellCallAgent]` + - `"gpt-4-0314"` - The agent that produced this item. + - `"gpt-4-0613"` - - `agent_name: str` + - `"gpt-4-32k"` - The canonical name of the agent that produced this item. + - `"gpt-4-32k-0314"` - - `class LocalShellCallOutput: …` + - `"gpt-4-32k-0613"` - The output of a local shell tool call. + - `"gpt-3.5-turbo"` - - `id: str` + - `"gpt-3.5-turbo-16k"` - The unique ID of the local shell tool call generated by the model. + - `"gpt-3.5-turbo-0301"` - - `output: str` + - `"gpt-3.5-turbo-0613"` - A JSON string of the output of the local shell tool call. + - `"gpt-3.5-turbo-1106"` - - `type: Literal["local_shell_call_output"]` + - `"gpt-3.5-turbo-0125"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `"gpt-3.5-turbo-16k-0613"` - - `"local_shell_call_output"` +- `description: Optional[str]` - - `agent: Optional[LocalShellCallOutputAgent]` + The description of the assistant. The maximum length is 512 characters. - The agent that produced this item. +- `instructions: Optional[str]` - - `agent_name: str` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - The canonical name of the agent that produced this item. +- `metadata: Optional[Metadata]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + 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. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"in_progress"` +- `name: Optional[str]` - - `"completed"` + The name of the assistant. The maximum length is 256 characters. - - `"incomplete"` +- `reasoning_effort: Optional[ReasoningEffort]` - - `class BetaResponseFunctionShellToolCall: …` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - A tool call that executes one or more shell commands in a managed environment. + - `"none"` - - `id: str` + - `"minimal"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"low"` - - `action: Action` + - `"medium"` - The shell commands and limits that describe how to run the tool call. + - `"high"` - - `commands: List[str]` + - `"xhigh"` - - `max_output_length: Optional[int]` + - `"max"` - Optional maximum number of characters to return from each command. +- `response_format: Optional[AssistantResponseFormatOptionParam]` - - `timeout_ms: Optional[int]` + 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`. - Optional timeout in milliseconds for the commands. + 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). - - `call_id: str` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The unique ID of the shell tool call generated by the model. + **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. - - `environment: Optional[Environment]` + - `Literal["auto"]` - Represents the use of a local environment to perform shell actions. + `auto` is the default value - - `class BetaResponseLocalEnvironment: …` + - `"auto"` - Represents the use of a local environment to perform shell actions. + - `class ResponseFormatText: …` - - `type: Literal["local"]` + Default response format. Used to generate text responses. - The environment type. Always `local`. + - `type: Literal["text"]` - - `"local"` + The type of response format being defined. Always `text`. - - `class BetaResponseContainerReference: …` + - `"text"` - Represents a container created with /v1/containers. + - `class ResponseFormatJSONObject: …` - - `container_id: str` + 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["container_reference"]` + - `type: Literal["json_object"]` - The environment type. Always `container_reference`. + The type of response format being defined. Always `json_object`. - - `"container_reference"` + - `"json_object"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `class ResponseFormatJSONSchema: …` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `"in_progress"` + - `json_schema: JSONSchema` - - `"completed"` + Structured Outputs configuration options, including a JSON Schema. - - `"incomplete"` + - `name: str` - - `type: Literal["shell_call"]` + 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. - The type of the item. Always `shell_call`. + - `description: Optional[str]` - - `"shell_call"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `agent: Optional[Agent]` + - `schema: Optional[Dict[str, object]]` - The agent that produced this item. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `agent_name: str` + - `strict: Optional[bool]` - The canonical name of the agent that produced this item. + 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). - - `caller: Optional[Caller]` + - `type: Literal["json_schema"]` - The execution context that produced this tool call. + The type of response format being defined. Always `json_schema`. - - `class CallerDirect: …` + - `"json_schema"` - - `type: Literal["direct"]` +- `temperature: Optional[float]` - - `"direct"` + 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. - - `class CallerProgram: …` +- `tool_resources: Optional[ToolResources]` - - `caller_id: str` + 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. - The call ID of the program item that produced this tool call. + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - `type: Literal["program"]` + - `file_ids: Optional[Sequence[str]]` - - `"program"` + 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. - - `created_by: Optional[str]` + - `file_search: Optional[ToolResourcesFileSearch]` - The ID of the entity that created this tool call. + - `vector_store_ids: Optional[Sequence[str]]` - - `class BetaResponseFunctionShellToolCallOutput: …` + 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. - The output of a shell tool call that was emitted. + - `vector_stores: Optional[Iterable[ToolResourcesFileSearchVectorStore]]` - - `id: str` + 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. - The unique ID of the shell call output. Populated when this item is returned via API. + - `chunking_strategy: Optional[ToolResourcesFileSearchVectorStoreChunkingStrategy]` - - `call_id: str` + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - The unique ID of the shell tool call generated by the model. + - `class ToolResourcesFileSearchVectorStoreChunkingStrategyAuto: …` - - `max_output_length: Optional[int]` + The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `type: Literal["auto"]` - - `output: List[Output]` + Always `auto`. - An array of shell call output contents + - `"auto"` - - `outcome: OutputOutcome` + - `class ToolResourcesFileSearchVectorStoreChunkingStrategyStatic: …` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `static: ToolResourcesFileSearchVectorStoreChunkingStrategyStaticStatic` - - `class OutputOutcomeTimeout: …` + - `chunk_overlap_tokens: int` - Indicates that the shell call exceeded its configured time limit. + The number of tokens that overlap between chunks. The default value is `400`. - - `type: Literal["timeout"]` + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - The outcome type. Always `timeout`. + - `max_chunk_size_tokens: int` - - `"timeout"` + The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - - `class OutputOutcomeExit: …` + - `type: Literal["static"]` - Indicates that the shell commands finished and returned an exit code. + Always `static`. - - `exit_code: int` + - `"static"` - Exit code from the shell process. + - `file_ids: Optional[Sequence[str]]` - - `type: Literal["exit"]` + 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. - The outcome type. Always `exit`. + - `metadata: Optional[Metadata]` - - `"exit"` + 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. - - `stderr: str` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The standard error output that was captured. +- `tools: Optional[Iterable[AssistantToolParam]]` - - `stdout: str` + 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`. - The standard output that was captured. + - `class CodeInterpreterTool: …` - - `created_by: Optional[str]` + - `type: Literal["code_interpreter"]` - The identifier of the actor that created the item. + The type of tool being defined: `code_interpreter` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"code_interpreter"` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `class FileSearchTool: …` - - `"in_progress"` + - `type: Literal["file_search"]` - - `"completed"` + The type of tool being defined: `file_search` - - `"incomplete"` + - `"file_search"` - - `type: Literal["shell_call_output"]` + - `file_search: Optional[FileSearch]` - The type of the shell call output. Always `shell_call_output`. + Overrides for the file search tool. - - `"shell_call_output"` + - `max_num_results: Optional[int]` - - `agent: Optional[Agent]` + 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. - The agent that produced this item. + 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. - - `agent_name: str` + - `ranking_options: Optional[FileSearchRankingOptions]` - The canonical name of the agent that produced this item. + 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. - - `caller: Optional[Caller]` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The execution context that produced this tool call. + - `score_threshold: float` - - `class CallerDirect: …` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: Literal["direct"]` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - `"direct"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `class CallerProgram: …` + - `"auto"` - - `caller_id: str` + - `"default_2024_08_21"` - The call ID of the program item that produced this tool call. + - `class FunctionTool: …` - - `type: Literal["program"]` + - `function: FunctionDefinition` - - `"program"` + - `name: str` - - `created_by: Optional[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. - The identifier of the actor that created the item. + - `description: Optional[str]` - - `class BetaResponseApplyPatchToolCall: …` + A description of what the function does, used by the model to choose when and how to call the function. - A tool call that applies file diffs by creating, deleting, or updating files. + - `parameters: Optional[FunctionParameters]` - - `id: str` + 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. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Omitting `parameters` defines a function with an empty parameter list. - - `call_id: str` + - `strict: Optional[bool]` - The unique ID of the apply patch tool call generated by the model. + 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). - - `operation: Operation` + - `type: Literal["function"]` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The type of tool being defined: `function` - - `class OperationCreateFile: …` + - `"function"` - Instruction describing how to create a file via the apply_patch tool. +- `top_p: Optional[float]` - - `diff: str` + 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. - Diff to apply. + We generally recommend altering this or temperature but not both. - - `path: str` +### Returns - Path of the file to create. +- `class Assistant: …` - - `type: Literal["create_file"]` + Represents an `assistant` that can call the model and use tools. - Create a new file with the provided diff. + - `id: str` - - `"create_file"` + The identifier, which can be referenced in API endpoints. - - `class OperationDeleteFile: …` + - `created_at: int` - Instruction describing how to delete a file via the apply_patch tool. + The Unix timestamp (in seconds) for when the assistant was created. - - `path: str` + - `description: Optional[str]` - Path of the file to delete. + The description of the assistant. The maximum length is 512 characters. - - `type: Literal["delete_file"]` + - `instructions: Optional[str]` - Delete the specified file. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `"delete_file"` + - `metadata: Optional[Metadata]` - - `class OperationUpdateFile: …` + 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. - Instruction describing how to update a file via the apply_patch tool. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `diff: str` + - `model: str` - Diff to apply. + 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. - - `path: str` + - `name: Optional[str]` - Path of the file to update. + The name of the assistant. The maximum length is 256 characters. - - `type: Literal["update_file"]` + - `object: Literal["assistant"]` - Update an existing file with the provided diff. + The object type, which is always `assistant`. - - `"update_file"` + - `"assistant"` - - `status: Literal["in_progress", "completed"]` + - `tools: List[AssistantTool]` - The status of the apply patch tool call. One of `in_progress` or `completed`. + 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`. - - `"in_progress"` + - `class CodeInterpreterTool: …` - - `"completed"` + - `type: Literal["code_interpreter"]` - - `type: Literal["apply_patch_call"]` + The type of tool being defined: `code_interpreter` - The type of the item. Always `apply_patch_call`. + - `"code_interpreter"` - - `"apply_patch_call"` + - `class FileSearchTool: …` - - `agent: Optional[Agent]` + - `type: Literal["file_search"]` - The agent that produced this item. + The type of tool being defined: `file_search` - - `agent_name: str` + - `"file_search"` - The canonical name of the agent that produced this item. + - `file_search: Optional[FileSearch]` - - `caller: Optional[Caller]` + Overrides for the file search tool. - The execution context that produced this tool call. + - `max_num_results: Optional[int]` - - `class CallerDirect: …` + 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. - - `type: Literal["direct"]` + 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. - - `"direct"` + - `ranking_options: Optional[FileSearchRankingOptions]` - - `class CallerProgram: …` + 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. - - `caller_id: str` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The call ID of the program item that produced this tool call. + - `score_threshold: float` - - `type: Literal["program"]` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"program"` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - `created_by: Optional[str]` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The ID of the entity that created this tool call. + - `"auto"` - - `class BetaResponseApplyPatchToolCallOutput: …` + - `"default_2024_08_21"` - The output emitted by an apply patch tool call. + - `class FunctionTool: …` - - `id: str` + - `function: FunctionDefinition` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `name: str` - - `call_id: 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. - The unique ID of the apply patch tool call generated by the model. + - `description: Optional[str]` - - `status: Literal["completed", "failed"]` + A description of what the function does, used by the model to choose when and how to call the function. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `parameters: Optional[FunctionParameters]` - - `"completed"` + 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. - - `"failed"` + Omitting `parameters` defines a function with an empty parameter list. - - `type: Literal["apply_patch_call_output"]` + - `strict: Optional[bool]` - The type of the item. Always `apply_patch_call_output`. + 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). - - `"apply_patch_call_output"` + - `type: Literal["function"]` - - `agent: Optional[Agent]` + The type of tool being defined: `function` - The agent that produced this item. + - `"function"` - - `agent_name: str` + - `response_format: Optional[AssistantResponseFormatOption]` - The canonical name of the agent that produced this item. + 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`. - - `caller: Optional[Caller]` + 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). - The execution context that produced this tool call. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `class CallerDirect: …` + **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. - - `type: Literal["direct"]` + - `Literal["auto"]` - - `"direct"` + `auto` is the default value - - `class CallerProgram: …` + - `"auto"` - - `caller_id: str` + - `class ResponseFormatText: …` - The call ID of the program item that produced this tool call. + Default response format. Used to generate text responses. - - `type: Literal["program"]` + - `type: Literal["text"]` - - `"program"` + The type of response format being defined. Always `text`. - - `created_by: Optional[str]` + - `"text"` - The ID of the entity that created this tool call output. + - `class ResponseFormatJSONObject: …` - - `output: Optional[str]` + 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. - Optional textual output returned by the apply patch tool. + - `type: Literal["json_object"]` - - `class McpCall: …` + The type of response format being defined. Always `json_object`. - An invocation of a tool on an MCP server. + - `"json_object"` - - `id: str` + - `class ResponseFormatJSONSchema: …` - The unique ID of the tool call. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `arguments: str` + - `json_schema: JSONSchema` - A JSON string of the arguments passed to the tool. + Structured Outputs configuration options, including a JSON Schema. - `name: str` - The name of the tool that was run. - - - `server_label: 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. - The label of the MCP server running the tool. + - `description: Optional[str]` - - `type: Literal["mcp_call"]` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The type of the item. Always `mcp_call`. + - `schema: Optional[Dict[str, object]]` - - `"mcp_call"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `agent: Optional[McpCallAgent]` + - `strict: Optional[bool]` - The agent that produced this item. + 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). - - `agent_name: str` + - `type: Literal["json_schema"]` - The canonical name of the agent that produced this item. + The type of response format being defined. Always `json_schema`. - - `approval_request_id: Optional[str]` + - `"json_schema"` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `temperature: Optional[float]` - - `error: Optional[str]` + 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. - The error from the tool call, if any. + - `tool_resources: Optional[ToolResources]` - - `output: Optional[str]` + 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. - The output from the tool call. + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `file_ids: Optional[List[str]]` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + 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. - - `"in_progress"` + - `file_search: Optional[ToolResourcesFileSearch]` - - `"completed"` + - `vector_store_ids: Optional[List[str]]` - - `"incomplete"` + 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. - - `"calling"` + - `top_p: Optional[float]` - - `"failed"` + 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. - - `class McpListTools: …` + We generally recommend altering this or temperature but not both. - A list of tools available on an MCP server. +### Example - - `id: str` +```python +import os +from openai import OpenAI - The unique ID of the list. +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) +``` - - `server_label: str` +#### Response - The label of the MCP server. +```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 +} +``` - - `tools: List[McpListToolsTool]` +### Code Interpreter - The tools available on the server. +```python +from openai import OpenAI +client = OpenAI() - - `input_schema: object` +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) +``` - The JSON schema describing the tool's input. +#### Response - - `name: str` +```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" +} +``` - The name of the tool. +### Files - - `annotations: Optional[object]` +```python +from openai import OpenAI +client = OpenAI() - Additional annotations about the tool. +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) +``` - - `description: Optional[str]` +#### Response - The description of the tool. +```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" +} +``` - - `type: Literal["mcp_list_tools"]` +## Retrieve assistant - The type of the item. Always `mcp_list_tools`. +`beta.assistants.retrieve(strassistant_id) -> Assistant` - - `"mcp_list_tools"` +**get** `/assistants/{assistant_id}` - - `agent: Optional[McpListToolsAgent]` +Retrieves an assistant. - The agent that produced this item. +### Parameters - - `agent_name: str` +- `assistant_id: str` - The canonical name of the agent that produced this item. +### Returns - - `error: Optional[str]` +- `class Assistant: …` - Error message if the server could not list tools. + Represents an `assistant` that can call the model and use tools. - - `class McpApprovalRequest: …` + - `id: str` - A request for human approval of a tool invocation. + The identifier, which can be referenced in API endpoints. - - `id: str` + - `created_at: int` - The unique ID of the approval request. + The Unix timestamp (in seconds) for when the assistant was created. - - `arguments: str` + - `description: Optional[str]` - A JSON string of arguments for the tool. + The description of the assistant. The maximum length is 512 characters. - - `name: str` + - `instructions: Optional[str]` - The name of the tool to run. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `server_label: str` + - `metadata: Optional[Metadata]` - The label of the MCP server making the request. + 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. - - `type: Literal["mcp_approval_request"]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of the item. Always `mcp_approval_request`. + - `model: str` - - `"mcp_approval_request"` + 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. - - `agent: Optional[McpApprovalRequestAgent]` + - `name: Optional[str]` - The agent that produced this item. + The name of the assistant. The maximum length is 256 characters. - - `agent_name: str` + - `object: Literal["assistant"]` - The canonical name of the agent that produced this item. + The object type, which is always `assistant`. - - `class McpApprovalResponse: …` + - `"assistant"` - A response to an MCP approval request. + - `tools: List[AssistantTool]` - - `id: str` + 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`. - The unique ID of the approval response + - `class CodeInterpreterTool: …` - - `approval_request_id: str` + - `type: Literal["code_interpreter"]` - The ID of the approval request being answered. + The type of tool being defined: `code_interpreter` - - `approve: bool` + - `"code_interpreter"` - Whether the request was approved. + - `class FileSearchTool: …` - - `type: Literal["mcp_approval_response"]` + - `type: Literal["file_search"]` - The type of the item. Always `mcp_approval_response`. + The type of tool being defined: `file_search` - - `"mcp_approval_response"` + - `"file_search"` - - `agent: Optional[McpApprovalResponseAgent]` + - `file_search: Optional[FileSearch]` - The agent that produced this item. + Overrides for the file search tool. - - `agent_name: str` + - `max_num_results: Optional[int]` - The canonical name of the agent that produced this item. + 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. - - `reason: Optional[str]` + 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. - Optional reason for the decision. + - `ranking_options: Optional[FileSearchRankingOptions]` - - `class BetaResponseCustomToolCall: …` + 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. - A call to a custom tool created by the model. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `class BetaResponseCustomToolCallOutputItem: …` + - `score_threshold: float` - The output of a custom tool call from your code, being sent back to the model. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `id: str` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - The unique ID of the custom tool call output item. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"auto"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"default_2024_08_21"` - - `"in_progress"` + - `class FunctionTool: …` - - `"completed"` + - `function: FunctionDefinition` - - `"incomplete"` + - `name: str` - - `created_by: Optional[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. - The identifier of the actor that created the item. + - `description: Optional[str]` - - `parallel_tool_calls: bool` + A description of what the function does, used by the model to choose when and how to call the function. - Whether to allow the model to run tool calls in parallel. + - `parameters: Optional[FunctionParameters]` - - `temperature: Optional[float]` + 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. - 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. - We generally recommend altering this or `top_p` but not both. + Omitting `parameters` defines a function with an empty parameter list. - - `tool_choice: ToolChoice` + - `strict: Optional[bool]` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + 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). - - `Literal["none", "auto", "required"]` + - `type: Literal["function"]` - - `"none"` + The type of tool being defined: `function` - - `"auto"` + - `"function"` - - `"required"` + - `response_format: Optional[AssistantResponseFormatOption]` - - `class BetaToolChoiceAllowed: …` + 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`. - Constrains the tools available to the model to a pre-defined set. + 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). - - `mode: Literal["auto", "required"]` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - Constrains the tools available to the model to a pre-defined set. + **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. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `Literal["auto"]` - `required` requires the model to call one or more of the allowed tools. + `auto` is the default value - `"auto"` - - `"required"` + - `class ResponseFormatText: …` - - `tools: List[Dict[str, object]]` + Default response format. Used to generate text responses. - A list of tool definitions that the model should be allowed to call. + - `type: Literal["text"]` - For the Responses API, the list of tool definitions might look like: + The type of response format being defined. Always `text`. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `"text"` - - `type: Literal["allowed_tools"]` + - `class ResponseFormatJSONObject: …` - Allowed tool configuration type. Always `allowed_tools`. + 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. - - `"allowed_tools"` + - `type: Literal["json_object"]` - - `class BetaToolChoiceTypes: …` + The type of response format being defined. Always `json_object`. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `"json_object"` - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + - `class ResponseFormatJSONSchema: …` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - Allowed values are: + - `json_schema: JSONSchema` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + Structured Outputs configuration options, including a JSON Schema. - - `"file_search"` + - `name: str` - - `"web_search_preview"` + 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. - - `"computer"` + - `description: Optional[str]` - - `"computer_use_preview"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"computer_use"` + - `schema: Optional[Dict[str, object]]` - - `"web_search_preview_2025_03_11"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"image_generation"` + - `strict: Optional[bool]` - - `"code_interpreter"` + 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). - - `class BetaToolChoiceFunction: …` + - `type: Literal["json_schema"]` - Use this option to force the model to call a specific function. + The type of response format being defined. Always `json_schema`. - - `name: str` + - `"json_schema"` - The name of the function to call. + - `temperature: Optional[float]` - - `type: Literal["function"]` + 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. - For function calling, the type is always `function`. + - `tool_resources: Optional[ToolResources]` - - `"function"` + 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. - - `class BetaToolChoiceMcp: …` + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - Use this option to force the model to call a specific tool on a remote MCP server. + - `file_ids: Optional[List[str]]` - - `server_label: 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. - The label of the MCP server to use. + - `file_search: Optional[ToolResourcesFileSearch]` - - `type: Literal["mcp"]` + - `vector_store_ids: Optional[List[str]]` - For MCP tools, the type is always `mcp`. + 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. - - `"mcp"` + - `top_p: Optional[float]` - - `name: Optional[str]` + 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. - The name of the tool to call on the server. + We generally recommend altering this or temperature but not both. - - `class BetaToolChoiceCustom: …` +### Example - Use this option to force the model to call a specific custom tool. +```python +import os +from openai import OpenAI - - `name: str` +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) +``` - The name of the custom tool to call. +#### Response - - `type: Literal["custom"]` +```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 +} +``` - For custom tool calling, the type is always `custom`. +### Example - - `"custom"` +```python +from openai import OpenAI +client = OpenAI() - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` +my_assistant = client.beta.assistants.retrieve("asst_abc123") +print(my_assistant) +``` - - `type: Literal["programmatic_tool_calling"]` +#### Response - The tool to call. Always `programmatic_tool_calling`. +```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" +} +``` - - `"programmatic_tool_calling"` +## Modify assistant - - `class BetaToolChoiceApplyPatch: …` +`beta.assistants.update(strassistant_id, AssistantUpdateParams**kwargs) -> Assistant` - Forces the model to call the apply_patch tool when executing a tool call. +**post** `/assistants/{assistant_id}` - - `type: Literal["apply_patch"]` +Modifies an assistant. - The tool to call. Always `apply_patch`. +### Parameters - - `"apply_patch"` +- `assistant_id: str` - - `class BetaToolChoiceShell: …` +- `description: Optional[str]` - Forces the model to call the shell tool when a tool call is required. + The description of the assistant. The maximum length is 512 characters. - - `type: Literal["shell"]` +- `instructions: Optional[str]` - The tool to call. Always `shell`. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `"shell"` +- `metadata: Optional[Metadata]` - - `tools: List[BetaTool]` + 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. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - We support the following categories of tools: +- `model: Optional[Union[str, Literal["gpt-5", "gpt-5-mini", "gpt-5-nano", 39 more]]]` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + 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. - - `class BetaFunctionTool: …` + - `str` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `Literal["gpt-5", "gpt-5-mini", "gpt-5-nano", 39 more]` - - `class BetaFileSearchTool: …` + 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. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `"gpt-5"` - - `class BetaComputerTool: …` + - `"gpt-5-mini"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"gpt-5-nano"` - - `class BetaComputerUsePreviewTool: …` + - `"gpt-5-2025-08-07"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"gpt-5-mini-2025-08-07"` - - `class BetaWebSearchTool: …` + - `"gpt-5-nano-2025-08-07"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"gpt-4.1"` - - `class Mcp: …` + - `"gpt-4.1-mini"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"gpt-4.1-nano"` - - `class CodeInterpreter: …` + - `"gpt-4.1-2025-04-14"` - A tool that runs Python code to help generate a response to a prompt. + - `"gpt-4.1-mini-2025-04-14"` - - `class ProgrammaticToolCalling: …` + - `"gpt-4.1-nano-2025-04-14"` - - `class ImageGeneration: …` + - `"o3-mini"` - A tool that generates images using the GPT image models. + - `"o3-mini-2025-01-31"` - - `class LocalShell: …` + - `"o1"` - A tool that allows the model to execute shell commands in a local environment. + - `"o1-2024-12-17"` - - `class BetaFunctionShellTool: …` + - `"gpt-4o"` - A tool that allows the model to execute shell commands. + - `"gpt-4o-2024-11-20"` - - `class BetaCustomTool: …` + - `"gpt-4o-2024-08-06"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"gpt-4o-2024-05-13"` - - `class BetaNamespaceTool: …` + - `"gpt-4o-mini"` - Groups function/custom tools under a shared namespace. + - `"gpt-4o-mini-2024-07-18"` - - `class BetaToolSearchTool: …` + - `"gpt-4.5-preview"` - Hosted or BYOT tool search configuration for deferred tools. + - `"gpt-4.5-preview-2025-02-27"` - - `class BetaWebSearchPreviewTool: …` + - `"gpt-4-turbo"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"gpt-4-turbo-2024-04-09"` - - `class BetaApplyPatchTool: …` + - `"gpt-4-0125-preview"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"gpt-4-turbo-preview"` - - `top_p: Optional[float]` + - `"gpt-4-1106-preview"` - 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. + - `"gpt-4-vision-preview"` - We generally recommend altering this or `temperature` but not both. + - `"gpt-4"` - - `background: Optional[bool]` + - `"gpt-4-0314"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `"gpt-4-0613"` - - `completed_at: Optional[float]` + - `"gpt-4-32k"` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `"gpt-4-32k-0314"` - - `conversation: Optional[Conversation]` + - `"gpt-4-32k-0613"` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `"gpt-3.5-turbo"` - - `id: str` + - `"gpt-3.5-turbo-16k"` - The unique ID of the conversation that this response was associated with. + - `"gpt-3.5-turbo-0613"` - - `max_output_tokens: Optional[int]` + - `"gpt-3.5-turbo-1106"` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `"gpt-3.5-turbo-0125"` - - `max_tool_calls: Optional[int]` + - `"gpt-3.5-turbo-16k-0613"` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. +- `name: Optional[str]` - - `moderation: Optional[Moderation]` + The name of the assistant. The maximum length is 256 characters. - Moderation results for the response input and output, if moderated completions were requested. +- `reasoning_effort: Optional[ReasoningEffort]` - - `input: ModerationInput` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - Moderation for the response input. + - `"none"` - - `class ModerationInputModerationResult: …` + - `"minimal"` - A moderation result produced for the response input or output. + - `"low"` - - `categories: Dict[str, bool]` + - `"medium"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"high"` - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `"xhigh"` - Which modalities of input are reflected by the score for each category. + - `"max"` - - `"text"` +- `response_format: Optional[AssistantResponseFormatOptionParam]` - - `"image"` + 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`. - - `category_scores: Dict[str, float]` + 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). - A dictionary of moderation categories to scores. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `flagged: bool` + **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. - A boolean indicating whether the content was flagged by any category. + - `Literal["auto"]` - - `model: str` + `auto` is the default value - The moderation model that produced this result. + - `"auto"` - - `type: Literal["moderation_result"]` + - `class ResponseFormatText: …` - The object type, which was always `moderation_result` for successful moderation results. + Default response format. Used to generate text responses. - - `"moderation_result"` + - `type: Literal["text"]` - - `class ModerationInputError: …` + The type of response format being defined. Always `text`. - An error produced while attempting moderation for the response input or output. + - `"text"` - - `code: str` + - `class ResponseFormatJSONObject: …` - The error code. + 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. - - `message: str` + - `type: Literal["json_object"]` - The error message. + The type of response format being defined. Always `json_object`. - - `type: Literal["error"]` + - `"json_object"` - The object type, which was always `error` for moderation failures. + - `class ResponseFormatJSONSchema: …` - - `"error"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `output: ModerationOutput` + - `json_schema: JSONSchema` - Moderation for the response output. + Structured Outputs configuration options, including a JSON Schema. - - `class ModerationOutputModerationResult: …` + - `name: str` - A moderation result produced for the response input or output. + 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. - - `categories: Dict[str, bool]` + - `description: Optional[str]` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `category_applied_input_types: Dict[str, List[Literal["text", "image"]]]` + - `schema: Optional[Dict[str, object]]` - Which modalities of input are reflected by the score for each category. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"text"` + - `strict: Optional[bool]` - - `"image"` + 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). - - `category_scores: Dict[str, float]` + - `type: Literal["json_schema"]` - A dictionary of moderation categories to scores. + The type of response format being defined. Always `json_schema`. - - `flagged: bool` + - `"json_schema"` - A boolean indicating whether the content was flagged by any category. +- `temperature: Optional[float]` - - `model: str` + 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. - The moderation model that produced this result. +- `tool_resources: Optional[ToolResources]` - - `type: Literal["moderation_result"]` + 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. - The object type, which was always `moderation_result` for successful moderation results. + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - `"moderation_result"` + - `file_ids: Optional[Sequence[str]]` - - `class ModerationOutputError: …` + 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. - An error produced while attempting moderation for the response input or output. + - `file_search: Optional[ToolResourcesFileSearch]` - - `code: str` + - `vector_store_ids: Optional[Sequence[str]]` - The error code. + 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. - - `message: str` +- `tools: Optional[Iterable[AssistantToolParam]]` - The error message. + 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`. - - `type: Literal["error"]` + - `class CodeInterpreterTool: …` - The object type, which was always `error` for moderation failures. + - `type: Literal["code_interpreter"]` - - `"error"` + The type of tool being defined: `code_interpreter` - - `previous_response_id: Optional[str]` + - `"code_interpreter"` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `class FileSearchTool: …` - - `prompt: Optional[BetaResponsePrompt]` + - `type: Literal["file_search"]` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The type of tool being defined: `file_search` - - `id: str` + - `"file_search"` - The unique identifier of the prompt template to use. + - `file_search: Optional[FileSearch]` - - `variables: Optional[Dict[str, Variables]]` + Overrides for the file search tool. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `max_num_results: Optional[int]` - - `str` + 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. - - `class BetaResponseInputText: …` + 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. - A text input to the model. + - `ranking_options: Optional[FileSearchRankingOptions]` - - `class BetaResponseInputImage: …` + 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. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `class BetaResponseInputFile: …` + - `score_threshold: float` - A file input to the model. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `version: Optional[str]` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - Optional version of the prompt template. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `prompt_cache_key: Optional[str]` + - `"auto"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `"default_2024_08_21"` - - `prompt_cache_options: Optional[PromptCacheOptions]` + - `class FunctionTool: …` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `function: FunctionDefinition` - - `mode: Literal["implicit", "explicit"]` + - `name: str` - Whether implicit prompt-cache breakpoints were enabled. + 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. - - `"implicit"` + - `description: Optional[str]` - - `"explicit"` + A description of what the function does, used by the model to choose when and how to call the function. - - `ttl: Literal["30m"]` + - `parameters: Optional[FunctionParameters]` - The minimum lifetime applied to each cache breakpoint. + 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. - - `"30m"` + Omitting `parameters` defines a function with an empty parameter list. - - `prompt_cache_retention: Optional[Literal["in_memory", "24h"]]` + - `strict: Optional[bool]` - Deprecated. Use `prompt_cache_options.ttl` instead. + 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). - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `type: Literal["function"]` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The type of tool being defined: `function` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `"function"` - - `"in_memory"` +- `top_p: Optional[float]` - - `"24h"` + 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. - - `reasoning: Optional[Reasoning]` + We generally recommend altering this or temperature but not both. - **gpt-5 and o-series models only** +### Returns - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). +- `class Assistant: …` - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + Represents an `assistant` that can call the model and use tools. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `id: str` - - `"auto"` + The identifier, which can be referenced in API endpoints. - - `"current_turn"` + - `created_at: int` - - `"all_turns"` + The Unix timestamp (in seconds) for when the assistant was created. - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + - `description: Optional[str]` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The description of the assistant. The maximum length is 512 characters. - - `"none"` + - `instructions: Optional[str]` - - `"minimal"` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `"low"` + - `metadata: Optional[Metadata]` - - `"medium"` + 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. - - `"high"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"xhigh"` + - `model: str` - - `"max"` + 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. - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + - `name: Optional[str]` - **Deprecated:** use `summary` instead. + The name of the assistant. The maximum length is 256 characters. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `object: Literal["assistant"]` - - `"auto"` + The object type, which is always `assistant`. - - `"concise"` + - `"assistant"` - - `"detailed"` + - `tools: List[AssistantTool]` - - `mode: Optional[Union[str, Literal["standard", "pro"], null]]` + 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`. - Controls the reasoning execution mode for the request. + - `class CodeInterpreterTool: …` - When returned on a response, this is the effective execution mode. + - `type: Literal["code_interpreter"]` - - `str` + The type of tool being defined: `code_interpreter` - - `Literal["standard", "pro"]` + - `"code_interpreter"` - Controls the reasoning execution mode for the request. + - `class FileSearchTool: …` - When returned on a response, this is the effective execution mode. + - `type: Literal["file_search"]` - - `"standard"` + The type of tool being defined: `file_search` - - `"pro"` + - `"file_search"` - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + - `file_search: Optional[FileSearch]` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + Overrides for the file search tool. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `max_num_results: Optional[int]` - - `"auto"` + 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. - - `"concise"` + 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. - - `"detailed"` + - `ranking_options: Optional[FileSearchRankingOptions]` - - `safety_identifier: Optional[str]` + 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. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `service_tier: Optional[Literal["auto", "default", "flex", 2 more]]` + - `score_threshold: float` - Specifies the processing type used for serving the request. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + The ranker to use for the file search. If not specified will use the `auto` ranker. - `"auto"` - - `"default"` + - `"default_2024_08_21"` - - `"flex"` + - `class FunctionTool: …` - - `"scale"` + - `function: FunctionDefinition` - - `"priority"` + - `name: str` - - `status: Optional[BetaResponseStatus]` + 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. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `description: Optional[str]` - - `"completed"` + A description of what the function does, used by the model to choose when and how to call the function. - - `"failed"` + - `parameters: Optional[FunctionParameters]` - - `"in_progress"` + 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. - - `"cancelled"` + Omitting `parameters` defines a function with an empty parameter list. - - `"queued"` + - `strict: Optional[bool]` - - `"incomplete"` + 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). - - `text: Optional[BetaResponseTextConfig]` + - `type: Literal["function"]` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The type of tool being defined: `function` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `"function"` - - `format: Optional[BetaResponseFormatTextConfig]` + - `response_format: Optional[AssistantResponseFormatOption]` - An object specifying the format that the model must output. + 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`. - Configuring `{ "type": "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_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). - The default format is `{ "type": "text" }` with no additional options. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - **Not recommended for gpt-4o and newer models:** + **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. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `Literal["auto"]` - - `class Text: …` + `auto` is the default value + + - `"auto"` + + - `class ResponseFormatText: …` Default response format. Used to generate text responses. @@ -149274,7035 +161372,7766 @@ print(compacted_response) - `"text"` - - `class BetaResponseFormatTextJSONSchemaConfig: …` + - `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. - - `schema: Dict[str, object]` + - `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"` - - `description: Optional[str]` + - `temperature: Optional[float]` - A description of what the response format is for, used by the model to - determine how to respond in the format. + 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. - - `strict: Optional[bool]` + - `tool_resources: Optional[ToolResources]` - 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). + 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. - - `class JSONObject: …` + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - 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. + - `file_ids: Optional[List[str]]` - - `type: Literal["json_object"]` + 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. - The type of response format being defined. Always `json_object`. + - `file_search: Optional[ToolResourcesFileSearch]` - - `"json_object"` + - `vector_store_ids: Optional[List[str]]` - - `verbosity: Optional[Literal["low", "medium", "high"]]` + 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. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `top_p: Optional[float]` - - `"low"` + 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. - - `"medium"` + We generally recommend altering this or temperature but not both. - - `"high"` +### Example - - `top_logprobs: Optional[int]` +```python +import os +from openai import OpenAI - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. +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) +``` - - `truncation: Optional[Literal["auto", "disabled"]]` +#### Response - The truncation strategy to use for the model 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 +} +``` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. +### Example - - `"auto"` +```python +from openai import OpenAI +client = OpenAI() - - `"disabled"` +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" +) - - `usage: Optional[BetaResponseUsage]` +print(my_updated_assistant) +``` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. +#### Response - - `input_tokens: int` +```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" +} +``` - The number of input tokens. +## Delete assistant - - `input_tokens_details: InputTokensDetails` +`beta.assistants.delete(strassistant_id) -> AssistantDeleted` - A detailed breakdown of the input tokens. +**delete** `/assistants/{assistant_id}` - - `cache_write_tokens: int` +Delete an assistant. - The number of input tokens that were written to the cache. +### Parameters - - `cached_tokens: int` +- `assistant_id: str` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). +### Returns - - `output_tokens: int` +- `class AssistantDeleted: …` - The number of output tokens. + - `id: str` - - `output_tokens_details: OutputTokensDetails` + - `deleted: bool` - A detailed breakdown of the output tokens. + - `object: Literal["assistant.deleted"]` - - `reasoning_tokens: int` + - `"assistant.deleted"` - The number of reasoning tokens. +### Example - - `total_tokens: int` +```python +import os +from openai import OpenAI - The total number of tokens used. +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) +``` - - `user: Optional[str]` +#### Response - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). +```json +{ + "id": "id", + "deleted": true, + "object": "assistant.deleted" +} +``` - - `sequence_number: int` +### Example - The sequence number for this event. +```python +from openai import OpenAI +client = OpenAI() - - `type: Literal["response.completed"]` +response = client.beta.assistants.delete("asst_abc123") +print(response) +``` - The type of the event. Always `response.completed`. +#### Response - - `"response.completed"` +```json +{ + "id": "asst_abc123", + "object": "assistant.deleted", + "deleted": true +} +``` - - `agent: Optional[Agent]` +## Domain Types - The agent that owns this multi-agent streaming event. +### Assistant - - `agent_name: str` +- `class Assistant: …` - The canonical name of the agent that produced this item. + Represents an `assistant` that can call the model and use tools. - - `class BetaResponseContentPartAddedEvent: …` + - `id: str` - Emitted when a new content part is added. + The identifier, which can be referenced in API endpoints. - - `content_index: int` + - `created_at: int` - The index of the content part that was added. + The Unix timestamp (in seconds) for when the assistant was created. - - `item_id: str` + - `description: Optional[str]` - The ID of the output item that the content part was added to. + The description of the assistant. The maximum length is 512 characters. - - `output_index: int` + - `instructions: Optional[str]` - The index of the output item that the content part was added to. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `part: Part` + - `metadata: Optional[Metadata]` - The content part that was added. + 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. - - `class BetaResponseOutputText: …` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A text output from the model. + - `model: str` - - `class BetaResponseOutputRefusal: …` + 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. - A refusal from the model. + - `name: Optional[str]` - - `class PartReasoningText: …` + The name of the assistant. The maximum length is 256 characters. - Reasoning text from the model. + - `object: Literal["assistant"]` - - `text: str` + The object type, which is always `assistant`. - The reasoning text from the model. + - `"assistant"` - - `type: Literal["reasoning_text"]` + - `tools: List[AssistantTool]` - The type of the reasoning text. Always `reasoning_text`. + 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`. - - `"reasoning_text"` + - `class CodeInterpreterTool: …` - - `sequence_number: int` + - `type: Literal["code_interpreter"]` - The sequence number of this event. + The type of tool being defined: `code_interpreter` - - `type: Literal["response.content_part.added"]` + - `"code_interpreter"` - The type of the event. Always `response.content_part.added`. + - `class FileSearchTool: …` - - `"response.content_part.added"` + - `type: Literal["file_search"]` - - `agent: Optional[Agent]` + The type of tool being defined: `file_search` - The agent that owns this multi-agent streaming event. + - `"file_search"` - - `agent_name: str` + - `file_search: Optional[FileSearch]` - The canonical name of the agent that produced this item. + Overrides for the file search tool. - - `class BetaResponseContentPartDoneEvent: …` + - `max_num_results: Optional[int]` - Emitted when a content part is done. + 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. - - `content_index: int` + 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. - The index of the content part that is done. + - `ranking_options: Optional[FileSearchRankingOptions]` - - `item_id: str` + 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. - The ID of the output item that the content part was added to. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `output_index: int` + - `score_threshold: float` - The index of the output item that the content part was added to. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `part: Part` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - The content part that is done. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `class BetaResponseOutputText: …` + - `"auto"` - A text output from the model. + - `"default_2024_08_21"` - - `class BetaResponseOutputRefusal: …` + - `class FunctionTool: …` - A refusal from the model. + - `function: FunctionDefinition` - - `class PartReasoningText: …` + - `name: str` - Reasoning text from the model. + 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. - - `text: str` + - `description: Optional[str]` - The reasoning text from the model. + A description of what the function does, used by the model to choose when and how to call the function. - - `type: Literal["reasoning_text"]` + - `parameters: Optional[FunctionParameters]` - The type of the reasoning text. Always `reasoning_text`. + 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. - - `"reasoning_text"` + Omitting `parameters` defines a function with an empty parameter list. - - `sequence_number: int` + - `strict: Optional[bool]` - The sequence number of this event. + 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["response.content_part.done"]` + - `type: Literal["function"]` - The type of the event. Always `response.content_part.done`. + The type of tool being defined: `function` - - `"response.content_part.done"` + - `"function"` - - `agent: Optional[Agent]` + - `response_format: Optional[AssistantResponseFormatOption]` - The agent that owns this multi-agent streaming event. + 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`. - - `agent_name: str` + 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). - The canonical name of the agent that produced this item. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `class BetaResponseCreatedEvent: …` + **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. - An event that is emitted when a response is created. + - `Literal["auto"]` - - `response: BetaResponse` + `auto` is the default value - The response that was created. + - `"auto"` - - `sequence_number: int` + - `class ResponseFormatText: …` - The sequence number for this event. + Default response format. Used to generate text responses. - - `type: Literal["response.created"]` + - `type: Literal["text"]` - The type of the event. Always `response.created`. + The type of response format being defined. Always `text`. - - `"response.created"` + - `"text"` - - `agent: Optional[Agent]` + - `class ResponseFormatJSONObject: …` - The agent that owns this multi-agent streaming event. + 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. - - `agent_name: str` + - `type: Literal["json_object"]` - The canonical name of the agent that produced this item. + The type of response format being defined. Always `json_object`. - - `class BetaResponseErrorEvent: …` + - `"json_object"` - Emitted when an error occurs. + - `class ResponseFormatJSONSchema: …` - - `code: Optional[str]` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The error code. + - `json_schema: JSONSchema` - - `message: str` + Structured Outputs configuration options, including a JSON Schema. - The error message. + - `name: str` - - `param: Optional[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. - The error parameter. + - `description: Optional[str]` - - `sequence_number: int` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The sequence number of this event. + - `schema: Optional[Dict[str, object]]` - - `type: Literal["error"]` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The type of the event. Always `error`. + - `strict: Optional[bool]` - - `"error"` + 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). - - `agent: Optional[Agent]` + - `type: Literal["json_schema"]` - The agent that owns this multi-agent streaming event. + The type of response format being defined. Always `json_schema`. - - `agent_name: str` + - `"json_schema"` - The canonical name of the agent that produced this item. + - `temperature: Optional[float]` - - `class BetaResponseFileSearchCallCompletedEvent: …` + 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. - Emitted when a file search call is completed (results found). + - `tool_resources: Optional[ToolResources]` - - `item_id: str` + 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. - The ID of the output item that the file search call is initiated. + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - `output_index: int` + - `file_ids: Optional[List[str]]` - The index of the output item that the file search call is initiated. + 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. - - `sequence_number: int` + - `file_search: Optional[ToolResourcesFileSearch]` - The sequence number of this event. + - `vector_store_ids: Optional[List[str]]` - - `type: Literal["response.file_search_call.completed"]` + 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. - The type of the event. Always `response.file_search_call.completed`. + - `top_p: Optional[float]` - - `"response.file_search_call.completed"` + 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. - - `agent: Optional[Agent]` + We generally recommend altering this or temperature but not both. - The agent that owns this multi-agent streaming event. +### Assistant Deleted - - `agent_name: str` +- `class AssistantDeleted: …` - The canonical name of the agent that produced this item. + - `id: str` - - `class BetaResponseFileSearchCallInProgressEvent: …` + - `deleted: bool` - Emitted when a file search call is initiated. + - `object: Literal["assistant.deleted"]` - - `item_id: str` + - `"assistant.deleted"` - The ID of the output item that the file search call is initiated. +### Assistant Stream Event - - `output_index: int` +- `AssistantStreamEvent` - The index of the output item that the file search call is initiated. + Represents an event emitted when streaming a Run. - - `sequence_number: int` + Each event in a server-sent events stream has an `event` and `data` property: - The sequence number of this event. + ``` + event: thread.created + data: {"id": "thread_123", "object": "thread", ...} + ``` - - `type: Literal["response.file_search_call.in_progress"]` + 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. - The type of the event. Always `response.file_search_call.in_progress`. + - `object: Literal["thread"]` - - `"response.file_search_call.in_progress"` + The object type, which is always `thread`. - - `agent: Optional[Agent]` + - `"thread"` - The agent that owns this multi-agent streaming event. + - `tool_resources: Optional[ToolResources]` - - `agent_name: str` + 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. - The canonical name of the agent that produced this item. + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - `class BetaResponseFileSearchCallSearchingEvent: …` + - `file_ids: Optional[List[str]]` - Emitted when a file search is currently searching. + 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. - - `item_id: str` + - `file_search: Optional[ToolResourcesFileSearch]` - The ID of the output item that the file search call is initiated. + - `vector_store_ids: Optional[List[str]]` - - `output_index: int` + 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. - The index of the output item that the file search call is searching. + - `event: Literal["thread.created"]` - - `sequence_number: int` + - `"thread.created"` - The sequence number of this event. + - `enabled: Optional[bool]` - - `type: Literal["response.file_search_call.searching"]` + Whether to enable input audio transcription. - The type of the event. Always `response.file_search_call.searching`. + - `class ThreadRunCreated: …` - - `"response.file_search_call.searching"` + Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. - - `agent: Optional[Agent]` + - `data: Run` - The agent that owns this multi-agent streaming event. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `agent_name: str` + - `id: str` - The canonical name of the agent that produced this item. + The identifier, which can be referenced in API endpoints. - - `class BetaResponseFunctionCallArgumentsDeltaEvent: …` + - `assistant_id: str` - Emitted when there is a partial function-call arguments delta. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `delta: str` + - `cancelled_at: Optional[int]` - The function-call arguments delta that is added. + The Unix timestamp (in seconds) for when the run was cancelled. - - `item_id: str` + - `completed_at: Optional[int]` - The ID of the output item that the function-call arguments delta is added to. + The Unix timestamp (in seconds) for when the run was completed. - - `output_index: int` + - `created_at: int` - The index of the output item that the function-call arguments delta is added to. + The Unix timestamp (in seconds) for when the run was created. - - `sequence_number: int` + - `expires_at: Optional[int]` - The sequence number of this event. + The Unix timestamp (in seconds) for when the run will expire. - - `type: Literal["response.function_call_arguments.delta"]` + - `failed_at: Optional[int]` - The type of the event. Always `response.function_call_arguments.delta`. + The Unix timestamp (in seconds) for when the run failed. - - `"response.function_call_arguments.delta"` + - `incomplete_details: Optional[IncompleteDetails]` - - `agent: Optional[Agent]` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The agent that owns this multi-agent streaming event. + - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` - - `agent_name: str` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The canonical name of the agent that produced this item. + - `"max_completion_tokens"` - - `class BetaResponseFunctionCallArgumentsDoneEvent: …` + - `"max_prompt_tokens"` - Emitted when function-call arguments are finalized. + - `instructions: str` - - `arguments: str` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The function-call arguments. + - `last_error: Optional[LastError]` - - `item_id: str` + The last error associated with this run. Will be `null` if there are no errors. - The ID of the item. + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` - - `name: str` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The name of the function that was called. + - `"server_error"` - - `output_index: int` + - `"rate_limit_exceeded"` - The index of the output item. + - `"invalid_prompt"` - - `sequence_number: int` + - `message: str` - The sequence number of this event. + A human-readable description of the error. - - `type: Literal["response.function_call_arguments.done"]` + - `max_completion_tokens: Optional[int]` - - `"response.function_call_arguments.done"` + The maximum number of completion tokens specified to have been used over the course of the run. - - `agent: Optional[Agent]` + - `max_prompt_tokens: Optional[int]` - The agent that owns this multi-agent streaming event. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `agent_name: str` + - `metadata: Optional[Metadata]` - The canonical name of the agent that produced this item. + 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. - - `class BetaResponseInProgressEvent: …` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Emitted when the response is in progress. + - `model: str` - - `response: BetaResponse` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The response that is in progress. + - `object: Literal["thread.run"]` - - `sequence_number: int` + The object type, which is always `thread.run`. - The sequence number of this event. + - `"thread.run"` - - `type: Literal["response.in_progress"]` + - `parallel_tool_calls: bool` - The type of the event. Always `response.in_progress`. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"response.in_progress"` + - `required_action: Optional[RequiredAction]` - - `agent: Optional[Agent]` + Details on the action required to continue the run. Will be `null` if no action is required. - The agent that owns this multi-agent streaming event. + - `submit_tool_outputs: RequiredActionSubmitToolOutputs` - - `agent_name: str` + Details on the tool outputs needed for this run to continue. - The canonical name of the agent that produced this item. + - `tool_calls: List[RequiredActionFunctionToolCall]` - - `class BetaResponseFailedEvent: …` + A list of the relevant tool calls. - An event that is emitted when a response fails. + - `id: str` - - `response: BetaResponse` + 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. - The response that failed. + - `function: Function` - - `sequence_number: int` + The function definition. - The sequence number of this event. + - `arguments: str` - - `type: Literal["response.failed"]` + The arguments that the model expects you to pass to the function. - The type of the event. Always `response.failed`. + - `name: str` - - `"response.failed"` + The name of the function. - - `agent: Optional[Agent]` + - `type: Literal["function"]` - The agent that owns this multi-agent streaming event. + The type of tool call the output is required for. For now, this is always `function`. - - `agent_name: str` + - `"function"` - The canonical name of the agent that produced this item. + - `type: Literal["submit_tool_outputs"]` - - `class BetaResponseIncompleteEvent: …` + For now, this is always `submit_tool_outputs`. - An event that is emitted when a response finishes as incomplete. + - `"submit_tool_outputs"` - - `response: BetaResponse` + - `response_format: Optional[AssistantResponseFormatOption]` - The response that was incomplete. + 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`. - - `sequence_number: int` + 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). - The sequence number of this event. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `type: Literal["response.incomplete"]` + **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. - The type of the event. Always `response.incomplete`. + - `Literal["auto"]` - - `"response.incomplete"` + `auto` is the default value - - `agent: Optional[Agent]` + - `"auto"` - The agent that owns this multi-agent streaming event. + - `class ResponseFormatText: …` - - `agent_name: str` + Default response format. Used to generate text responses. - The canonical name of the agent that produced this item. + - `type: Literal["text"]` - - `class BetaResponseOutputItemAddedEvent: …` + The type of response format being defined. Always `text`. - Emitted when a new output item is added. + - `"text"` - - `item: BetaResponseOutputItem` + - `class ResponseFormatJSONObject: …` - The output item that was added. + 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. - - `class BetaResponseOutputMessage: …` + - `type: Literal["json_object"]` - An output message from the model. + The type of response format being defined. Always `json_object`. - - `class BetaResponseFileSearchToolCall: …` + - `"json_object"` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `class ResponseFormatJSONSchema: …` - - `class BetaResponseFunctionToolCall: …` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `json_schema: JSONSchema` - - `class BetaResponseFunctionToolCallOutputItem: …` + Structured Outputs configuration options, including a JSON Schema. - - `class AgentMessage: …` + - `name: str` - - `class MultiAgentCall: …` + 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. - - `class MultiAgentCallOutput: …` + - `description: Optional[str]` - - `class BetaResponseFunctionWebSearch: …` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `schema: Optional[Dict[str, object]]` - - `class BetaResponseComputerToolCall: …` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `strict: Optional[bool]` - - `class BetaResponseComputerToolCallOutputItem: …` + 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). - - `class BetaResponseReasoningItem: …` + - `type: Literal["json_schema"]` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The type of response format being defined. Always `json_schema`. - - `class Program: …` + - `"json_schema"` - - `class ProgramOutput: …` + - `started_at: Optional[int]` - - `class BetaResponseToolSearchCall: …` + The Unix timestamp (in seconds) for when the run was started. - - `class BetaResponseToolSearchOutputItem: …` + - `status: RunStatus` - - `class AdditionalTools: …` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `class BetaResponseCompactionItem: …` + - `"queued"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"in_progress"` - - `class ImageGenerationCall: …` + - `"requires_action"` - An image generation request made by the model. + - `"cancelling"` - - `class BetaResponseCodeInterpreterToolCall: …` + - `"cancelled"` - A tool call to run code. + - `"failed"` - - `class LocalShellCall: …` + - `"completed"` - A tool call to run a command on the local shell. + - `"incomplete"` - - `class LocalShellCallOutput: …` + - `"expired"` - The output of a local shell tool call. + - `thread_id: str` - - `class BetaResponseFunctionShellToolCall: …` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - A tool call that executes one or more shell commands in a managed environment. + - `tool_choice: Optional[AssistantToolChoiceOption]` - - `class BetaResponseFunctionShellToolCallOutput: …` + 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. - The output of a shell tool call that was emitted. + - `Literal["none", "auto", "required"]` - - `class BetaResponseApplyPatchToolCall: …` + `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. - A tool call that applies file diffs by creating, deleting, or updating files. + - `"none"` - - `class BetaResponseApplyPatchToolCallOutput: …` + - `"auto"` - The output emitted by an apply patch tool call. + - `"required"` - - `class McpCall: …` + - `class AssistantToolChoice: …` - An invocation of a tool on an MCP server. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `class McpListTools: …` + - `type: Literal["function", "code_interpreter", "file_search"]` - A list of tools available on an MCP server. + The type of the tool. If type is `function`, the function name must be set - - `class McpApprovalRequest: …` + - `"function"` - A request for human approval of a tool invocation. + - `"code_interpreter"` - - `class McpApprovalResponse: …` + - `"file_search"` - A response to an MCP approval request. + - `function: Optional[AssistantToolChoiceFunction]` - - `class BetaResponseCustomToolCall: …` + - `name: str` - A call to a custom tool created by the model. + The name of the function to call. - - `class BetaResponseCustomToolCallOutputItem: …` + - `tools: List[AssistantTool]` - The output of a custom tool call from your code, being sent back to the model. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `output_index: int` + - `class CodeInterpreterTool: …` - The index of the output item that was added. + - `type: Literal["code_interpreter"]` - - `sequence_number: int` + The type of tool being defined: `code_interpreter` - The sequence number of this event. + - `"code_interpreter"` - - `type: Literal["response.output_item.added"]` + - `class FileSearchTool: …` - The type of the event. Always `response.output_item.added`. + - `type: Literal["file_search"]` - - `"response.output_item.added"` + The type of tool being defined: `file_search` - - `agent: Optional[Agent]` + - `"file_search"` - The agent that owns this multi-agent streaming event. + - `file_search: Optional[FileSearch]` - - `agent_name: str` + Overrides for the file search tool. - The canonical name of the agent that produced this item. + - `max_num_results: Optional[int]` - - `class BetaResponseOutputItemDoneEvent: …` + 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. - Emitted when an output item is marked done. + 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. - - `item: BetaResponseOutputItem` + - `ranking_options: Optional[FileSearchRankingOptions]` - The output item that was marked done. + 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. - - `output_index: int` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The index of the output item that was marked done. + - `score_threshold: float` - - `sequence_number: int` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The sequence number of this event. + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - `type: Literal["response.output_item.done"]` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The type of the event. Always `response.output_item.done`. + - `"auto"` - - `"response.output_item.done"` + - `"default_2024_08_21"` - - `agent: Optional[Agent]` + - `class FunctionTool: …` - The agent that owns this multi-agent streaming event. + - `function: FunctionDefinition` - - `agent_name: str` + - `name: str` - The canonical name of the agent that produced this item. + 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. - - `class BetaResponseReasoningSummaryPartAddedEvent: …` + - `description: Optional[str]` - Emitted when a new reasoning summary part is added. + A description of what the function does, used by the model to choose when and how to call the function. - - `item_id: str` + - `parameters: Optional[FunctionParameters]` - The ID of the item this summary part is associated with. + 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. - - `output_index: int` + Omitting `parameters` defines a function with an empty parameter list. - The index of the output item this summary part is associated with. + - `strict: Optional[bool]` - - `part: Part` + 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). - The summary part that was added. + - `type: Literal["function"]` - - `text: str` + The type of tool being defined: `function` - The text of the summary part. + - `"function"` - - `type: Literal["summary_text"]` + - `truncation_strategy: Optional[TruncationStrategy]` - The type of the summary part. Always `summary_text`. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"summary_text"` + - `type: Literal["auto", "last_messages"]` - - `sequence_number: int` + 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`. - The sequence number of this event. + - `"auto"` - - `summary_index: int` + - `"last_messages"` - The index of the summary part within the reasoning summary. + - `last_messages: Optional[int]` - - `type: Literal["response.reasoning_summary_part.added"]` + The number of most recent messages from the thread when constructing the context for the run. - The type of the event. Always `response.reasoning_summary_part.added`. + - `usage: Optional[Usage]` - - `"response.reasoning_summary_part.added"` + 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.). - - `agent: Optional[Agent]` + - `completion_tokens: int` - The agent that owns this multi-agent streaming event. + Number of completion tokens used over the course of the run. - - `agent_name: str` + - `prompt_tokens: int` - The canonical name of the agent that produced this item. + Number of prompt tokens used over the course of the run. - - `class BetaResponseReasoningSummaryPartDoneEvent: …` + - `total_tokens: int` - Emitted when a reasoning summary part is completed. + Total number of tokens used (prompt + completion). - - `item_id: str` + - `temperature: Optional[float]` - The ID of the item this summary part is associated with. + The sampling temperature used for this run. If not set, defaults to 1. - - `output_index: int` + - `top_p: Optional[float]` - The index of the output item this summary part is associated with. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `part: Part` + - `event: Literal["thread.run.created"]` - The completed summary part. + - `"thread.run.created"` - - `text: str` + - `class ThreadRunQueued: …` - The text of the summary part. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. - - `type: Literal["summary_text"]` + - `data: Run` - The type of the summary part. Always `summary_text`. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"summary_text"` + - `event: Literal["thread.run.queued"]` - - `sequence_number: int` + - `"thread.run.queued"` - The sequence number of this event. + - `class ThreadRunInProgress: …` - - `summary_index: int` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. - The index of the summary part within the reasoning summary. + - `data: Run` - - `type: Literal["response.reasoning_summary_part.done"]` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The type of the event. Always `response.reasoning_summary_part.done`. + - `event: Literal["thread.run.in_progress"]` - - `"response.reasoning_summary_part.done"` + - `"thread.run.in_progress"` - - `agent: Optional[Agent]` + - `class ThreadRunRequiresAction: …` - The agent that owns this multi-agent streaming event. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. - - `agent_name: str` + - `data: Run` - The canonical name of the agent that produced this item. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `status: Optional[Literal["incomplete"]]` + - `event: Literal["thread.run.requires_action"]` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + - `"thread.run.requires_action"` - - `"incomplete"` + - `class ThreadRunCompleted: …` - - `class BetaResponseReasoningSummaryTextDeltaEvent: …` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. - Emitted when a delta is added to a reasoning summary text. + - `data: Run` - - `delta: str` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The text delta that was added to the summary. + - `event: Literal["thread.run.completed"]` - - `item_id: str` + - `"thread.run.completed"` - The ID of the item this summary text delta is associated with. + - `class ThreadRunIncomplete: …` - - `output_index: int` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. - The index of the output item this summary text delta is associated with. + - `data: Run` - - `sequence_number: int` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The sequence number of this event. + - `event: Literal["thread.run.incomplete"]` - - `summary_index: int` + - `"thread.run.incomplete"` - The index of the summary part within the reasoning summary. + - `class ThreadRunFailed: …` - - `type: Literal["response.reasoning_summary_text.delta"]` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. - The type of the event. Always `response.reasoning_summary_text.delta`. + - `data: Run` - - `"response.reasoning_summary_text.delta"` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `agent: Optional[Agent]` + - `event: Literal["thread.run.failed"]` - The agent that owns this multi-agent streaming event. + - `"thread.run.failed"` - - `agent_name: str` + - `class ThreadRunCancelling: …` - The canonical name of the agent that produced this item. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. - - `class BetaResponseReasoningSummaryTextDoneEvent: …` + - `data: Run` - Emitted when a reasoning summary text is completed. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `item_id: str` + - `event: Literal["thread.run.cancelling"]` - The ID of the item this summary text is associated with. + - `"thread.run.cancelling"` - - `output_index: int` + - `class ThreadRunCancelled: …` - The index of the output item this summary text is associated with. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. - - `sequence_number: int` + - `data: Run` - The sequence number of this event. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `summary_index: int` + - `event: Literal["thread.run.cancelled"]` - The index of the summary part within the reasoning summary. + - `"thread.run.cancelled"` - - `text: str` + - `class ThreadRunExpired: …` - The full text of the completed reasoning summary. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. - - `type: Literal["response.reasoning_summary_text.done"]` + - `data: Run` - The type of the event. Always `response.reasoning_summary_text.done`. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"response.reasoning_summary_text.done"` + - `event: Literal["thread.run.expired"]` - - `agent: Optional[Agent]` + - `"thread.run.expired"` - The agent that owns this multi-agent streaming event. + - `class ThreadRunStepCreated: …` - - `agent_name: str` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. - The canonical name of the agent that produced this item. + - `data: RunStep` - - `class BetaResponseReasoningTextDeltaEvent: …` + Represents a step in execution of a run. - Emitted when a delta is added to a reasoning text. + - `id: str` - - `content_index: int` + The identifier of the run step, which can be referenced in API endpoints. - The index of the reasoning content part this delta is associated with. + - `assistant_id: str` - - `delta: str` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - The text delta that was added to the reasoning content. + - `cancelled_at: Optional[int]` - - `item_id: str` + The Unix timestamp (in seconds) for when the run step was cancelled. - The ID of the item this reasoning text delta is associated with. + - `completed_at: Optional[int]` - - `output_index: int` + The Unix timestamp (in seconds) for when the run step completed. - The index of the output item this reasoning text delta is associated with. + - `created_at: int` - - `sequence_number: int` + The Unix timestamp (in seconds) for when the run step was created. - The sequence number of this event. + - `expired_at: Optional[int]` - - `type: Literal["response.reasoning_text.delta"]` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The type of the event. Always `response.reasoning_text.delta`. + - `failed_at: Optional[int]` - - `"response.reasoning_text.delta"` + The Unix timestamp (in seconds) for when the run step failed. - - `agent: Optional[Agent]` + - `last_error: Optional[LastError]` - The agent that owns this multi-agent streaming event. + The last error associated with this run step. Will be `null` if there are no errors. - - `agent_name: str` + - `code: Literal["server_error", "rate_limit_exceeded"]` - The canonical name of the agent that produced this item. + One of `server_error` or `rate_limit_exceeded`. - - `class BetaResponseReasoningTextDoneEvent: …` + - `"server_error"` - Emitted when a reasoning text is completed. + - `"rate_limit_exceeded"` - - `content_index: int` + - `message: str` - The index of the reasoning content part. + A human-readable description of the error. - - `item_id: str` + - `metadata: Optional[Metadata]` - The ID of the item this reasoning text is associated with. + 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. - - `output_index: int` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The index of the output item this reasoning text is associated with. + - `object: Literal["thread.run.step"]` - - `sequence_number: int` + The object type, which is always `thread.run.step`. - The sequence number of this event. + - `"thread.run.step"` - - `text: str` + - `run_id: str` - The full text of the completed reasoning content. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `type: Literal["response.reasoning_text.done"]` + - `status: Literal["in_progress", "cancelled", "failed", 2 more]` - The type of the event. Always `response.reasoning_text.done`. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `"response.reasoning_text.done"` + - `"in_progress"` - - `agent: Optional[Agent]` + - `"cancelled"` - The agent that owns this multi-agent streaming event. + - `"failed"` - - `agent_name: str` + - `"completed"` - The canonical name of the agent that produced this item. + - `"expired"` - - `class BetaResponseRefusalDeltaEvent: …` + - `step_details: StepDetails` - Emitted when there is a partial refusal text. + The details of the run step. - - `content_index: int` + - `class MessageCreationStepDetails: …` - The index of the content part that the refusal text is added to. + Details of the message creation by the run step. - - `delta: str` + - `message_creation: MessageCreation` - The refusal text that is added. + - `message_id: str` - - `item_id: str` + The ID of the message that was created by this run step. - The ID of the output item that the refusal text is added to. + - `type: Literal["message_creation"]` - - `output_index: int` + Always `message_creation`. - The index of the output item that the refusal text is added to. + - `"message_creation"` - - `sequence_number: int` + - `class ToolCallsStepDetails: …` - The sequence number of this event. + Details of the tool call. - - `type: Literal["response.refusal.delta"]` + - `tool_calls: List[ToolCall]` - The type of the event. Always `response.refusal.delta`. + 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`. - - `"response.refusal.delta"` + - `class CodeInterpreterToolCall: …` - - `agent: Optional[Agent]` + Details of the Code Interpreter tool call the run step was involved in. - The agent that owns this multi-agent streaming event. + - `id: str` - - `agent_name: str` + The ID of the tool call. - The canonical name of the agent that produced this item. + - `code_interpreter: CodeInterpreter` - - `class BetaResponseRefusalDoneEvent: …` + The Code Interpreter tool call definition. - Emitted when refusal text is finalized. + - `input: str` - - `content_index: int` + The input to the Code Interpreter tool call. - The index of the content part that the refusal text is finalized. + - `outputs: List[CodeInterpreterOutput]` - - `item_id: str` + 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. - The ID of the output item that the refusal text is finalized. + - `class CodeInterpreterOutputLogs: …` - - `output_index: int` + Text output from the Code Interpreter tool call as part of a run step. - The index of the output item that the refusal text is finalized. + - `logs: str` - - `refusal: str` + The text output from the Code Interpreter tool call. - The refusal text that is finalized. + - `type: Literal["logs"]` - - `sequence_number: int` + Always `logs`. - The sequence number of this event. + - `"logs"` - - `type: Literal["response.refusal.done"]` + - `class CodeInterpreterOutputImage: …` - The type of the event. Always `response.refusal.done`. + - `image: CodeInterpreterOutputImageImage` - - `"response.refusal.done"` + - `file_id: str` - - `agent: Optional[Agent]` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The agent that owns this multi-agent streaming event. + - `type: Literal["image"]` - - `agent_name: str` + Always `image`. - The canonical name of the agent that produced this item. + - `"image"` - - `class BetaResponseTextDeltaEvent: …` + - `type: Literal["code_interpreter"]` - Emitted when there is an additional text delta. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `content_index: int` + - `"code_interpreter"` - The index of the content part that the text delta was added to. + - `class FileSearchToolCall: …` - - `delta: str` + - `id: str` - The text delta that was added. + The ID of the tool call object. - - `item_id: str` + - `file_search: FileSearch` - The ID of the output item that the text delta was added to. + For now, this is always going to be an empty object. - - `logprobs: List[Logprob]` + - `ranking_options: Optional[FileSearchRankingOptions]` - The log probabilities of the tokens in the delta. + The ranking options for the file search. - - `token: str` + - `ranker: Literal["auto", "default_2024_08_21"]` - A possible text token. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `logprob: float` + - `"auto"` - The log probability of this token. + - `"default_2024_08_21"` - - `top_logprobs: Optional[List[LogprobTopLogprob]]` + - `score_threshold: float` - The log probabilities of up to 20 of the most likely tokens. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `token: Optional[str]` + - `results: Optional[List[FileSearchResult]]` - A possible text token. + The results of the file search. - - `logprob: Optional[float]` + - `file_id: str` - The log probability of this token. + The ID of the file that result was found in. - - `output_index: int` + - `file_name: str` - The index of the output item that the text delta was added to. + The name of the file that result was found in. - - `sequence_number: int` + - `score: float` - The sequence number for this event. + The score of the result. All values must be a floating point number between 0 and 1. - - `type: Literal["response.output_text.delta"]` + - `content: Optional[List[FileSearchResultContent]]` - The type of the event. Always `response.output_text.delta`. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `"response.output_text.delta"` + - `text: Optional[str]` - - `agent: Optional[Agent]` + The text content of the file. - The agent that owns this multi-agent streaming event. + - `type: Optional[Literal["text"]]` - - `agent_name: str` + The type of the content. - The canonical name of the agent that produced this item. + - `"text"` - - `class BetaResponseTextDoneEvent: …` + - `type: Literal["file_search"]` - Emitted when text content is finalized. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `content_index: int` + - `"file_search"` - The index of the content part that the text content is finalized. + - `class FunctionToolCall: …` - - `item_id: str` + - `id: str` - The ID of the output item that the text content is finalized. + The ID of the tool call object. - - `logprobs: List[Logprob]` + - `function: Function` - The log probabilities of the tokens in the delta. + The definition of the function that was called. - - `token: str` + - `arguments: str` - A possible text token. + The arguments passed to the function. - - `logprob: float` + - `name: str` - The log probability of this token. + The name of the function. - - `top_logprobs: Optional[List[LogprobTopLogprob]]` + - `output: Optional[str]` - The log probabilities of up to 20 of the most likely tokens. + 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. - - `token: Optional[str]` + - `type: Literal["function"]` - A possible text token. + The type of tool call. This is always going to be `function` for this type of tool call. - - `logprob: Optional[float]` + - `"function"` - The log probability of this token. + - `type: Literal["tool_calls"]` - - `output_index: int` + Always `tool_calls`. - The index of the output item that the text content is finalized. + - `"tool_calls"` - - `sequence_number: int` + - `thread_id: str` - The sequence number for this event. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `text: str` + - `type: Literal["message_creation", "tool_calls"]` - The text content that is finalized. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `type: Literal["response.output_text.done"]` + - `"message_creation"` - The type of the event. Always `response.output_text.done`. + - `"tool_calls"` - - `"response.output_text.done"` + - `usage: Optional[Usage]` - - `agent: Optional[Agent]` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - The agent that owns this multi-agent streaming event. + - `completion_tokens: int` - - `agent_name: str` + Number of completion tokens used over the course of the run step. - The canonical name of the agent that produced this item. + - `prompt_tokens: int` - - `class BetaResponseWebSearchCallCompletedEvent: …` + Number of prompt tokens used over the course of the run step. - Emitted when a web search call is completed. + - `total_tokens: int` - - `item_id: str` + Total number of tokens used (prompt + completion). - Unique ID for the output item associated with the web search call. + - `event: Literal["thread.run.step.created"]` - - `output_index: int` + - `"thread.run.step.created"` - The index of the output item that the web search call is associated with. + - `class ThreadRunStepInProgress: …` - - `sequence_number: int` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. - The sequence number of the web search call being processed. + - `data: RunStep` - - `type: Literal["response.web_search_call.completed"]` + Represents a step in execution of a run. - The type of the event. Always `response.web_search_call.completed`. + - `event: Literal["thread.run.step.in_progress"]` - - `"response.web_search_call.completed"` + - `"thread.run.step.in_progress"` - - `agent: Optional[Agent]` + - `class ThreadRunStepDelta: …` - The agent that owns this multi-agent streaming event. + Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. - - `agent_name: str` + - `data: RunStepDeltaEvent` - The canonical name of the agent that produced this item. + Represents a run step delta i.e. any changed fields on a run step during streaming. - - `class BetaResponseWebSearchCallInProgressEvent: …` + - `id: str` - Emitted when a web search call is initiated. + The identifier of the run step, which can be referenced in API endpoints. - - `item_id: str` + - `delta: RunStepDelta` - Unique ID for the output item associated with the web search call. + The delta containing the fields that have changed on the run step. - - `output_index: int` + - `step_details: Optional[StepDetails]` - The index of the output item that the web search call is associated with. + The details of the run step. - - `sequence_number: int` + - `class RunStepDeltaMessageDelta: …` - The sequence number of the web search call being processed. + Details of the message creation by the run step. - - `type: Literal["response.web_search_call.in_progress"]` + - `type: Literal["message_creation"]` - The type of the event. Always `response.web_search_call.in_progress`. + Always `message_creation`. - - `"response.web_search_call.in_progress"` + - `"message_creation"` - - `agent: Optional[Agent]` + - `message_creation: Optional[MessageCreation]` - The agent that owns this multi-agent streaming event. + - `message_id: Optional[str]` - - `agent_name: str` + The ID of the message that was created by this run step. - The canonical name of the agent that produced this item. + - `class ToolCallDeltaObject: …` - - `class BetaResponseWebSearchCallSearchingEvent: …` + Details of the tool call. - Emitted when a web search call is executing. + - `type: Literal["tool_calls"]` - - `item_id: str` + Always `tool_calls`. - Unique ID for the output item associated with the web search call. + - `"tool_calls"` - - `output_index: int` + - `tool_calls: Optional[List[ToolCallDelta]]` - The index of the output item that the web search call is associated with. + 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`. - - `sequence_number: int` + - `class CodeInterpreterToolCallDelta: …` - The sequence number of the web search call being processed. + Details of the Code Interpreter tool call the run step was involved in. - - `type: Literal["response.web_search_call.searching"]` + - `index: int` - The type of the event. Always `response.web_search_call.searching`. + The index of the tool call in the tool calls array. - - `"response.web_search_call.searching"` + - `type: Literal["code_interpreter"]` - - `agent: Optional[Agent]` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The agent that owns this multi-agent streaming event. + - `"code_interpreter"` - - `agent_name: str` + - `id: Optional[str]` - The canonical name of the agent that produced this item. + The ID of the tool call. - - `class BetaResponseImageGenCallCompletedEvent: …` + - `code_interpreter: Optional[CodeInterpreter]` - Emitted when an image generation tool call has completed and the final image is available. + The Code Interpreter tool call definition. - - `item_id: str` + - `input: Optional[str]` - The unique identifier of the image generation item being processed. + The input to the Code Interpreter tool call. - - `output_index: int` + - `outputs: Optional[List[CodeInterpreterOutput]]` - The index of the output item in the response's output array. + 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. - - `sequence_number: int` + - `class CodeInterpreterLogs: …` - The sequence number of this event. + Text output from the Code Interpreter tool call as part of a run step. - - `type: Literal["response.image_generation_call.completed"]` + - `index: int` - The type of the event. Always 'response.image_generation_call.completed'. + The index of the output in the outputs array. - - `"response.image_generation_call.completed"` + - `type: Literal["logs"]` - - `agent: Optional[Agent]` + Always `logs`. - The agent that owns this multi-agent streaming event. + - `"logs"` - - `agent_name: str` + - `logs: Optional[str]` - The canonical name of the agent that produced this item. + The text output from the Code Interpreter tool call. - - `class BetaResponseImageGenCallGeneratingEvent: …` + - `class CodeInterpreterOutputImage: …` - Emitted when an image generation tool call is actively generating an image (intermediate state). + - `index: int` - - `item_id: str` + The index of the output in the outputs array. - The unique identifier of the image generation item being processed. + - `type: Literal["image"]` - - `output_index: int` + Always `image`. - The index of the output item in the response's output array. + - `"image"` - - `sequence_number: int` + - `image: Optional[Image]` - The sequence number of the image generation item being processed. + - `file_id: Optional[str]` - - `type: Literal["response.image_generation_call.generating"]` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The type of the event. Always 'response.image_generation_call.generating'. + - `class FileSearchToolCallDelta: …` - - `"response.image_generation_call.generating"` + - `file_search: object` - - `agent: Optional[Agent]` + For now, this is always going to be an empty object. - The agent that owns this multi-agent streaming event. + - `index: int` - - `agent_name: str` + The index of the tool call in the tool calls array. - The canonical name of the agent that produced this item. + - `type: Literal["file_search"]` - - `class BetaResponseImageGenCallInProgressEvent: …` + The type of tool call. This is always going to be `file_search` for this type of tool call. - Emitted when an image generation tool call is in progress. + - `"file_search"` - - `item_id: str` + - `id: Optional[str]` - The unique identifier of the image generation item being processed. + The ID of the tool call object. - - `output_index: int` + - `class FunctionToolCallDelta: …` - The index of the output item in the response's output array. + - `index: int` - - `sequence_number: int` + The index of the tool call in the tool calls array. - The sequence number of the image generation item being processed. + - `type: Literal["function"]` - - `type: Literal["response.image_generation_call.in_progress"]` + The type of tool call. This is always going to be `function` for this type of tool call. - The type of the event. Always 'response.image_generation_call.in_progress'. + - `"function"` - - `"response.image_generation_call.in_progress"` + - `id: Optional[str]` - - `agent: Optional[Agent]` + The ID of the tool call object. - The agent that owns this multi-agent streaming event. + - `function: Optional[Function]` - - `agent_name: str` + The definition of the function that was called. - The canonical name of the agent that produced this item. + - `arguments: Optional[str]` - - `class BetaResponseImageGenCallPartialImageEvent: …` + The arguments passed to the function. - Emitted when a partial image is available during image generation streaming. + - `name: Optional[str]` - - `item_id: str` + The name of the function. - The unique identifier of the image generation item being processed. + - `output: Optional[str]` - - `output_index: int` + 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. - The index of the output item in the response's output array. + - `object: Literal["thread.run.step.delta"]` - - `partial_image_b64: str` + The object type, which is always `thread.run.step.delta`. - Base64-encoded partial image data, suitable for rendering as an image. + - `"thread.run.step.delta"` - - `partial_image_index: int` + - `event: Literal["thread.run.step.delta"]` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + - `"thread.run.step.delta"` - - `sequence_number: int` + - `class ThreadRunStepCompleted: …` - The sequence number of the image generation item being processed. + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. - - `type: Literal["response.image_generation_call.partial_image"]` + - `data: RunStep` - The type of the event. Always 'response.image_generation_call.partial_image'. + Represents a step in execution of a run. - - `"response.image_generation_call.partial_image"` + - `event: Literal["thread.run.step.completed"]` - - `agent: Optional[Agent]` + - `"thread.run.step.completed"` - The agent that owns this multi-agent streaming event. + - `class ThreadRunStepFailed: …` - - `agent_name: str` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. - The canonical name of the agent that produced this item. + - `data: RunStep` - - `class BetaResponseMcpCallArgumentsDeltaEvent: …` + Represents a step in execution of a run. - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + - `event: Literal["thread.run.step.failed"]` - - `delta: str` + - `"thread.run.step.failed"` - A JSON string containing the partial update to the arguments for the MCP tool call. + - `class ThreadRunStepCancelled: …` - - `item_id: str` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. - The unique identifier of the MCP tool call item being processed. + - `data: RunStep` - - `output_index: int` + Represents a step in execution of a run. - The index of the output item in the response's output array. + - `event: Literal["thread.run.step.cancelled"]` - - `sequence_number: int` + - `"thread.run.step.cancelled"` - The sequence number of this event. + - `class ThreadRunStepExpired: …` - - `type: Literal["response.mcp_call_arguments.delta"]` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. - The type of the event. Always 'response.mcp_call_arguments.delta'. + - `data: RunStep` - - `"response.mcp_call_arguments.delta"` + Represents a step in execution of a run. - - `agent: Optional[Agent]` + - `event: Literal["thread.run.step.expired"]` - The agent that owns this multi-agent streaming event. + - `"thread.run.step.expired"` - - `agent_name: str` + - `class ThreadMessageCreated: …` - The canonical name of the agent that produced this item. + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - - `class BetaResponseMcpCallArgumentsDoneEvent: …` + - `data: Message` - Emitted when the arguments for an MCP tool call are finalized. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `arguments: str` + - `id: str` - A JSON string containing the finalized arguments for the MCP tool call. + The identifier, which can be referenced in API endpoints. - - `item_id: str` + - `assistant_id: Optional[str]` - The unique identifier of the MCP tool call item being processed. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `output_index: int` + - `attachments: Optional[List[Attachment]]` - The index of the output item in the response's output array. + A list of files attached to the message, and the tools they were added to. - - `sequence_number: int` + - `file_id: Optional[str]` - The sequence number of this event. + The ID of the file to attach to the message. - - `type: Literal["response.mcp_call_arguments.done"]` + - `tools: Optional[List[AttachmentTool]]` - The type of the event. Always 'response.mcp_call_arguments.done'. + The tools to add this file to. - - `"response.mcp_call_arguments.done"` + - `class CodeInterpreterTool: …` - - `agent: Optional[Agent]` + - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` - The agent that owns this multi-agent streaming event. + - `type: Literal["file_search"]` - - `agent_name: str` + The type of tool being defined: `file_search` - The canonical name of the agent that produced this item. + - `"file_search"` - - `class BetaResponseMcpCallCompletedEvent: …` + - `completed_at: Optional[int]` - Emitted when an MCP tool call has completed successfully. + The Unix timestamp (in seconds) for when the message was completed. - - `item_id: str` + - `content: List[MessageContent]` - The ID of the MCP tool call item that completed. + The content of the message in array of text and/or images. - - `output_index: int` + - `class ImageFileContentBlock: …` - The index of the output item that completed. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `sequence_number: int` + - `image_file: ImageFile` - The sequence number of this event. + - `file_id: str` - - `type: Literal["response.mcp_call.completed"]` + 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. - The type of the event. Always 'response.mcp_call.completed'. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"response.mcp_call.completed"` + 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`. - - `agent: Optional[Agent]` + - `"auto"` - The agent that owns this multi-agent streaming event. + - `"low"` - - `agent_name: str` + - `"high"` - The canonical name of the agent that produced this item. + - `type: Literal["image_file"]` - - `class BetaResponseMcpCallFailedEvent: …` + Always `image_file`. - Emitted when an MCP tool call has failed. + - `"image_file"` - - `item_id: str` + - `class ImageURLContentBlock: …` - The ID of the MCP tool call item that failed. + References an image URL in the content of a message. - - `output_index: int` + - `image_url: ImageURL` - The index of the output item that failed. + - `url: str` - - `sequence_number: int` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The sequence number of this event. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `type: Literal["response.mcp_call.failed"]` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - The type of the event. Always 'response.mcp_call.failed'. + - `"auto"` - - `"response.mcp_call.failed"` + - `"low"` - - `agent: Optional[Agent]` + - `"high"` - The agent that owns this multi-agent streaming event. + - `type: Literal["image_url"]` - - `agent_name: str` + The type of the content part. - The canonical name of the agent that produced this item. + - `"image_url"` - - `class BetaResponseMcpCallInProgressEvent: …` + - `class TextContentBlock: …` - Emitted when an MCP tool call is in progress. + The text content that is part of a message. - - `item_id: str` + - `text: Text` - The unique identifier of the MCP tool call item being processed. + - `annotations: List[Annotation]` - - `output_index: int` + - `class FileCitationAnnotation: …` - The index of the output item in the response's output array. + 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. - - `sequence_number: int` + - `end_index: int` - The sequence number of this event. + - `file_citation: FileCitation` - - `type: Literal["response.mcp_call.in_progress"]` + - `file_id: str` - The type of the event. Always 'response.mcp_call.in_progress'. + The ID of the specific File the citation is from. - - `"response.mcp_call.in_progress"` + - `start_index: int` - - `agent: Optional[Agent]` + - `text: str` - The agent that owns this multi-agent streaming event. + The text in the message content that needs to be replaced. - - `agent_name: str` + - `type: Literal["file_citation"]` - The canonical name of the agent that produced this item. + Always `file_citation`. - - `class BetaResponseMcpListToolsCompletedEvent: …` + - `"file_citation"` - Emitted when the list of available MCP tools has been successfully retrieved. + - `class FilePathAnnotation: …` - - `item_id: str` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The ID of the MCP tool call item that produced this output. + - `end_index: int` - - `output_index: int` + - `file_path: FilePath` - The index of the output item that was processed. + - `file_id: str` - - `sequence_number: int` + The ID of the file that was generated. - The sequence number of this event. + - `start_index: int` - - `type: Literal["response.mcp_list_tools.completed"]` + - `text: str` - The type of the event. Always 'response.mcp_list_tools.completed'. + The text in the message content that needs to be replaced. - - `"response.mcp_list_tools.completed"` + - `type: Literal["file_path"]` - - `agent: Optional[Agent]` + Always `file_path`. - The agent that owns this multi-agent streaming event. + - `"file_path"` - - `agent_name: str` + - `value: str` - The canonical name of the agent that produced this item. + The data that makes up the text. - - `class BetaResponseMcpListToolsFailedEvent: …` + - `type: Literal["text"]` - Emitted when the attempt to list available MCP tools has failed. + Always `text`. - - `item_id: str` + - `"text"` - The ID of the MCP tool call item that failed. + - `class RefusalContentBlock: …` - - `output_index: int` + The refusal content generated by the assistant. - The index of the output item that failed. + - `refusal: str` - - `sequence_number: int` + - `type: Literal["refusal"]` - The sequence number of this event. + Always `refusal`. - - `type: Literal["response.mcp_list_tools.failed"]` + - `"refusal"` - The type of the event. Always 'response.mcp_list_tools.failed'. + - `created_at: int` - - `"response.mcp_list_tools.failed"` + The Unix timestamp (in seconds) for when the message was created. - - `agent: Optional[Agent]` + - `incomplete_at: Optional[int]` - The agent that owns this multi-agent streaming event. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `agent_name: str` + - `incomplete_details: Optional[IncompleteDetails]` - The canonical name of the agent that produced this item. + On an incomplete message, details about why the message is incomplete. - - `class BetaResponseMcpListToolsInProgressEvent: …` + - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` - Emitted when the system is in the process of retrieving the list of available MCP tools. + The reason the message is incomplete. - - `item_id: str` + - `"content_filter"` - The ID of the MCP tool call item that is being processed. + - `"max_tokens"` - - `output_index: int` + - `"run_cancelled"` - The index of the output item that is being processed. + - `"run_expired"` - - `sequence_number: int` + - `"run_failed"` - The sequence number of this event. + - `metadata: Optional[Metadata]` - - `type: Literal["response.mcp_list_tools.in_progress"]` + 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. - The type of the event. Always 'response.mcp_list_tools.in_progress'. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"response.mcp_list_tools.in_progress"` + - `object: Literal["thread.message"]` - - `agent: Optional[Agent]` + The object type, which is always `thread.message`. - The agent that owns this multi-agent streaming event. + - `"thread.message"` - - `agent_name: str` + - `role: Literal["user", "assistant"]` - The canonical name of the agent that produced this item. + The entity that produced the message. One of `user` or `assistant`. - - `class BetaResponseOutputTextAnnotationAddedEvent: …` + - `"user"` - Emitted when an annotation is added to output text content. + - `"assistant"` - - `annotation: object` + - `run_id: Optional[str]` - The annotation object being added. (See annotation schema for details.) + 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. - - `annotation_index: int` + - `status: Literal["in_progress", "incomplete", "completed"]` - The index of the annotation within the content part. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `content_index: int` + - `"in_progress"` - The index of the content part within the output item. + - `"incomplete"` - - `item_id: str` + - `"completed"` - The unique identifier of the item to which the annotation is being added. + - `thread_id: str` - - `output_index: int` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - The index of the output item in the response's output array. + - `event: Literal["thread.message.created"]` - - `sequence_number: int` + - `"thread.message.created"` - The sequence number of this event. + - `class ThreadMessageInProgress: …` - - `type: Literal["response.output_text.annotation.added"]` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. - The type of the event. Always 'response.output_text.annotation.added'. + - `data: Message` - - `"response.output_text.annotation.added"` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `agent: Optional[Agent]` + - `event: Literal["thread.message.in_progress"]` - The agent that owns this multi-agent streaming event. + - `"thread.message.in_progress"` - - `agent_name: str` + - `class ThreadMessageDelta: …` - The canonical name of the agent that produced this item. + Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. - - `class BetaResponseQueuedEvent: …` + - `data: MessageDeltaEvent` - Emitted when a response is queued and waiting to be processed. + Represents a message delta i.e. any changed fields on a message during streaming. - - `response: BetaResponse` + - `id: str` - The full response object that is queued. + The identifier of the message, which can be referenced in API endpoints. - - `sequence_number: int` + - `delta: MessageDelta` - The sequence number for this event. + The delta containing the fields that have changed on the Message. - - `type: Literal["response.queued"]` + - `content: Optional[List[MessageContentDelta]]` - The type of the event. Always 'response.queued'. + The content of the message in array of text and/or images. - - `"response.queued"` + - `class ImageFileDeltaBlock: …` - - `agent: Optional[Agent]` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The agent that owns this multi-agent streaming event. + - `index: int` - - `agent_name: str` + The index of the content part in the message. - The canonical name of the agent that produced this item. + - `type: Literal["image_file"]` - - `class BetaResponseCustomToolCallInputDeltaEvent: …` + Always `image_file`. - Event representing a delta (partial update) to the input of a custom tool call. + - `"image_file"` - - `delta: str` + - `image_file: Optional[ImageFileDelta]` - The incremental input data (delta) for the custom tool call. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `item_id: str` + 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`. - Unique identifier for the API item associated with this event. + - `"auto"` - - `output_index: int` + - `"low"` - The index of the output this delta applies to. + - `"high"` - - `sequence_number: int` + - `file_id: Optional[str]` - The sequence number of this event. + 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. - - `type: Literal["response.custom_tool_call_input.delta"]` + - `class TextDeltaBlock: …` - The event type identifier. + The text content that is part of a message. - - `"response.custom_tool_call_input.delta"` + - `index: int` - - `agent: Optional[Agent]` + The index of the content part in the message. - The agent that owns this multi-agent streaming event. + - `type: Literal["text"]` - - `agent_name: str` + Always `text`. - The canonical name of the agent that produced this item. + - `"text"` - - `class BetaResponseCustomToolCallInputDoneEvent: …` + - `text: Optional[TextDelta]` - Event indicating that input for a custom tool call is complete. + - `annotations: Optional[List[AnnotationDelta]]` - - `input: str` + - `class FileCitationDeltaAnnotation: …` - The complete input data for the custom tool call. + 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. - - `item_id: str` + - `index: int` - Unique identifier for the API item associated with this event. + The index of the annotation in the text content part. - - `output_index: int` + - `type: Literal["file_citation"]` - The index of the output this event applies to. + Always `file_citation`. - - `sequence_number: int` + - `"file_citation"` - The sequence number of this event. + - `end_index: Optional[int]` - - `type: Literal["response.custom_tool_call_input.done"]` + - `file_citation: Optional[FileCitation]` - The event type identifier. + - `file_id: Optional[str]` - - `"response.custom_tool_call_input.done"` + The ID of the specific File the citation is from. - - `agent: Optional[Agent]` + - `quote: Optional[str]` - The agent that owns this multi-agent streaming event. + The specific quote in the file. - - `agent_name: str` + - `start_index: Optional[int]` - The canonical name of the agent that produced this item. + - `text: Optional[str]` - - `class ResponseInjectCreated: …` + The text in the message content that needs to be replaced. - Emitted when all injected input items were validated and committed to the - active response. + - `class FilePathDeltaAnnotation: …` - - `response_id: str` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The ID of the response that accepted the input. + - `index: int` - - `sequence_number: int` + The index of the annotation in the text content part. - The sequence number for this event. + - `type: Literal["file_path"]` - - `type: Literal["response.inject.created"]` + Always `file_path`. - The event discriminator. Always `response.inject.created`. + - `"file_path"` - - `"response.inject.created"` + - `end_index: Optional[int]` - - `stream_id: Optional[str]` + - `file_path: Optional[FilePath]` - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + - `file_id: Optional[str]` - - `class ResponseInjectFailed: …` + The ID of the file that was generated. - Emitted when injected input could not be committed to a response. The event - returns the uncommitted raw input so the client can retry it in another - response when appropriate. + - `start_index: Optional[int]` - - `error: ResponseInjectFailedError` + - `text: Optional[str]` - Information about why the input was not committed. + The text in the message content that needs to be replaced. - - `code: Literal["response_already_completed", "response_not_found"]` + - `value: Optional[str]` - A machine-readable error code. + The data that makes up the text. - - `"response_already_completed"` + - `class RefusalDeltaBlock: …` - - `"response_not_found"` + The refusal content that is part of a message. - - `message: str` + - `index: int` - A human-readable description of the error. + The index of the refusal part in the message. - - `input: List[BetaResponseInputItem]` + - `type: Literal["refusal"]` - The raw input items that were not committed. + Always `refusal`. - - `class BetaEasyInputMessage: …` + - `"refusal"` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `refusal: Optional[str]` - - `class Message: …` + - `class ImageURLDeltaBlock: …` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + References an image URL in the content of a message. - - `class BetaResponseOutputMessage: …` + - `index: int` - An output message from the model. + The index of the content part in the message. - - `class BetaResponseFileSearchToolCall: …` + - `type: Literal["image_url"]` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + Always `image_url`. - - `class BetaResponseComputerToolCall: …` + - `"image_url"` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `image_url: Optional[ImageURLDelta]` - - `class ComputerCallOutput: …` + - `detail: Optional[Literal["auto", "low", "high"]]` - The output of a computer tool call. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `class BetaResponseFunctionWebSearch: …` + - `"auto"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `"low"` - - `class BetaResponseFunctionToolCall: …` + - `"high"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `url: Optional[str]` - - `class FunctionCallOutput: …` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The output of a function tool call. + - `role: Optional[Literal["user", "assistant"]]` - - `class AgentMessage: …` + The entity that produced the message. One of `user` or `assistant`. - A message routed between agents. + - `"user"` - - `class MultiAgentCall: …` + - `"assistant"` - - `class MultiAgentCallOutput: …` + - `object: Literal["thread.message.delta"]` - - `class ToolSearchCall: …` + The object type, which is always `thread.message.delta`. - - `class BetaResponseToolSearchOutputItemParam: …` + - `"thread.message.delta"` - - `class AdditionalTools: …` + - `event: Literal["thread.message.delta"]` - - `class BetaResponseReasoningItem: …` + - `"thread.message.delta"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class ThreadMessageCompleted: …` - - `class BetaResponseCompactionItemParam: …` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `data: Message` - - `class ImageGenerationCall: …` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - An image generation request made by the model. + - `event: Literal["thread.message.completed"]` - - `class BetaResponseCodeInterpreterToolCall: …` + - `"thread.message.completed"` - A tool call to run code. + - `class ThreadMessageIncomplete: …` - - `class LocalShellCall: …` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. - A tool call to run a command on the local shell. + - `data: Message` - - `class LocalShellCallOutput: …` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - The output of a local shell tool call. + - `event: Literal["thread.message.incomplete"]` - - `class ShellCall: …` + - `"thread.message.incomplete"` - A tool representing a request to execute one or more shell commands. + - `class ErrorEvent: …` - - `class ShellCallOutput: …` + 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. - The streamed output items emitted by a shell tool call. + - `data: ErrorObject` - - `class ApplyPatchCall: …` + - `code: Optional[str]` - A tool call representing a request to create, delete, or update files using diff patches. + - `message: str` - - `class ApplyPatchCallOutput: …` + - `param: Optional[str]` - The streamed output emitted by an apply patch tool call. + - `type: str` - - `class McpListTools: …` + - `event: Literal["error"]` - A list of tools available on an MCP server. + - `"error"` - - `class McpApprovalRequest: …` +### Assistant Tool - A request for human approval of a tool invocation. +- `AssistantTool` - - `class McpApprovalResponse: …` + - `class CodeInterpreterTool: …` - A response to an MCP approval request. + - `type: Literal["code_interpreter"]` - - `class McpCall: …` + The type of tool being defined: `code_interpreter` - An invocation of a tool on an MCP server. + - `"code_interpreter"` - - `class BetaResponseCustomToolCallOutput: …` + - `class FileSearchTool: …` - The output of a custom tool call from your code, being sent back to the model. + - `type: Literal["file_search"]` - - `class BetaResponseCustomToolCall: …` + The type of tool being defined: `file_search` - A call to a custom tool created by the model. + - `"file_search"` - - `class CompactionTrigger: …` + - `file_search: Optional[FileSearch]` - Compacts the current context. Must be the final input item. + Overrides for the file search tool. - - `class ItemReference: …` + - `max_num_results: Optional[int]` - An internal identifier for an item to reference. + 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. - - `class Program: …` + 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. - - `class ProgramOutput: …` + - `ranking_options: Optional[FileSearchRankingOptions]` - - `response_id: str` + 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. - The ID of the response that rejected the input. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `sequence_number: int` + - `score_threshold: float` - The sequence number for this event. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: Literal["response.inject.failed"]` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - The event discriminator. Always `response.inject.failed`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"response.inject.failed"` + - `"auto"` - - `stream_id: Optional[str]` + - `"default_2024_08_21"` - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + - `class FunctionTool: …` -### Beta Skill Reference + - `function: FunctionDefinition` -- `class BetaSkillReference: …` + - `name: str` - - `skill_id: 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. - The ID of the referenced skill. + - `description: Optional[str]` - - `type: Literal["skill_reference"]` + A description of what the function does, used by the model to choose when and how to call the function. - References a skill created with the /v1/skills endpoint. + - `parameters: Optional[FunctionParameters]` - - `"skill_reference"` + 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. - - `version: Optional[str]` + Omitting `parameters` defines a function with an empty parameter list. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `strict: Optional[bool]` -### Beta Tool + 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). -- `BetaTool` + - `type: Literal["function"]` - A tool that can be used to generate a response. + The type of tool being defined: `function` - - `class BetaFunctionTool: …` + - `"function"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). +### Code Interpreter Tool - - `name: str` +- `class CodeInterpreterTool: …` - The name of the function to call. + - `type: Literal["code_interpreter"]` - - `parameters: Optional[Dict[str, object]]` + The type of tool being defined: `code_interpreter` - A JSON schema object describing the parameters of the function. + - `"code_interpreter"` - - `strict: Optional[bool]` +### File Search Tool - Whether strict parameter validation is enforced for this function tool. +- `class FileSearchTool: …` - - `type: Literal["function"]` + - `type: Literal["file_search"]` - The type of the function tool. Always `function`. + The type of tool being defined: `file_search` - - `"function"` + - `"file_search"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `file_search: Optional[FileSearch]` - The tool invocation context(s). + Overrides for the file search tool. - - `"direct"` + - `max_num_results: Optional[int]` - - `"programmatic"` + 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. - - `defer_loading: Optional[bool]` + 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. - Whether this function is deferred and loaded via tool search. + - `ranking_options: Optional[FileSearchRankingOptions]` - - `description: Optional[str]` + 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. - A description of the function. Used by the model to determine whether or not to call the function. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `output_schema: Optional[Dict[str, object]]` + - `score_threshold: float` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `class BetaFileSearchTool: …` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `type: Literal["file_search"]` + - `"auto"` - The type of the file search tool. Always `file_search`. + - `"default_2024_08_21"` - - `"file_search"` +### Function Tool - - `vector_store_ids: List[str]` +- `class FunctionTool: …` - The IDs of the vector stores to search. + - `function: FunctionDefinition` - - `filters: Optional[Filters]` + - `name: str` - A filter to apply. + 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. - - `class FiltersComparisonFilter: …` + - `description: Optional[str]` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + A description of what the function does, used by the model to choose when and how to call the function. - - `key: str` + - `parameters: Optional[FunctionParameters]` - The key to compare against the value. + 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. - - `type: Literal["eq", "ne", "gt", 5 more]` + Omitting `parameters` defines a function with an empty parameter list. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `strict: Optional[bool]` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + 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). - - `"eq"` + - `type: Literal["function"]` - - `"ne"` + The type of tool being defined: `function` - - `"gt"` + - `"function"` - - `"gte"` +### Message Stream Event - - `"lt"` +- `MessageStreamEvent` - - `"lte"` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - - `"in"` + - `class ThreadMessageCreated: …` - - `"nin"` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - - `value: Union[str, float, bool, List[object]]` + - `data: Message` - The value to compare against the attribute key; supports string, number, or boolean types. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `str` + - `id: str` - - `float` + The identifier, which can be referenced in API endpoints. - - `bool` + - `assistant_id: Optional[str]` - - `List[object]` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `class FiltersCompoundFilter: …` + - `attachments: Optional[List[Attachment]]` - Combine multiple filters using `and` or `or`. + A list of files attached to the message, and the tools they were added to. - - `filters: List[FiltersCompoundFilterFilter]` + - `file_id: Optional[str]` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The ID of the file to attach to the message. - - `class FiltersCompoundFilterFilterComparisonFilter: …` + - `tools: Optional[List[AttachmentTool]]` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The tools to add this file to. - - `key: str` + - `class CodeInterpreterTool: …` - The key to compare against the value. + - `type: Literal["code_interpreter"]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The type of tool being defined: `code_interpreter` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"code_interpreter"` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` - - `"eq"` + - `type: Literal["file_search"]` - - `"ne"` + The type of tool being defined: `file_search` - - `"gt"` + - `"file_search"` - - `"gte"` + - `completed_at: Optional[int]` - - `"lt"` + The Unix timestamp (in seconds) for when the message was completed. - - `"lte"` + - `content: List[MessageContent]` - - `"in"` + The content of the message in array of text and/or images. - - `"nin"` + - `class ImageFileContentBlock: …` - - `value: Union[str, float, bool, List[object]]` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The value to compare against the attribute key; supports string, number, or boolean types. + - `image_file: ImageFile` - - `str` + - `file_id: str` - - `float` + 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. - - `bool` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `List[object]` + 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`. - - `object` + - `"auto"` - - `type: Literal["and", "or"]` + - `"low"` - Type of operation: `and` or `or`. + - `"high"` - - `"and"` + - `type: Literal["image_file"]` - - `"or"` + Always `image_file`. - - `max_num_results: Optional[int]` + - `"image_file"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `class ImageURLContentBlock: …` - - `ranking_options: Optional[RankingOptions]` + References an image URL in the content of a message. - Ranking options for search. + - `image_url: ImageURL` - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + - `url: str` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `embedding_weight: float` + - `detail: Optional[Literal["auto", "low", "high"]]` - The weight of the embedding in the reciprocal ranking fusion. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `text_weight: float` + - `"auto"` - The weight of the text in the reciprocal ranking fusion. + - `"low"` - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + - `"high"` - The ranker to use for the file search. + - `type: Literal["image_url"]` - - `"auto"` + The type of the content part. - - `"default-2024-11-15"` + - `"image_url"` - - `score_threshold: Optional[float]` + - `class TextContentBlock: …` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The text content that is part of a message. - - `class BetaComputerTool: …` + - `text: Text` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `annotations: List[Annotation]` - - `type: Literal["computer"]` + - `class FileCitationAnnotation: …` - The type of the computer tool. Always `computer`. + 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. - - `"computer"` + - `end_index: int` - - `class BetaComputerUsePreviewTool: …` + - `file_citation: FileCitation` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `file_id: str` - - `display_height: int` + The ID of the specific File the citation is from. - The height of the computer display. + - `start_index: int` - - `display_width: int` + - `text: str` - The width of the computer display. + The text in the message content that needs to be replaced. - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `type: Literal["file_citation"]` - The type of computer environment to control. + Always `file_citation`. - - `"windows"` + - `"file_citation"` - - `"mac"` + - `class FilePathAnnotation: …` - - `"linux"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"ubuntu"` + - `end_index: int` - - `"browser"` + - `file_path: FilePath` - - `type: Literal["computer_use_preview"]` + - `file_id: str` - The type of the computer use tool. Always `computer_use_preview`. + The ID of the file that was generated. - - `"computer_use_preview"` + - `start_index: int` - - `class BetaWebSearchTool: …` + - `text: str` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The text in the message content that needs to be replaced. - - `type: Literal["web_search", "web_search_2025_08_26"]` + - `type: Literal["file_path"]` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + Always `file_path`. - - `"web_search"` + - `"file_path"` - - `"web_search_2025_08_26"` + - `value: str` - - `filters: Optional[Filters]` + The data that makes up the text. - Filters for the search. + - `type: Literal["text"]` - - `allowed_domains: Optional[List[str]]` + Always `text`. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"text"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `class RefusalContentBlock: …` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + The refusal content generated by the assistant. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `refusal: str` - - `"low"` + - `type: Literal["refusal"]` - - `"medium"` + Always `refusal`. - - `"high"` + - `"refusal"` - - `user_location: Optional[UserLocation]` + - `created_at: int` - The approximate location of the user. + The Unix timestamp (in seconds) for when the message was created. - - `city: Optional[str]` + - `incomplete_at: Optional[int]` - Free text input for the city of the user, e.g. `San Francisco`. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `country: Optional[str]` + - `incomplete_details: Optional[IncompleteDetails]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + On an incomplete message, details about why the message is incomplete. - - `region: Optional[str]` + - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` - Free text input for the region of the user, e.g. `California`. + The reason the message is incomplete. - - `timezone: Optional[str]` + - `"content_filter"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"max_tokens"` - - `type: Optional[Literal["approximate"]]` + - `"run_cancelled"` - The type of location approximation. Always `approximate`. + - `"run_expired"` - - `"approximate"` + - `"run_failed"` - - `class Mcp: …` + - `metadata: Optional[Metadata]` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + 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. - - `server_label: str` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A label for this MCP server, used to identify it in tool calls. + - `object: Literal["thread.message"]` - - `type: Literal["mcp"]` + The object type, which is always `thread.message`. - The type of the MCP tool. Always `mcp`. + - `"thread.message"` - - `"mcp"` + - `role: Literal["user", "assistant"]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The entity that produced the message. One of `user` or `assistant`. - The tool invocation context(s). + - `"user"` - - `"direct"` + - `"assistant"` - - `"programmatic"` + - `run_id: Optional[str]` - - `allowed_tools: Optional[McpAllowedTools]` + 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. - List of allowed tool names or a filter object. + - `status: Literal["in_progress", "incomplete", "completed"]` - - `List[str]` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - A string array of allowed tool names + - `"in_progress"` - - `class McpAllowedToolsMcpToolFilter: …` + - `"incomplete"` - A filter object to specify which tools are allowed. + - `"completed"` - - `read_only: Optional[bool]` + - `thread_id: str` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `tool_names: Optional[List[str]]` + - `event: Literal["thread.message.created"]` - List of allowed tool names. + - `"thread.message.created"` - - `authorization: Optional[str]` + - `class ThreadMessageInProgress: …` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + - `data: Message` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - Currently supported `connector_id` values are: + - `event: Literal["thread.message.in_progress"]` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `"thread.message.in_progress"` - - `"connector_dropbox"` + - `class ThreadMessageDelta: …` - - `"connector_gmail"` + Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. - - `"connector_googlecalendar"` + - `data: MessageDeltaEvent` - - `"connector_googledrive"` + Represents a message delta i.e. any changed fields on a message during streaming. - - `"connector_microsoftteams"` + - `id: str` - - `"connector_outlookcalendar"` + The identifier of the message, which can be referenced in API endpoints. - - `"connector_outlookemail"` + - `delta: MessageDelta` - - `"connector_sharepoint"` + The delta containing the fields that have changed on the Message. - - `defer_loading: Optional[bool]` + - `content: Optional[List[MessageContentDelta]]` - Whether this MCP tool is deferred and discovered via tool search. + The content of the message in array of text and/or images. - - `headers: Optional[Dict[str, str]]` + - `class ImageFileDeltaBlock: …` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `require_approval: Optional[McpRequireApproval]` + - `index: int` - Specify which of the MCP server's tools require approval. + The index of the content part in the message. - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `type: Literal["image_file"]` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + Always `image_file`. - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `"image_file"` - A filter object to specify which tools are allowed. + - `image_file: Optional[ImageFileDelta]` - - `read_only: Optional[bool]` + - `detail: Optional[Literal["auto", "low", "high"]]` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + 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`. - - `tool_names: Optional[List[str]]` + - `"auto"` - List of allowed tool names. + - `"low"` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + - `"high"` - A filter object to specify which tools are allowed. + - `file_id: Optional[str]` - - `read_only: Optional[bool]` + 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. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `class TextDeltaBlock: …` - - `tool_names: Optional[List[str]]` + The text content that is part of a message. - List of allowed tool names. + - `index: int` - - `Literal["always", "never"]` + The index of the content part in the message. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `type: Literal["text"]` - - `"always"` + Always `text`. - - `"never"` + - `"text"` - - `server_description: Optional[str]` + - `text: Optional[TextDelta]` - Optional description of the MCP server, used to provide more context. + - `annotations: Optional[List[AnnotationDelta]]` - - `server_url: Optional[str]` + - `class FileCitationDeltaAnnotation: …` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + 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. - - `tunnel_id: Optional[str]` + - `index: int` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + The index of the annotation in the text content part. - - `class CodeInterpreter: …` + - `type: Literal["file_citation"]` - A tool that runs Python code to help generate a response to a prompt. + Always `file_citation`. - - `container: CodeInterpreterContainer` + - `"file_citation"` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `end_index: Optional[int]` - - `str` + - `file_citation: Optional[FileCitation]` - The container ID. + - `file_id: Optional[str]` - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + The ID of the specific File the citation is from. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `quote: Optional[str]` - - `type: Literal["auto"]` + The specific quote in the file. - Always `auto`. + - `start_index: Optional[int]` - - `"auto"` + - `text: Optional[str]` - - `file_ids: Optional[List[str]]` + The text in the message content that needs to be replaced. - An optional list of uploaded files to make available to your code. + - `class FilePathDeltaAnnotation: …` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The memory limit for the code interpreter container. + - `index: int` - - `"1g"` + The index of the annotation in the text content part. - - `"4g"` + - `type: Literal["file_path"]` - - `"16g"` + Always `file_path`. - - `"64g"` + - `"file_path"` - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `end_index: Optional[int]` - Network access policy for the container. + - `file_path: Optional[FilePath]` - - `class BetaContainerNetworkPolicyDisabled: …` + - `file_id: Optional[str]` - - `type: Literal["disabled"]` + The ID of the file that was generated. - Disable outbound network access. Always `disabled`. + - `start_index: Optional[int]` - - `"disabled"` + - `text: Optional[str]` - - `class BetaContainerNetworkPolicyAllowlist: …` + The text in the message content that needs to be replaced. - - `allowed_domains: List[str]` + - `value: Optional[str]` - A list of allowed domains when type is `allowlist`. + The data that makes up the text. - - `type: Literal["allowlist"]` + - `class RefusalDeltaBlock: …` - Allow outbound network access only to specified domains. Always `allowlist`. + The refusal content that is part of a message. - - `"allowlist"` + - `index: int` - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + The index of the refusal part in the message. - Optional domain-scoped secrets for allowlisted domains. + - `type: Literal["refusal"]` - - `domain: str` + Always `refusal`. - The domain associated with the secret. + - `"refusal"` - - `name: str` + - `refusal: Optional[str]` - The name of the secret to inject for the domain. + - `class ImageURLDeltaBlock: …` - - `value: str` + References an image URL in the content of a message. - The secret value to inject for the domain. + - `index: int` - - `type: Literal["code_interpreter"]` + The index of the content part in the message. - The type of the code interpreter tool. Always `code_interpreter`. + - `type: Literal["image_url"]` - - `"code_interpreter"` + Always `image_url`. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"image_url"` - The tool invocation context(s). + - `image_url: Optional[ImageURLDelta]` - - `"direct"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"programmatic"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `class ProgrammaticToolCalling: …` + - `"auto"` - - `type: Literal["programmatic_tool_calling"]` + - `"low"` - The type of the tool. Always `programmatic_tool_calling`. + - `"high"` - - `"programmatic_tool_calling"` + - `url: Optional[str]` - - `class ImageGeneration: …` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - A tool that generates images using the GPT image models. + - `role: Optional[Literal["user", "assistant"]]` - - `type: Literal["image_generation"]` + The entity that produced the message. One of `user` or `assistant`. - The type of the image generation tool. Always `image_generation`. + - `"user"` - - `"image_generation"` + - `"assistant"` - - `action: Optional[Literal["generate", "edit", "auto"]]` + - `object: Literal["thread.message.delta"]` - Whether to generate a new image or edit an existing image. Default: `auto`. + The object type, which is always `thread.message.delta`. - - `"generate"` + - `"thread.message.delta"` - - `"edit"` + - `event: Literal["thread.message.delta"]` - - `"auto"` + - `"thread.message.delta"` - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + - `class ThreadMessageCompleted: …` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `data: Message` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"transparent"` + - `event: Literal["thread.message.completed"]` - - `"opaque"` + - `"thread.message.completed"` - - `"auto"` + - `class ThreadMessageIncomplete: …` - - `input_fidelity: Optional[Literal["high", "low"]]` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `data: Message` - - `"high"` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"low"` + - `event: Literal["thread.message.incomplete"]` - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + - `"thread.message.incomplete"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). +### Run Step Stream Event - - `file_id: Optional[str]` +- `RunStepStreamEvent` - File ID for the mask image. + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. - - `image_url: Optional[str]` + - `class ThreadRunStepCreated: …` - Base64-encoded mask image. + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + - `data: RunStep` - The image generation model to use. Default: `gpt-image-1`. + Represents a step in execution of a run. - - `str` + - `id: str` - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + The identifier of the run step, which can be referenced in API endpoints. - The image generation model to use. Default: `gpt-image-1`. + - `assistant_id: str` - - `"gpt-image-1"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `"gpt-image-1-mini"` + - `cancelled_at: Optional[int]` - - `"gpt-image-2"` + The Unix timestamp (in seconds) for when the run step was cancelled. - - `"gpt-image-2-2026-04-21"` + - `completed_at: Optional[int]` - - `"gpt-image-1.5"` + The Unix timestamp (in seconds) for when the run step completed. - - `"chatgpt-image-latest"` + - `created_at: int` - - `moderation: Optional[Literal["auto", "low"]]` + The Unix timestamp (in seconds) for when the run step was created. - Moderation level for the generated image. Default: `auto`. + - `expired_at: Optional[int]` - - `"auto"` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `"low"` + - `failed_at: Optional[int]` - - `output_compression: Optional[int]` + The Unix timestamp (in seconds) for when the run step failed. - Compression level for the output image. Default: 100. + - `last_error: Optional[LastError]` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + The last error associated with this run step. Will be `null` if there are no errors. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `code: Literal["server_error", "rate_limit_exceeded"]` - - `"png"` + One of `server_error` or `rate_limit_exceeded`. - - `"webp"` + - `"server_error"` - - `"jpeg"` + - `"rate_limit_exceeded"` - - `partial_images: Optional[int]` + - `message: str` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + A human-readable description of the error. - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + - `metadata: Optional[Metadata]` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + 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. - - `"low"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"medium"` + - `object: Literal["thread.run.step"]` - - `"high"` + The object type, which is always `thread.run.step`. - - `"auto"` + - `"thread.run.step"` - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + - `run_id: str` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `str` + - `status: Literal["in_progress", "cancelled", "failed", 2 more]` - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"in_progress"` - - `"1024x1024"` + - `"cancelled"` - - `"1024x1536"` + - `"failed"` - - `"1536x1024"` + - `"completed"` - - `"auto"` + - `"expired"` - - `class LocalShell: …` + - `step_details: StepDetails` - A tool that allows the model to execute shell commands in a local environment. + The details of the run step. - - `type: Literal["local_shell"]` + - `class MessageCreationStepDetails: …` - The type of the local shell tool. Always `local_shell`. + Details of the message creation by the run step. - - `"local_shell"` + - `message_creation: MessageCreation` - - `class BetaFunctionShellTool: …` + - `message_id: str` - A tool that allows the model to execute shell commands. + The ID of the message that was created by this run step. - - `type: Literal["shell"]` + - `type: Literal["message_creation"]` - The type of the shell tool. Always `shell`. + Always `message_creation`. - - `"shell"` + - `"message_creation"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `class ToolCallsStepDetails: …` - The tool invocation context(s). + Details of the tool call. - - `"direct"` + - `tool_calls: List[ToolCall]` - - `"programmatic"` + 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`. - - `environment: Optional[Environment]` + - `class CodeInterpreterToolCall: …` - - `class BetaContainerAuto: …` + Details of the Code Interpreter tool call the run step was involved in. - - `type: Literal["container_auto"]` + - `id: str` - Automatically creates a container for this request + The ID of the tool call. - - `"container_auto"` + - `code_interpreter: CodeInterpreter` - - `file_ids: Optional[List[str]]` + The Code Interpreter tool call definition. - An optional list of uploaded files to make available to your code. + - `input: str` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + The input to the Code Interpreter tool call. - The memory limit for the container. + - `outputs: List[CodeInterpreterOutput]` - - `"1g"` + 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. - - `"4g"` + - `class CodeInterpreterOutputLogs: …` - - `"16g"` + Text output from the Code Interpreter tool call as part of a run step. - - `"64g"` + - `logs: str` - - `network_policy: Optional[NetworkPolicy]` + The text output from the Code Interpreter tool call. - Network access policy for the container. + - `type: Literal["logs"]` - - `class BetaContainerNetworkPolicyDisabled: …` + Always `logs`. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `"logs"` - - `skills: Optional[List[Skill]]` + - `class CodeInterpreterOutputImage: …` - An optional list of skills referenced by id or inline data. + - `image: CodeInterpreterOutputImageImage` - - `class BetaSkillReference: …` + - `file_id: str` - - `skill_id: str` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The ID of the referenced skill. + - `type: Literal["image"]` - - `type: Literal["skill_reference"]` + Always `image`. - References a skill created with the /v1/skills endpoint. + - `"image"` - - `"skill_reference"` + - `type: Literal["code_interpreter"]` - - `version: Optional[str]` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"code_interpreter"` - - `class BetaInlineSkill: …` + - `class FileSearchToolCall: …` - - `description: str` + - `id: str` - The description of the skill. + The ID of the tool call object. - - `name: str` + - `file_search: FileSearch` - The name of the skill. + For now, this is always going to be an empty object. - - `source: BetaInlineSkillSource` + - `ranking_options: Optional[FileSearchRankingOptions]` - Inline skill payload + The ranking options for the file search. - - `data: str` + - `ranker: Literal["auto", "default_2024_08_21"]` - Base64-encoded skill zip bundle. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `media_type: Literal["application/zip"]` + - `"auto"` - The media type of the inline skill payload. Must be `application/zip`. + - `"default_2024_08_21"` - - `"application/zip"` + - `score_threshold: float` - - `type: Literal["base64"]` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The type of the inline skill source. Must be `base64`. + - `results: Optional[List[FileSearchResult]]` - - `"base64"` + The results of the file search. - - `type: Literal["inline"]` + - `file_id: str` - Defines an inline skill for this request. + The ID of the file that result was found in. - - `"inline"` + - `file_name: str` - - `class BetaLocalEnvironment: …` + The name of the file that result was found in. - - `type: Literal["local"]` + - `score: float` - Use a local computer environment. + The score of the result. All values must be a floating point number between 0 and 1. - - `"local"` + - `content: Optional[List[FileSearchResultContent]]` - - `skills: Optional[List[BetaLocalSkill]]` + The content of the result that was found. The content is only included if requested via the include query parameter. - An optional list of skills. + - `text: Optional[str]` - - `description: str` + The text content of the file. - The description of the skill. + - `type: Optional[Literal["text"]]` - - `name: str` + The type of the content. - The name of the skill. + - `"text"` - - `path: str` + - `type: Literal["file_search"]` - The path to the directory containing the skill. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `class BetaContainerReference: …` + - `"file_search"` - - `container_id: str` + - `class FunctionToolCall: …` - The ID of the referenced container. + - `id: str` - - `type: Literal["container_reference"]` + The ID of the tool call object. - References a container created with the /v1/containers endpoint + - `function: Function` - - `"container_reference"` + The definition of the function that was called. - - `class BetaCustomTool: …` + - `arguments: str` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The arguments passed to the function. - `name: str` - The name of the custom tool, used to identify it in tool calls. + The name of the function. - - `type: Literal["custom"]` + - `output: Optional[str]` - The type of the custom tool. Always `custom`. + 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. - - `"custom"` + - `type: Literal["function"]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + The type of tool call. This is always going to be `function` for this type of tool call. - The tool invocation context(s). + - `"function"` - - `"direct"` + - `type: Literal["tool_calls"]` - - `"programmatic"` + Always `tool_calls`. - - `defer_loading: Optional[bool]` + - `"tool_calls"` - Whether this tool should be deferred and discovered via tool search. + - `thread_id: str` - - `description: Optional[str]` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - Optional description of the custom tool, used to provide more context. + - `type: Literal["message_creation", "tool_calls"]` - - `format: Optional[Format]` + The type of run step, which can be either `message_creation` or `tool_calls`. - The input format for the custom tool. Default is unconstrained text. + - `"message_creation"` - - `class FormatText: …` + - `"tool_calls"` - Unconstrained free-form text. + - `usage: Optional[Usage]` - - `type: Literal["text"]` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - Unconstrained text format. Always `text`. + - `completion_tokens: int` - - `"text"` + Number of completion tokens used over the course of the run step. - - `class FormatGrammar: …` + - `prompt_tokens: int` - A grammar defined by the user. + Number of prompt tokens used over the course of the run step. - - `definition: str` + - `total_tokens: int` - The grammar definition. + Total number of tokens used (prompt + completion). - - `syntax: Literal["lark", "regex"]` + - `event: Literal["thread.run.step.created"]` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"thread.run.step.created"` - - `"lark"` + - `class ThreadRunStepInProgress: …` - - `"regex"` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. - - `type: Literal["grammar"]` + - `data: RunStep` - Grammar format. Always `grammar`. + Represents a step in execution of a run. - - `"grammar"` + - `event: Literal["thread.run.step.in_progress"]` - - `class BetaNamespaceTool: …` + - `"thread.run.step.in_progress"` - Groups function/custom tools under a shared namespace. + - `class ThreadRunStepDelta: …` - - `description: str` + Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. - A description of the namespace shown to the model. + - `data: RunStepDeltaEvent` - - `name: str` + Represents a run step delta i.e. any changed fields on a run step during streaming. - The namespace name used in tool calls (for example, `crm`). + - `id: str` - - `tools: List[Tool]` + The identifier of the run step, which can be referenced in API endpoints. - The function/custom tools available inside this namespace. + - `delta: RunStepDelta` - - `class ToolFunction: …` + The delta containing the fields that have changed on the run step. - - `name: str` + - `step_details: Optional[StepDetails]` - - `type: Literal["function"]` + The details of the run step. - - `"function"` + - `class RunStepDeltaMessageDelta: …` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + Details of the message creation by the run step. - The tool invocation context(s). + - `type: Literal["message_creation"]` - - `"direct"` + Always `message_creation`. - - `"programmatic"` + - `"message_creation"` - - `defer_loading: Optional[bool]` + - `message_creation: Optional[MessageCreation]` - Whether this function should be deferred and discovered via tool search. + - `message_id: Optional[str]` - - `description: Optional[str]` + The ID of the message that was created by this run step. - - `output_schema: Optional[Dict[str, object]]` + - `class ToolCallDeltaObject: …` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + Details of the tool call. - - `parameters: Optional[object]` + - `type: Literal["tool_calls"]` - - `strict: Optional[bool]` + Always `tool_calls`. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `"tool_calls"` - - `class BetaCustomTool: …` + - `tool_calls: Optional[List[ToolCallDelta]]` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + 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`. - - `type: Literal["namespace"]` + - `class CodeInterpreterToolCallDelta: …` - The type of the tool. Always `namespace`. + Details of the Code Interpreter tool call the run step was involved in. - - `"namespace"` + - `index: int` - - `class BetaToolSearchTool: …` + The index of the tool call in the tool calls array. - Hosted or BYOT tool search configuration for deferred tools. + - `type: Literal["code_interpreter"]` - - `type: Literal["tool_search"]` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The type of the tool. Always `tool_search`. + - `"code_interpreter"` - - `"tool_search"` + - `id: Optional[str]` - - `description: Optional[str]` + The ID of the tool call. - Description shown to the model for a client-executed tool search tool. + - `code_interpreter: Optional[CodeInterpreter]` - - `execution: Optional[Literal["server", "client"]]` + The Code Interpreter tool call definition. - Whether tool search is executed by the server or by the client. + - `input: Optional[str]` - - `"server"` + The input to the Code Interpreter tool call. - - `"client"` + - `outputs: Optional[List[CodeInterpreterOutput]]` - - `parameters: Optional[object]` + 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. - Parameter schema for a client-executed tool search tool. + - `class CodeInterpreterLogs: …` - - `class BetaWebSearchPreviewTool: …` + Text output from the Code Interpreter tool call as part of a run step. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `index: int` - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + The index of the output in the outputs array. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `type: Literal["logs"]` - - `"web_search_preview"` + Always `logs`. - - `"web_search_preview_2025_03_11"` + - `"logs"` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + - `logs: Optional[str]` - - `"text"` + The text output from the Code Interpreter tool call. - - `"image"` + - `class CodeInterpreterOutputImage: …` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `index: int` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The index of the output in the outputs array. - - `"low"` + - `type: Literal["image"]` - - `"medium"` + Always `image`. - - `"high"` + - `"image"` - - `user_location: Optional[UserLocation]` + - `image: Optional[Image]` - The user's location. + - `file_id: Optional[str]` - - `type: Literal["approximate"]` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The type of location approximation. Always `approximate`. + - `class FileSearchToolCallDelta: …` - - `"approximate"` + - `file_search: object` - - `city: Optional[str]` + For now, this is always going to be an empty object. - Free text input for the city of the user, e.g. `San Francisco`. + - `index: int` - - `country: Optional[str]` + The index of the tool call in the tool calls array. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: Literal["file_search"]` - - `region: Optional[str]` + The type of tool call. This is always going to be `file_search` for this type of tool call. - Free text input for the region of the user, e.g. `California`. + - `"file_search"` - - `timezone: Optional[str]` + - `id: Optional[str]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The ID of the tool call object. - - `class BetaApplyPatchTool: …` + - `class FunctionToolCallDelta: …` - Allows the assistant to create, delete, or update files using unified diffs. + - `index: int` - - `type: Literal["apply_patch"]` + The index of the tool call in the tool calls array. - The type of the tool. Always `apply_patch`. + - `type: Literal["function"]` - - `"apply_patch"` + The type of tool call. This is always going to be `function` for this type of tool call. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"function"` - The tool invocation context(s). + - `id: Optional[str]` - - `"direct"` + The ID of the tool call object. - - `"programmatic"` + - `function: Optional[Function]` -### Beta Tool Choice Allowed + The definition of the function that was called. -- `class BetaToolChoiceAllowed: …` + - `arguments: Optional[str]` - Constrains the tools available to the model to a pre-defined set. + The arguments passed to the function. - - `mode: Literal["auto", "required"]` + - `name: Optional[str]` - Constrains the tools available to the model to a pre-defined set. + The name of the function. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `output: Optional[str]` - `required` requires the model to call one or more of the allowed tools. + 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. - - `"auto"` + - `object: Literal["thread.run.step.delta"]` - - `"required"` + The object type, which is always `thread.run.step.delta`. - - `tools: List[Dict[str, object]]` + - `"thread.run.step.delta"` - A list of tool definitions that the model should be allowed to call. + - `event: Literal["thread.run.step.delta"]` - For the Responses API, the list of tool definitions might look like: + - `"thread.run.step.delta"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `class ThreadRunStepCompleted: …` - - `type: Literal["allowed_tools"]` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. - Allowed tool configuration type. Always `allowed_tools`. + - `data: RunStep` - - `"allowed_tools"` + Represents a step in execution of a run. -### Beta Tool Choice Apply Patch + - `event: Literal["thread.run.step.completed"]` -- `class BetaToolChoiceApplyPatch: …` + - `"thread.run.step.completed"` - Forces the model to call the apply_patch tool when executing a tool call. + - `class ThreadRunStepFailed: …` - - `type: Literal["apply_patch"]` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. - The tool to call. Always `apply_patch`. + - `data: RunStep` - - `"apply_patch"` + Represents a step in execution of a run. -### Beta Tool Choice Custom + - `event: Literal["thread.run.step.failed"]` -- `class BetaToolChoiceCustom: …` + - `"thread.run.step.failed"` - Use this option to force the model to call a specific custom tool. + - `class ThreadRunStepCancelled: …` - - `name: str` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. - The name of the custom tool to call. + - `data: RunStep` - - `type: Literal["custom"]` + Represents a step in execution of a run. - For custom tool calling, the type is always `custom`. + - `event: Literal["thread.run.step.cancelled"]` - - `"custom"` + - `"thread.run.step.cancelled"` -### Beta Tool Choice Function + - `class ThreadRunStepExpired: …` -- `class BetaToolChoiceFunction: …` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. - Use this option to force the model to call a specific function. + - `data: RunStep` - - `name: str` + Represents a step in execution of a run. - The name of the function to call. + - `event: Literal["thread.run.step.expired"]` - - `type: Literal["function"]` + - `"thread.run.step.expired"` - For function calling, the type is always `function`. +### Run Stream Event - - `"function"` +- `RunStreamEvent` -### Beta Tool Choice Mcp + Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. -- `class BetaToolChoiceMcp: …` + - `class ThreadRunCreated: …` - Use this option to force the model to call a specific tool on a remote MCP server. + Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. - - `server_label: str` + - `data: Run` - The label of the MCP server to use. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `type: Literal["mcp"]` + - `id: str` - For MCP tools, the type is always `mcp`. + The identifier, which can be referenced in API endpoints. - - `"mcp"` + - `assistant_id: str` - - `name: Optional[str]` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The name of the tool to call on the server. + - `cancelled_at: Optional[int]` -### Beta Tool Choice Options + The Unix timestamp (in seconds) for when the run was cancelled. -- `Literal["none", "auto", "required"]` + - `completed_at: Optional[int]` - Controls which (if any) tool is called by the model. + The Unix timestamp (in seconds) for when the run was completed. - `none` means the model will not call any tool and instead generates a message. + - `created_at: int` - `auto` means the model can pick between generating a message or calling one or - more tools. + The Unix timestamp (in seconds) for when the run was created. - `required` means the model must call one or more tools. + - `expires_at: Optional[int]` - - `"none"` + The Unix timestamp (in seconds) for when the run will expire. - - `"auto"` + - `failed_at: Optional[int]` - - `"required"` + The Unix timestamp (in seconds) for when the run failed. -### Beta Tool Choice Shell + - `incomplete_details: Optional[IncompleteDetails]` -- `class BetaToolChoiceShell: …` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - Forces the model to call the shell tool when a tool call is required. + - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` - - `type: Literal["shell"]` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The tool to call. Always `shell`. + - `"max_completion_tokens"` - - `"shell"` + - `"max_prompt_tokens"` -### Beta Tool Choice Types + - `instructions: str` -- `class BetaToolChoiceTypes: …` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `last_error: Optional[LastError]` - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + The last error associated with this run. Will be `null` if there are no errors. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` - Allowed values are: + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"server_error"` - - `"file_search"` + - `"rate_limit_exceeded"` - - `"web_search_preview"` + - `"invalid_prompt"` - - `"computer"` + - `message: str` - - `"computer_use_preview"` + A human-readable description of the error. - - `"computer_use"` + - `max_completion_tokens: Optional[int]` - - `"web_search_preview_2025_03_11"` + The maximum number of completion tokens specified to have been used over the course of the run. - - `"image_generation"` + - `max_prompt_tokens: Optional[int]` - - `"code_interpreter"` + The maximum number of prompt tokens specified to have been used over the course of the run. -### Beta Tool Search Tool + - `metadata: Optional[Metadata]` -- `class BetaToolSearchTool: …` + 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. - Hosted or BYOT tool search configuration for deferred tools. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: Literal["tool_search"]` + - `model: str` - The type of the tool. Always `tool_search`. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"tool_search"` + - `object: Literal["thread.run"]` - - `description: Optional[str]` + The object type, which is always `thread.run`. - Description shown to the model for a client-executed tool search tool. + - `"thread.run"` - - `execution: Optional[Literal["server", "client"]]` + - `parallel_tool_calls: bool` - Whether tool search is executed by the server or by the client. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"server"` + - `required_action: Optional[RequiredAction]` - - `"client"` + Details on the action required to continue the run. Will be `null` if no action is required. - - `parameters: Optional[object]` + - `submit_tool_outputs: RequiredActionSubmitToolOutputs` - Parameter schema for a client-executed tool search tool. + Details on the tool outputs needed for this run to continue. -### Beta Web Search Preview Tool + - `tool_calls: List[RequiredActionFunctionToolCall]` -- `class BetaWebSearchPreviewTool: …` + A list of the relevant tool calls. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `id: str` - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + 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. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `function: Function` - - `"web_search_preview"` + The function definition. - - `"web_search_preview_2025_03_11"` + - `arguments: str` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + The arguments that the model expects you to pass to the function. - - `"text"` + - `name: str` - - `"image"` + The name of the function. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `type: Literal["function"]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of tool call the output is required for. For now, this is always `function`. - - `"low"` + - `"function"` - - `"medium"` + - `type: Literal["submit_tool_outputs"]` - - `"high"` + For now, this is always `submit_tool_outputs`. - - `user_location: Optional[UserLocation]` + - `"submit_tool_outputs"` - The user's location. + - `response_format: Optional[AssistantResponseFormatOption]` - - `type: Literal["approximate"]` + 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`. - The type of location approximation. Always `approximate`. + 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). - - `"approximate"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `city: Optional[str]` + **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. - Free text input for the city of the user, e.g. `San Francisco`. + - `Literal["auto"]` - - `country: Optional[str]` + `auto` is the default value - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"auto"` - - `region: Optional[str]` + - `class ResponseFormatText: …` - Free text input for the region of the user, e.g. `California`. + Default response format. Used to generate text responses. - - `timezone: Optional[str]` + - `type: Literal["text"]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The type of response format being defined. Always `text`. -### Beta Web Search Tool + - `"text"` -- `class BetaWebSearchTool: …` + - `class ResponseFormatJSONObject: …` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + 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["web_search", "web_search_2025_08_26"]` + - `type: Literal["json_object"]` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The type of response format being defined. Always `json_object`. - - `"web_search"` + - `"json_object"` - - `"web_search_2025_08_26"` + - `class ResponseFormatJSONSchema: …` - - `filters: Optional[Filters]` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - Filters for the search. + - `json_schema: JSONSchema` - - `allowed_domains: Optional[List[str]]` + Structured Outputs configuration options, including a JSON Schema. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `name: str` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + 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. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `description: Optional[str]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"low"` + - `schema: Optional[Dict[str, object]]` - - `"medium"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"high"` + - `strict: Optional[bool]` - - `user_location: Optional[UserLocation]` + 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). - The approximate location of the user. + - `type: Literal["json_schema"]` - - `city: Optional[str]` + The type of response format being defined. Always `json_schema`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"json_schema"` - - `country: Optional[str]` + - `started_at: Optional[int]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The Unix timestamp (in seconds) for when the run was started. - - `region: Optional[str]` + - `status: RunStatus` - Free text input for the region of the user, e.g. `California`. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `timezone: Optional[str]` + - `"queued"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"in_progress"` - - `type: Optional[Literal["approximate"]]` + - `"requires_action"` - The type of location approximation. Always `approximate`. + - `"cancelling"` - - `"approximate"` + - `"cancelled"` -# Input Items + - `"failed"` -## List input items + - `"completed"` -`beta.responses.input_items.list(strresponse_id, InputItemListParams**kwargs) -> SyncCursorPage[BetaResponseItem]` + - `"incomplete"` -**get** `/responses/{response_id}/input_items?beta=true` + - `"expired"` -List input items + - `thread_id: str` -### Parameters + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. -- `response_id: str` + - `tool_choice: Optional[AssistantToolChoiceOption]` -- `after: Optional[str]` + 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. - An item ID to list items after, used in pagination. + - `Literal["none", "auto", "required"]` -- `include: Optional[List[BetaResponseIncludable]]` + `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. - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. + - `"none"` - - `"file_search_call.results"` + - `"auto"` - - `"web_search_call.results"` + - `"required"` - - `"web_search_call.action.sources"` + - `class AssistantToolChoice: …` - - `"message.input_image.image_url"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `"computer_call_output.output.image_url"` + - `type: Literal["function", "code_interpreter", "file_search"]` - - `"code_interpreter_call.outputs"` + The type of the tool. If type is `function`, the function name must be set - - `"reasoning.encrypted_content"` + - `"function"` - - `"message.output_text.logprobs"` + - `"code_interpreter"` -- `limit: Optional[int]` + - `"file_search"` - A limit on the number of objects to be returned. Limit can range between - 1 and 100, and the default is 20. + - `function: Optional[AssistantToolChoiceFunction]` + + - `name: str` + + The name of the function to call. + + - `tools: List[AssistantTool]` -- `order: Optional[Literal["asc", "desc"]]` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The order to return the input items in. Default is `desc`. + - `class CodeInterpreterTool: …` - - `asc`: Return the input items in ascending order. - - `desc`: Return the input items in descending order. + - `type: Literal["code_interpreter"]` - - `"asc"` + The type of tool being defined: `code_interpreter` - - `"desc"` + - `"code_interpreter"` -- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` + - `class FileSearchTool: …` - - `"responses_multi_agent=v1"` + - `type: Literal["file_search"]` -### Returns + The type of tool being defined: `file_search` -- `BetaResponseItem` + - `"file_search"` - Content item used to generate a response. + - `file_search: Optional[FileSearch]` - - `class BetaResponseInputMessageItem: …` + Overrides for the file search tool. - - `id: str` + - `max_num_results: Optional[int]` - The unique ID of the message input. + 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. - - `content: BetaResponseInputMessageContentList` + 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. - A list of one or many input items to the model, containing different content - types. + - `ranking_options: Optional[FileSearchRankingOptions]` - - `class BetaResponseInputText: …` + 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. - A text input to the model. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `text: str` + - `score_threshold: float` - The text input to the model. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: Literal["input_text"]` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - The type of the input item. Always `input_text`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"input_text"` + - `"auto"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"default_2024_08_21"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class FunctionTool: …` - - `mode: Literal["explicit"]` + - `function: FunctionDefinition` - The breakpoint mode. Always `explicit`. + - `name: str` - - `"explicit"` + 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. - - `class BetaResponseInputImage: …` + - `description: Optional[str]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A description of what the function does, used by the model to choose when and how to call the function. - - `detail: Literal["low", "high", "auto", "original"]` + - `parameters: Optional[FunctionParameters]` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + 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. - - `"low"` + Omitting `parameters` defines a function with an empty parameter list. - - `"high"` + - `strict: Optional[bool]` - - `"auto"` + 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). - - `"original"` + - `type: Literal["function"]` - - `type: Literal["input_image"]` + The type of tool being defined: `function` - The type of the input item. Always `input_image`. + - `"function"` - - `"input_image"` + - `truncation_strategy: Optional[TruncationStrategy]` - - `file_id: Optional[str]` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The ID of the file to be sent to the model. + - `type: Literal["auto", "last_messages"]` - - `image_url: Optional[str]` + 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`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"auto"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"last_messages"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `last_messages: Optional[int]` - - `mode: Literal["explicit"]` + The number of most recent messages from the thread when constructing the context for the run. - The breakpoint mode. Always `explicit`. + - `usage: Optional[Usage]` - - `"explicit"` + 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.). - - `class BetaResponseInputFile: …` + - `completion_tokens: int` - A file input to the model. + Number of completion tokens used over the course of the run. - - `type: Literal["input_file"]` + - `prompt_tokens: int` - The type of the input item. Always `input_file`. + Number of prompt tokens used over the course of the run. - - `"input_file"` + - `total_tokens: int` - - `detail: Optional[Literal["auto", "low", "high"]]` + Total number of tokens used (prompt + completion). - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `temperature: Optional[float]` - - `"auto"` + The sampling temperature used for this run. If not set, defaults to 1. - - `"low"` + - `top_p: Optional[float]` - - `"high"` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `file_data: Optional[str]` + - `event: Literal["thread.run.created"]` - The content of the file to be sent to the model. + - `"thread.run.created"` - - `file_id: Optional[str]` + - `class ThreadRunQueued: …` - The ID of the file to be sent to the model. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. - - `file_url: Optional[str]` + - `data: Run` - The URL of the file to be sent to the model. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `filename: Optional[str]` + - `event: Literal["thread.run.queued"]` - The name of the file to be sent to the model. + - `"thread.run.queued"` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `class ThreadRunInProgress: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. - - `mode: Literal["explicit"]` + - `data: Run` - The breakpoint mode. Always `explicit`. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"explicit"` + - `event: Literal["thread.run.in_progress"]` - - `role: Literal["user", "system", "developer"]` + - `"thread.run.in_progress"` - The role of the message input. One of `user`, `system`, or `developer`. + - `class ThreadRunRequiresAction: …` - - `"user"` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. - - `"system"` + - `data: Run` - - `"developer"` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `type: Literal["message"]` + - `event: Literal["thread.run.requires_action"]` - The type of the message input. Always set to `message`. + - `"thread.run.requires_action"` - - `"message"` + - `class ThreadRunCompleted: …` - - `agent: Optional[Agent]` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. - The agent that produced this item. + - `data: Run` - - `agent_name: str` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The canonical name of the agent that produced this item. + - `event: Literal["thread.run.completed"]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"thread.run.completed"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class ThreadRunIncomplete: …` - - `"in_progress"` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. - - `"completed"` + - `data: Run` - - `"incomplete"` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `class BetaResponseOutputMessage: …` + - `event: Literal["thread.run.incomplete"]` - An output message from the model. + - `"thread.run.incomplete"` - - `id: str` + - `class ThreadRunFailed: …` - The unique ID of the output message. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. - - `content: List[Content]` + - `data: Run` - The content of the output message. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `class BetaResponseOutputText: …` + - `event: Literal["thread.run.failed"]` - A text output from the model. + - `"thread.run.failed"` - - `annotations: List[Annotation]` + - `class ThreadRunCancelling: …` - The annotations of the text output. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. - - `class AnnotationFileCitation: …` + - `data: Run` - A citation to a file. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `file_id: str` + - `event: Literal["thread.run.cancelling"]` - The ID of the file. + - `"thread.run.cancelling"` - - `filename: str` + - `class ThreadRunCancelled: …` - The filename of the file cited. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. - - `index: int` + - `data: Run` - The index of the file in the list of files. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `type: Literal["file_citation"]` + - `event: Literal["thread.run.cancelled"]` - The type of the file citation. Always `file_citation`. + - `"thread.run.cancelled"` - - `"file_citation"` + - `class ThreadRunExpired: …` - - `class AnnotationURLCitation: …` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. - A citation for a web resource used to generate a model response. + - `data: Run` - - `end_index: int` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The index of the last character of the URL citation in the message. + - `event: Literal["thread.run.expired"]` - - `start_index: int` + - `"thread.run.expired"` - The index of the first character of the URL citation in the message. +### Thread Stream Event - - `title: str` +- `class ThreadStreamEvent: …` - The title of the web resource. + Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. - - `type: Literal["url_citation"]` + - `data: Thread` - The type of the URL citation. Always `url_citation`. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `"url_citation"` + - `id: str` - - `url: str` + The identifier, which can be referenced in API endpoints. - The URL of the web resource. + - `created_at: int` - - `class AnnotationContainerFileCitation: …` + The Unix timestamp (in seconds) for when the thread was created. - A citation for a container file used to generate a model response. + - `metadata: Optional[Metadata]` - - `container_id: str` + 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. - The ID of the container file. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `end_index: int` + - `object: Literal["thread"]` - The index of the last character of the container file citation in the message. + The object type, which is always `thread`. - - `file_id: str` + - `"thread"` - The ID of the file. + - `tool_resources: Optional[ToolResources]` - - `filename: str` + 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. - The filename of the container file cited. + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - `start_index: int` + - `file_ids: Optional[List[str]]` - The index of the first character of the container file citation in the message. + 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. - - `type: Literal["container_file_citation"]` + - `file_search: Optional[ToolResourcesFileSearch]` - The type of the container file citation. Always `container_file_citation`. + - `vector_store_ids: Optional[List[str]]` - - `"container_file_citation"` + 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. - - `class AnnotationFilePath: …` + - `event: Literal["thread.created"]` - A path to a file. + - `"thread.created"` - - `file_id: str` + - `enabled: Optional[bool]` - The ID of the file. + Whether to enable input audio transcription. - - `index: int` +# Threads - The index of the file in the list of files. +## Create thread - - `type: Literal["file_path"]` +`beta.threads.create(ThreadCreateParams**kwargs) -> Thread` - The type of the file path. Always `file_path`. +**post** `/threads` - - `"file_path"` +Create a thread. - - `text: str` +### Parameters - The text output from the model. +- `messages: Optional[Iterable[Message]]` - - `type: Literal["output_text"]` + A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. - The type of the output text. Always `output_text`. + - `content: Union[str, Iterable[MessageContentPartParam]]` - - `"output_text"` + The text contents of the message. - - `logprobs: Optional[List[Logprob]]` + - `str` - - `token: str` + The text contents of the message. - - `bytes: List[int]` + - `Iterable[MessageContentPartParam]` - - `logprob: float` + An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](https://platform.openai.com/docs/models). - - `top_logprobs: List[LogprobTopLogprob]` + - `class ImageFileContentBlock: …` - - `token: str` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `bytes: List[int]` + - `image_file: ImageFile` - - `logprob: float` + - `file_id: str` - - `class BetaResponseOutputRefusal: …` + 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. - A refusal from the model. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `refusal: str` + 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`. - The refusal explanation from the model. + - `"auto"` - - `type: Literal["refusal"]` + - `"low"` - The type of the refusal. Always `refusal`. + - `"high"` - - `"refusal"` + - `type: Literal["image_file"]` - - `role: Literal["assistant"]` + Always `image_file`. - The role of the output message. Always `assistant`. + - `"image_file"` - - `"assistant"` + - `class ImageURLContentBlock: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + References an image URL in the content of a message. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `image_url: ImageURL` - - `"in_progress"` + - `url: str` - - `"completed"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"incomplete"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `type: Literal["message"]` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - The type of the output message. Always `message`. + - `"auto"` - - `"message"` + - `"low"` - - `agent: Optional[Agent]` + - `"high"` - The agent that produced this item. + - `type: Literal["image_url"]` - - `agent_name: str` + The type of the content part. - The canonical name of the agent that produced this item. + - `"image_url"` - - `phase: Optional[Literal["commentary"]]` + - `class TextContentBlockParam: …` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The text content that is part of a message. - - `"commentary"` + - `text: str` - - `class BetaResponseFileSearchToolCall: …` + Text content to be sent to the model - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `type: Literal["text"]` - - `id: str` + Always `text`. - The unique ID of the file search tool call. + - `"text"` - - `queries: List[str]` + - `role: Literal["user", "assistant"]` - The queries used to search for files. + The role of the entity that is creating the message. Allowed values include: - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"user"` - - `"in_progress"` + - `"assistant"` - - `"searching"` + - `attachments: Optional[Iterable[MessageAttachment]]` - - `"completed"` + A list of files attached to the message, and the tools they should be added to. - - `"incomplete"` + - `file_id: Optional[str]` - - `"failed"` + The ID of the file to attach to the message. - - `type: Literal["file_search_call"]` + - `tools: Optional[Iterable[MessageAttachmentTool]]` - The type of the file search tool call. Always `file_search_call`. + The tools to add this file to. - - `"file_search_call"` + - `class CodeInterpreterTool: …` - - `agent: Optional[Agent]` + - `type: Literal["code_interpreter"]` - The agent that produced this item. + The type of tool being defined: `code_interpreter` - - `agent_name: str` + - `"code_interpreter"` - The canonical name of the agent that produced this item. + - `class MessageAttachmentToolFileSearch: …` - - `results: Optional[List[Result]]` + - `type: Literal["file_search"]` - The results of the file search tool call. + The type of tool being defined: `file_search` - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + - `"file_search"` + + - `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, booleans, or numbers. + format, and querying for objects via API or the dashboard. - - `str` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `float` +- `metadata: Optional[Metadata]` - - `bool` + 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. - - `file_id: Optional[str]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The unique ID of the file. +- `tool_resources: Optional[ToolResources]` - - `filename: Optional[str]` + 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. - The name of the file. + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - `score: Optional[float]` + - `file_ids: Optional[Sequence[str]]` - The relevance score of the file - a value between 0 and 1. + 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. - - `text: Optional[str]` + - `file_search: Optional[ToolResourcesFileSearch]` - The text that was retrieved from the file. + - `vector_store_ids: Optional[Sequence[str]]` - - `class BetaResponseComputerToolCall: …` + 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. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `vector_stores: Optional[Iterable[ToolResourcesFileSearchVectorStore]]` - - `id: str` + 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 thread. There can be a maximum of 1 vector store attached to the thread. - The unique ID of the computer call. + - `chunking_strategy: Optional[ToolResourcesFileSearchVectorStoreChunkingStrategy]` - - `call_id: str` + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - An identifier used when responding to the tool call with output. + - `class ToolResourcesFileSearchVectorStoreChunkingStrategyAuto: …` - - `pending_safety_checks: List[PendingSafetyCheck]` + The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - The pending safety checks for the computer call. + - `type: Literal["auto"]` - - `id: str` + Always `auto`. - The ID of the pending safety check. + - `"auto"` - - `code: Optional[str]` + - `class ToolResourcesFileSearchVectorStoreChunkingStrategyStatic: …` - The type of the pending safety check. + - `static: ToolResourcesFileSearchVectorStoreChunkingStrategyStaticStatic` - - `message: Optional[str]` + - `chunk_overlap_tokens: int` - Details about the pending safety check. + The number of tokens that overlap between chunks. The default value is `400`. - - `status: Literal["in_progress", "completed", "incomplete"]` + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `max_chunk_size_tokens: int` - - `"in_progress"` + The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - - `"completed"` + - `type: Literal["static"]` - - `"incomplete"` + Always `static`. - - `type: Literal["computer_call"]` + - `"static"` - The type of the computer call. Always `computer_call`. + - `file_ids: Optional[Sequence[str]]` - - `"computer_call"` + 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. - - `action: Optional[BetaComputerAction]` + - `metadata: Optional[Metadata]` - A click action. + 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. - - `class Click: …` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A click action. +### Returns - - `button: Literal["left", "right", "wheel", 2 more]` +- `class Thread: …` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `"left"` + - `id: str` - - `"right"` + The identifier, which can be referenced in API endpoints. - - `"wheel"` + - `created_at: int` - - `"back"` + The Unix timestamp (in seconds) for when the thread was created. - - `"forward"` + - `metadata: Optional[Metadata]` - - `type: Literal["click"]` + 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. - Specifies the event type. For a click action, this property is always `click`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"click"` + - `object: Literal["thread"]` - - `x: int` + The object type, which is always `thread`. - The x-coordinate where the click occurred. + - `"thread"` - - `y: int` + - `tool_resources: Optional[ToolResources]` - The y-coordinate where the click occurred. + 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. - - `keys: Optional[List[str]]` + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - The keys being held while clicking. + - `file_ids: Optional[List[str]]` - - `class DoubleClick: …` + 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. - A double click action. + - `file_search: Optional[ToolResourcesFileSearch]` - - `keys: Optional[List[str]]` + - `vector_store_ids: Optional[List[str]]` - The keys being held while double-clicking. + 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. - - `type: Literal["double_click"]` +### Example - Specifies the event type. For a double click action, this property is always set to `double_click`. +```python +import os +from openai import OpenAI - - `"double_click"` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +thread = client.beta.threads.create() +print(thread.id) +``` - - `x: int` +#### Response - The x-coordinate where the double click occurred. +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - - `y: int` +### Empty - The y-coordinate where the double click occurred. +```python +from openai import OpenAI +client = OpenAI() - - `class Drag: …` +empty_thread = client.beta.threads.create() +print(empty_thread) +``` - A drag action. +#### Response - - `path: List[DragPath]` +```json +{ + "id": "thread_abc123", + "object": "thread", + "created_at": 1699012949, + "metadata": {}, + "tool_resources": {} +} +``` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg +### Messages - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } +```python +from openai import OpenAI +client = OpenAI() + +message_thread = client.beta.threads.create( + messages=[ + { + "role": "user", + "content": "Hello, what is AI?" + }, + { + "role": "user", + "content": "How does AI work? Explain it in simple terms." + }, ] - ``` +) - - `x: int` +print(message_thread) +``` - The x-coordinate. +#### Response - - `y: int` +```json +{ + "id": "thread_abc123", + "object": "thread", + "created_at": 1699014083, + "metadata": {}, + "tool_resources": {} +} +``` - The y-coordinate. +## Create thread and run - - `type: Literal["drag"]` +`beta.threads.create_and_run(ThreadCreateAndRunParams**kwargs) -> Run` - Specifies the event type. For a drag action, this property is always set to `drag`. +**post** `/threads/runs` - - `"drag"` +Create a thread and run it in one request. - - `keys: Optional[List[str]]` +### Parameters - The keys being held while dragging the mouse. +- `assistant_id: str` - - `class Keypress: …` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. - A collection of keypresses the model would like to perform. +- `instructions: Optional[str]` - - `keys: List[str]` + Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. +- `max_completion_tokens: Optional[int]` - - `type: Literal["keypress"]` + The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - Specifies the event type. For a keypress action, this property is always set to `keypress`. +- `max_prompt_tokens: Optional[int]` - - `"keypress"` + The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - - `class Move: …` +- `metadata: Optional[Metadata]` - A mouse move action. + 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. - - `type: Literal["move"]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Specifies the event type. For a move action, this property is always set to `move`. +- `model: Optional[Union[str, ChatModel, null]]` - - `"move"` + The ID of the [Model](https://platform.openai.com/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. - - `x: int` + - `str` - The x-coordinate to move to. + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 78 more]` - - `y: int` + - `"gpt-5.6-sol"` - The y-coordinate to move to. + - `"gpt-5.6-terra"` - - `keys: Optional[List[str]]` + - `"gpt-5.6-luna"` - The keys being held while moving the mouse. + - `"gpt-5.4"` - - `class Screenshot: …` + - `"gpt-5.4-mini"` - A screenshot action. + - `"gpt-5.4-nano"` - - `type: Literal["screenshot"]` + - `"gpt-5.4-mini-2026-03-17"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"gpt-5.4-nano-2026-03-17"` - - `"screenshot"` + - `"gpt-5.3-chat-latest"` - - `class Scroll: …` + - `"gpt-5.2"` - A scroll action. + - `"gpt-5.2-2025-12-11"` - - `scroll_x: int` + - `"gpt-5.2-chat-latest"` - The horizontal scroll distance. + - `"gpt-5.2-pro"` - - `scroll_y: int` + - `"gpt-5.2-pro-2025-12-11"` - The vertical scroll distance. + - `"gpt-5.1"` - - `type: Literal["scroll"]` + - `"gpt-5.1-2025-11-13"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"gpt-5.1-codex"` - - `"scroll"` + - `"gpt-5.1-mini"` - - `x: int` + - `"gpt-5.1-chat-latest"` - The x-coordinate where the scroll occurred. + - `"gpt-5"` - - `y: int` + - `"gpt-5-mini"` - The y-coordinate where the scroll occurred. + - `"gpt-5-nano"` - - `keys: Optional[List[str]]` + - `"gpt-5-2025-08-07"` - The keys being held while scrolling. + - `"gpt-5-mini-2025-08-07"` - - `class Type: …` + - `"gpt-5-nano-2025-08-07"` - An action to type in text. + - `"gpt-5-chat-latest"` - - `text: str` + - `"gpt-4.1"` - The text to type. + - `"gpt-4.1-mini"` - - `type: Literal["type"]` + - `"gpt-4.1-nano"` - Specifies the event type. For a type action, this property is always set to `type`. + - `"gpt-4.1-2025-04-14"` - - `"type"` + - `"gpt-4.1-mini-2025-04-14"` - - `class Wait: …` + - `"gpt-4.1-nano-2025-04-14"` - A wait action. + - `"o4-mini"` - - `type: Literal["wait"]` + - `"o4-mini-2025-04-16"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"o3"` - - `"wait"` + - `"o3-2025-04-16"` - - `actions: Optional[BetaComputerActionList]` + - `"o3-mini"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"o3-mini-2025-01-31"` - - `class Click: …` + - `"o1"` - A click action. + - `"o1-2024-12-17"` - - `class DoubleClick: …` + - `"o1-preview"` - A double click action. + - `"o1-preview-2024-09-12"` - - `class Drag: …` + - `"o1-mini"` - A drag action. + - `"o1-mini-2024-09-12"` - - `class Keypress: …` + - `"gpt-4o"` - A collection of keypresses the model would like to perform. + - `"gpt-4o-2024-11-20"` - - `class Move: …` + - `"gpt-4o-2024-08-06"` - A mouse move action. + - `"gpt-4o-2024-05-13"` - - `class Screenshot: …` + - `"gpt-4o-audio-preview"` - A screenshot action. + - `"gpt-4o-audio-preview-2024-10-01"` - - `class Scroll: …` + - `"gpt-4o-audio-preview-2024-12-17"` - A scroll action. + - `"gpt-4o-audio-preview-2025-06-03"` - - `class Type: …` + - `"gpt-4o-mini-audio-preview"` - An action to type in text. + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `class Wait: …` + - `"gpt-4o-search-preview"` - A wait action. + - `"gpt-4o-mini-search-preview"` - - `agent: Optional[Agent]` + - `"gpt-4o-search-preview-2025-03-11"` - The agent that produced this item. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `agent_name: str` + - `"chatgpt-4o-latest"` - The canonical name of the agent that produced this item. + - `"codex-mini-latest"` - - `class BetaResponseComputerToolCallOutputItem: …` + - `"gpt-4o-mini"` - - `id: str` + - `"gpt-4o-mini-2024-07-18"` - The unique ID of the computer call tool output. + - `"gpt-4-turbo"` - - `call_id: str` + - `"gpt-4-turbo-2024-04-09"` - The ID of the computer tool call that produced the output. + - `"gpt-4-0125-preview"` - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"gpt-4-turbo-preview"` - A computer screenshot image used with the computer use tool. + - `"gpt-4-1106-preview"` - - `type: Literal["computer_screenshot"]` + - `"gpt-4-vision-preview"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"gpt-4"` - - `"computer_screenshot"` + - `"gpt-4-0314"` - - `file_id: Optional[str]` + - `"gpt-4-0613"` - The identifier of an uploaded file that contains the screenshot. + - `"gpt-4-32k"` - - `image_url: Optional[str]` + - `"gpt-4-32k-0314"` - The URL of the screenshot image. + - `"gpt-4-32k-0613"` - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + - `"gpt-3.5-turbo"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"gpt-3.5-turbo-16k"` - - `"completed"` + - `"gpt-3.5-turbo-0301"` - - `"incomplete"` + - `"gpt-3.5-turbo-0613"` - - `"failed"` + - `"gpt-3.5-turbo-1106"` - - `"in_progress"` + - `"gpt-3.5-turbo-0125"` - - `type: Literal["computer_call_output"]` + - `"gpt-3.5-turbo-16k-0613"` - The type of the computer tool call output. Always `computer_call_output`. +- `parallel_tool_calls: Optional[bool]` - - `"computer_call_output"` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` +- `response_format: Optional[AssistantResponseFormatOptionParam]` - The safety checks reported by the API that have been acknowledged by the - developer. + 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`. - - `id: str` + 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). - The ID of the pending safety check. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `code: Optional[str]` + **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. - The type of the pending safety check. + - `Literal["auto"]` - - `message: Optional[str]` + `auto` is the default value - Details about the pending safety check. + - `"auto"` - - `agent: Optional[Agent]` + - `class ResponseFormatText: …` - The agent that produced this item. + Default response format. Used to generate text responses. - - `agent_name: str` + - `type: Literal["text"]` - The canonical name of the agent that produced this item. + The type of response format being defined. Always `text`. - - `created_by: Optional[str]` + - `"text"` - The identifier of the actor that created the item. + - `class ResponseFormatJSONObject: …` - - `class BetaResponseFunctionWebSearch: …` + 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. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `type: Literal["json_object"]` - - `id: str` + The type of response format being defined. Always `json_object`. - The unique ID of the web search tool call. + - `"json_object"` - - `action: Action` + - `class ResponseFormatJSONSchema: …` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `class ActionSearch: …` + - `json_schema: JSONSchema` - Action type "search" - Performs a web search query. + Structured Outputs configuration options, including a JSON Schema. - - `type: Literal["search"]` + - `name: str` - The action type. + 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. - - `"search"` + - `description: Optional[str]` - - `queries: Optional[List[str]]` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The search queries. + - `schema: Optional[Dict[str, object]]` - - `query: Optional[str]` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The search query. + - `strict: Optional[bool]` - - `sources: Optional[List[ActionSearchSource]]` + 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). - The sources used in the search. + - `type: Literal["json_schema"]` - - `type: Literal["url"]` + The type of response format being defined. Always `json_schema`. - The type of source. Always `url`. + - `"json_schema"` - - `"url"` +- `stream: Optional[Literal[false]]` - - `url: str` + If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. - The URL of the source. + - `false` - - `class ActionOpenPage: …` +- `temperature: Optional[float]` - Action type "open_page" - Opens a specific URL from search results. + 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. - - `type: Literal["open_page"]` +- `thread: Optional[Thread]` - The action type. + Options to create a new thread. If no thread is provided when running a + request, an empty thread will be created. - - `"open_page"` + - `messages: Optional[Iterable[ThreadMessage]]` - - `url: Optional[str]` + A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. - The URL opened by the model. + - `content: Union[str, Iterable[MessageContentPartParam]]` - - `class ActionFindInPage: …` + The text contents of the message. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `str` - - `pattern: str` + The text contents of the message. - The pattern or text to search for within the page. + - `Iterable[MessageContentPartParam]` - - `type: Literal["find_in_page"]` + An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](https://platform.openai.com/docs/models). - The action type. + - `class ImageFileContentBlock: …` - - `"find_in_page"` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `url: str` + - `image_file: ImageFile` - The URL of the page searched for the pattern. + - `file_id: str` - - `status: Literal["in_progress", "searching", "completed", "failed"]` + 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. - The status of the web search tool call. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"in_progress"` + 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`. - - `"searching"` + - `"auto"` - - `"completed"` + - `"low"` - - `"failed"` + - `"high"` - - `type: Literal["web_search_call"]` + - `type: Literal["image_file"]` - The type of the web search tool call. Always `web_search_call`. + Always `image_file`. - - `"web_search_call"` + - `"image_file"` - - `agent: Optional[Agent]` + - `class ImageURLContentBlock: …` - The agent that produced this item. + References an image URL in the content of a message. - - `agent_name: str` + - `image_url: ImageURL` - The canonical name of the agent that produced this item. + - `url: str` - - `class BetaResponseFunctionToolCallItem: …` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `id: str` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - The unique ID of the function tool call. + - `"auto"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"low"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"high"` - - `"in_progress"` + - `type: Literal["image_url"]` - - `"completed"` + The type of the content part. - - `"incomplete"` + - `"image_url"` - - `created_by: Optional[str]` + - `class TextContentBlockParam: …` + + The text content that is part of a message. - The identifier of the actor that created the item. + - `text: str` - - `class BetaResponseFunctionToolCallOutputItem: …` + Text content to be sent to the model - - `id: str` + - `type: Literal["text"]` - The unique ID of the function call tool output. + Always `text`. - - `call_id: str` + - `"text"` - The unique ID of the function tool call generated by the model. + - `role: Literal["user", "assistant"]` - - `output: Union[str, List[OutputOutputContentList]]` + The role of the entity that is creating the message. Allowed values include: - The output from the function call generated by your code. - Can be a string or an list of output content. + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. - - `str` + - `"user"` - A string of the output of the function call. + - `"assistant"` - - `List[OutputOutputContentList]` + - `attachments: Optional[Iterable[ThreadMessageAttachment]]` - Text, image, or file output of the function call. + A list of files attached to the message, and the tools they should be added to. - - `class BetaResponseInputText: …` + - `file_id: Optional[str]` - A text input to the model. + The ID of the file to attach to the message. - - `class BetaResponseInputImage: …` + - `tools: Optional[Iterable[ThreadMessageAttachmentTool]]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The tools to add this file to. - - `class BetaResponseInputFile: …` + - `class CodeInterpreterTool: …` - A file input to the model. + - `type: Literal["code_interpreter"]` - - `status: Literal["in_progress", "completed", "incomplete"]` + The type of tool being defined: `code_interpreter` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"code_interpreter"` - - `"in_progress"` + - `class ThreadMessageAttachmentToolFileSearch: …` - - `"completed"` + - `type: Literal["file_search"]` - - `"incomplete"` + The type of tool being defined: `file_search` - - `type: Literal["function_call_output"]` + - `"file_search"` - The type of the function tool call output. Always `function_call_output`. + - `metadata: Optional[Metadata]` - - `"function_call_output"` + 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. - - `agent: Optional[Agent]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The agent that produced this item. + - `metadata: Optional[Metadata]` - - `agent_name: str` + 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. - The canonical name of the agent that produced this item. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `caller: Optional[Caller]` + - `tool_resources: Optional[ThreadToolResources]` - The execution context that produced this tool call. + 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. - - `class CallerDirect: …` + - `code_interpreter: Optional[ThreadToolResourcesCodeInterpreter]` - - `type: Literal["direct"]` + - `file_ids: Optional[Sequence[str]]` - The caller type. Always `direct`. + 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. - - `"direct"` + - `file_search: Optional[ThreadToolResourcesFileSearch]` - - `class CallerProgram: …` + - `vector_store_ids: Optional[Sequence[str]]` - - `caller_id: 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. - The call ID of the program item that produced this tool call. + - `vector_stores: Optional[Iterable[ThreadToolResourcesFileSearchVectorStore]]` - - `type: Literal["program"]` + 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 thread. There can be a maximum of 1 vector store attached to the thread. - The caller type. Always `program`. + - `chunking_strategy: Optional[ThreadToolResourcesFileSearchVectorStoreChunkingStrategy]` - - `"program"` + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - `created_by: Optional[str]` + - `class ThreadToolResourcesFileSearchVectorStoreChunkingStrategyAuto: …` - The identifier of the actor that created the item. + The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - - `class AgentMessage: …` + - `type: Literal["auto"]` - - `id: str` + Always `auto`. - The unique ID of the agent message. + - `"auto"` - - `author: str` + - `class ThreadToolResourcesFileSearchVectorStoreChunkingStrategyStatic: …` - The sending agent identity. + - `static: ThreadToolResourcesFileSearchVectorStoreChunkingStrategyStaticStatic` - - `content: List[AgentMessageContent]` + - `chunk_overlap_tokens: int` - Encrypted content sent between agents. + The number of tokens that overlap between chunks. The default value is `400`. - - `class BetaResponseInputText: …` + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - A text input to the model. + - `max_chunk_size_tokens: int` - - `class BetaResponseOutputText: …` + The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - A text output from the model. + - `type: Literal["static"]` - - `class AgentMessageContentText: …` + Always `static`. - A text content. + - `"static"` - - `text: str` + - `file_ids: Optional[Sequence[str]]` - - `type: Literal["text"]` + 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. - - `"text"` + - `metadata: Optional[Metadata]` - - `class AgentMessageContentSummaryText: …` + 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. - A summary text from the model. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `text: str` +- `tool_choice: Optional[AssistantToolChoiceOptionParam]` - A summary of the reasoning output from the model so far. + 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. - - `type: Literal["summary_text"]` + - `Literal["none", "auto", "required"]` - The type of the object. Always `summary_text`. + `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. - - `"summary_text"` + - `"none"` - - `class AgentMessageContentReasoningText: …` + - `"auto"` - Reasoning text from the model. + - `"required"` - - `text: str` + - `class AssistantToolChoice: …` - The reasoning text from the model. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `type: Literal["reasoning_text"]` + - `type: Literal["function", "code_interpreter", "file_search"]` - The type of the reasoning text. Always `reasoning_text`. + The type of the tool. If type is `function`, the function name must be set - - `"reasoning_text"` + - `"function"` - - `class BetaResponseOutputRefusal: …` + - `"code_interpreter"` - A refusal from the model. + - `"file_search"` - - `class BetaResponseInputImage: …` + - `function: Optional[AssistantToolChoiceFunction]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `name: str` - - `class AgentMessageContentComputerScreenshot: …` + The name of the function to call. - A screenshot of a computer. +- `tool_resources: Optional[ToolResources]` - - `detail: Literal["low", "high", "auto", "original"]` + 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. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - `"low"` + - `file_ids: Optional[Sequence[str]]` - - `"high"` + 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. - - `"auto"` + - `file_search: Optional[ToolResourcesFileSearch]` - - `"original"` + - `vector_store_ids: Optional[Sequence[str]]` - - `file_id: Optional[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. - The identifier of an uploaded file that contains the screenshot. +- `tools: Optional[Iterable[AssistantToolParam]]` - - `image_url: Optional[str]` + Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - The URL of the screenshot image. + - `class CodeInterpreterTool: …` - - `type: Literal["computer_screenshot"]` + - `class FileSearchTool: …` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `type: Literal["file_search"]` - - `"computer_screenshot"` + The type of tool being defined: `file_search` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `"file_search"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `file_search: Optional[FileSearch]` - - `mode: Literal["explicit"]` + Overrides for the file search tool. - The breakpoint mode. Always `explicit`. + - `max_num_results: Optional[int]` - - `"explicit"` + 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. - - `class BetaResponseInputFile: …` + 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. - A file input to the model. + - `ranking_options: Optional[FileSearchRankingOptions]` - - `class AgentMessageContentEncryptedContent: …` + 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. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `encrypted_content: str` + - `score_threshold: float` - Opaque encrypted content. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: Literal["encrypted_content"]` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - The type of the input item. Always `encrypted_content`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"encrypted_content"` + - `"auto"` - - `recipient: str` + - `"default_2024_08_21"` - The destination agent identity. + - `class FunctionTool: …` - - `type: Literal["agent_message"]` + - `function: FunctionDefinition` - The type of the item. Always `agent_message`. + - `name: str` - - `"agent_message"` + 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. - - `agent: Optional[AgentMessageAgent]` + - `description: Optional[str]` - The agent that produced this item. + A description of what the function does, used by the model to choose when and how to call the function. - - `agent_name: str` + - `parameters: Optional[FunctionParameters]` - The canonical name of the agent that produced this item. + 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. - - `class MultiAgentCall: …` + Omitting `parameters` defines a function with an empty parameter list. - - `id: str` + - `strict: Optional[bool]` - The unique ID of the multi-agent call item. + 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). - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `type: Literal["function"]` - The multi-agent action to execute. + The type of tool being defined: `function` - - `"spawn_agent"` + - `"function"` - - `"interrupt_agent"` +- `top_p: Optional[float]` - - `"list_agents"` + 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. - - `"send_message"` + We generally recommend altering this or temperature but not both. - - `"followup_task"` +- `truncation_strategy: Optional[TruncationStrategy]` - - `"wait_agent"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `arguments: str` + - `type: Literal["auto", "last_messages"]` - The JSON string of arguments generated for the action. + 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`. - - `call_id: str` + - `"auto"` - The unique ID linking this call to its output. + - `"last_messages"` - - `type: Literal["multi_agent_call"]` + - `last_messages: Optional[int]` - The type of the multi-agent call. Always `multi_agent_call`. + The number of most recent messages from the thread when constructing the context for the run. - - `"multi_agent_call"` +### Returns - - `agent: Optional[MultiAgentCallAgent]` +- `class Run: …` - The agent that produced this item. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `agent_name: str` + - `id: str` - The canonical name of the agent that produced this item. + The identifier, which can be referenced in API endpoints. - - `class MultiAgentCallOutput: …` + - `assistant_id: str` - - `id: str` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The unique ID of the multi-agent call output item. + - `cancelled_at: Optional[int]` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The Unix timestamp (in seconds) for when the run was cancelled. - The multi-agent action that produced this result. + - `completed_at: Optional[int]` - - `"spawn_agent"` + The Unix timestamp (in seconds) for when the run was completed. - - `"interrupt_agent"` + - `created_at: int` - - `"list_agents"` + The Unix timestamp (in seconds) for when the run was created. - - `"send_message"` + - `expires_at: Optional[int]` - - `"followup_task"` + The Unix timestamp (in seconds) for when the run will expire. - - `"wait_agent"` + - `failed_at: Optional[int]` - - `call_id: str` + The Unix timestamp (in seconds) for when the run failed. - The unique ID of the multi-agent call. + - `incomplete_details: Optional[IncompleteDetails]` - - `output: List[BetaResponseOutputText]` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - Text output returned by the multi-agent action. + - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` - - `annotations: List[Annotation]` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The annotations of the text output. + - `"max_completion_tokens"` - - `text: str` + - `"max_prompt_tokens"` - The text output from the model. + - `instructions: str` - - `type: Literal["output_text"]` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The type of the output text. Always `output_text`. + - `last_error: Optional[LastError]` - - `logprobs: Optional[List[Logprob]]` + The last error associated with this run. Will be `null` if there are no errors. - - `type: Literal["multi_agent_call_output"]` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` - The type of the multi-agent result. Always `multi_agent_call_output`. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `"multi_agent_call_output"` + - `"server_error"` - - `agent: Optional[MultiAgentCallOutputAgent]` + - `"rate_limit_exceeded"` - The agent that produced this item. + - `"invalid_prompt"` - - `agent_name: str` + - `message: str` - The canonical name of the agent that produced this item. + A human-readable description of the error. - - `class BetaResponseToolSearchCall: …` + - `max_completion_tokens: Optional[int]` - - `id: str` + The maximum number of completion tokens specified to have been used over the course of the run. - The unique ID of the tool search call item. + - `max_prompt_tokens: Optional[int]` - - `arguments: object` + The maximum number of prompt tokens specified to have been used over the course of the run. - Arguments used for the tool search call. + - `metadata: Optional[Metadata]` - - `call_id: Optional[str]` + 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. - The unique ID of the tool search call generated by the model. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `execution: Literal["server", "client"]` + - `model: str` - Whether tool search was executed by the server or by the client. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"server"` + - `object: Literal["thread.run"]` - - `"client"` + The object type, which is always `thread.run`. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"thread.run"` - The status of the tool search call item that was recorded. + - `parallel_tool_calls: bool` - - `"in_progress"` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"completed"` + - `required_action: Optional[RequiredAction]` - - `"incomplete"` + Details on the action required to continue the run. Will be `null` if no action is required. - - `type: Literal["tool_search_call"]` + - `submit_tool_outputs: RequiredActionSubmitToolOutputs` - The type of the item. Always `tool_search_call`. + Details on the tool outputs needed for this run to continue. - - `"tool_search_call"` + - `tool_calls: List[RequiredActionFunctionToolCall]` - - `agent: Optional[Agent]` + A list of the relevant tool calls. - The agent that produced this item. + - `id: str` - - `agent_name: 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. - The canonical name of the agent that produced this item. + - `function: Function` - - `created_by: Optional[str]` + The function definition. - The identifier of the actor that created the item. + - `arguments: str` - - `class BetaResponseToolSearchOutputItem: …` + The arguments that the model expects you to pass to the function. - - `id: str` + - `name: str` - The unique ID of the tool search output item. + The name of the function. - - `call_id: Optional[str]` + - `type: Literal["function"]` - The unique ID of the tool search call generated by the model. + The type of tool call the output is required for. For now, this is always `function`. - - `execution: Literal["server", "client"]` + - `"function"` - Whether tool search was executed by the server or by the client. + - `type: Literal["submit_tool_outputs"]` - - `"server"` + For now, this is always `submit_tool_outputs`. - - `"client"` + - `"submit_tool_outputs"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `response_format: Optional[AssistantResponseFormatOption]` - The status of the tool search output item that was recorded. + 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`. - - `"in_progress"` + 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). - - `"completed"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"incomplete"` + **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. - - `tools: List[BetaTool]` + - `Literal["auto"]` - The loaded tool definitions returned by tool search. + `auto` is the default value - - `class BetaFunctionTool: …` + - `"auto"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class ResponseFormatText: …` - - `name: str` + Default response format. Used to generate text responses. - The name of the function to call. + - `type: Literal["text"]` - - `parameters: Optional[Dict[str, object]]` + The type of response format being defined. Always `text`. - A JSON schema object describing the parameters of the function. + - `"text"` - - `strict: Optional[bool]` + - `class ResponseFormatJSONObject: …` - Whether strict parameter validation is enforced for this function tool. + 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["function"]` + - `type: Literal["json_object"]` - The type of the function tool. Always `function`. + The type of response format being defined. Always `json_object`. - - `"function"` + - `"json_object"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `class ResponseFormatJSONSchema: …` - The tool invocation context(s). + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `"direct"` + - `json_schema: JSONSchema` - - `"programmatic"` + Structured Outputs configuration options, including a JSON Schema. - - `defer_loading: Optional[bool]` + - `name: str` - Whether this function is deferred and loaded via tool search. + 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 the function. Used by the model to determine whether or not to call the function. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `output_schema: Optional[Dict[str, object]]` + - `schema: Optional[Dict[str, object]]` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `class BetaFileSearchTool: …` + - `strict: Optional[bool]` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + 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["file_search"]` + - `type: Literal["json_schema"]` - The type of the file search tool. Always `file_search`. + The type of response format being defined. Always `json_schema`. - - `"file_search"` + - `"json_schema"` - - `vector_store_ids: List[str]` + - `started_at: Optional[int]` - The IDs of the vector stores to search. + The Unix timestamp (in seconds) for when the run was started. - - `filters: Optional[Filters]` + - `status: RunStatus` - A filter to apply. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `class FiltersComparisonFilter: …` + - `"queued"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"in_progress"` - - `key: str` + - `"requires_action"` - The key to compare against the value. + - `"cancelling"` - - `type: Literal["eq", "ne", "gt", 5 more]` + - `"cancelled"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"failed"` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `"completed"` - - `"eq"` + - `"incomplete"` - - `"ne"` + - `"expired"` - - `"gt"` + - `thread_id: str` - - `"gte"` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `"lt"` + - `tool_choice: Optional[AssistantToolChoiceOption]` - - `"lte"` + 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. - - `"in"` + - `Literal["none", "auto", "required"]` - - `"nin"` + `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. - - `value: Union[str, float, bool, List[object]]` + - `"none"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"auto"` - - `str` + - `"required"` - - `float` + - `class AssistantToolChoice: …` - - `bool` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `List[object]` + - `type: Literal["function", "code_interpreter", "file_search"]` - - `class FiltersCompoundFilter: …` + The type of the tool. If type is `function`, the function name must be set - Combine multiple filters using `and` or `or`. + - `"function"` - - `filters: List[FiltersCompoundFilterFilter]` + - `"code_interpreter"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"file_search"` - - `class FiltersCompoundFilterFilterComparisonFilter: …` + - `function: Optional[AssistantToolChoiceFunction]` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `name: str` - - `key: str` + The name of the function to call. - The key to compare against the value. + - `tools: List[AssistantTool]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `class CodeInterpreterTool: …` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `type: Literal["code_interpreter"]` - - `"eq"` + The type of tool being defined: `code_interpreter` - - `"ne"` + - `"code_interpreter"` - - `"gt"` + - `class FileSearchTool: …` - - `"gte"` + - `type: Literal["file_search"]` - - `"lt"` + The type of tool being defined: `file_search` - - `"lte"` + - `"file_search"` - - `"in"` + - `file_search: Optional[FileSearch]` - - `"nin"` + Overrides for the file search tool. - - `value: Union[str, float, bool, List[object]]` + - `max_num_results: Optional[int]` - The value to compare against the attribute key; supports string, number, or boolean types. + 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. - - `str` + 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. - - `float` + - `ranking_options: Optional[FileSearchRankingOptions]` - - `bool` + 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. - - `List[object]` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `object` + - `score_threshold: float` - - `type: Literal["and", "or"]` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Type of operation: `and` or `or`. + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - `"and"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"or"` + - `"auto"` - - `max_num_results: Optional[int]` + - `"default_2024_08_21"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `class FunctionTool: …` - - `ranking_options: Optional[RankingOptions]` + - `function: FunctionDefinition` - Ranking options for search. + - `name: str` - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + 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. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `description: Optional[str]` - - `embedding_weight: float` + A description of what the function does, used by the model to choose when and how to call the function. - The weight of the embedding in the reciprocal ranking fusion. + - `parameters: Optional[FunctionParameters]` - - `text_weight: float` + 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. - The weight of the text in the reciprocal ranking fusion. + Omitting `parameters` defines a function with an empty parameter list. - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + - `strict: Optional[bool]` - The ranker to use for the file search. + 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). - - `"auto"` + - `type: Literal["function"]` - - `"default-2024-11-15"` + The type of tool being defined: `function` - - `score_threshold: Optional[float]` + - `"function"` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `truncation_strategy: Optional[TruncationStrategy]` - - `class BetaComputerTool: …` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: Literal["auto", "last_messages"]` - - `type: Literal["computer"]` + 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`. - The type of the computer tool. Always `computer`. + - `"auto"` - - `"computer"` + - `"last_messages"` - - `class BetaComputerUsePreviewTool: …` + - `last_messages: Optional[int]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The number of most recent messages from the thread when constructing the context for the run. - - `display_height: int` + - `usage: Optional[Usage]` - The height of the computer display. + 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.). - - `display_width: int` + - `completion_tokens: int` - The width of the computer display. + Number of completion tokens used over the course of the run. - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `prompt_tokens: int` - The type of computer environment to control. + Number of prompt tokens used over the course of the run. - - `"windows"` + - `total_tokens: int` - - `"mac"` + Total number of tokens used (prompt + completion). - - `"linux"` + - `temperature: Optional[float]` - - `"ubuntu"` + The sampling temperature used for this run. If not set, defaults to 1. - - `"browser"` + - `top_p: Optional[float]` - - `type: Literal["computer_use_preview"]` + The nucleus sampling value used for this run. If not set, defaults to 1. - The type of the computer use tool. Always `computer_use_preview`. +### Example - - `"computer_use_preview"` +```python +import os +from openai import OpenAI - - `class BetaWebSearchTool: …` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +for thread in client.beta.threads.create_and_run( + assistant_id="assistant_id", +): + print(thread) +``` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). +#### Response - - `type: Literal["web_search", "web_search_2025_08_26"]` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. +### Example - - `"web_search"` +```python +from openai import OpenAI +client = OpenAI() - - `"web_search_2025_08_26"` +run = client.beta.threads.create_and_run( + assistant_id="asst_abc123", + thread={ + "messages": [ + {"role": "user", "content": "Explain deep learning to a 5 year old."} + ] + } +) - - `filters: Optional[Filters]` +print(run) +``` - Filters for the search. +#### Response - - `allowed_domains: Optional[List[str]]` +```json +{ + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699076792, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "queued", + "started_at": null, + "expires_at": 1699077392, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "required_action": null, + "last_error": null, + "model": "gpt-4o", + "instructions": "You are a helpful assistant.", + "tools": [], + "tool_resources": {}, + "metadata": {}, + "temperature": 1.0, + "top_p": 1.0, + "max_completion_tokens": null, + "max_prompt_tokens": null, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "incomplete_details": null, + "usage": null, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true +} +``` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. +### Streaming - Example: `["pubmed.ncbi.nlm.nih.gov"]` +```python +from openai import OpenAI +client = OpenAI() - - `search_context_size: Optional[Literal["low", "medium", "high"]]` +stream = client.beta.threads.create_and_run( + assistant_id="asst_123", + thread={ + "messages": [ + {"role": "user", "content": "Hello"} + ] + }, + stream=True +) - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. +for event in stream: + print(event) +``` - - `"low"` +#### Response - - `"medium"` +```json +event: thread.created +data: {"id":"thread_123","object":"thread","created_at":1710348075,"metadata":{}} - - `"high"` +event: thread.run.created +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} - - `user_location: Optional[UserLocation]` +event: thread.run.queued +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} - The approximate location of the user. +event: thread.run.in_progress +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} - - `city: Optional[str]` +event: thread.run.step.created +data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} - Free text input for the city of the user, e.g. `San Francisco`. +event: thread.run.step.in_progress +data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} - - `country: Optional[str]` +event: thread.message.created +data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[], "metadata":{}} - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. +event: thread.message.in_progress +data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[], "metadata":{}} - - `region: Optional[str]` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} - Free text input for the region of the user, e.g. `California`. +... - - `timezone: Optional[str]` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} - - `type: Optional[Literal["approximate"]]` +event: thread.message.completed +data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}], "metadata":{}} - The type of location approximation. Always `approximate`. +event: thread.run.step.completed +data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} - - `"approximate"` +event: thread.run.completed +{"id":"run_123","object":"thread.run","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1713226836,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1713226837,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} - - `class Mcp: …` +event: done +data: [DONE] +``` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). +### Streaming with Functions - - `server_label: str` +```python +from openai import OpenAI +client = OpenAI() - A label for this MCP server, used to identify it in tool calls. +tools = [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, + }, + "required": ["location"], + }, + } + } +] - - `type: Literal["mcp"]` +stream = client.beta.threads.create_and_run( + thread={ + "messages": [ + {"role": "user", "content": "What is the weather like in San Francisco?"} + ] + }, + assistant_id="asst_abc123", + tools=tools, + stream=True +) - The type of the MCP tool. Always `mcp`. +for event in stream: + print(event) +``` - - `"mcp"` +#### Response - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` +```json +event: thread.created +data: {"id":"thread_123","object":"thread","created_at":1710351818,"metadata":{}} - The tool invocation context(s). +event: thread.run.created +data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `"direct"` +event: thread.run.queued +data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `"programmatic"` +event: thread.run.in_progress +data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `allowed_tools: Optional[McpAllowedTools]` +event: thread.run.step.created +data: {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} - List of allowed tool names or a filter object. +event: thread.run.step.in_progress +data: {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} - - `List[str]` +event: thread.run.step.delta +data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"","output":null}}]}}} - A string array of allowed tool names +event: thread.run.step.delta +data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"{\""}}]}}} - - `class McpAllowedToolsMcpToolFilter: …` +event: thread.run.step.delta +data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"location"}}]}}} - A filter object to specify which tools are allowed. +... - - `read_only: Optional[bool]` +event: thread.run.step.delta +data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"ahrenheit"}}]}}} - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. +event: thread.run.step.delta +data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"\"}"}}]}}} - - `tool_names: Optional[List[str]]` +event: thread.run.requires_action +data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"requires_action","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":{"type":"submit_tool_outputs","submit_tool_outputs":{"tool_calls":[{"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}"}}]}},"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - List of allowed tool names. +event: done +data: [DONE] +``` - - `authorization: Optional[str]` +## Retrieve thread - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. +`beta.threads.retrieve(strthread_id) -> Thread` - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` +**get** `/threads/{thread_id}` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). +Retrieves a thread. - Currently supported `connector_id` values are: +### Parameters - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` +- `thread_id: str` - - `"connector_dropbox"` +### Returns - - `"connector_gmail"` +- `class Thread: …` - - `"connector_googlecalendar"` + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `"connector_googledrive"` + - `id: str` - - `"connector_microsoftteams"` + The identifier, which can be referenced in API endpoints. - - `"connector_outlookcalendar"` + - `created_at: int` - - `"connector_outlookemail"` + The Unix timestamp (in seconds) for when the thread was created. - - `"connector_sharepoint"` + - `metadata: Optional[Metadata]` - - `defer_loading: Optional[bool]` + 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. - Whether this MCP tool is deferred and discovered via tool search. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `headers: Optional[Dict[str, str]]` + - `object: Literal["thread"]` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The object type, which is always `thread`. - - `require_approval: Optional[McpRequireApproval]` + - `"thread"` - Specify which of the MCP server's tools require approval. + - `tool_resources: Optional[ToolResources]` - - `class McpRequireApprovalMcpToolApprovalFilter: …` + 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. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `file_ids: Optional[List[str]]` - A filter object to specify which tools are allowed. + 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. - - `read_only: Optional[bool]` + - `file_search: Optional[ToolResourcesFileSearch]` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `vector_store_ids: Optional[List[str]]` - - `tool_names: 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. - List of allowed tool names. +### Example - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` +```python +import os +from openai import OpenAI - A filter object to specify which tools are allowed. +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +thread = client.beta.threads.retrieve( + "thread_id", +) +print(thread.id) +``` - - `read_only: Optional[bool]` +#### Response - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - - `tool_names: Optional[List[str]]` +### Example - List of allowed tool names. +```python +from openai import OpenAI +client = OpenAI() - - `Literal["always", "never"]` +my_thread = client.beta.threads.retrieve("thread_abc123") +print(my_thread) +``` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. +#### Response - - `"always"` +```json +{ + "id": "thread_abc123", + "object": "thread", + "created_at": 1699014083, + "metadata": {}, + "tool_resources": { + "code_interpreter": { + "file_ids": [] + } + } +} +``` - - `"never"` +## Modify thread - - `server_description: Optional[str]` +`beta.threads.update(strthread_id, ThreadUpdateParams**kwargs) -> Thread` - Optional description of the MCP server, used to provide more context. +**post** `/threads/{thread_id}` - - `server_url: Optional[str]` +Modifies a thread. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. +### Parameters - - `tunnel_id: Optional[str]` +- `thread_id: str` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. +- `metadata: Optional[Metadata]` - - `class CodeInterpreter: …` + 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. - A tool that runs Python code to help generate a response to a prompt. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `container: CodeInterpreterContainer` +- `tool_resources: Optional[ToolResources]` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + 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. - - `str` + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - The container ID. + - `file_ids: Optional[Sequence[str]]` - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + 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. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `file_search: Optional[ToolResourcesFileSearch]` - - `type: Literal["auto"]` + - `vector_store_ids: Optional[Sequence[str]]` - Always `auto`. + 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. - - `"auto"` +### Returns - - `file_ids: Optional[List[str]]` +- `class Thread: …` - An optional list of uploaded files to make available to your code. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `id: str` - The memory limit for the code interpreter container. + The identifier, which can be referenced in API endpoints. - - `"1g"` + - `created_at: int` - - `"4g"` + The Unix timestamp (in seconds) for when the thread was created. - - `"16g"` + - `metadata: Optional[Metadata]` - - `"64g"` + 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. - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Network access policy for the container. + - `object: Literal["thread"]` - - `class BetaContainerNetworkPolicyDisabled: …` + The object type, which is always `thread`. - - `type: Literal["disabled"]` + - `"thread"` - Disable outbound network access. Always `disabled`. + - `tool_resources: Optional[ToolResources]` - - `"disabled"` + 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. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - `allowed_domains: List[str]` + - `file_ids: Optional[List[str]]` - A list of allowed domains when type is `allowlist`. + 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. - - `type: Literal["allowlist"]` + - `file_search: Optional[ToolResourcesFileSearch]` - Allow outbound network access only to specified domains. Always `allowlist`. + - `vector_store_ids: Optional[List[str]]` - - `"allowlist"` + 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. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` +### Example - Optional domain-scoped secrets for allowlisted domains. +```python +import os +from openai import OpenAI - - `domain: str` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +thread = client.beta.threads.update( + thread_id="thread_id", +) +print(thread.id) +``` - The domain associated with the secret. +#### Response - - `name: str` +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - The name of the secret to inject for the domain. +### Example - - `value: str` +```python +from openai import OpenAI +client = OpenAI() - The secret value to inject for the domain. +my_updated_thread = client.beta.threads.update( + "thread_abc123", + metadata={ + "modified": "true", + "user": "abc123" + } +) +print(my_updated_thread) +``` - - `type: Literal["code_interpreter"]` +#### Response - The type of the code interpreter tool. Always `code_interpreter`. +```json +{ + "id": "thread_abc123", + "object": "thread", + "created_at": 1699014083, + "metadata": { + "modified": "true", + "user": "abc123" + }, + "tool_resources": {} +} +``` - - `"code_interpreter"` +## Delete thread - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` +`beta.threads.delete(strthread_id) -> ThreadDeleted` - The tool invocation context(s). +**delete** `/threads/{thread_id}` - - `"direct"` +Delete a thread. - - `"programmatic"` +### Parameters - - `class ProgrammaticToolCalling: …` +- `thread_id: str` - - `type: Literal["programmatic_tool_calling"]` +### Returns - The type of the tool. Always `programmatic_tool_calling`. +- `class ThreadDeleted: …` - - `"programmatic_tool_calling"` + - `id: str` - - `class ImageGeneration: …` + - `deleted: bool` - A tool that generates images using the GPT image models. + - `object: Literal["thread.deleted"]` - - `type: Literal["image_generation"]` + - `"thread.deleted"` - The type of the image generation tool. Always `image_generation`. +### Example - - `"image_generation"` +```python +import os +from openai import OpenAI - - `action: Optional[Literal["generate", "edit", "auto"]]` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +thread_deleted = client.beta.threads.delete( + "thread_id", +) +print(thread_deleted.id) +``` - Whether to generate a new image or edit an existing image. Default: `auto`. +#### Response - - `"generate"` +```json +{ + "id": "id", + "deleted": true, + "object": "thread.deleted" +} +``` - - `"edit"` +### Example - - `"auto"` +```python +from openai import OpenAI +client = OpenAI() - - `background: Optional[Literal["transparent", "opaque", "auto"]]` +response = client.beta.threads.delete("thread_abc123") +print(response) +``` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. +#### Response - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. +```json +{ + "id": "thread_abc123", + "object": "thread.deleted", + "deleted": true +} +``` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. +## Domain Types - - `"transparent"` +### Assistant Response Format Option - - `"opaque"` +- `AssistantResponseFormatOption` - - `"auto"` + 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`. - - `input_fidelity: Optional[Literal["high", "low"]]` + 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). - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"high"` + **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. - - `"low"` + - `Literal["auto"]` - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + `auto` is the default value - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"auto"` - - `file_id: Optional[str]` + - `class ResponseFormatText: …` - File ID for the mask image. + Default response format. Used to generate text responses. - - `image_url: Optional[str]` + - `type: Literal["text"]` - Base64-encoded mask image. + The type of response format being defined. Always `text`. - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + - `"text"` - The image generation model to use. Default: `gpt-image-1`. + - `class ResponseFormatJSONObject: …` - - `str` + 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. - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + - `type: Literal["json_object"]` - The image generation model to use. Default: `gpt-image-1`. + The type of response format being defined. Always `json_object`. - - `"gpt-image-1"` + - `"json_object"` - - `"gpt-image-1-mini"` + - `class ResponseFormatJSONSchema: …` - - `"gpt-image-2"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `"gpt-image-2-2026-04-21"` + - `json_schema: JSONSchema` - - `"gpt-image-1.5"` + Structured Outputs configuration options, including a JSON Schema. - - `"chatgpt-image-latest"` + - `name: str` - - `moderation: Optional[Literal["auto", "low"]]` + 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. - Moderation level for the generated image. Default: `auto`. + - `description: Optional[str]` - - `"auto"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"low"` + - `schema: Optional[Dict[str, object]]` - - `output_compression: Optional[int]` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Compression level for the output image. Default: 100. + - `strict: Optional[bool]` - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` + 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). - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `type: Literal["json_schema"]` - - `"png"` + The type of response format being defined. Always `json_schema`. - - `"webp"` + - `"json_schema"` - - `"jpeg"` +### Assistant Tool Choice - - `partial_images: Optional[int]` +- `class AssistantToolChoice: …` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + - `type: Literal["function", "code_interpreter", "file_search"]` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The type of the tool. If type is `function`, the function name must be set - - `"low"` + - `"function"` - - `"medium"` + - `"code_interpreter"` - - `"high"` + - `"file_search"` - - `"auto"` + - `function: Optional[AssistantToolChoiceFunction]` - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + - `name: str` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The name of the function to call. - - `str` +### Assistant Tool Choice Function - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` +- `class AssistantToolChoiceFunction: …` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `name: str` - - `"1024x1024"` + The name of the function to call. - - `"1024x1536"` +### Assistant Tool Choice Option - - `"1536x1024"` +- `AssistantToolChoiceOption` - - `"auto"` + 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. - - `class LocalShell: …` + - `Literal["none", "auto", "required"]` - A tool that allows the model to execute shell commands in a local environment. + `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. - - `type: Literal["local_shell"]` + - `"none"` - The type of the local shell tool. Always `local_shell`. + - `"auto"` - - `"local_shell"` + - `"required"` - - `class BetaFunctionShellTool: …` + - `class AssistantToolChoice: …` - A tool that allows the model to execute shell commands. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `type: Literal["shell"]` + - `type: Literal["function", "code_interpreter", "file_search"]` - The type of the shell tool. Always `shell`. + The type of the tool. If type is `function`, the function name must be set - - `"shell"` + - `"function"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"code_interpreter"` - The tool invocation context(s). + - `"file_search"` - - `"direct"` + - `function: Optional[AssistantToolChoiceFunction]` - - `"programmatic"` + - `name: str` - - `environment: Optional[Environment]` + The name of the function to call. - - `class BetaContainerAuto: …` +### Thread - - `type: Literal["container_auto"]` +- `class Thread: …` - Automatically creates a container for this request + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `"container_auto"` + - `id: str` - - `file_ids: Optional[List[str]]` + The identifier, which can be referenced in API endpoints. - An optional list of uploaded files to make available to your code. + - `created_at: int` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + The Unix timestamp (in seconds) for when the thread was created. - The memory limit for the container. + - `metadata: Optional[Metadata]` - - `"1g"` + 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. - - `"4g"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"16g"` + - `object: Literal["thread"]` - - `"64g"` + The object type, which is always `thread`. - - `network_policy: Optional[NetworkPolicy]` + - `"thread"` - Network access policy for the container. + - `tool_resources: Optional[ToolResources]` - - `class BetaContainerNetworkPolicyDisabled: …` + 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. - - `class BetaContainerNetworkPolicyAllowlist: …` + - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - `skills: Optional[List[Skill]]` + - `file_ids: Optional[List[str]]` - An optional list of skills referenced by id or inline data. + 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. - - `class BetaSkillReference: …` + - `file_search: Optional[ToolResourcesFileSearch]` - - `skill_id: str` + - `vector_store_ids: Optional[List[str]]` - The ID of the referenced skill. + 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. - - `type: Literal["skill_reference"]` +### Thread Deleted - References a skill created with the /v1/skills endpoint. +- `class ThreadDeleted: …` - - `"skill_reference"` + - `id: str` - - `version: Optional[str]` + - `deleted: bool` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `object: Literal["thread.deleted"]` - - `class BetaInlineSkill: …` + - `"thread.deleted"` - - `description: str` +# Runs - The description of the skill. +## List runs - - `name: str` +`beta.threads.runs.list(strthread_id, RunListParams**kwargs) -> SyncCursorPage[Run]` - The name of the skill. +**get** `/threads/{thread_id}/runs` - - `source: BetaInlineSkillSource` +Returns a list of runs belonging to a thread. - Inline skill payload +### Parameters - - `data: str` +- `thread_id: str` - Base64-encoded skill zip bundle. +- `after: Optional[str]` - - `media_type: Literal["application/zip"]` + 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. - The media type of the inline skill payload. Must be `application/zip`. +- `before: Optional[str]` - - `"application/zip"` + 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. - - `type: Literal["base64"]` +- `limit: Optional[int]` - The type of the inline skill source. Must be `base64`. + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `"base64"` +- `order: Optional[Literal["asc", "desc"]]` - - `type: Literal["inline"]` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - Defines an inline skill for this request. + - `"asc"` - - `"inline"` + - `"desc"` - - `class BetaLocalEnvironment: …` +### Returns - - `type: Literal["local"]` +- `class Run: …` - Use a local computer environment. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"local"` + - `id: str` - - `skills: Optional[List[BetaLocalSkill]]` + The identifier, which can be referenced in API endpoints. - An optional list of skills. + - `assistant_id: str` - - `description: str` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The description of the skill. + - `cancelled_at: Optional[int]` - - `name: str` + The Unix timestamp (in seconds) for when the run was cancelled. - The name of the skill. + - `completed_at: Optional[int]` - - `path: str` + The Unix timestamp (in seconds) for when the run was completed. - The path to the directory containing the skill. + - `created_at: int` - - `class BetaContainerReference: …` + The Unix timestamp (in seconds) for when the run was created. - - `container_id: str` + - `expires_at: Optional[int]` - The ID of the referenced container. + The Unix timestamp (in seconds) for when the run will expire. - - `type: Literal["container_reference"]` + - `failed_at: Optional[int]` - References a container created with the /v1/containers endpoint + The Unix timestamp (in seconds) for when the run failed. - - `"container_reference"` + - `incomplete_details: Optional[IncompleteDetails]` - - `class BetaCustomTool: …` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` - - `name: str` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The name of the custom tool, used to identify it in tool calls. + - `"max_completion_tokens"` - - `type: Literal["custom"]` + - `"max_prompt_tokens"` - The type of the custom tool. Always `custom`. + - `instructions: str` - - `"custom"` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `last_error: Optional[LastError]` - The tool invocation context(s). + The last error associated with this run. Will be `null` if there are no errors. - - `"direct"` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` - - `"programmatic"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `defer_loading: Optional[bool]` + - `"server_error"` - Whether this tool should be deferred and discovered via tool search. + - `"rate_limit_exceeded"` - - `description: Optional[str]` + - `"invalid_prompt"` - Optional description of the custom tool, used to provide more context. + - `message: str` - - `format: Optional[Format]` + A human-readable description of the error. - The input format for the custom tool. Default is unconstrained text. + - `max_completion_tokens: Optional[int]` - - `class FormatText: …` + The maximum number of completion tokens specified to have been used over the course of the run. - Unconstrained free-form text. + - `max_prompt_tokens: Optional[int]` - - `type: Literal["text"]` + The maximum number of prompt tokens specified to have been used over the course of the run. - Unconstrained text format. Always `text`. + - `metadata: Optional[Metadata]` - - `"text"` + 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. - - `class FormatGrammar: …` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A grammar defined by the user. + - `model: str` - - `definition: str` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The grammar definition. + - `object: Literal["thread.run"]` - - `syntax: Literal["lark", "regex"]` + The object type, which is always `thread.run`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"thread.run"` - - `"lark"` + - `parallel_tool_calls: bool` - - `"regex"` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `type: Literal["grammar"]` + - `required_action: Optional[RequiredAction]` - Grammar format. Always `grammar`. + Details on the action required to continue the run. Will be `null` if no action is required. - - `"grammar"` + - `submit_tool_outputs: RequiredActionSubmitToolOutputs` - - `class BetaNamespaceTool: …` + Details on the tool outputs needed for this run to continue. - Groups function/custom tools under a shared namespace. + - `tool_calls: List[RequiredActionFunctionToolCall]` - - `description: str` + A list of the relevant tool calls. - A description of the namespace shown to the model. + - `id: str` - - `name: 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. - The namespace name used in tool calls (for example, `crm`). + - `function: Function` - - `tools: List[Tool]` + The function definition. - The function/custom tools available inside this namespace. + - `arguments: str` - - `class ToolFunction: …` + 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"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["submit_tool_outputs"]` - The tool invocation context(s). + For now, this is always `submit_tool_outputs`. - - `"direct"` + - `"submit_tool_outputs"` - - `"programmatic"` + - `response_format: Optional[AssistantResponseFormatOption]` - - `defer_loading: Optional[bool]` + 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`. - Whether this function should be deferred and discovered via tool search. + 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). - - `description: Optional[str]` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `output_schema: Optional[Dict[str, object]]` + **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. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `Literal["auto"]` - - `parameters: Optional[object]` + `auto` is the default value - - `strict: Optional[bool]` + - `"auto"` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class ResponseFormatText: …` - - `class BetaCustomTool: …` + Default response format. Used to generate text responses. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: Literal["text"]` - - `type: Literal["namespace"]` + The type of response format being defined. Always `text`. - The type of the tool. Always `namespace`. + - `"text"` - - `"namespace"` + - `class ResponseFormatJSONObject: …` - - `class BetaToolSearchTool: …` + 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. - Hosted or BYOT tool search configuration for deferred tools. + - `type: Literal["json_object"]` - - `type: Literal["tool_search"]` + The type of response format being defined. Always `json_object`. - The type of the tool. Always `tool_search`. + - `"json_object"` - - `"tool_search"` + - `class ResponseFormatJSONSchema: …` - - `description: Optional[str]` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - Description shown to the model for a client-executed tool search tool. + - `json_schema: JSONSchema` - - `execution: Optional[Literal["server", "client"]]` + Structured Outputs configuration options, including a JSON Schema. - Whether tool search is executed by the server or by the client. + - `name: str` - - `"server"` + 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. - - `"client"` + - `description: Optional[str]` - - `parameters: Optional[object]` + A description of what the response format is for, used by the model to + determine how to respond in the format. - Parameter schema for a client-executed tool search tool. + - `schema: Optional[Dict[str, object]]` - - `class BetaWebSearchPreviewTool: …` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `strict: Optional[bool]` - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + 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). - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `type: Literal["json_schema"]` - - `"web_search_preview"` + The type of response format being defined. Always `json_schema`. - - `"web_search_preview_2025_03_11"` + - `"json_schema"` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + - `started_at: Optional[int]` - - `"text"` + The Unix timestamp (in seconds) for when the run was started. - - `"image"` + - `status: RunStatus` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"queued"` - - `"low"` + - `"in_progress"` - - `"medium"` + - `"requires_action"` - - `"high"` + - `"cancelling"` - - `user_location: Optional[UserLocation]` + - `"cancelled"` - The user's location. + - `"failed"` - - `type: Literal["approximate"]` + - `"completed"` - The type of location approximation. Always `approximate`. + - `"incomplete"` - - `"approximate"` + - `"expired"` - - `city: Optional[str]` + - `thread_id: str` - Free text input for the city of the user, e.g. `San Francisco`. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `country: Optional[str]` + - `tool_choice: Optional[AssistantToolChoiceOption]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + 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. - - `region: Optional[str]` + - `Literal["none", "auto", "required"]` - Free text input for the region of the user, e.g. `California`. + `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. - - `timezone: Optional[str]` + - `"none"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"auto"` - - `class BetaApplyPatchTool: …` + - `"required"` - Allows the assistant to create, delete, or update files using unified diffs. + - `class AssistantToolChoice: …` - - `type: Literal["apply_patch"]` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The type of the tool. Always `apply_patch`. + - `type: Literal["function", "code_interpreter", "file_search"]` - - `"apply_patch"` + The type of the tool. If type is `function`, the function name must be set - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"function"` - The tool invocation context(s). + - `"code_interpreter"` - - `"direct"` + - `"file_search"` - - `"programmatic"` + - `function: Optional[AssistantToolChoiceFunction]` - - `type: Literal["tool_search_output"]` + - `name: str` - The type of the item. Always `tool_search_output`. + The name of the function to call. - - `"tool_search_output"` + - `tools: List[AssistantTool]` - - `agent: Optional[Agent]` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The agent that produced this item. + - `class CodeInterpreterTool: …` - - `agent_name: str` + - `type: Literal["code_interpreter"]` - The canonical name of the agent that produced this item. + The type of tool being defined: `code_interpreter` - - `created_by: Optional[str]` + - `"code_interpreter"` - The identifier of the actor that created the item. + - `class FileSearchTool: …` - - `class AdditionalTools: …` + - `type: Literal["file_search"]` - - `id: str` + The type of tool being defined: `file_search` - The unique ID of the additional tools item. + - `"file_search"` - - `role: Literal["unknown", "user", "assistant", 5 more]` + - `file_search: Optional[FileSearch]` - The role that provided the additional tools. + Overrides for the file search tool. - - `"unknown"` + - `max_num_results: Optional[int]` - - `"user"` + 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. - - `"assistant"` + 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. - - `"system"` + - `ranking_options: Optional[FileSearchRankingOptions]` - - `"critic"` + 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. - - `"discriminator"` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"developer"` + - `score_threshold: float` - - `"tool"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `tools: List[BetaTool]` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - The additional tool definitions made available at this item. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `class BetaFunctionTool: …` + - `"auto"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `"default_2024_08_21"` - - `class BetaFileSearchTool: …` + - `class FunctionTool: …` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `function: FunctionDefinition` - - `class BetaComputerTool: …` + - `name: str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + 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. - - `class BetaComputerUsePreviewTool: …` + - `description: Optional[str]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A description of what the function does, used by the model to choose when and how to call the function. - - `class BetaWebSearchTool: …` + - `parameters: Optional[FunctionParameters]` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + 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. - - `class Mcp: …` + Omitting `parameters` defines a function with an empty parameter list. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `strict: Optional[bool]` - - `class CodeInterpreter: …` + 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). - A tool that runs Python code to help generate a response to a prompt. + - `type: Literal["function"]` - - `class ProgrammaticToolCalling: …` + The type of tool being defined: `function` - - `class ImageGeneration: …` + - `"function"` - A tool that generates images using the GPT image models. + - `truncation_strategy: Optional[TruncationStrategy]` - - `class LocalShell: …` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - A tool that allows the model to execute shell commands in a local environment. + - `type: Literal["auto", "last_messages"]` - - `class BetaFunctionShellTool: …` + 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`. - A tool that allows the model to execute shell commands. + - `"auto"` - - `class BetaCustomTool: …` + - `"last_messages"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `last_messages: Optional[int]` - - `class BetaNamespaceTool: …` + The number of most recent messages from the thread when constructing the context for the run. - Groups function/custom tools under a shared namespace. + - `usage: Optional[Usage]` - - `class BetaToolSearchTool: …` + 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.). - Hosted or BYOT tool search configuration for deferred tools. + - `completion_tokens: int` - - `class BetaWebSearchPreviewTool: …` + Number of completion tokens used over the course of the run. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `prompt_tokens: int` - - `class BetaApplyPatchTool: …` + Number of prompt tokens used over the course of the run. - Allows the assistant to create, delete, or update files using unified diffs. + - `total_tokens: int` - - `type: Literal["additional_tools"]` + Total number of tokens used (prompt + completion). - The type of the item. Always `additional_tools`. + - `temperature: Optional[float]` - - `"additional_tools"` + The sampling temperature used for this run. If not set, defaults to 1. - - `agent: Optional[AdditionalToolsAgent]` + - `top_p: Optional[float]` - The agent that produced this item. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `agent_name: str` +### Example - The canonical name of the agent that produced this item. +```python +import os +from openai import OpenAI - - `class BetaResponseReasoningItem: …` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +page = client.beta.threads.runs.list( + thread_id="thread_id", +) +page = page.data[0] +print(page.id) +``` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). +#### Response - - `id: str` +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 + } + ], + "first_id": "run_abc123", + "has_more": false, + "last_id": "run_abc456", + "object": "list" +} +``` - The unique identifier of the reasoning content. +### Example - - `summary: List[Summary]` +```python +from openai import OpenAI +client = OpenAI() - Reasoning summary content. +runs = client.beta.threads.runs.list( + "thread_abc123" +) - - `text: str` +print(runs) +``` - A summary of the reasoning output from the model so far. +#### Response - - `type: Literal["summary_text"]` +```json +{ + "object": "list", + "data": [ + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] + } + }, + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + }, + { + "id": "run_abc456", + "object": "thread.run", + "created_at": 1699063290, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699063290, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699063291, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] + } + }, + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + ], + "first_id": "run_abc123", + "last_id": "run_abc456", + "has_more": false +} +``` - The type of the object. Always `summary_text`. +## Create run - - `"summary_text"` +`beta.threads.runs.create(strthread_id, RunCreateParams**kwargs) -> Run` - - `type: Literal["reasoning"]` +**post** `/threads/{thread_id}/runs` - The type of the object. Always `reasoning`. +Create a run. - - `"reasoning"` +### Parameters - - `agent: Optional[Agent]` +- `thread_id: str` - The agent that produced this item. +- `assistant_id: str` - - `agent_name: str` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. - The canonical name of the agent that produced this item. +- `include: Optional[List[RunStepInclude]]` - - `content: Optional[List[Content]]` + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - Reasoning text content. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `text: str` + - `"step_details.tool_calls[*].file_search.results[*].content"` - The reasoning text from the model. +- `additional_instructions: Optional[str]` - - `type: Literal["reasoning_text"]` + Appends additional instructions at the end of the instructions for the run. This is useful for modifying the behavior on a per-run basis without overriding other instructions. - The type of the reasoning text. Always `reasoning_text`. +- `additional_messages: Optional[Iterable[AdditionalMessage]]` - - `"reasoning_text"` + Adds additional messages to the thread before creating the run. - - `encrypted_content: Optional[str]` + - `content: Union[str, Iterable[MessageContentPartParam]]` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The text contents of the message. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `str` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The text contents of the message. - - `"in_progress"` + - `Iterable[MessageContentPartParam]` - - `"completed"` + An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](https://platform.openai.com/docs/models). - - `"incomplete"` + - `class ImageFileContentBlock: …` - - `class Program: …` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `id: str` + - `image_file: ImageFile` - The unique ID of the program item. + - `file_id: str` - - `call_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. - The stable call ID of the program item. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `code: str` + 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`. - The JavaScript source executed by programmatic tool calling. + - `"auto"` - - `fingerprint: str` + - `"low"` - Opaque program replay fingerprint that must be round-tripped. + - `"high"` - - `type: Literal["program"]` + - `type: Literal["image_file"]` - The type of the item. Always `program`. + Always `image_file`. - - `"program"` + - `"image_file"` - - `agent: Optional[ProgramAgent]` + - `class ImageURLContentBlock: …` - The agent that produced this item. + References an image URL in the content of a message. - - `agent_name: str` + - `image_url: ImageURL` - The canonical name of the agent that produced this item. + - `url: str` - - `class ProgramOutput: …` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `id: str` + - `detail: Optional[Literal["auto", "low", "high"]]` - The unique ID of the program output item. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `call_id: str` + - `"auto"` - The call ID of the program item. + - `"low"` - - `result: str` + - `"high"` - The result produced by the program item. + - `type: Literal["image_url"]` - - `status: Literal["completed", "incomplete"]` + The type of the content part. - The terminal status of the program output item. + - `"image_url"` - - `"completed"` + - `class TextContentBlockParam: …` - - `"incomplete"` + The text content that is part of a message. - - `type: Literal["program_output"]` + - `text: str` - The type of the item. Always `program_output`. + Text content to be sent to the model - - `"program_output"` + - `type: Literal["text"]` - - `agent: Optional[ProgramOutputAgent]` + Always `text`. - The agent that produced this item. + - `"text"` - - `agent_name: str` + - `role: Literal["user", "assistant"]` - The canonical name of the agent that produced this item. + The role of the entity that is creating the message. Allowed values include: - - `class BetaResponseCompactionItem: …` + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"user"` - - `id: str` + - `"assistant"` - The unique ID of the compaction item. + - `attachments: Optional[Iterable[AdditionalMessageAttachment]]` - - `encrypted_content: str` + A list of files attached to the message, and the tools they should be added to. - The encrypted content that was produced by compaction. + - `file_id: Optional[str]` - - `type: Literal["compaction"]` + The ID of the file to attach to the message. - The type of the item. Always `compaction`. + - `tools: Optional[Iterable[AdditionalMessageAttachmentTool]]` - - `"compaction"` + The tools to add this file to. - - `agent: Optional[Agent]` + - `class CodeInterpreterTool: …` - The agent that produced this item. + - `type: Literal["code_interpreter"]` - - `agent_name: str` + The type of tool being defined: `code_interpreter` - The canonical name of the agent that produced this item. + - `"code_interpreter"` - - `created_by: Optional[str]` + - `class AdditionalMessageAttachmentToolFileSearch: …` - The identifier of the actor that created the item. + - `type: Literal["file_search"]` - - `class ImageGenerationCall: …` + The type of tool being defined: `file_search` - An image generation request made by the model. + - `"file_search"` - - `id: str` + - `metadata: Optional[Metadata]` - The unique ID of the image generation call. + 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. - - `result: Optional[str]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The generated image encoded in base64. +- `instructions: Optional[str]` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + Overrides the [instructions](https://platform.openai.com/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis. - The status of the image generation call. +- `max_completion_tokens: Optional[int]` - - `"in_progress"` + The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - - `"completed"` +- `max_prompt_tokens: Optional[int]` - - `"generating"` + The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - - `"failed"` +- `metadata: Optional[Metadata]` - - `type: Literal["image_generation_call"]` + 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. - The type of the image generation call. Always `image_generation_call`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"image_generation_call"` +- `model: Optional[Union[str, ChatModel, null]]` - - `agent: Optional[ImageGenerationCallAgent]` + The ID of the [Model](https://platform.openai.com/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. - The agent that produced this item. + - `str` - - `agent_name: str` + - `Literal["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", 78 more]` - The canonical name of the agent that produced this item. + - `"gpt-5.6-sol"` - - `class BetaResponseCodeInterpreterToolCall: …` + - `"gpt-5.6-terra"` - A tool call to run code. + - `"gpt-5.6-luna"` - - `id: str` + - `"gpt-5.4"` - The unique ID of the code interpreter tool call. + - `"gpt-5.4-mini"` - - `code: Optional[str]` + - `"gpt-5.4-nano"` - The code to run, or null if not available. + - `"gpt-5.4-mini-2026-03-17"` - - `container_id: str` + - `"gpt-5.4-nano-2026-03-17"` - The ID of the container used to run the code. + - `"gpt-5.3-chat-latest"` - - `outputs: Optional[List[Output]]` + - `"gpt-5.2"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"gpt-5.2-2025-12-11"` - - `class OutputLogs: …` + - `"gpt-5.2-chat-latest"` - The logs output from the code interpreter. + - `"gpt-5.2-pro"` - - `logs: str` + - `"gpt-5.2-pro-2025-12-11"` - The logs output from the code interpreter. + - `"gpt-5.1"` - - `type: Literal["logs"]` + - `"gpt-5.1-2025-11-13"` - The type of the output. Always `logs`. + - `"gpt-5.1-codex"` - - `"logs"` + - `"gpt-5.1-mini"` - - `class OutputImage: …` + - `"gpt-5.1-chat-latest"` - The image output from the code interpreter. + - `"gpt-5"` - - `type: Literal["image"]` + - `"gpt-5-mini"` - The type of the output. Always `image`. + - `"gpt-5-nano"` - - `"image"` + - `"gpt-5-2025-08-07"` - - `url: str` + - `"gpt-5-mini-2025-08-07"` - The URL of the image output from the code interpreter. + - `"gpt-5-nano-2025-08-07"` - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + - `"gpt-5-chat-latest"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"gpt-4.1"` - - `"in_progress"` + - `"gpt-4.1-mini"` - - `"completed"` + - `"gpt-4.1-nano"` - - `"incomplete"` + - `"gpt-4.1-2025-04-14"` - - `"interpreting"` + - `"gpt-4.1-mini-2025-04-14"` - - `"failed"` + - `"gpt-4.1-nano-2025-04-14"` - - `type: Literal["code_interpreter_call"]` + - `"o4-mini"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `"o4-mini-2025-04-16"` - - `"code_interpreter_call"` + - `"o3"` - - `agent: Optional[Agent]` + - `"o3-2025-04-16"` - The agent that produced this item. + - `"o3-mini"` - - `agent_name: str` + - `"o3-mini-2025-01-31"` - The canonical name of the agent that produced this item. + - `"o1"` - - `class LocalShellCall: …` + - `"o1-2024-12-17"` - A tool call to run a command on the local shell. + - `"o1-preview"` - - `id: str` + - `"o1-preview-2024-09-12"` - The unique ID of the local shell call. + - `"o1-mini"` - - `action: LocalShellCallAction` + - `"o1-mini-2024-09-12"` - Execute a shell command on the server. + - `"gpt-4o"` - - `command: List[str]` + - `"gpt-4o-2024-11-20"` - The command to run. + - `"gpt-4o-2024-08-06"` - - `env: Dict[str, str]` + - `"gpt-4o-2024-05-13"` - Environment variables to set for the command. + - `"gpt-4o-audio-preview"` - - `type: Literal["exec"]` + - `"gpt-4o-audio-preview-2024-10-01"` - The type of the local shell action. Always `exec`. + - `"gpt-4o-audio-preview-2024-12-17"` - - `"exec"` + - `"gpt-4o-audio-preview-2025-06-03"` - - `timeout_ms: Optional[int]` + - `"gpt-4o-mini-audio-preview"` - Optional timeout in milliseconds for the command. + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `user: Optional[str]` + - `"gpt-4o-search-preview"` - Optional user to run the command as. + - `"gpt-4o-mini-search-preview"` - - `working_directory: Optional[str]` + - `"gpt-4o-search-preview-2025-03-11"` - Optional working directory to run the command in. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `call_id: str` + - `"chatgpt-4o-latest"` - The unique ID of the local shell tool call generated by the model. + - `"codex-mini-latest"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"gpt-4o-mini"` - The status of the local shell call. + - `"gpt-4o-mini-2024-07-18"` - - `"in_progress"` + - `"gpt-4-turbo"` - - `"completed"` + - `"gpt-4-turbo-2024-04-09"` - - `"incomplete"` + - `"gpt-4-0125-preview"` - - `type: Literal["local_shell_call"]` + - `"gpt-4-turbo-preview"` - The type of the local shell call. Always `local_shell_call`. + - `"gpt-4-1106-preview"` - - `"local_shell_call"` + - `"gpt-4-vision-preview"` - - `agent: Optional[LocalShellCallAgent]` + - `"gpt-4"` - The agent that produced this item. + - `"gpt-4-0314"` - - `agent_name: str` + - `"gpt-4-0613"` - The canonical name of the agent that produced this item. + - `"gpt-4-32k"` - - `class LocalShellCallOutput: …` + - `"gpt-4-32k-0314"` - The output of a local shell tool call. + - `"gpt-4-32k-0613"` - - `id: str` + - `"gpt-3.5-turbo"` - The unique ID of the local shell tool call generated by the model. + - `"gpt-3.5-turbo-16k"` - - `output: str` + - `"gpt-3.5-turbo-0301"` - A JSON string of the output of the local shell tool call. + - `"gpt-3.5-turbo-0613"` - - `type: Literal["local_shell_call_output"]` + - `"gpt-3.5-turbo-1106"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `"gpt-3.5-turbo-0125"` - - `"local_shell_call_output"` + - `"gpt-3.5-turbo-16k-0613"` - - `agent: Optional[LocalShellCallOutputAgent]` +- `parallel_tool_calls: Optional[bool]` - The agent that produced this item. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `agent_name: str` +- `reasoning_effort: Optional[ReasoningEffort]` - The canonical name of the agent that produced this item. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"none"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"minimal"` - - `"in_progress"` + - `"low"` - - `"completed"` + - `"medium"` - - `"incomplete"` + - `"high"` - - `class BetaResponseFunctionShellToolCall: …` + - `"xhigh"` - A tool call that executes one or more shell commands in a managed environment. + - `"max"` - - `id: str` +- `response_format: Optional[AssistantResponseFormatOptionParam]` - The unique ID of the shell tool call. Populated when this item is returned via API. + 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`. - - `action: Action` + 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). - The shell commands and limits that describe how to run the tool call. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `commands: List[str]` + **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. - - `max_output_length: Optional[int]` + - `Literal["auto"]` - Optional maximum number of characters to return from each command. + `auto` is the default value - - `timeout_ms: Optional[int]` + - `"auto"` - Optional timeout in milliseconds for the commands. + - `class ResponseFormatText: …` - - `call_id: str` + Default response format. Used to generate text responses. - The unique ID of the shell tool call generated by the model. + - `type: Literal["text"]` - - `environment: Optional[Environment]` + The type of response format being defined. Always `text`. - Represents the use of a local environment to perform shell actions. + - `"text"` - - `class BetaResponseLocalEnvironment: …` + - `class ResponseFormatJSONObject: …` - Represents the use of a local environment to perform shell actions. + 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["local"]` + - `type: Literal["json_object"]` - The environment type. Always `local`. + The type of response format being defined. Always `json_object`. - - `"local"` + - `"json_object"` - - `class BetaResponseContainerReference: …` + - `class ResponseFormatJSONSchema: …` - Represents a container created with /v1/containers. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `container_id: str` + - `json_schema: JSONSchema` - - `type: Literal["container_reference"]` + Structured Outputs configuration options, including a JSON Schema. - The environment type. Always `container_reference`. + - `name: str` - - `"container_reference"` + 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. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `description: Optional[str]` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"in_progress"` + - `schema: Optional[Dict[str, object]]` - - `"completed"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"incomplete"` + - `strict: Optional[bool]` - - `type: Literal["shell_call"]` + 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). - The type of the item. Always `shell_call`. + - `type: Literal["json_schema"]` - - `"shell_call"` + The type of response format being defined. Always `json_schema`. - - `agent: Optional[Agent]` + - `"json_schema"` - The agent that produced this item. +- `stream: Optional[Literal[false]]` - - `agent_name: str` + If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. - The canonical name of the agent that produced this item. + - `false` - - `caller: Optional[Caller]` +- `temperature: Optional[float]` - The execution context that produced this tool call. + 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. - - `class CallerDirect: …` +- `tool_choice: Optional[AssistantToolChoiceOptionParam]` - - `type: Literal["direct"]` + 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. - - `"direct"` + - `Literal["none", "auto", "required"]` - - `class CallerProgram: …` + `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. - - `caller_id: str` + - `"none"` - The call ID of the program item that produced this tool call. + - `"auto"` - - `type: Literal["program"]` + - `"required"` - - `"program"` + - `class AssistantToolChoice: …` - - `created_by: Optional[str]` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The ID of the entity that created this tool call. + - `type: Literal["function", "code_interpreter", "file_search"]` - - `class BetaResponseFunctionShellToolCallOutput: …` + The type of the tool. If type is `function`, the function name must be set - The output of a shell tool call that was emitted. + - `"function"` - - `id: str` + - `"code_interpreter"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `"file_search"` - - `call_id: str` + - `function: Optional[AssistantToolChoiceFunction]` - The unique ID of the shell tool call generated by the model. + - `name: str` - - `max_output_length: Optional[int]` + The name of the function to call. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. +- `tools: Optional[Iterable[AssistantToolParam]]` - - `output: List[Output]` + Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - An array of shell call output contents + - `class CodeInterpreterTool: …` - - `outcome: OutputOutcome` + - `class FileSearchTool: …` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `type: Literal["file_search"]` - - `class OutputOutcomeTimeout: …` + The type of tool being defined: `file_search` - Indicates that the shell call exceeded its configured time limit. + - `"file_search"` - - `type: Literal["timeout"]` + - `file_search: Optional[FileSearch]` - The outcome type. Always `timeout`. + Overrides for the file search tool. - - `"timeout"` + - `max_num_results: Optional[int]` - - `class OutputOutcomeExit: …` + 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. - Indicates that the shell commands finished and returned an exit code. + 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. - - `exit_code: int` + - `ranking_options: Optional[FileSearchRankingOptions]` - Exit code from the shell process. + 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. - - `type: Literal["exit"]` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The outcome type. Always `exit`. + - `score_threshold: float` - - `"exit"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `stderr: str` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - The standard error output that was captured. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `stdout: str` + - `"auto"` - The standard output that was captured. + - `"default_2024_08_21"` - - `created_by: Optional[str]` + - `class FunctionTool: …` - The identifier of the actor that created the item. + - `function: FunctionDefinition` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `name: str` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + 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. - - `"in_progress"` + - `description: Optional[str]` - - `"completed"` + A description of what the function does, used by the model to choose when and how to call the function. - - `"incomplete"` + - `parameters: Optional[FunctionParameters]` - - `type: Literal["shell_call_output"]` + 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. - The type of the shell call output. Always `shell_call_output`. + Omitting `parameters` defines a function with an empty parameter list. - - `"shell_call_output"` + - `strict: Optional[bool]` - - `agent: Optional[Agent]` + 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). - The agent that produced this item. + - `type: Literal["function"]` - - `agent_name: str` + The type of tool being defined: `function` - The canonical name of the agent that produced this item. + - `"function"` - - `caller: Optional[Caller]` +- `top_p: Optional[float]` - The execution context that produced this tool call. + 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. - - `class CallerDirect: …` + We generally recommend altering this or temperature but not both. - - `type: Literal["direct"]` +- `truncation_strategy: Optional[TruncationStrategy]` - - `"direct"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `class CallerProgram: …` + - `type: Literal["auto", "last_messages"]` - - `caller_id: str` + 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`. - The call ID of the program item that produced this tool call. + - `"auto"` - - `type: Literal["program"]` + - `"last_messages"` - - `"program"` + - `last_messages: Optional[int]` - - `created_by: Optional[str]` + The number of most recent messages from the thread when constructing the context for the run. - The identifier of the actor that created the item. +### Returns - - `class BetaResponseApplyPatchToolCall: …` +- `class Run: …` - A tool call that applies file diffs by creating, deleting, or updating files. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - `id: str` - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `call_id: str` - - The unique ID of the apply patch tool call generated by the model. - - - `operation: Operation` - - One of the create_file, delete_file, or update_file operations applied via apply_patch. - - - `class OperationCreateFile: …` + The identifier, which can be referenced in API endpoints. - Instruction describing how to create a file via the apply_patch tool. + - `assistant_id: str` - - `diff: str` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - Diff to apply. + - `cancelled_at: Optional[int]` - - `path: str` + The Unix timestamp (in seconds) for when the run was cancelled. - Path of the file to create. + - `completed_at: Optional[int]` - - `type: Literal["create_file"]` + The Unix timestamp (in seconds) for when the run was completed. - Create a new file with the provided diff. + - `created_at: int` - - `"create_file"` + The Unix timestamp (in seconds) for when the run was created. - - `class OperationDeleteFile: …` + - `expires_at: Optional[int]` - Instruction describing how to delete a file via the apply_patch tool. + The Unix timestamp (in seconds) for when the run will expire. - - `path: str` + - `failed_at: Optional[int]` - Path of the file to delete. + The Unix timestamp (in seconds) for when the run failed. - - `type: Literal["delete_file"]` + - `incomplete_details: Optional[IncompleteDetails]` - Delete the specified file. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `"delete_file"` + - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` - - `class OperationUpdateFile: …` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - Instruction describing how to update a file via the apply_patch tool. + - `"max_completion_tokens"` - - `diff: str` + - `"max_prompt_tokens"` - Diff to apply. + - `instructions: str` - - `path: str` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Path of the file to update. + - `last_error: Optional[LastError]` - - `type: Literal["update_file"]` + The last error associated with this run. Will be `null` if there are no errors. - Update an existing file with the provided diff. + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` - - `"update_file"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `status: Literal["in_progress", "completed"]` + - `"server_error"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"rate_limit_exceeded"` - - `"in_progress"` + - `"invalid_prompt"` - - `"completed"` + - `message: str` - - `type: Literal["apply_patch_call"]` + A human-readable description of the error. - The type of the item. Always `apply_patch_call`. + - `max_completion_tokens: Optional[int]` - - `"apply_patch_call"` + The maximum number of completion tokens specified to have been used over the course of the run. - - `agent: Optional[Agent]` + - `max_prompt_tokens: Optional[int]` - The agent that produced this item. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `agent_name: str` + - `metadata: Optional[Metadata]` - The canonical name of the agent that produced this item. + 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. - - `caller: Optional[Caller]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The execution context that produced this tool call. + - `model: str` - - `class CallerDirect: …` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `type: Literal["direct"]` + - `object: Literal["thread.run"]` - - `"direct"` + The object type, which is always `thread.run`. - - `class CallerProgram: …` + - `"thread.run"` - - `caller_id: str` + - `parallel_tool_calls: bool` - The call ID of the program item that produced this tool call. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `type: Literal["program"]` + - `required_action: Optional[RequiredAction]` - - `"program"` + Details on the action required to continue the run. Will be `null` if no action is required. - - `created_by: Optional[str]` + - `submit_tool_outputs: RequiredActionSubmitToolOutputs` - The ID of the entity that created this tool call. + Details on the tool outputs needed for this run to continue. - - `class BetaResponseApplyPatchToolCallOutput: …` + - `tool_calls: List[RequiredActionFunctionToolCall]` - The output emitted by an apply patch tool call. + A list of the relevant tool calls. - `id: str` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - - `call_id: str` - - The unique ID of the apply patch tool call generated by the model. - - - `status: Literal["completed", "failed"]` + 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. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `function: Function` - - `"completed"` + The function definition. - - `"failed"` + - `arguments: str` - - `type: Literal["apply_patch_call_output"]` + The arguments that the model expects you to pass to the function. - The type of the item. Always `apply_patch_call_output`. + - `name: str` - - `"apply_patch_call_output"` + The name of the function. - - `agent: Optional[Agent]` + - `type: Literal["function"]` - The agent that produced this item. + The type of tool call the output is required for. For now, this is always `function`. - - `agent_name: str` + - `"function"` - The canonical name of the agent that produced this item. + - `type: Literal["submit_tool_outputs"]` - - `caller: Optional[Caller]` + For now, this is always `submit_tool_outputs`. - The execution context that produced this tool call. + - `"submit_tool_outputs"` - - `class CallerDirect: …` + - `response_format: Optional[AssistantResponseFormatOption]` - - `type: Literal["direct"]` + 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`. - - `"direct"` + 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). - - `class CallerProgram: …` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `caller_id: str` + **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. - The call ID of the program item that produced this tool call. + - `Literal["auto"]` - - `type: Literal["program"]` + `auto` is the default value - - `"program"` + - `"auto"` - - `created_by: Optional[str]` + - `class ResponseFormatText: …` - The ID of the entity that created this tool call output. + Default response format. Used to generate text responses. - - `output: Optional[str]` + - `type: Literal["text"]` - Optional textual output returned by the apply patch tool. + The type of response format being defined. Always `text`. - - `class McpListTools: …` + - `"text"` - A list of tools available on an MCP server. + - `class ResponseFormatJSONObject: …` - - `id: str` + 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. - The unique ID of the list. + - `type: Literal["json_object"]` - - `server_label: str` + The type of response format being defined. Always `json_object`. - The label of the MCP server. + - `"json_object"` - - `tools: List[McpListToolsTool]` + - `class ResponseFormatJSONSchema: …` - The tools available on the server. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `input_schema: object` + - `json_schema: JSONSchema` - The JSON schema describing the tool's input. + Structured Outputs configuration options, including a JSON Schema. - `name: str` - The name of the tool. + 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. - - `annotations: Optional[object]` + - `description: Optional[str]` - Additional annotations about the tool. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `description: Optional[str]` + - `schema: Optional[Dict[str, object]]` - The description of the tool. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `type: Literal["mcp_list_tools"]` + - `strict: Optional[bool]` - The type of the item. Always `mcp_list_tools`. + 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). - - `"mcp_list_tools"` + - `type: Literal["json_schema"]` - - `agent: Optional[McpListToolsAgent]` + The type of response format being defined. Always `json_schema`. - The agent that produced this item. + - `"json_schema"` - - `agent_name: str` + - `started_at: Optional[int]` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run was started. - - `error: Optional[str]` + - `status: RunStatus` - Error message if the server could not list tools. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `class McpApprovalRequest: …` + - `"queued"` - A request for human approval of a tool invocation. + - `"in_progress"` - - `id: str` + - `"requires_action"` - The unique ID of the approval request. + - `"cancelling"` - - `arguments: str` + - `"cancelled"` - A JSON string of arguments for the tool. + - `"failed"` - - `name: str` + - `"completed"` - The name of the tool to run. + - `"incomplete"` - - `server_label: str` + - `"expired"` - The label of the MCP server making the request. + - `thread_id: str` - - `type: Literal["mcp_approval_request"]` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The type of the item. Always `mcp_approval_request`. + - `tool_choice: Optional[AssistantToolChoiceOption]` - - `"mcp_approval_request"` + 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. - - `agent: Optional[McpApprovalRequestAgent]` + - `Literal["none", "auto", "required"]` - The agent that produced this item. + `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. - - `agent_name: str` + - `"none"` - The canonical name of the agent that produced this item. + - `"auto"` - - `class McpApprovalResponse: …` + - `"required"` - A response to an MCP approval request. + - `class AssistantToolChoice: …` - - `id: str` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The unique ID of the approval response + - `type: Literal["function", "code_interpreter", "file_search"]` - - `approval_request_id: str` + The type of the tool. If type is `function`, the function name must be set - The ID of the approval request being answered. + - `"function"` - - `approve: bool` + - `"code_interpreter"` - Whether the request was approved. + - `"file_search"` - - `type: Literal["mcp_approval_response"]` + - `function: Optional[AssistantToolChoiceFunction]` - The type of the item. Always `mcp_approval_response`. + - `name: str` - - `"mcp_approval_response"` + The name of the function to call. - - `agent: Optional[McpApprovalResponseAgent]` + - `tools: List[AssistantTool]` - The agent that produced this item. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `agent_name: str` + - `class CodeInterpreterTool: …` - The canonical name of the agent that produced this item. + - `type: Literal["code_interpreter"]` - - `reason: Optional[str]` + The type of tool being defined: `code_interpreter` - Optional reason for the decision. + - `"code_interpreter"` - - `class McpCall: …` + - `class FileSearchTool: …` - An invocation of a tool on an MCP server. + - `type: Literal["file_search"]` - - `id: str` + The type of tool being defined: `file_search` - The unique ID of the tool call. + - `"file_search"` - - `arguments: str` + - `file_search: Optional[FileSearch]` - A JSON string of the arguments passed to the tool. + Overrides for the file search tool. - - `name: str` + - `max_num_results: Optional[int]` - The name of the tool that was run. + 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. - - `server_label: str` + 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. - The label of the MCP server running the tool. + - `ranking_options: Optional[FileSearchRankingOptions]` - - `type: Literal["mcp_call"]` + 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. - The type of the item. Always `mcp_call`. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"mcp_call"` + - `score_threshold: float` - - `agent: Optional[McpCallAgent]` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The agent that produced this item. + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - `agent_name: str` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The canonical name of the agent that produced this item. + - `"auto"` - - `approval_request_id: Optional[str]` + - `"default_2024_08_21"` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `class FunctionTool: …` - - `error: Optional[str]` + - `function: FunctionDefinition` - The error from the tool call, if any. + - `name: str` - - `output: Optional[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. - The output from the tool call. + - `description: Optional[str]` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + A description of what the function does, used by the model to choose when and how to call the function. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `parameters: Optional[FunctionParameters]` - - `"in_progress"` + 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. - - `"completed"` + Omitting `parameters` defines a function with an empty parameter list. - - `"incomplete"` + - `strict: Optional[bool]` - - `"calling"` + 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). - - `"failed"` + - `type: Literal["function"]` - - `class BetaResponseCustomToolCallItem: …` + The type of tool being defined: `function` - A call to a custom tool created by the model. + - `"function"` - - `id: str` + - `truncation_strategy: Optional[TruncationStrategy]` - The unique ID of the custom tool call item. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `type: Literal["auto", "last_messages"]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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`. - - `"in_progress"` + - `"auto"` - - `"completed"` + - `"last_messages"` - - `"incomplete"` + - `last_messages: Optional[int]` - - `created_by: Optional[str]` + The number of most recent messages from the thread when constructing the context for the run. - The identifier of the actor that created the item. + - `usage: Optional[Usage]` - - `class BetaResponseCustomToolCallOutputItem: …` + 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.). - The output of a custom tool call from your code, being sent back to the model. + - `completion_tokens: int` - - `id: str` + Number of completion tokens used over the course of the run. - The unique ID of the custom tool call output item. + - `prompt_tokens: int` - - `status: Literal["in_progress", "completed", "incomplete"]` + Number of prompt tokens used over the course of the run. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `total_tokens: int` - - `"in_progress"` + Total number of tokens used (prompt + completion). - - `"completed"` + - `temperature: Optional[float]` - - `"incomplete"` + The sampling temperature used for this run. If not set, defaults to 1. - - `created_by: Optional[str]` + - `top_p: Optional[float]` - The identifier of the actor that created the item. + The nucleus sampling value used for this run. If not set, defaults to 1. ### Example @@ -156313,41 +169142,76 @@ 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.responses.input_items.list( - response_id="response_id", -) -page = page.data[0] -print(page) +for run in client.beta.threads.runs.create( + thread_id="thread_id", + assistant_id="assistant_id", +): + print(run) ``` #### Response ```json { - "data": [ - { "id": "id", - "content": [ + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ { - "text": "text", - "type": "input_text", - "prompt_cache_breakpoint": { - "mode": "explicit" - } + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" } - ], - "role": "user", - "type": "message", - "agent": { - "agent_name": "agent_name" + ] }, - "status": "in_progress" + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" } ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 } ``` @@ -156357,7954 +169221,8861 @@ print(page) from openai import OpenAI client = OpenAI() -response = client.responses.input_items.list("resp_123") -print(response.data) +run = client.beta.threads.runs.create( + thread_id="thread_abc123", + assistant_id="asst_abc123" +) + +print(run) ``` #### Response ```json { - "object": "list", - "data": [ - { - "id": "msg_abc123", - "type": "message", - "role": "user", - "content": [ + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699063290, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "queued", + "started_at": 1699063290, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699063291, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ { - "type": "input_text", - "text": "Tell me a three sentence bedtime story about a unicorn." - } - ] + "type": "code_interpreter" } ], - "first_id": "msg_abc123", - "last_id": "msg_abc123", - "has_more": false + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true } ``` -## Domain Types - -### Beta Response Item List - -- `class BetaResponseItemList: …` - - A list of Response items. - - - `data: List[BetaResponseItem]` - - A list of items used to generate this response. - - - `class BetaResponseInputMessageItem: …` - - - `id: str` - - The unique ID of the message input. - - - `content: BetaResponseInputMessageContentList` - - A list of one or many input items to the model, containing different content - types. - - - `class BetaResponseInputText: …` - - A text input to the model. +### Streaming - - `text: str` +```python +from openai import OpenAI +client = OpenAI() - The text input to the model. +stream = client.beta.threads.runs.create( + thread_id="thread_123", + assistant_id="asst_123", + stream=True +) - - `type: Literal["input_text"]` +for event in stream: + print(event) +``` - The type of the input item. Always `input_text`. +#### Response - - `"input_text"` +```json +event: thread.run.created +data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` +event: thread.run.queued +data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. +event: thread.run.in_progress +data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710330641,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `mode: Literal["explicit"]` +event: thread.run.step.created +data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} - The breakpoint mode. Always `explicit`. +event: thread.run.step.in_progress +data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} - - `"explicit"` +event: thread.message.created +data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - - `class BetaResponseInputImage: …` +event: thread.message.in_progress +data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} - - `detail: Literal["low", "high", "auto", "original"]` +... - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} - - `"low"` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} - - `"high"` +event: thread.message.completed +data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710330642,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} - - `"auto"` +event: thread.run.step.completed +data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710330642,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} - - `"original"` +event: thread.run.completed +data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710330641,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710330642,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `type: Literal["input_image"]` +event: done +data: [DONE] +``` - The type of the input item. Always `input_image`. +### Streaming with Functions - - `"input_image"` +```python +from openai import OpenAI +client = OpenAI() - - `file_id: Optional[str]` +tools = [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, + }, + "required": ["location"], + }, + } + } +] - The ID of the file to be sent to the model. +stream = client.beta.threads.runs.create( + thread_id="thread_abc123", + assistant_id="asst_abc123", + tools=tools, + stream=True +) - - `image_url: Optional[str]` +for event in stream: + print(event) +``` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. +#### Response - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` +```json +event: thread.run.created +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. +event: thread.run.queued +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `mode: Literal["explicit"]` +event: thread.run.in_progress +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710348075,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - The breakpoint mode. Always `explicit`. +event: thread.run.step.created +data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} - - `"explicit"` +event: thread.run.step.in_progress +data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} - - `class BetaResponseInputFile: …` +event: thread.message.created +data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - A file input to the model. +event: thread.message.in_progress +data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - - `type: Literal["input_file"]` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} - The type of the input item. Always `input_file`. +... - - `"input_file"` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} - - `detail: Optional[Literal["auto", "low", "high"]]` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. +event: thread.message.completed +data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} - - `"auto"` +event: thread.run.step.completed +data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} - - `"low"` +event: thread.run.completed +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710348075,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710348077,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `"high"` +event: done +data: [DONE] +``` - - `file_data: Optional[str]` +## Retrieve run - The content of the file to be sent to the model. +`beta.threads.runs.retrieve(strrun_id, RunRetrieveParams**kwargs) -> Run` - - `file_id: Optional[str]` +**get** `/threads/{thread_id}/runs/{run_id}` - The ID of the file to be sent to the model. +Retrieves a run. - - `file_url: Optional[str]` +### Parameters - The URL of the file to be sent to the model. +- `thread_id: str` - - `filename: Optional[str]` +- `run_id: str` - The name of the file to be sent to the model. +### Returns - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` +- `class Run: …` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `mode: Literal["explicit"]` + - `id: str` - The breakpoint mode. Always `explicit`. + The identifier, which can be referenced in API endpoints. - - `"explicit"` + - `assistant_id: str` - - `role: Literal["user", "system", "developer"]` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The role of the message input. One of `user`, `system`, or `developer`. + - `cancelled_at: Optional[int]` - - `"user"` + The Unix timestamp (in seconds) for when the run was cancelled. - - `"system"` + - `completed_at: Optional[int]` - - `"developer"` + The Unix timestamp (in seconds) for when the run was completed. - - `type: Literal["message"]` + - `created_at: int` - The type of the message input. Always set to `message`. + The Unix timestamp (in seconds) for when the run was created. - - `"message"` + - `expires_at: Optional[int]` - - `agent: Optional[Agent]` + The Unix timestamp (in seconds) for when the run will expire. - The agent that produced this item. + - `failed_at: Optional[int]` - - `agent_name: str` + The Unix timestamp (in seconds) for when the run failed. - The canonical name of the agent that produced this item. + - `incomplete_details: Optional[IncompleteDetails]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` - - `"in_progress"` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"completed"` + - `"max_completion_tokens"` - - `"incomplete"` + - `"max_prompt_tokens"` - - `class BetaResponseOutputMessage: …` + - `instructions: str` - An output message from the model. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `id: str` + - `last_error: Optional[LastError]` - The unique ID of the output message. + The last error associated with this run. Will be `null` if there are no errors. - - `content: List[Content]` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` - The content of the output message. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `class BetaResponseOutputText: …` + - `"server_error"` - A text output from the model. + - `"rate_limit_exceeded"` - - `annotations: List[Annotation]` + - `"invalid_prompt"` - The annotations of the text output. + - `message: str` - - `class AnnotationFileCitation: …` + A human-readable description of the error. - A citation to a file. + - `max_completion_tokens: Optional[int]` - - `file_id: str` + The maximum number of completion tokens specified to have been used over the course of the run. - The ID of the file. + - `max_prompt_tokens: Optional[int]` - - `filename: str` + The maximum number of prompt tokens specified to have been used over the course of the run. - The filename of the file cited. + - `metadata: Optional[Metadata]` - - `index: int` + 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. - The index of the file in the list of files. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: Literal["file_citation"]` + - `model: str` - The type of the file citation. Always `file_citation`. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"file_citation"` + - `object: Literal["thread.run"]` - - `class AnnotationURLCitation: …` + The object type, which is always `thread.run`. - A citation for a web resource used to generate a model response. + - `"thread.run"` - - `end_index: int` + - `parallel_tool_calls: bool` - The index of the last character of the URL citation in the message. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `start_index: int` + - `required_action: Optional[RequiredAction]` - The index of the first character of the URL citation in the message. + Details on the action required to continue the run. Will be `null` if no action is required. - - `title: str` + - `submit_tool_outputs: RequiredActionSubmitToolOutputs` - The title of the web resource. + Details on the tool outputs needed for this run to continue. - - `type: Literal["url_citation"]` + - `tool_calls: List[RequiredActionFunctionToolCall]` - The type of the URL citation. Always `url_citation`. + A list of the relevant tool calls. - - `"url_citation"` + - `id: str` - - `url: 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. - The URL of the web resource. + - `function: Function` - - `class AnnotationContainerFileCitation: …` + The function definition. - A citation for a container file used to generate a model response. + - `arguments: str` - - `container_id: str` + The arguments that the model expects you to pass to the function. - The ID of the container file. + - `name: str` - - `end_index: int` + The name of the function. - The index of the last character of the container file citation in the message. + - `type: Literal["function"]` - - `file_id: str` + The type of tool call the output is required for. For now, this is always `function`. - The ID of the file. + - `"function"` - - `filename: str` + - `type: Literal["submit_tool_outputs"]` - The filename of the container file cited. + For now, this is always `submit_tool_outputs`. - - `start_index: int` + - `"submit_tool_outputs"` - The index of the first character of the container file citation in the message. + - `response_format: Optional[AssistantResponseFormatOption]` - - `type: Literal["container_file_citation"]` + 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`. - The type of the container file citation. Always `container_file_citation`. + 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). - - `"container_file_citation"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `class AnnotationFilePath: …` + **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. - A path to a file. + - `Literal["auto"]` - - `file_id: str` + `auto` is the default value - The ID of the file. + - `"auto"` - - `index: int` + - `class ResponseFormatText: …` - The index of the file in the list of files. + Default response format. Used to generate text responses. - - `type: Literal["file_path"]` + - `type: Literal["text"]` - The type of the file path. Always `file_path`. + The type of response format being defined. Always `text`. - - `"file_path"` + - `"text"` - - `text: str` + - `class ResponseFormatJSONObject: …` - The text output from the model. + 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["output_text"]` + - `type: Literal["json_object"]` - The type of the output text. Always `output_text`. + The type of response format being defined. Always `json_object`. - - `"output_text"` + - `"json_object"` - - `logprobs: Optional[List[Logprob]]` + - `class ResponseFormatJSONSchema: …` - - `token: str` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `bytes: List[int]` + - `json_schema: JSONSchema` - - `logprob: float` + Structured Outputs configuration options, including a JSON Schema. - - `top_logprobs: List[LogprobTopLogprob]` + - `name: str` - - `token: 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. - - `bytes: List[int]` + - `description: Optional[str]` - - `logprob: float` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `class BetaResponseOutputRefusal: …` + - `schema: Optional[Dict[str, object]]` - A refusal from the model. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `refusal: str` + - `strict: Optional[bool]` - The refusal explanation from the model. + 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["refusal"]` + - `type: Literal["json_schema"]` - The type of the refusal. Always `refusal`. + The type of response format being defined. Always `json_schema`. - - `"refusal"` + - `"json_schema"` - - `role: Literal["assistant"]` + - `started_at: Optional[int]` - The role of the output message. Always `assistant`. + The Unix timestamp (in seconds) for when the run was started. - - `"assistant"` + - `status: RunStatus` - - `status: Literal["in_progress", "completed", "incomplete"]` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"queued"` - `"in_progress"` - - `"completed"` - - - `"incomplete"` - - - `type: Literal["message"]` - - The type of the output message. Always `message`. - - - `"message"` - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `phase: Optional[Literal["commentary"]]` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - - `"commentary"` - - - `class BetaResponseFileSearchToolCall: …` - - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - - `id: str` - - The unique ID of the file search tool call. - - - `queries: List[str]` - - The queries used to search for files. - - - `status: Literal["in_progress", "searching", "completed", 2 more]` + - `"requires_action"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"cancelling"` - - `"in_progress"` + - `"cancelled"` - - `"searching"` + - `"failed"` - `"completed"` - `"incomplete"` - - `"failed"` - - - `type: Literal["file_search_call"]` - - The type of the file search tool call. Always `file_search_call`. - - - `"file_search_call"` - - - `agent: Optional[Agent]` - - The agent that produced this item. - - - `agent_name: str` - - The canonical name of the agent that produced this item. - - - `results: Optional[List[Result]]` + - `"expired"` - The results of the file search tool call. + - `thread_id: str` - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - 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, booleans, or numbers. + - `tool_choice: Optional[AssistantToolChoiceOption]` - - `str` + 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. - - `float` + - `Literal["none", "auto", "required"]` - - `bool` + `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. - - `file_id: Optional[str]` + - `"none"` - The unique ID of the file. + - `"auto"` - - `filename: Optional[str]` + - `"required"` - The name of the file. + - `class AssistantToolChoice: …` - - `score: Optional[float]` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The relevance score of the file - a value between 0 and 1. + - `type: Literal["function", "code_interpreter", "file_search"]` - - `text: Optional[str]` + The type of the tool. If type is `function`, the function name must be set - The text that was retrieved from the file. + - `"function"` - - `class BetaResponseComputerToolCall: …` + - `"code_interpreter"` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `"file_search"` - - `id: str` + - `function: Optional[AssistantToolChoiceFunction]` - The unique ID of the computer call. + - `name: str` - - `call_id: str` + The name of the function to call. - An identifier used when responding to the tool call with output. + - `tools: List[AssistantTool]` - - `pending_safety_checks: List[PendingSafetyCheck]` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The pending safety checks for the computer call. + - `class CodeInterpreterTool: …` - - `id: str` + - `type: Literal["code_interpreter"]` - The ID of the pending safety check. + The type of tool being defined: `code_interpreter` - - `code: Optional[str]` + - `"code_interpreter"` - The type of the pending safety check. + - `class FileSearchTool: …` - - `message: Optional[str]` + - `type: Literal["file_search"]` - Details about the pending safety check. + The type of tool being defined: `file_search` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"file_search"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `file_search: Optional[FileSearch]` - - `"in_progress"` + Overrides for the file search tool. - - `"completed"` + - `max_num_results: Optional[int]` - - `"incomplete"` + 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. - - `type: Literal["computer_call"]` + 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. - The type of the computer call. Always `computer_call`. + - `ranking_options: Optional[FileSearchRankingOptions]` - - `"computer_call"` + 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. - - `action: Optional[BetaComputerAction]` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - A click action. + - `score_threshold: float` - - `class Click: …` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - A click action. + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - `button: Literal["left", "right", "wheel", 2 more]` + The ranker to use for the file search. If not specified will use the `auto` ranker. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"auto"` - - `"left"` + - `"default_2024_08_21"` - - `"right"` + - `class FunctionTool: …` - - `"wheel"` + - `function: FunctionDefinition` - - `"back"` + - `name: str` - - `"forward"` + 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. - - `type: Literal["click"]` + - `description: Optional[str]` - Specifies the event type. For a click action, this property is always `click`. + A description of what the function does, used by the model to choose when and how to call the function. - - `"click"` + - `parameters: Optional[FunctionParameters]` - - `x: int` + 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. - The x-coordinate where the click occurred. + Omitting `parameters` defines a function with an empty parameter list. - - `y: int` + - `strict: Optional[bool]` - The y-coordinate where the click occurred. + 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). - - `keys: Optional[List[str]]` + - `type: Literal["function"]` - The keys being held while clicking. + The type of tool being defined: `function` - - `class DoubleClick: …` + - `"function"` - A double click action. + - `truncation_strategy: Optional[TruncationStrategy]` - - `keys: Optional[List[str]]` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The keys being held while double-clicking. + - `type: Literal["auto", "last_messages"]` - - `type: Literal["double_click"]` + 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`. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"auto"` - - `"double_click"` + - `"last_messages"` - - `x: int` + - `last_messages: Optional[int]` - The x-coordinate where the double click occurred. + The number of most recent messages from the thread when constructing the context for the run. - - `y: int` + - `usage: Optional[Usage]` - The y-coordinate where the double click occurred. + 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.). - - `class Drag: …` + - `completion_tokens: int` - A drag action. + Number of completion tokens used over the course of the run. - - `path: List[DragPath]` + - `prompt_tokens: int` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Number of prompt tokens used over the course of the run. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `total_tokens: int` - - `x: int` + Total number of tokens used (prompt + completion). - The x-coordinate. + - `temperature: Optional[float]` - - `y: int` + The sampling temperature used for this run. If not set, defaults to 1. - The y-coordinate. + - `top_p: Optional[float]` - - `type: Literal["drag"]` + The nucleus sampling value used for this run. If not set, defaults to 1. - Specifies the event type. For a drag action, this property is always set to `drag`. +### Example - - `"drag"` +```python +import os +from openai import OpenAI - - `keys: Optional[List[str]]` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +run = client.beta.threads.runs.retrieve( + run_id="run_id", + thread_id="thread_id", +) +print(run.id) +``` - The keys being held while dragging the mouse. +#### Response - - `class Keypress: …` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - A collection of keypresses the model would like to perform. +### Example - - `keys: List[str]` +```python +from openai import OpenAI +client = OpenAI() - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. +run = client.beta.threads.runs.retrieve( + thread_id="thread_abc123", + run_id="run_abc123" +) - - `type: Literal["keypress"]` +print(run) +``` - Specifies the event type. For a keypress action, this property is always set to `keypress`. +#### Response - - `"keypress"` +```json +{ + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true +} +``` - - `class Move: …` +## Modify run - A mouse move action. +`beta.threads.runs.update(strrun_id, RunUpdateParams**kwargs) -> Run` - - `type: Literal["move"]` +**post** `/threads/{thread_id}/runs/{run_id}` - Specifies the event type. For a move action, this property is always set to `move`. +Modifies a run. - - `"move"` +### Parameters - - `x: int` +- `thread_id: str` - The x-coordinate to move to. +- `run_id: str` - - `y: int` +- `metadata: Optional[Metadata]` - The y-coordinate to move to. + 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: Optional[List[str]]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The keys being held while moving the mouse. +### Returns - - `class Screenshot: …` +- `class Run: …` - A screenshot action. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `type: Literal["screenshot"]` + - `id: str` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The identifier, which can be referenced in API endpoints. - - `"screenshot"` + - `assistant_id: str` - - `class Scroll: …` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - A scroll action. + - `cancelled_at: Optional[int]` - - `scroll_x: int` + The Unix timestamp (in seconds) for when the run was cancelled. - The horizontal scroll distance. + - `completed_at: Optional[int]` - - `scroll_y: int` + The Unix timestamp (in seconds) for when the run was completed. - The vertical scroll distance. + - `created_at: int` - - `type: Literal["scroll"]` + The Unix timestamp (in seconds) for when the run was created. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `expires_at: Optional[int]` - - `"scroll"` + The Unix timestamp (in seconds) for when the run will expire. - - `x: int` + - `failed_at: Optional[int]` - The x-coordinate where the scroll occurred. + The Unix timestamp (in seconds) for when the run failed. - - `y: int` + - `incomplete_details: Optional[IncompleteDetails]` - The y-coordinate where the scroll occurred. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `keys: Optional[List[str]]` + - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` - The keys being held while scrolling. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `class Type: …` + - `"max_completion_tokens"` - An action to type in text. + - `"max_prompt_tokens"` - - `text: str` + - `instructions: str` - The text to type. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `type: Literal["type"]` + - `last_error: Optional[LastError]` - Specifies the event type. For a type action, this property is always set to `type`. + The last error associated with this run. Will be `null` if there are no errors. - - `"type"` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` - - `class Wait: …` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - A wait action. + - `"server_error"` - - `type: Literal["wait"]` + - `"rate_limit_exceeded"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"invalid_prompt"` - - `"wait"` + - `message: str` - - `actions: Optional[BetaComputerActionList]` + A human-readable description of the error. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `max_completion_tokens: Optional[int]` - - `class Click: …` + The maximum number of completion tokens specified to have been used over the course of the run. - A click action. + - `max_prompt_tokens: Optional[int]` - - `class DoubleClick: …` + The maximum number of prompt tokens specified to have been used over the course of the run. - A double click action. + - `metadata: Optional[Metadata]` - - `class Drag: …` + 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. - A drag action. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `class Keypress: …` + - `model: str` - A collection of keypresses the model would like to perform. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `class Move: …` + - `object: Literal["thread.run"]` - A mouse move action. + The object type, which is always `thread.run`. - - `class Screenshot: …` + - `"thread.run"` - A screenshot action. + - `parallel_tool_calls: bool` - - `class Scroll: …` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - A scroll action. + - `required_action: Optional[RequiredAction]` - - `class Type: …` + Details on the action required to continue the run. Will be `null` if no action is required. - An action to type in text. + - `submit_tool_outputs: RequiredActionSubmitToolOutputs` - - `class Wait: …` + Details on the tool outputs needed for this run to continue. - A wait action. + - `tool_calls: List[RequiredActionFunctionToolCall]` - - `agent: Optional[Agent]` + A list of the relevant tool calls. - The agent that produced this item. + - `id: str` - - `agent_name: 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. - The canonical name of the agent that produced this item. + - `function: Function` - - `class BetaResponseComputerToolCallOutputItem: …` + The function definition. - - `id: str` + - `arguments: str` - The unique ID of the computer call tool output. + The arguments that the model expects you to pass to the function. - - `call_id: str` + - `name: str` - The ID of the computer tool call that produced the output. + The name of the function. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `type: Literal["function"]` - A computer screenshot image used with the computer use tool. + The type of tool call the output is required for. For now, this is always `function`. - - `type: Literal["computer_screenshot"]` + - `"function"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `type: Literal["submit_tool_outputs"]` - - `"computer_screenshot"` + For now, this is always `submit_tool_outputs`. - - `file_id: Optional[str]` + - `"submit_tool_outputs"` - The identifier of an uploaded file that contains the screenshot. + - `response_format: Optional[AssistantResponseFormatOption]` - - `image_url: Optional[str]` + 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`. - The URL of the screenshot image. + 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). - - `status: Literal["completed", "incomplete", "failed", "in_progress"]` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + **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. - - `"completed"` + - `Literal["auto"]` - - `"incomplete"` + `auto` is the default value - - `"failed"` + - `"auto"` - - `"in_progress"` + - `class ResponseFormatText: …` - - `type: Literal["computer_call_output"]` + Default response format. Used to generate text responses. - The type of the computer tool call output. Always `computer_call_output`. + - `type: Literal["text"]` - - `"computer_call_output"` + The type of response format being defined. Always `text`. - - `acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]]` + - `"text"` - The safety checks reported by the API that have been acknowledged by the - developer. + - `class ResponseFormatJSONObject: …` - - `id: str` + 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. - The ID of the pending safety check. + - `type: Literal["json_object"]` - - `code: Optional[str]` + The type of response format being defined. Always `json_object`. - The type of the pending safety check. + - `"json_object"` - - `message: Optional[str]` + - `class ResponseFormatJSONSchema: …` - Details about the pending safety check. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `agent: Optional[Agent]` + - `json_schema: JSONSchema` - The agent that produced this item. + Structured Outputs configuration options, including a JSON Schema. - - `agent_name: str` + - `name: str` - The canonical name of the agent that produced this item. + 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. - - `created_by: Optional[str]` + - `description: Optional[str]` - The identifier of the actor that created the item. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `class BetaResponseFunctionWebSearch: …` + - `schema: Optional[Dict[str, object]]` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `id: str` + - `strict: Optional[bool]` - The unique ID of the web search tool call. + 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). - - `action: Action` + - `type: Literal["json_schema"]` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + The type of response format being defined. Always `json_schema`. - - `class ActionSearch: …` + - `"json_schema"` - Action type "search" - Performs a web search query. + - `started_at: Optional[int]` - - `type: Literal["search"]` + The Unix timestamp (in seconds) for when the run was started. - The action type. + - `status: RunStatus` - - `"search"` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `queries: Optional[List[str]]` + - `"queued"` - The search queries. + - `"in_progress"` - - `query: Optional[str]` + - `"requires_action"` - The search query. + - `"cancelling"` - - `sources: Optional[List[ActionSearchSource]]` + - `"cancelled"` - The sources used in the search. + - `"failed"` - - `type: Literal["url"]` + - `"completed"` - The type of source. Always `url`. + - `"incomplete"` - - `"url"` + - `"expired"` - - `url: str` + - `thread_id: str` - The URL of the source. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `class ActionOpenPage: …` + - `tool_choice: Optional[AssistantToolChoiceOption]` - Action type "open_page" - Opens a specific URL from search results. + 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. - - `type: Literal["open_page"]` + - `Literal["none", "auto", "required"]` - The action type. + `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. - - `"open_page"` + - `"none"` - - `url: Optional[str]` + - `"auto"` - The URL opened by the model. + - `"required"` - - `class ActionFindInPage: …` + - `class AssistantToolChoice: …` - Action type "find_in_page": Searches for a pattern within a loaded page. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `pattern: str` + - `type: Literal["function", "code_interpreter", "file_search"]` - The pattern or text to search for within the page. + The type of the tool. If type is `function`, the function name must be set - - `type: Literal["find_in_page"]` + - `"function"` - The action type. + - `"code_interpreter"` - - `"find_in_page"` + - `"file_search"` - - `url: str` + - `function: Optional[AssistantToolChoiceFunction]` - The URL of the page searched for the pattern. + - `name: str` - - `status: Literal["in_progress", "searching", "completed", "failed"]` + The name of the function to call. - The status of the web search tool call. + - `tools: List[AssistantTool]` - - `"in_progress"` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"searching"` + - `class CodeInterpreterTool: …` - - `"completed"` + - `type: Literal["code_interpreter"]` - - `"failed"` + The type of tool being defined: `code_interpreter` - - `type: Literal["web_search_call"]` + - `"code_interpreter"` - The type of the web search tool call. Always `web_search_call`. + - `class FileSearchTool: …` - - `"web_search_call"` + - `type: Literal["file_search"]` - - `agent: Optional[Agent]` + The type of tool being defined: `file_search` - The agent that produced this item. + - `"file_search"` - - `agent_name: str` + - `file_search: Optional[FileSearch]` - The canonical name of the agent that produced this item. + Overrides for the file search tool. - - `class BetaResponseFunctionToolCallItem: …` + - `max_num_results: Optional[int]` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + 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. - - `id: str` + 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. - The unique ID of the function tool call. + - `ranking_options: Optional[FileSearchRankingOptions]` - - `status: Literal["in_progress", "completed", "incomplete"]` + 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. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"in_progress"` + - `score_threshold: float` - - `"completed"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"incomplete"` + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - `created_by: Optional[str]` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The identifier of the actor that created the item. + - `"auto"` - - `class BetaResponseFunctionToolCallOutputItem: …` + - `"default_2024_08_21"` - - `id: str` + - `class FunctionTool: …` - The unique ID of the function call tool output. + - `function: FunctionDefinition` - - `call_id: str` + - `name: str` - The unique ID of the function tool call generated by the model. + 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. - - `output: Union[str, List[OutputOutputContentList]]` + - `description: Optional[str]` - The output from the function call generated by your code. - Can be a string or an list of output content. + A description of what the function does, used by the model to choose when and how to call the function. - - `str` + - `parameters: Optional[FunctionParameters]` - A string of the output of the function call. + 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. - - `List[OutputOutputContentList]` + Omitting `parameters` defines a function with an empty parameter list. - Text, image, or file output of the function call. + - `strict: Optional[bool]` - - `class BetaResponseInputText: …` + 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). - A text input to the model. + - `type: Literal["function"]` - - `class BetaResponseInputImage: …` + The type of tool being defined: `function` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"function"` - - `class BetaResponseInputFile: …` + - `truncation_strategy: Optional[TruncationStrategy]` - A file input to the model. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `type: Literal["auto", "last_messages"]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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`. - - `"in_progress"` + - `"auto"` - - `"completed"` + - `"last_messages"` - - `"incomplete"` + - `last_messages: Optional[int]` - - `type: Literal["function_call_output"]` + The number of most recent messages from the thread when constructing the context for the run. - The type of the function tool call output. Always `function_call_output`. + - `usage: Optional[Usage]` - - `"function_call_output"` + 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.). - - `agent: Optional[Agent]` + - `completion_tokens: int` - The agent that produced this item. + Number of completion tokens used over the course of the run. - - `agent_name: str` + - `prompt_tokens: int` - The canonical name of the agent that produced this item. + Number of prompt tokens used over the course of the run. - - `caller: Optional[Caller]` + - `total_tokens: int` - The execution context that produced this tool call. + Total number of tokens used (prompt + completion). - - `class CallerDirect: …` + - `temperature: Optional[float]` - - `type: Literal["direct"]` + The sampling temperature used for this run. If not set, defaults to 1. - The caller type. Always `direct`. + - `top_p: Optional[float]` - - `"direct"` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `class CallerProgram: …` +### Example - - `caller_id: str` +```python +import os +from openai import OpenAI - The call ID of the program item that produced this tool call. +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +run = client.beta.threads.runs.update( + run_id="run_id", + thread_id="thread_id", +) +print(run.id) +``` - - `type: Literal["program"]` +#### Response - The caller type. Always `program`. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - - `"program"` +### Example - - `created_by: Optional[str]` +```python +from openai import OpenAI +client = OpenAI() - The identifier of the actor that created the item. +run = client.beta.threads.runs.update( + thread_id="thread_abc123", + run_id="run_abc123", + metadata={"user_id": "user_abc123"}, +) - - `class AgentMessage: …` +print(run) +``` - - `id: str` +#### Response - The unique ID of the agent message. +```json +{ + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] + } + }, + "metadata": { + "user_id": "user_abc123" + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true +} +``` - - `author: str` +## Submit tool outputs to run - The sending agent identity. +`beta.threads.runs.submit_tool_outputs(strrun_id, RunSubmitToolOutputsParams**kwargs) -> Run` - - `content: List[AgentMessageContent]` +**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` - Encrypted content sent between agents. +When a run has the `status: "requires_action"` and `required_action.type` is `submit_tool_outputs`, this endpoint can be used to submit the outputs from the tool calls once they're all completed. All outputs must be submitted in a single request. - - `class BetaResponseInputText: …` +### Parameters - A text input to the model. +- `thread_id: str` - - `class BetaResponseOutputText: …` +- `run_id: str` - A text output from the model. +- `tool_outputs: Iterable[ToolOutput]` - - `class AgentMessageContentText: …` + A list of tools for which the outputs are being submitted. - A text content. + - `output: Optional[str]` - - `text: str` + The output of the tool call to be submitted to continue the run. - - `type: Literal["text"]` + - `tool_call_id: Optional[str]` - - `"text"` + The ID of the tool call in the `required_action` object within the run object the output is being submitted for. - - `class AgentMessageContentSummaryText: …` +- `stream: Optional[Literal[false]]` - A summary text from the model. + If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. - - `text: str` + - `false` - A summary of the reasoning output from the model so far. +### Returns - - `type: Literal["summary_text"]` +- `class Run: …` - The type of the object. Always `summary_text`. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"summary_text"` + - `id: str` - - `class AgentMessageContentReasoningText: …` + The identifier, which can be referenced in API endpoints. - Reasoning text from the model. + - `assistant_id: str` - - `text: str` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The reasoning text from the model. + - `cancelled_at: Optional[int]` - - `type: Literal["reasoning_text"]` + The Unix timestamp (in seconds) for when the run was cancelled. - The type of the reasoning text. Always `reasoning_text`. + - `completed_at: Optional[int]` - - `"reasoning_text"` + The Unix timestamp (in seconds) for when the run was completed. - - `class BetaResponseOutputRefusal: …` + - `created_at: int` - A refusal from the model. + The Unix timestamp (in seconds) for when the run was created. - - `class BetaResponseInputImage: …` + - `expires_at: Optional[int]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The Unix timestamp (in seconds) for when the run will expire. - - `class AgentMessageContentComputerScreenshot: …` + - `failed_at: Optional[int]` - A screenshot of a computer. + The Unix timestamp (in seconds) for when the run failed. - - `detail: Literal["low", "high", "auto", "original"]` + - `incomplete_details: Optional[IncompleteDetails]` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `"low"` + - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` - - `"high"` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"auto"` + - `"max_completion_tokens"` - - `"original"` + - `"max_prompt_tokens"` - - `file_id: Optional[str]` + - `instructions: str` - The identifier of an uploaded file that contains the screenshot. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `image_url: Optional[str]` + - `last_error: Optional[LastError]` - The URL of the screenshot image. + The last error associated with this run. Will be `null` if there are no errors. - - `type: Literal["computer_screenshot"]` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `"computer_screenshot"` + - `"server_error"` - - `prompt_cache_breakpoint: Optional[AgentMessageContentComputerScreenshotPromptCacheBreakpoint]` + - `"rate_limit_exceeded"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"invalid_prompt"` - - `mode: Literal["explicit"]` + - `message: str` - The breakpoint mode. Always `explicit`. + A human-readable description of the error. - - `"explicit"` + - `max_completion_tokens: Optional[int]` - - `class BetaResponseInputFile: …` + The maximum number of completion tokens specified to have been used over the course of the run. - A file input to the model. + - `max_prompt_tokens: Optional[int]` - - `class AgentMessageContentEncryptedContent: …` + The maximum number of prompt tokens specified to have been used over the course of the run. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `metadata: Optional[Metadata]` - - `encrypted_content: str` + 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. - Opaque encrypted content. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: Literal["encrypted_content"]` + - `model: str` - The type of the input item. Always `encrypted_content`. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"encrypted_content"` + - `object: Literal["thread.run"]` - - `recipient: str` + The object type, which is always `thread.run`. - The destination agent identity. + - `"thread.run"` - - `type: Literal["agent_message"]` + - `parallel_tool_calls: bool` - The type of the item. Always `agent_message`. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"agent_message"` + - `required_action: Optional[RequiredAction]` - - `agent: Optional[AgentMessageAgent]` + Details on the action required to continue the run. Will be `null` if no action is required. - The agent that produced this item. + - `submit_tool_outputs: RequiredActionSubmitToolOutputs` - - `agent_name: str` + Details on the tool outputs needed for this run to continue. - The canonical name of the agent that produced this item. + - `tool_calls: List[RequiredActionFunctionToolCall]` - - `class MultiAgentCall: …` + A list of the relevant tool calls. - `id: str` - The unique ID of the multi-agent call item. - - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + 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. - The multi-agent action to execute. + - `function: Function` - - `"spawn_agent"` + The function definition. - - `"interrupt_agent"` + - `arguments: str` - - `"list_agents"` + The arguments that the model expects you to pass to the function. - - `"send_message"` + - `name: str` - - `"followup_task"` + The name of the function. - - `"wait_agent"` + - `type: Literal["function"]` - - `arguments: str` + The type of tool call the output is required for. For now, this is always `function`. - The JSON string of arguments generated for the action. + - `"function"` - - `call_id: str` + - `type: Literal["submit_tool_outputs"]` - The unique ID linking this call to its output. + For now, this is always `submit_tool_outputs`. - - `type: Literal["multi_agent_call"]` + - `"submit_tool_outputs"` - The type of the multi-agent call. Always `multi_agent_call`. + - `response_format: Optional[AssistantResponseFormatOption]` - - `"multi_agent_call"` + 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`. - - `agent: Optional[MultiAgentCallAgent]` + 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). - The agent that produced this item. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `agent_name: str` + **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. - The canonical name of the agent that produced this item. + - `Literal["auto"]` - - `class MultiAgentCallOutput: …` + `auto` is the default value - - `id: str` + - `"auto"` - The unique ID of the multi-agent call output item. + - `class ResponseFormatText: …` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + Default response format. Used to generate text responses. - The multi-agent action that produced this result. + - `type: Literal["text"]` - - `"spawn_agent"` + The type of response format being defined. Always `text`. - - `"interrupt_agent"` + - `"text"` - - `"list_agents"` + - `class ResponseFormatJSONObject: …` - - `"send_message"` + 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. - - `"followup_task"` + - `type: Literal["json_object"]` - - `"wait_agent"` + The type of response format being defined. Always `json_object`. - - `call_id: str` + - `"json_object"` - The unique ID of the multi-agent call. + - `class ResponseFormatJSONSchema: …` - - `output: List[BetaResponseOutputText]` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - Text output returned by the multi-agent action. + - `json_schema: JSONSchema` - - `annotations: List[Annotation]` + Structured Outputs configuration options, including a JSON Schema. - The annotations of the text output. + - `name: str` - - `text: 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. - The text output from the model. + - `description: Optional[str]` - - `type: Literal["output_text"]` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The type of the output text. Always `output_text`. + - `schema: Optional[Dict[str, object]]` - - `logprobs: Optional[List[Logprob]]` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `type: Literal["multi_agent_call_output"]` + - `strict: Optional[bool]` - The type of the multi-agent result. Always `multi_agent_call_output`. + 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). - - `"multi_agent_call_output"` + - `type: Literal["json_schema"]` - - `agent: Optional[MultiAgentCallOutputAgent]` + The type of response format being defined. Always `json_schema`. - The agent that produced this item. + - `"json_schema"` - - `agent_name: str` + - `started_at: Optional[int]` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run was started. - - `class BetaResponseToolSearchCall: …` + - `status: RunStatus` - - `id: str` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The unique ID of the tool search call item. + - `"queued"` - - `arguments: object` + - `"in_progress"` - Arguments used for the tool search call. + - `"requires_action"` - - `call_id: Optional[str]` + - `"cancelling"` - The unique ID of the tool search call generated by the model. + - `"cancelled"` - - `execution: Literal["server", "client"]` + - `"failed"` - Whether tool search was executed by the server or by the client. + - `"completed"` - - `"server"` + - `"incomplete"` - - `"client"` + - `"expired"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `thread_id: str` - The status of the tool search call item that was recorded. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `"in_progress"` + - `tool_choice: Optional[AssistantToolChoiceOption]` - - `"completed"` + 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. - - `"incomplete"` + - `Literal["none", "auto", "required"]` - - `type: Literal["tool_search_call"]` + `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. - The type of the item. Always `tool_search_call`. + - `"none"` - - `"tool_search_call"` + - `"auto"` - - `agent: Optional[Agent]` + - `"required"` - The agent that produced this item. + - `class AssistantToolChoice: …` - - `agent_name: str` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The canonical name of the agent that produced this item. + - `type: Literal["function", "code_interpreter", "file_search"]` - - `created_by: Optional[str]` + The type of the tool. If type is `function`, the function name must be set - The identifier of the actor that created the item. + - `"function"` - - `class BetaResponseToolSearchOutputItem: …` + - `"code_interpreter"` - - `id: str` + - `"file_search"` - The unique ID of the tool search output item. + - `function: Optional[AssistantToolChoiceFunction]` - - `call_id: Optional[str]` + - `name: str` - The unique ID of the tool search call generated by the model. + The name of the function to call. - - `execution: Literal["server", "client"]` + - `tools: List[AssistantTool]` - Whether tool search was executed by the server or by the client. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"server"` + - `class CodeInterpreterTool: …` - - `"client"` + - `type: Literal["code_interpreter"]` - - `status: Literal["in_progress", "completed", "incomplete"]` + The type of tool being defined: `code_interpreter` - The status of the tool search output item that was recorded. + - `"code_interpreter"` - - `"in_progress"` + - `class FileSearchTool: …` - - `"completed"` + - `type: Literal["file_search"]` - - `"incomplete"` + The type of tool being defined: `file_search` - - `tools: List[BetaTool]` + - `"file_search"` - The loaded tool definitions returned by tool search. + - `file_search: Optional[FileSearch]` - - `class BetaFunctionTool: …` + Overrides for the file search tool. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `max_num_results: Optional[int]` - - `name: str` + 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. - The name of the function to call. + 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. - - `parameters: Optional[Dict[str, object]]` + - `ranking_options: Optional[FileSearchRankingOptions]` - A JSON schema object describing the parameters of the function. + 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. - - `strict: Optional[bool]` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Whether strict parameter validation is enforced for this function tool. + - `score_threshold: float` - - `type: Literal["function"]` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The type of the function tool. Always `function`. + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - `"function"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"auto"` - The tool invocation context(s). + - `"default_2024_08_21"` - - `"direct"` + - `class FunctionTool: …` - - `"programmatic"` + - `function: FunctionDefinition` - - `defer_loading: Optional[bool]` + - `name: str` - Whether this function is deferred and loaded via tool search. + 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 the function. Used by the model to determine whether or not to call the function. - - - `output_schema: Optional[Dict[str, object]]` + A description of what the function does, used by the model to choose when and how to call the function. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `parameters: Optional[FunctionParameters]` - - `class BetaFileSearchTool: …` + 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. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + Omitting `parameters` defines a function with an empty parameter list. - - `type: Literal["file_search"]` + - `strict: Optional[bool]` - The type of the file search tool. Always `file_search`. + 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). - - `"file_search"` + - `type: Literal["function"]` - - `vector_store_ids: List[str]` + The type of tool being defined: `function` - The IDs of the vector stores to search. + - `"function"` - - `filters: Optional[Filters]` + - `truncation_strategy: Optional[TruncationStrategy]` - A filter to apply. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `class FiltersComparisonFilter: …` + - `type: Literal["auto", "last_messages"]` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + 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`. - - `key: str` + - `"auto"` - The key to compare against the value. + - `"last_messages"` - - `type: Literal["eq", "ne", "gt", 5 more]` + - `last_messages: Optional[int]` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The number of most recent messages from the thread when constructing the context for the run. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `usage: Optional[Usage]` - - `"eq"` + 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.). - - `"ne"` + - `completion_tokens: int` - - `"gt"` + Number of completion tokens used over the course of the run. - - `"gte"` + - `prompt_tokens: int` - - `"lt"` + Number of prompt tokens used over the course of the run. - - `"lte"` + - `total_tokens: int` - - `"in"` + Total number of tokens used (prompt + completion). - - `"nin"` + - `temperature: Optional[float]` - - `value: Union[str, float, bool, List[object]]` + The sampling temperature used for this run. If not set, defaults to 1. - The value to compare against the attribute key; supports string, number, or boolean types. + - `top_p: Optional[float]` - - `str` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `float` +### Example - - `bool` +```python +import os +from openai import OpenAI - - `List[object]` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +for run in client.beta.threads.runs.submit_tool_outputs( + run_id="run_id", + thread_id="thread_id", + tool_outputs=[{}], +): + print(run) +``` - - `class FiltersCompoundFilter: …` +#### Response - Combine multiple filters using `and` or `or`. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - - `filters: List[FiltersCompoundFilterFilter]` +### Example - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. +```python +from openai import OpenAI +client = OpenAI() - - `class FiltersCompoundFilterFilterComparisonFilter: …` +run = client.beta.threads.runs.submit_tool_outputs( + thread_id="thread_123", + run_id="run_123", + tool_outputs=[ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ] +) - A filter used to compare a specified attribute key to a given value using a defined comparison operation. +print(run) +``` - - `key: str` +#### Response - The key to compare against the value. +```json +{ + "id": "run_123", + "object": "thread.run", + "created_at": 1699075592, + "assistant_id": "asst_123", + "thread_id": "thread_123", + "status": "queued", + "started_at": 1699075592, + "expires_at": 1699076192, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location"] + } + } + } + ], + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true +} +``` - - `type: Literal["eq", "ne", "gt", 5 more]` +### Streaming - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. +```python +from openai import OpenAI +client = OpenAI() - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in +stream = client.beta.threads.runs.submit_tool_outputs( + thread_id="thread_123", + run_id="run_123", + tool_outputs=[ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ], + stream=True +) - - `"eq"` +for event in stream: + print(event) +``` - - `"ne"` +#### Response - - `"gt"` +```json +event: thread.run.step.completed +data: {"id":"step_001","object":"thread.run.step","created_at":1710352449,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"completed","cancelled_at":null,"completed_at":1710352475,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[{"id":"call_iWr0kQ2EaYMaxNdl0v3KYkx7","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}","output":"70 degrees and sunny."}}]},"usage":{"prompt_tokens":291,"completion_tokens":24,"total_tokens":315}} - - `"gte"` +event: thread.run.queued +data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":1710352448,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `"lt"` +event: thread.run.in_progress +data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710352475,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `"lte"` +event: thread.run.step.created +data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} - - `"in"` +event: thread.run.step.in_progress +data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} - - `"nin"` +event: thread.message.created +data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - - `value: Union[str, float, bool, List[object]]` +event: thread.message.in_progress +data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - The value to compare against the attribute key; supports string, number, or boolean types. +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"The","annotations":[]}}]}} - - `str` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" current"}}]}} - - `float` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" weather"}}]}} - - `bool` +... - - `List[object]` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" sunny"}}]}} - - `object` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"."}}]}} - - `type: Literal["and", "or"]` +event: thread.message.completed +data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710352477,"role":"assistant","content":[{"type":"text","text":{"value":"The current weather in San Francisco, CA is 70 degrees Fahrenheit and sunny.","annotations":[]}}],"metadata":{}} - Type of operation: `and` or `or`. +event: thread.run.step.completed +data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710352477,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":{"prompt_tokens":329,"completion_tokens":18,"total_tokens":347}} - - `"and"` +event: thread.run.completed +data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710352475,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710352477,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `"or"` +event: done +data: [DONE] +``` - - `max_num_results: Optional[int]` +## Cancel a run - The maximum number of results to return. This number should be between 1 and 50 inclusive. +`beta.threads.runs.cancel(strrun_id, RunCancelParams**kwargs) -> Run` - - `ranking_options: Optional[RankingOptions]` +**post** `/threads/{thread_id}/runs/{run_id}/cancel` - Ranking options for search. +Cancels a run that is `in_progress`. - - `hybrid_search: Optional[RankingOptionsHybridSearch]` +### Parameters - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. +- `thread_id: str` - - `embedding_weight: float` +- `run_id: str` - The weight of the embedding in the reciprocal ranking fusion. +### Returns - - `text_weight: float` +- `class Run: …` - The weight of the text in the reciprocal ranking fusion. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + - `id: str` - The ranker to use for the file search. + The identifier, which can be referenced in API endpoints. - - `"auto"` + - `assistant_id: str` - - `"default-2024-11-15"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `score_threshold: Optional[float]` + - `cancelled_at: Optional[int]` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The Unix timestamp (in seconds) for when the run was cancelled. - - `class BetaComputerTool: …` + - `completed_at: Optional[int]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The Unix timestamp (in seconds) for when the run was completed. - - `type: Literal["computer"]` + - `created_at: int` - The type of the computer tool. Always `computer`. + The Unix timestamp (in seconds) for when the run was created. - - `"computer"` + - `expires_at: Optional[int]` - - `class BetaComputerUsePreviewTool: …` + The Unix timestamp (in seconds) for when the run will expire. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `failed_at: Optional[int]` - - `display_height: int` + The Unix timestamp (in seconds) for when the run failed. - The height of the computer display. + - `incomplete_details: Optional[IncompleteDetails]` - - `display_width: int` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The width of the computer display. + - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` - - `environment: Literal["windows", "mac", "linux", 2 more]` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The type of computer environment to control. + - `"max_completion_tokens"` - - `"windows"` + - `"max_prompt_tokens"` - - `"mac"` + - `instructions: str` - - `"linux"` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"ubuntu"` + - `last_error: Optional[LastError]` - - `"browser"` + The last error associated with this run. Will be `null` if there are no errors. - - `type: Literal["computer_use_preview"]` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` - The type of the computer use tool. Always `computer_use_preview`. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `"computer_use_preview"` + - `"server_error"` - - `class BetaWebSearchTool: …` + - `"rate_limit_exceeded"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"invalid_prompt"` - - `type: Literal["web_search", "web_search_2025_08_26"]` + - `message: str` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + A human-readable description of the error. - - `"web_search"` + - `max_completion_tokens: Optional[int]` - - `"web_search_2025_08_26"` + The maximum number of completion tokens specified to have been used over the course of the run. - - `filters: Optional[Filters]` + - `max_prompt_tokens: Optional[int]` - Filters for the search. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `allowed_domains: Optional[List[str]]` + - `metadata: Optional[Metadata]` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + 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. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `model: str` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"low"` + - `object: Literal["thread.run"]` - - `"medium"` + The object type, which is always `thread.run`. - - `"high"` + - `"thread.run"` - - `user_location: Optional[UserLocation]` + - `parallel_tool_calls: bool` - The approximate location of the user. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `city: Optional[str]` + - `required_action: Optional[RequiredAction]` - Free text input for the city of the user, e.g. `San Francisco`. + Details on the action required to continue the run. Will be `null` if no action is required. - - `country: Optional[str]` + - `submit_tool_outputs: RequiredActionSubmitToolOutputs` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Details on the tool outputs needed for this run to continue. - - `region: Optional[str]` + - `tool_calls: List[RequiredActionFunctionToolCall]` - Free text input for the region of the user, e.g. `California`. + A list of the relevant tool calls. - - `timezone: Optional[str]` + - `id: str` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + 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. - - `type: Optional[Literal["approximate"]]` + - `function: Function` - The type of location approximation. Always `approximate`. + The function definition. - - `"approximate"` + - `arguments: str` - - `class Mcp: …` + The arguments that the model expects you to pass to the function. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `name: str` - - `server_label: str` + The name of the function. - A label for this MCP server, used to identify it in tool calls. + - `type: Literal["function"]` - - `type: Literal["mcp"]` + The type of tool call the output is required for. For now, this is always `function`. - The type of the MCP tool. Always `mcp`. + - `"function"` - - `"mcp"` + - `type: Literal["submit_tool_outputs"]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + For now, this is always `submit_tool_outputs`. - The tool invocation context(s). + - `"submit_tool_outputs"` - - `"direct"` + - `response_format: Optional[AssistantResponseFormatOption]` - - `"programmatic"` + 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`. - - `allowed_tools: Optional[McpAllowedTools]` + 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). - List of allowed tool names or a filter object. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `List[str]` + **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. - A string array of allowed tool names + - `Literal["auto"]` - - `class McpAllowedToolsMcpToolFilter: …` + `auto` is the default value - A filter object to specify which tools are allowed. + - `"auto"` - - `read_only: Optional[bool]` + - `class ResponseFormatText: …` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + Default response format. Used to generate text responses. - - `tool_names: Optional[List[str]]` + - `type: Literal["text"]` - List of allowed tool names. + The type of response format being defined. Always `text`. - - `authorization: Optional[str]` + - `"text"` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `class ResponseFormatJSONObject: …` - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` + 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. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `type: Literal["json_object"]` - Currently supported `connector_id` values are: + The type of response format being defined. Always `json_object`. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `"json_object"` - - `"connector_dropbox"` + - `class ResponseFormatJSONSchema: …` - - `"connector_gmail"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `"connector_googlecalendar"` + - `json_schema: JSONSchema` - - `"connector_googledrive"` + Structured Outputs configuration options, including a JSON Schema. - - `"connector_microsoftteams"` + - `name: str` - - `"connector_outlookcalendar"` + 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. - - `"connector_outlookemail"` + - `description: Optional[str]` - - `"connector_sharepoint"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `defer_loading: Optional[bool]` + - `schema: Optional[Dict[str, object]]` - Whether this MCP tool is deferred and discovered via tool search. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `headers: Optional[Dict[str, str]]` + - `strict: Optional[bool]` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + 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). - - `require_approval: Optional[McpRequireApproval]` + - `type: Literal["json_schema"]` - Specify which of the MCP server's tools require approval. + The type of response format being defined. Always `json_schema`. - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `"json_schema"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `started_at: Optional[int]` - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + The Unix timestamp (in seconds) for when the run was started. - A filter object to specify which tools are allowed. + - `status: RunStatus` - - `read_only: Optional[bool]` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"queued"` - - `tool_names: Optional[List[str]]` + - `"in_progress"` - List of allowed tool names. + - `"requires_action"` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + - `"cancelling"` - A filter object to specify which tools are allowed. + - `"cancelled"` - - `read_only: Optional[bool]` + - `"failed"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"completed"` - - `tool_names: Optional[List[str]]` + - `"incomplete"` - List of allowed tool names. + - `"expired"` - - `Literal["always", "never"]` + - `thread_id: str` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `"always"` + - `tool_choice: Optional[AssistantToolChoiceOption]` - - `"never"` + 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. - - `server_description: Optional[str]` + - `Literal["none", "auto", "required"]` - Optional description of the MCP server, used to provide more context. + `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. - - `server_url: Optional[str]` + - `"none"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"auto"` - - `tunnel_id: Optional[str]` + - `"required"` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `class AssistantToolChoice: …` - - `class CodeInterpreter: …` + Specifies a tool the model should use. Use to force the model to call a specific tool. - A tool that runs Python code to help generate a response to a prompt. + - `type: Literal["function", "code_interpreter", "file_search"]` - - `container: CodeInterpreterContainer` + The type of the tool. If type is `function`, the function name must be set - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `"function"` - - `str` + - `"code_interpreter"` - The container ID. + - `"file_search"` - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `function: Optional[AssistantToolChoiceFunction]` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `name: str` - - `type: Literal["auto"]` + The name of the function to call. - Always `auto`. + - `tools: List[AssistantTool]` - - `"auto"` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `file_ids: Optional[List[str]]` + - `class CodeInterpreterTool: …` - An optional list of uploaded files to make available to your code. + - `type: Literal["code_interpreter"]` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + The type of tool being defined: `code_interpreter` - The memory limit for the code interpreter container. + - `"code_interpreter"` - - `"1g"` + - `class FileSearchTool: …` - - `"4g"` + - `type: Literal["file_search"]` - - `"16g"` + The type of tool being defined: `file_search` - - `"64g"` + - `"file_search"` - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `file_search: Optional[FileSearch]` - Network access policy for the container. + Overrides for the file search tool. - - `class BetaContainerNetworkPolicyDisabled: …` + - `max_num_results: Optional[int]` - - `type: Literal["disabled"]` + 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. - Disable outbound network access. Always `disabled`. + 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. - - `"disabled"` + - `ranking_options: Optional[FileSearchRankingOptions]` - - `class BetaContainerNetworkPolicyAllowlist: …` + 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. - - `allowed_domains: List[str]` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - A list of allowed domains when type is `allowlist`. + - `score_threshold: float` - - `type: Literal["allowlist"]` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Allow outbound network access only to specified domains. Always `allowlist`. + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - `"allowlist"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + - `"auto"` - Optional domain-scoped secrets for allowlisted domains. + - `"default_2024_08_21"` - - `domain: str` + - `class FunctionTool: …` - The domain associated with the secret. + - `function: FunctionDefinition` - `name: str` - The name of the secret to inject for the domain. + 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. - - `value: str` + - `description: Optional[str]` - The secret value to inject for the domain. + A description of what the function does, used by the model to choose when and how to call the function. - - `type: Literal["code_interpreter"]` + - `parameters: Optional[FunctionParameters]` - The type of the code interpreter tool. Always `code_interpreter`. + 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. - - `"code_interpreter"` + Omitting `parameters` defines a function with an empty parameter list. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `strict: Optional[bool]` - The tool invocation context(s). + 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). - - `"direct"` + - `type: Literal["function"]` - - `"programmatic"` + The type of tool being defined: `function` - - `class ProgrammaticToolCalling: …` + - `"function"` - - `type: Literal["programmatic_tool_calling"]` + - `truncation_strategy: Optional[TruncationStrategy]` - The type of the tool. Always `programmatic_tool_calling`. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"programmatic_tool_calling"` + - `type: Literal["auto", "last_messages"]` - - `class ImageGeneration: …` + 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`. - A tool that generates images using the GPT image models. + - `"auto"` - - `type: Literal["image_generation"]` + - `"last_messages"` - The type of the image generation tool. Always `image_generation`. + - `last_messages: Optional[int]` - - `"image_generation"` + The number of most recent messages from the thread when constructing the context for the run. - - `action: Optional[Literal["generate", "edit", "auto"]]` + - `usage: Optional[Usage]` - Whether to generate a new image or edit an existing image. Default: `auto`. + 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.). - - `"generate"` + - `completion_tokens: int` - - `"edit"` + Number of completion tokens used over the course of the run. - - `"auto"` + - `prompt_tokens: int` - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + Number of prompt tokens used over the course of the run. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `total_tokens: int` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + Total number of tokens used (prompt + completion). - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `temperature: Optional[float]` - - `"transparent"` + The sampling temperature used for this run. If not set, defaults to 1. - - `"opaque"` + - `top_p: Optional[float]` - - `"auto"` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `input_fidelity: Optional[Literal["high", "low"]]` +### Example - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. +```python +import os +from openai import OpenAI - - `"high"` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +run = client.beta.threads.runs.cancel( + run_id="run_id", + thread_id="thread_id", +) +print(run.id) +``` - - `"low"` +#### Response - - `input_image_mask: Optional[ImageGenerationInputImageMask]` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). +### Example - - `file_id: Optional[str]` +```python +from openai import OpenAI +client = OpenAI() - File ID for the mask image. +run = client.beta.threads.runs.cancel( + thread_id="thread_abc123", + run_id="run_abc123" +) - - `image_url: Optional[str]` +print(run) +``` - Base64-encoded mask image. +#### Response - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` +```json +{ + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699076126, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "cancelling", + "started_at": 1699076126, + "expires_at": 1699076726, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "last_error": null, + "model": "gpt-4o", + "instructions": "You summarize books.", + "tools": [ + { + "type": "file_search" + } + ], + "tool_resources": { + "file_search": { + "vector_store_ids": ["vs_123"] + } + }, + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true +} +``` - The image generation model to use. Default: `gpt-image-1`. +## Domain Types - - `str` +### Required Action Function Tool Call - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` +- `class RequiredActionFunctionToolCall: …` - The image generation model to use. Default: `gpt-image-1`. + Tool call objects - - `"gpt-image-1"` + - `id: str` - - `"gpt-image-1-mini"` + 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. - - `"gpt-image-2"` + - `function: Function` - - `"gpt-image-2-2026-04-21"` + The function definition. - - `"gpt-image-1.5"` + - `arguments: str` - - `"chatgpt-image-latest"` + The arguments that the model expects you to pass to the function. - - `moderation: Optional[Literal["auto", "low"]]` + - `name: str` - Moderation level for the generated image. Default: `auto`. + The name of the function. - - `"auto"` + - `type: Literal["function"]` - - `"low"` + The type of tool call the output is required for. For now, this is always `function`. - - `output_compression: Optional[int]` + - `"function"` - Compression level for the output image. Default: 100. +### Run - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` +- `class Run: …` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"png"` + - `id: str` - - `"webp"` + The identifier, which can be referenced in API endpoints. - - `"jpeg"` + - `assistant_id: str` - - `partial_images: Optional[int]` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `cancelled_at: Optional[int]` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` + The Unix timestamp (in seconds) for when the run was cancelled. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `completed_at: Optional[int]` - - `"low"` + The Unix timestamp (in seconds) for when the run was completed. - - `"medium"` + - `created_at: int` - - `"high"` + The Unix timestamp (in seconds) for when the run was created. - - `"auto"` + - `expires_at: Optional[int]` - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + The Unix timestamp (in seconds) for when the run will expire. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `failed_at: Optional[int]` - - `str` + The Unix timestamp (in seconds) for when the run failed. - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `incomplete_details: Optional[IncompleteDetails]` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `"1024x1024"` + - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` - - `"1024x1536"` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"1536x1024"` + - `"max_completion_tokens"` - - `"auto"` + - `"max_prompt_tokens"` - - `class LocalShell: …` + - `instructions: str` - A tool that allows the model to execute shell commands in a local environment. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `type: Literal["local_shell"]` + - `last_error: Optional[LastError]` - The type of the local shell tool. Always `local_shell`. + The last error associated with this run. Will be `null` if there are no errors. - - `"local_shell"` + - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` - - `class BetaFunctionShellTool: …` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - A tool that allows the model to execute shell commands. + - `"server_error"` - - `type: Literal["shell"]` + - `"rate_limit_exceeded"` - The type of the shell tool. Always `shell`. + - `"invalid_prompt"` - - `"shell"` + - `message: str` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + A human-readable description of the error. - The tool invocation context(s). + - `max_completion_tokens: Optional[int]` - - `"direct"` + The maximum number of completion tokens specified to have been used over the course of the run. - - `"programmatic"` + - `max_prompt_tokens: Optional[int]` - - `environment: Optional[Environment]` + The maximum number of prompt tokens specified to have been used over the course of the run. - - `class BetaContainerAuto: …` + - `metadata: Optional[Metadata]` - - `type: Literal["container_auto"]` + 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. - Automatically creates a container for this request + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"container_auto"` + - `model: str` - - `file_ids: Optional[List[str]]` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - An optional list of uploaded files to make available to your code. + - `object: Literal["thread.run"]` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + The object type, which is always `thread.run`. - The memory limit for the container. + - `"thread.run"` - - `"1g"` + - `parallel_tool_calls: bool` - - `"4g"` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"16g"` + - `required_action: Optional[RequiredAction]` - - `"64g"` + Details on the action required to continue the run. Will be `null` if no action is required. - - `network_policy: Optional[NetworkPolicy]` + - `submit_tool_outputs: RequiredActionSubmitToolOutputs` - Network access policy for the container. + Details on the tool outputs needed for this run to continue. - - `class BetaContainerNetworkPolicyDisabled: …` + - `tool_calls: List[RequiredActionFunctionToolCall]` - - `class BetaContainerNetworkPolicyAllowlist: …` + A list of the relevant tool calls. - - `skills: Optional[List[Skill]]` + - `id: str` - An optional list of skills referenced by id or inline data. + 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. - - `class BetaSkillReference: …` + - `function: Function` - - `skill_id: str` + The function definition. - The ID of the referenced skill. + - `arguments: str` - - `type: Literal["skill_reference"]` + The arguments that the model expects you to pass to the function. - References a skill created with the /v1/skills endpoint. + - `name: str` - - `"skill_reference"` + The name of the function. - - `version: Optional[str]` + - `type: Literal["function"]` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The type of tool call the output is required for. For now, this is always `function`. - - `class BetaInlineSkill: …` + - `"function"` - - `description: str` + - `type: Literal["submit_tool_outputs"]` - The description of the skill. + For now, this is always `submit_tool_outputs`. - - `name: str` + - `"submit_tool_outputs"` - The name of the skill. + - `response_format: Optional[AssistantResponseFormatOption]` - - `source: BetaInlineSkillSource` + 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`. - Inline skill payload + 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). - - `data: str` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - Base64-encoded skill zip bundle. + **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. - - `media_type: Literal["application/zip"]` + - `Literal["auto"]` - The media type of the inline skill payload. Must be `application/zip`. + `auto` is the default value - - `"application/zip"` + - `"auto"` - - `type: Literal["base64"]` + - `class ResponseFormatText: …` - The type of the inline skill source. Must be `base64`. + Default response format. Used to generate text responses. - - `"base64"` + - `type: Literal["text"]` - - `type: Literal["inline"]` + The type of response format being defined. Always `text`. - Defines an inline skill for this request. + - `"text"` - - `"inline"` + - `class ResponseFormatJSONObject: …` - - `class BetaLocalEnvironment: …` + 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["local"]` + - `type: Literal["json_object"]` - Use a local computer environment. + The type of response format being defined. Always `json_object`. - - `"local"` + - `"json_object"` - - `skills: Optional[List[BetaLocalSkill]]` + - `class ResponseFormatJSONSchema: …` - An optional list of skills. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `description: str` + - `json_schema: JSONSchema` - The description of the skill. + Structured Outputs configuration options, including a JSON Schema. - `name: str` - The name of the skill. + 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. - - `path: str` + - `description: Optional[str]` - The path to the directory containing the skill. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `class BetaContainerReference: …` + - `schema: Optional[Dict[str, object]]` - - `container_id: str` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The ID of the referenced container. + - `strict: Optional[bool]` - - `type: Literal["container_reference"]` + 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). - References a container created with the /v1/containers endpoint + - `type: Literal["json_schema"]` - - `"container_reference"` + The type of response format being defined. Always `json_schema`. - - `class BetaCustomTool: …` + - `"json_schema"` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `started_at: Optional[int]` - - `name: str` + The Unix timestamp (in seconds) for when the run was started. - The name of the custom tool, used to identify it in tool calls. + - `status: RunStatus` - - `type: Literal["custom"]` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The type of the custom tool. Always `custom`. + - `"queued"` - - `"custom"` + - `"in_progress"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"requires_action"` - The tool invocation context(s). + - `"cancelling"` - - `"direct"` + - `"cancelled"` - - `"programmatic"` + - `"failed"` - - `defer_loading: Optional[bool]` + - `"completed"` - Whether this tool should be deferred and discovered via tool search. + - `"incomplete"` - - `description: Optional[str]` + - `"expired"` - Optional description of the custom tool, used to provide more context. + - `thread_id: str` - - `format: Optional[Format]` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The input format for the custom tool. Default is unconstrained text. + - `tool_choice: Optional[AssistantToolChoiceOption]` - - `class FormatText: …` + 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. - Unconstrained free-form text. + - `Literal["none", "auto", "required"]` - - `type: Literal["text"]` + `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. - Unconstrained text format. Always `text`. + - `"none"` - - `"text"` + - `"auto"` - - `class FormatGrammar: …` + - `"required"` - A grammar defined by the user. + - `class AssistantToolChoice: …` - - `definition: str` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The grammar definition. + - `type: Literal["function", "code_interpreter", "file_search"]` - - `syntax: Literal["lark", "regex"]` + The type of the tool. If type is `function`, the function name must be set - The syntax of the grammar definition. One of `lark` or `regex`. + - `"function"` - - `"lark"` + - `"code_interpreter"` - - `"regex"` + - `"file_search"` - - `type: Literal["grammar"]` + - `function: Optional[AssistantToolChoiceFunction]` - Grammar format. Always `grammar`. + - `name: str` - - `"grammar"` + The name of the function to call. - - `class BetaNamespaceTool: …` + - `tools: List[AssistantTool]` - Groups function/custom tools under a shared namespace. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `description: str` + - `class CodeInterpreterTool: …` - A description of the namespace shown to the model. + - `type: Literal["code_interpreter"]` - - `name: str` + The type of tool being defined: `code_interpreter` - The namespace name used in tool calls (for example, `crm`). + - `"code_interpreter"` - - `tools: List[Tool]` + - `class FileSearchTool: …` - The function/custom tools available inside this namespace. + - `type: Literal["file_search"]` - - `class ToolFunction: …` + The type of tool being defined: `file_search` - - `name: str` + - `"file_search"` - - `type: Literal["function"]` + - `file_search: Optional[FileSearch]` - - `"function"` + Overrides for the file search tool. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `max_num_results: Optional[int]` - The tool invocation context(s). + 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. - - `"direct"` + 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. - - `"programmatic"` + - `ranking_options: Optional[FileSearchRankingOptions]` - - `defer_loading: Optional[bool]` + 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. - Whether this function should be deferred and discovered via tool search. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `description: Optional[str]` + - `score_threshold: float` - - `output_schema: Optional[Dict[str, object]]` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - `parameters: Optional[object]` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `strict: Optional[bool]` + - `"auto"` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `"default_2024_08_21"` - - `class BetaCustomTool: …` + - `class FunctionTool: …` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `function: FunctionDefinition` - - `type: Literal["namespace"]` + - `name: str` - The type of the tool. Always `namespace`. + 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. - - `"namespace"` + - `description: Optional[str]` - - `class BetaToolSearchTool: …` + A description of what the function does, used by the model to choose when and how to call the function. - Hosted or BYOT tool search configuration for deferred tools. + - `parameters: Optional[FunctionParameters]` - - `type: Literal["tool_search"]` + 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. - The type of the tool. Always `tool_search`. + Omitting `parameters` defines a function with an empty parameter list. - - `"tool_search"` + - `strict: Optional[bool]` - - `description: Optional[str]` + 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). - Description shown to the model for a client-executed tool search tool. + - `type: Literal["function"]` - - `execution: Optional[Literal["server", "client"]]` + The type of tool being defined: `function` - Whether tool search is executed by the server or by the client. + - `"function"` - - `"server"` + - `truncation_strategy: Optional[TruncationStrategy]` - - `"client"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `parameters: Optional[object]` + - `type: Literal["auto", "last_messages"]` - Parameter schema for a client-executed tool search tool. + 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`. - - `class BetaWebSearchPreviewTool: …` + - `"auto"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"last_messages"` - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + - `last_messages: Optional[int]` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The number of most recent messages from the thread when constructing the context for the run. - - `"web_search_preview"` + - `usage: Optional[Usage]` - - `"web_search_preview_2025_03_11"` + 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.). - - `search_content_types: Optional[List[Literal["text", "image"]]]` + - `completion_tokens: int` - - `"text"` + Number of completion tokens used over the course of the run. - - `"image"` + - `prompt_tokens: int` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + Number of prompt tokens used over the course of the run. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `total_tokens: int` - - `"low"` + Total number of tokens used (prompt + completion). - - `"medium"` + - `temperature: Optional[float]` - - `"high"` + The sampling temperature used for this run. If not set, defaults to 1. - - `user_location: Optional[UserLocation]` + - `top_p: Optional[float]` - The user's location. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `type: Literal["approximate"]` +### Run Status - The type of location approximation. Always `approximate`. +- `Literal["queued", "in_progress", "requires_action", 6 more]` - - `"approximate"` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `city: Optional[str]` + - `"queued"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"in_progress"` - - `country: Optional[str]` + - `"requires_action"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"cancelling"` - - `region: Optional[str]` + - `"cancelled"` - Free text input for the region of the user, e.g. `California`. + - `"failed"` - - `timezone: Optional[str]` + - `"completed"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"incomplete"` - - `class BetaApplyPatchTool: …` + - `"expired"` - Allows the assistant to create, delete, or update files using unified diffs. +# Steps - - `type: Literal["apply_patch"]` +## List run steps - The type of the tool. Always `apply_patch`. +`beta.threads.runs.steps.list(strrun_id, StepListParams**kwargs) -> SyncCursorPage[RunStep]` - - `"apply_patch"` +**get** `/threads/{thread_id}/runs/{run_id}/steps` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` +Returns a list of run steps belonging to a run. - The tool invocation context(s). +### Parameters - - `"direct"` +- `thread_id: str` - - `"programmatic"` +- `run_id: str` - - `type: Literal["tool_search_output"]` +- `after: Optional[str]` - The type of the item. Always `tool_search_output`. + 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. - - `"tool_search_output"` +- `before: Optional[str]` - - `agent: Optional[Agent]` + 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. - The agent that produced this item. +- `include: Optional[List[RunStepInclude]]` - - `agent_name: str` + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - The canonical name of the agent that produced this item. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `created_by: Optional[str]` + - `"step_details.tool_calls[*].file_search.results[*].content"` - The identifier of the actor that created the item. +- `limit: Optional[int]` - - `class AdditionalTools: …` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `id: str` +- `order: Optional[Literal["asc", "desc"]]` - The unique ID of the additional tools item. + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `role: Literal["unknown", "user", "assistant", 5 more]` + - `"asc"` - The role that provided the additional tools. + - `"desc"` - - `"unknown"` +### Returns - - `"user"` +- `class RunStep: …` - - `"assistant"` + Represents a step in execution of a run. - - `"system"` + - `id: str` - - `"critic"` + The identifier of the run step, which can be referenced in API endpoints. - - `"discriminator"` + - `assistant_id: str` - - `"developer"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `"tool"` + - `cancelled_at: Optional[int]` - - `tools: List[BetaTool]` + The Unix timestamp (in seconds) for when the run step was cancelled. - The additional tool definitions made available at this item. + - `completed_at: Optional[int]` - - `class BetaFunctionTool: …` + The Unix timestamp (in seconds) for when the run step completed. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `created_at: int` - - `class BetaFileSearchTool: …` + The Unix timestamp (in seconds) for when the run step was created. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `expired_at: Optional[int]` - - `class BetaComputerTool: …` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `failed_at: Optional[int]` - - `class BetaComputerUsePreviewTool: …` + The Unix timestamp (in seconds) for when the run step failed. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `last_error: Optional[LastError]` - - `class BetaWebSearchTool: …` + The last error associated with this run step. Will be `null` if there are no errors. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `code: Literal["server_error", "rate_limit_exceeded"]` - - `class Mcp: …` + One of `server_error` or `rate_limit_exceeded`. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"server_error"` - - `class CodeInterpreter: …` + - `"rate_limit_exceeded"` - A tool that runs Python code to help generate a response to a prompt. + - `message: str` - - `class ProgrammaticToolCalling: …` + A human-readable description of the error. - - `class ImageGeneration: …` + - `metadata: Optional[Metadata]` - A tool that generates images using the GPT image models. + 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. - - `class LocalShell: …` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A tool that allows the model to execute shell commands in a local environment. + - `object: Literal["thread.run.step"]` - - `class BetaFunctionShellTool: …` + The object type, which is always `thread.run.step`. - A tool that allows the model to execute shell commands. + - `"thread.run.step"` - - `class BetaCustomTool: …` + - `run_id: str` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `class BetaNamespaceTool: …` + - `status: Literal["in_progress", "cancelled", "failed", 2 more]` - Groups function/custom tools under a shared namespace. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `class BetaToolSearchTool: …` + - `"in_progress"` - Hosted or BYOT tool search configuration for deferred tools. + - `"cancelled"` - - `class BetaWebSearchPreviewTool: …` + - `"failed"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `"completed"` - - `class BetaApplyPatchTool: …` + - `"expired"` - Allows the assistant to create, delete, or update files using unified diffs. + - `step_details: StepDetails` - - `type: Literal["additional_tools"]` + The details of the run step. - The type of the item. Always `additional_tools`. + - `class MessageCreationStepDetails: …` - - `"additional_tools"` + Details of the message creation by the run step. - - `agent: Optional[AdditionalToolsAgent]` + - `message_creation: MessageCreation` - The agent that produced this item. + - `message_id: str` - - `agent_name: str` + The ID of the message that was created by this run step. - The canonical name of the agent that produced this item. + - `type: Literal["message_creation"]` - - `class BetaResponseReasoningItem: …` + Always `message_creation`. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `"message_creation"` - - `id: str` + - `class ToolCallsStepDetails: …` - The unique identifier of the reasoning content. + Details of the tool call. - - `summary: List[Summary]` + - `tool_calls: List[ToolCall]` - Reasoning summary content. + 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`. - - `text: str` + - `class CodeInterpreterToolCall: …` - A summary of the reasoning output from the model so far. + Details of the Code Interpreter tool call the run step was involved in. - - `type: Literal["summary_text"]` + - `id: str` - The type of the object. Always `summary_text`. + The ID of the tool call. - - `"summary_text"` + - `code_interpreter: CodeInterpreter` - - `type: Literal["reasoning"]` + The Code Interpreter tool call definition. - The type of the object. Always `reasoning`. + - `input: str` - - `"reasoning"` + The input to the Code Interpreter tool call. - - `agent: Optional[Agent]` + - `outputs: List[CodeInterpreterOutput]` - The agent that produced this item. + 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. - - `agent_name: str` + - `class CodeInterpreterOutputLogs: …` - The canonical name of the agent that produced this item. + Text output from the Code Interpreter tool call as part of a run step. - - `content: Optional[List[Content]]` + - `logs: str` - Reasoning text content. + The text output from the Code Interpreter tool call. - - `text: str` + - `type: Literal["logs"]` - The reasoning text from the model. + Always `logs`. - - `type: Literal["reasoning_text"]` + - `"logs"` - The type of the reasoning text. Always `reasoning_text`. + - `class CodeInterpreterOutputImage: …` - - `"reasoning_text"` + - `image: CodeInterpreterOutputImageImage` - - `encrypted_content: Optional[str]` + - `file_id: str` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `type: Literal["image"]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Always `image`. - - `"in_progress"` + - `"image"` - - `"completed"` + - `type: Literal["code_interpreter"]` - - `"incomplete"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `class Program: …` + - `"code_interpreter"` + + - `class FileSearchToolCall: …` - `id: str` - The unique ID of the program item. + The ID of the tool call object. - - `call_id: str` + - `file_search: FileSearch` - The stable call ID of the program item. + For now, this is always going to be an empty object. - - `code: str` + - `ranking_options: Optional[FileSearchRankingOptions]` - The JavaScript source executed by programmatic tool calling. + The ranking options for the file search. - - `fingerprint: str` + - `ranker: Literal["auto", "default_2024_08_21"]` - Opaque program replay fingerprint that must be round-tripped. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `type: Literal["program"]` + - `"auto"` - The type of the item. Always `program`. + - `"default_2024_08_21"` - - `"program"` + - `score_threshold: float` - - `agent: Optional[ProgramAgent]` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The agent that produced this item. + - `results: Optional[List[FileSearchResult]]` - - `agent_name: str` + The results of the file search. - The canonical name of the agent that produced this item. + - `file_id: str` - - `class ProgramOutput: …` + The ID of the file that result was found in. - - `id: str` + - `file_name: str` - The unique ID of the program output item. + The name of the file that result was found in. - - `call_id: str` + - `score: float` - The call ID of the program item. + The score of the result. All values must be a floating point number between 0 and 1. - - `result: str` + - `content: Optional[List[FileSearchResultContent]]` - The result produced by the program item. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `status: Literal["completed", "incomplete"]` + - `text: Optional[str]` - The terminal status of the program output item. + The text content of the file. - - `"completed"` + - `type: Optional[Literal["text"]]` - - `"incomplete"` + The type of the content. - - `type: Literal["program_output"]` + - `"text"` - The type of the item. Always `program_output`. + - `type: Literal["file_search"]` - - `"program_output"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `agent: Optional[ProgramOutputAgent]` + - `"file_search"` - The agent that produced this item. + - `class FunctionToolCall: …` - - `agent_name: str` + - `id: str` - The canonical name of the agent that produced this item. + The ID of the tool call object. - - `class BetaResponseCompactionItem: …` + - `function: Function` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The definition of the function that was called. - - `id: str` + - `arguments: str` - The unique ID of the compaction item. + The arguments passed to the function. - - `encrypted_content: str` + - `name: str` - The encrypted content that was produced by compaction. + The name of the function. - - `type: Literal["compaction"]` + - `output: Optional[str]` - The type of the item. Always `compaction`. + 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. - - `"compaction"` + - `type: Literal["function"]` - - `agent: Optional[Agent]` + The type of tool call. This is always going to be `function` for this type of tool call. - The agent that produced this item. + - `"function"` - - `agent_name: str` + - `type: Literal["tool_calls"]` - The canonical name of the agent that produced this item. + Always `tool_calls`. - - `created_by: Optional[str]` + - `"tool_calls"` - The identifier of the actor that created the item. + - `thread_id: str` - - `class ImageGenerationCall: …` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - An image generation request made by the model. + - `type: Literal["message_creation", "tool_calls"]` - - `id: str` + The type of run step, which can be either `message_creation` or `tool_calls`. - The unique ID of the image generation call. + - `"message_creation"` - - `result: Optional[str]` + - `"tool_calls"` - The generated image encoded in base64. + - `usage: Optional[Usage]` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - The status of the image generation call. + - `completion_tokens: int` - - `"in_progress"` + Number of completion tokens used over the course of the run step. - - `"completed"` + - `prompt_tokens: int` - - `"generating"` + Number of prompt tokens used over the course of the run step. - - `"failed"` + - `total_tokens: int` - - `type: Literal["image_generation_call"]` + Total number of tokens used (prompt + completion). - The type of the image generation call. Always `image_generation_call`. +### Example - - `"image_generation_call"` +```python +import os +from openai import OpenAI - - `agent: Optional[ImageGenerationCallAgent]` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +page = client.beta.threads.runs.steps.list( + run_id="run_id", + thread_id="thread_id", +) +page = page.data[0] +print(page.id) +``` - The agent that produced this item. +#### Response - - `agent_name: str` +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expired_at": 0, + "failed_at": 0, + "last_error": { + "code": "server_error", + "message": "message" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.run.step", + "run_id": "run_id", + "status": "in_progress", + "step_details": { + "message_creation": { + "message_id": "message_id" + }, + "type": "message_creation" + }, + "thread_id": "thread_id", + "type": "message_creation", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + } + } + ], + "first_id": "step_abc123", + "has_more": false, + "last_id": "step_abc456", + "object": "list" +} +``` - The canonical name of the agent that produced this item. +### Example - - `class BetaResponseCodeInterpreterToolCall: …` +```python +from openai import OpenAI +client = OpenAI() - A tool call to run code. +run_steps = client.beta.threads.runs.steps.list( + thread_id="thread_abc123", + run_id="run_abc123" +) - - `id: str` +print(run_steps) +``` - The unique ID of the code interpreter tool call. +#### Response - - `code: Optional[str]` +```json +{ + "object": "list", + "data": [ + { + "id": "step_abc123", + "object": "thread.run.step", + "created_at": 1699063291, + "run_id": "run_abc123", + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "type": "message_creation", + "status": "completed", + "cancelled_at": null, + "completed_at": 1699063291, + "expired_at": null, + "failed_at": null, + "last_error": null, + "step_details": { + "type": "message_creation", + "message_creation": { + "message_id": "msg_abc123" + } + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + } + } + ], + "first_id": "step_abc123", + "last_id": "step_abc456", + "has_more": false +} +``` - The code to run, or null if not available. +## Retrieve run step - - `container_id: str` +`beta.threads.runs.steps.retrieve(strstep_id, StepRetrieveParams**kwargs) -> RunStep` - The ID of the container used to run the code. +**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` - - `outputs: Optional[List[Output]]` +Retrieves a run step. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. +### Parameters - - `class OutputLogs: …` +- `thread_id: str` - The logs output from the code interpreter. +- `run_id: str` - - `logs: str` +- `step_id: str` - The logs output from the code interpreter. +- `include: Optional[List[RunStepInclude]]` - - `type: Literal["logs"]` + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - The type of the output. Always `logs`. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"logs"` + - `"step_details.tool_calls[*].file_search.results[*].content"` - - `class OutputImage: …` +### Returns - The image output from the code interpreter. +- `class RunStep: …` - - `type: Literal["image"]` + Represents a step in execution of a run. - The type of the output. Always `image`. + - `id: str` - - `"image"` + The identifier of the run step, which can be referenced in API endpoints. - - `url: str` + - `assistant_id: str` - The URL of the image output from the code interpreter. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + - `cancelled_at: Optional[int]` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The Unix timestamp (in seconds) for when the run step was cancelled. - - `"in_progress"` + - `completed_at: Optional[int]` - - `"completed"` + The Unix timestamp (in seconds) for when the run step completed. - - `"incomplete"` + - `created_at: int` - - `"interpreting"` + The Unix timestamp (in seconds) for when the run step was created. - - `"failed"` + - `expired_at: Optional[int]` - - `type: Literal["code_interpreter_call"]` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `failed_at: Optional[int]` - - `"code_interpreter_call"` + The Unix timestamp (in seconds) for when the run step failed. - - `agent: Optional[Agent]` + - `last_error: Optional[LastError]` - The agent that produced this item. + The last error associated with this run step. Will be `null` if there are no errors. - - `agent_name: str` + - `code: Literal["server_error", "rate_limit_exceeded"]` - The canonical name of the agent that produced this item. + One of `server_error` or `rate_limit_exceeded`. - - `class LocalShellCall: …` + - `"server_error"` - A tool call to run a command on the local shell. + - `"rate_limit_exceeded"` - - `id: str` + - `message: str` - The unique ID of the local shell call. + A human-readable description of the error. - - `action: LocalShellCallAction` + - `metadata: Optional[Metadata]` - Execute a shell command on the server. + 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. - - `command: List[str]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The command to run. + - `object: Literal["thread.run.step"]` - - `env: Dict[str, str]` + The object type, which is always `thread.run.step`. - Environment variables to set for the command. + - `"thread.run.step"` - - `type: Literal["exec"]` + - `run_id: str` - The type of the local shell action. Always `exec`. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `"exec"` + - `status: Literal["in_progress", "cancelled", "failed", 2 more]` - - `timeout_ms: Optional[int]` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - Optional timeout in milliseconds for the command. + - `"in_progress"` - - `user: Optional[str]` + - `"cancelled"` - Optional user to run the command as. + - `"failed"` - - `working_directory: Optional[str]` + - `"completed"` - Optional working directory to run the command in. + - `"expired"` - - `call_id: str` + - `step_details: StepDetails` - The unique ID of the local shell tool call generated by the model. + The details of the run step. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `class MessageCreationStepDetails: …` - The status of the local shell call. + Details of the message creation by the run step. - - `"in_progress"` + - `message_creation: MessageCreation` - - `"completed"` + - `message_id: str` - - `"incomplete"` + The ID of the message that was created by this run step. - - `type: Literal["local_shell_call"]` + - `type: Literal["message_creation"]` - The type of the local shell call. Always `local_shell_call`. + Always `message_creation`. - - `"local_shell_call"` + - `"message_creation"` - - `agent: Optional[LocalShellCallAgent]` + - `class ToolCallsStepDetails: …` - The agent that produced this item. + Details of the tool call. - - `agent_name: str` + - `tool_calls: List[ToolCall]` - The canonical name of the agent that produced this item. + 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 LocalShellCallOutput: …` + - `class CodeInterpreterToolCall: …` - The output of a local shell tool call. + Details of the Code Interpreter tool call the run step was involved in. - `id: str` - The unique ID of the local shell tool call generated by the model. + The ID of the tool call. - - `output: str` + - `code_interpreter: CodeInterpreter` - A JSON string of the output of the local shell tool call. + The Code Interpreter tool call definition. - - `type: Literal["local_shell_call_output"]` + - `input: str` - The type of the local shell tool call output. Always `local_shell_call_output`. + The input to the Code Interpreter tool call. - - `"local_shell_call_output"` + - `outputs: List[CodeInterpreterOutput]` - - `agent: Optional[LocalShellCallOutputAgent]` + 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. - The agent that produced this item. + - `class CodeInterpreterOutputLogs: …` - - `agent_name: str` + Text output from the Code Interpreter tool call as part of a run step. - The canonical name of the agent that produced this item. + - `logs: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The text output from the Code Interpreter tool call. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `type: Literal["logs"]` - - `"in_progress"` + Always `logs`. - - `"completed"` + - `"logs"` - - `"incomplete"` + - `class CodeInterpreterOutputImage: …` - - `class BetaResponseFunctionShellToolCall: …` + - `image: CodeInterpreterOutputImageImage` - A tool call that executes one or more shell commands in a managed environment. + - `file_id: str` - - `id: str` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `type: Literal["image"]` - - `action: Action` + Always `image`. - The shell commands and limits that describe how to run the tool call. + - `"image"` - - `commands: List[str]` + - `type: Literal["code_interpreter"]` - - `max_output_length: Optional[int]` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - Optional maximum number of characters to return from each command. + - `"code_interpreter"` - - `timeout_ms: Optional[int]` + - `class FileSearchToolCall: …` - Optional timeout in milliseconds for the commands. + - `id: str` - - `call_id: str` + The ID of the tool call object. - The unique ID of the shell tool call generated by the model. + - `file_search: FileSearch` - - `environment: Optional[Environment]` + For now, this is always going to be an empty object. - Represents the use of a local environment to perform shell actions. + - `ranking_options: Optional[FileSearchRankingOptions]` - - `class BetaResponseLocalEnvironment: …` + The ranking options for the file search. - Represents the use of a local environment to perform shell actions. + - `ranker: Literal["auto", "default_2024_08_21"]` - - `type: Literal["local"]` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The environment type. Always `local`. + - `"auto"` - - `"local"` + - `"default_2024_08_21"` - - `class BetaResponseContainerReference: …` + - `score_threshold: float` - Represents a container created with /v1/containers. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `container_id: str` + - `results: Optional[List[FileSearchResult]]` - - `type: Literal["container_reference"]` + The results of the file search. - The environment type. Always `container_reference`. + - `file_id: str` - - `"container_reference"` + The ID of the file that result was found in. - - `status: Literal["in_progress", "completed", "incomplete"]` + - `file_name: str` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The name of the file that result was found in. - - `"in_progress"` + - `score: float` - - `"completed"` + The score of the result. All values must be a floating point number between 0 and 1. - - `"incomplete"` + - `content: Optional[List[FileSearchResultContent]]` - - `type: Literal["shell_call"]` + The content of the result that was found. The content is only included if requested via the include query parameter. - The type of the item. Always `shell_call`. + - `text: Optional[str]` - - `"shell_call"` + The text content of the file. - - `agent: Optional[Agent]` + - `type: Optional[Literal["text"]]` - The agent that produced this item. + The type of the content. - - `agent_name: str` + - `"text"` - The canonical name of the agent that produced this item. + - `type: Literal["file_search"]` - - `caller: Optional[Caller]` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The execution context that produced this tool call. + - `"file_search"` - - `class CallerDirect: …` + - `class FunctionToolCall: …` - - `type: Literal["direct"]` + - `id: str` - - `"direct"` + The ID of the tool call object. - - `class CallerProgram: …` + - `function: Function` - - `caller_id: str` + The definition of the function that was called. - The call ID of the program item that produced this tool call. + - `arguments: str` - - `type: Literal["program"]` + The arguments passed to the function. - - `"program"` + - `name: str` - - `created_by: Optional[str]` + The name of the function. - The ID of the entity that created this tool call. + - `output: Optional[str]` - - `class BetaResponseFunctionShellToolCallOutput: …` + 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. - The output of a shell tool call that was emitted. + - `type: Literal["function"]` - - `id: str` + The type of tool call. This is always going to be `function` for this type of tool call. - The unique ID of the shell call output. Populated when this item is returned via API. + - `"function"` - - `call_id: str` + - `type: Literal["tool_calls"]` - The unique ID of the shell tool call generated by the model. + Always `tool_calls`. - - `max_output_length: Optional[int]` + - `"tool_calls"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `thread_id: str` - - `output: List[Output]` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - An array of shell call output contents + - `type: Literal["message_creation", "tool_calls"]` - - `outcome: OutputOutcome` + The type of run step, which can be either `message_creation` or `tool_calls`. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `"message_creation"` - - `class OutputOutcomeTimeout: …` + - `"tool_calls"` - Indicates that the shell call exceeded its configured time limit. + - `usage: Optional[Usage]` - - `type: Literal["timeout"]` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - The outcome type. Always `timeout`. + - `completion_tokens: int` - - `"timeout"` + Number of completion tokens used over the course of the run step. - - `class OutputOutcomeExit: …` + - `prompt_tokens: int` - Indicates that the shell commands finished and returned an exit code. + Number of prompt tokens used over the course of the run step. - - `exit_code: int` + - `total_tokens: int` - Exit code from the shell process. + Total number of tokens used (prompt + completion). - - `type: Literal["exit"]` +### Example - The outcome type. Always `exit`. +```python +import os +from openai import OpenAI - - `"exit"` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +run_step = client.beta.threads.runs.steps.retrieve( + step_id="step_id", + thread_id="thread_id", + run_id="run_id", +) +print(run_step.id) +``` - - `stderr: str` +#### Response - The standard error output that was captured. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expired_at": 0, + "failed_at": 0, + "last_error": { + "code": "server_error", + "message": "message" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.run.step", + "run_id": "run_id", + "status": "in_progress", + "step_details": { + "message_creation": { + "message_id": "message_id" + }, + "type": "message_creation" + }, + "thread_id": "thread_id", + "type": "message_creation", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + } +} +``` - - `stdout: str` +### Example - The standard output that was captured. +```python +from openai import OpenAI +client = OpenAI() - - `created_by: Optional[str]` +run_step = client.beta.threads.runs.steps.retrieve( + thread_id="thread_abc123", + run_id="run_abc123", + step_id="step_abc123" +) - The identifier of the actor that created the item. +print(run_step) +``` - - `status: Literal["in_progress", "completed", "incomplete"]` +#### Response - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. +```json +{ + "id": "step_abc123", + "object": "thread.run.step", + "created_at": 1699063291, + "run_id": "run_abc123", + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "type": "message_creation", + "status": "completed", + "cancelled_at": null, + "completed_at": 1699063291, + "expired_at": null, + "failed_at": null, + "last_error": null, + "step_details": { + "type": "message_creation", + "message_creation": { + "message_id": "msg_abc123" + } + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + } +} +``` - - `"in_progress"` +## Domain Types - - `"completed"` +### Code Interpreter Logs - - `"incomplete"` +- `class CodeInterpreterLogs: …` - - `type: Literal["shell_call_output"]` + Text output from the Code Interpreter tool call as part of a run step. - The type of the shell call output. Always `shell_call_output`. + - `index: int` - - `"shell_call_output"` + The index of the output in the outputs array. - - `agent: Optional[Agent]` + - `type: Literal["logs"]` - The agent that produced this item. + Always `logs`. - - `agent_name: str` + - `"logs"` - The canonical name of the agent that produced this item. + - `logs: Optional[str]` - - `caller: Optional[Caller]` + The text output from the Code Interpreter tool call. - The execution context that produced this tool call. +### Code Interpreter Output Image - - `class CallerDirect: …` +- `class CodeInterpreterOutputImage: …` - - `type: Literal["direct"]` + - `index: int` - - `"direct"` + The index of the output in the outputs array. - - `class CallerProgram: …` + - `type: Literal["image"]` - - `caller_id: str` + Always `image`. - The call ID of the program item that produced this tool call. + - `"image"` - - `type: Literal["program"]` + - `image: Optional[Image]` - - `"program"` + - `file_id: Optional[str]` - - `created_by: Optional[str]` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The identifier of the actor that created the item. +### Code Interpreter Tool Call - - `class BetaResponseApplyPatchToolCall: …` +- `class CodeInterpreterToolCall: …` - A tool call that applies file diffs by creating, deleting, or updating files. + Details of the Code Interpreter tool call the run step was involved in. - `id: str` - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `call_id: str` - - The unique ID of the apply patch tool call generated by the model. - - - `operation: Operation` - - One of the create_file, delete_file, or update_file operations applied via apply_patch. - - - `class OperationCreateFile: …` - - Instruction describing how to create a file via the apply_patch tool. + The ID of the tool call. - - `diff: str` + - `code_interpreter: CodeInterpreter` - Diff to apply. + The Code Interpreter tool call definition. - - `path: str` + - `input: str` - Path of the file to create. + The input to the Code Interpreter tool call. - - `type: Literal["create_file"]` + - `outputs: List[CodeInterpreterOutput]` - Create a new file with the provided diff. + 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. - - `"create_file"` + - `class CodeInterpreterOutputLogs: …` - - `class OperationDeleteFile: …` + Text output from the Code Interpreter tool call as part of a run step. - Instruction describing how to delete a file via the apply_patch tool. + - `logs: str` - - `path: str` + The text output from the Code Interpreter tool call. - Path of the file to delete. + - `type: Literal["logs"]` - - `type: Literal["delete_file"]` + Always `logs`. - Delete the specified file. + - `"logs"` - - `"delete_file"` + - `class CodeInterpreterOutputImage: …` - - `class OperationUpdateFile: …` + - `image: CodeInterpreterOutputImageImage` - Instruction describing how to update a file via the apply_patch tool. + - `file_id: str` - - `diff: str` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - Diff to apply. + - `type: Literal["image"]` - - `path: str` + Always `image`. - Path of the file to update. + - `"image"` - - `type: Literal["update_file"]` + - `type: Literal["code_interpreter"]` - Update an existing file with the provided diff. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `"update_file"` + - `"code_interpreter"` - - `status: Literal["in_progress", "completed"]` +### Code Interpreter Tool Call Delta - The status of the apply patch tool call. One of `in_progress` or `completed`. +- `class CodeInterpreterToolCallDelta: …` - - `"in_progress"` + Details of the Code Interpreter tool call the run step was involved in. - - `"completed"` + - `index: int` - - `type: Literal["apply_patch_call"]` + The index of the tool call in the tool calls array. - The type of the item. Always `apply_patch_call`. + - `type: Literal["code_interpreter"]` - - `"apply_patch_call"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `agent: Optional[Agent]` + - `"code_interpreter"` - The agent that produced this item. + - `id: Optional[str]` - - `agent_name: str` + The ID of the tool call. - The canonical name of the agent that produced this item. + - `code_interpreter: Optional[CodeInterpreter]` - - `caller: Optional[Caller]` + The Code Interpreter tool call definition. - The execution context that produced this tool call. + - `input: Optional[str]` - - `class CallerDirect: …` + The input to the Code Interpreter tool call. - - `type: Literal["direct"]` + - `outputs: Optional[List[CodeInterpreterOutput]]` - - `"direct"` + 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 CallerProgram: …` + - `class CodeInterpreterLogs: …` - - `caller_id: str` + Text output from the Code Interpreter tool call as part of a run step. - The call ID of the program item that produced this tool call. + - `index: int` - - `type: Literal["program"]` + The index of the output in the outputs array. - - `"program"` + - `type: Literal["logs"]` - - `created_by: Optional[str]` + Always `logs`. - The ID of the entity that created this tool call. + - `"logs"` - - `class BetaResponseApplyPatchToolCallOutput: …` + - `logs: Optional[str]` - The output emitted by an apply patch tool call. + The text output from the Code Interpreter tool call. - - `id: str` + - `class CodeInterpreterOutputImage: …` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `index: int` - - `call_id: str` + The index of the output in the outputs array. - The unique ID of the apply patch tool call generated by the model. + - `type: Literal["image"]` - - `status: Literal["completed", "failed"]` + Always `image`. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"image"` - - `"completed"` + - `image: Optional[Image]` - - `"failed"` + - `file_id: Optional[str]` - - `type: Literal["apply_patch_call_output"]` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The type of the item. Always `apply_patch_call_output`. +### File Search Tool Call - - `"apply_patch_call_output"` +- `class FileSearchToolCall: …` - - `agent: Optional[Agent]` + - `id: str` - The agent that produced this item. + The ID of the tool call object. - - `agent_name: str` + - `file_search: FileSearch` - The canonical name of the agent that produced this item. + For now, this is always going to be an empty object. - - `caller: Optional[Caller]` + - `ranking_options: Optional[FileSearchRankingOptions]` - The execution context that produced this tool call. + The ranking options for the file search. - - `class CallerDirect: …` + - `ranker: Literal["auto", "default_2024_08_21"]` - - `type: Literal["direct"]` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"direct"` + - `"auto"` - - `class CallerProgram: …` + - `"default_2024_08_21"` - - `caller_id: str` + - `score_threshold: float` - The call ID of the program item that produced this tool call. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: Literal["program"]` + - `results: Optional[List[FileSearchResult]]` - - `"program"` + The results of the file search. - - `created_by: Optional[str]` + - `file_id: str` - The ID of the entity that created this tool call output. + The ID of the file that result was found in. - - `output: Optional[str]` + - `file_name: str` - Optional textual output returned by the apply patch tool. + The name of the file that result was found in. - - `class McpListTools: …` + - `score: float` - A list of tools available on an MCP server. + The score of the result. All values must be a floating point number between 0 and 1. - - `id: str` + - `content: Optional[List[FileSearchResultContent]]` - The unique ID of the list. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `server_label: str` + - `text: Optional[str]` - The label of the MCP server. + The text content of the file. - - `tools: List[McpListToolsTool]` + - `type: Optional[Literal["text"]]` - The tools available on the server. + The type of the content. - - `input_schema: object` + - `"text"` - The JSON schema describing the tool's input. + - `type: Literal["file_search"]` - - `name: str` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The name of the tool. + - `"file_search"` - - `annotations: Optional[object]` +### File Search Tool Call Delta - Additional annotations about the tool. +- `class FileSearchToolCallDelta: …` - - `description: Optional[str]` + - `file_search: object` - The description of the tool. + For now, this is always going to be an empty object. - - `type: Literal["mcp_list_tools"]` + - `index: int` - The type of the item. Always `mcp_list_tools`. + The index of the tool call in the tool calls array. - - `"mcp_list_tools"` + - `type: Literal["file_search"]` - - `agent: Optional[McpListToolsAgent]` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The agent that produced this item. + - `"file_search"` - - `agent_name: str` + - `id: Optional[str]` - The canonical name of the agent that produced this item. + The ID of the tool call object. - - `error: Optional[str]` +### Function Tool Call - Error message if the server could not list tools. +- `class FunctionToolCall: …` - - `class McpApprovalRequest: …` + - `id: str` - A request for human approval of a tool invocation. + The ID of the tool call object. - - `id: str` + - `function: Function` - The unique ID of the approval request. + The definition of the function that was called. - `arguments: str` - A JSON string of arguments for the tool. + The arguments passed to the function. - `name: str` - The name of the tool to run. - - - `server_label: str` - - The label of the MCP server making the request. - - - `type: Literal["mcp_approval_request"]` - - The type of the item. Always `mcp_approval_request`. - - - `"mcp_approval_request"` - - - `agent: Optional[McpApprovalRequestAgent]` - - The agent that produced this item. + The name of the function. - - `agent_name: str` + - `output: Optional[str]` - The canonical name of the agent that produced this item. + 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. - - `class McpApprovalResponse: …` + - `type: Literal["function"]` - A response to an MCP approval request. + The type of tool call. This is always going to be `function` for this type of tool call. - - `id: str` + - `"function"` - The unique ID of the approval response +### Function Tool Call Delta - - `approval_request_id: str` +- `class FunctionToolCallDelta: …` - The ID of the approval request being answered. + - `index: int` - - `approve: bool` + The index of the tool call in the tool calls array. - Whether the request was approved. + - `type: Literal["function"]` - - `type: Literal["mcp_approval_response"]` + The type of tool call. This is always going to be `function` for this type of tool call. - The type of the item. Always `mcp_approval_response`. + - `"function"` - - `"mcp_approval_response"` + - `id: Optional[str]` - - `agent: Optional[McpApprovalResponseAgent]` + The ID of the tool call object. - The agent that produced this item. + - `function: Optional[Function]` - - `agent_name: str` + The definition of the function that was called. - The canonical name of the agent that produced this item. + - `arguments: Optional[str]` - - `reason: Optional[str]` + The arguments passed to the function. - Optional reason for the decision. + - `name: Optional[str]` - - `class McpCall: …` + The name of the function. - An invocation of a tool on an MCP server. + - `output: Optional[str]` - - `id: 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. - The unique ID of the tool call. +### Message Creation Step Details - - `arguments: str` +- `class MessageCreationStepDetails: …` - A JSON string of the arguments passed to the tool. + Details of the message creation by the run step. - - `name: str` + - `message_creation: MessageCreation` - The name of the tool that was run. + - `message_id: str` - - `server_label: str` + The ID of the message that was created by this run step. - The label of the MCP server running the tool. + - `type: Literal["message_creation"]` - - `type: Literal["mcp_call"]` + Always `message_creation`. - The type of the item. Always `mcp_call`. + - `"message_creation"` - - `"mcp_call"` +### Run Step - - `agent: Optional[McpCallAgent]` +- `class RunStep: …` - The agent that produced this item. + Represents a step in execution of a run. - - `agent_name: str` + - `id: str` - The canonical name of the agent that produced this item. + The identifier of the run step, which can be referenced in API endpoints. - - `approval_request_id: Optional[str]` + - `assistant_id: str` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `error: Optional[str]` + - `cancelled_at: Optional[int]` - The error from the tool call, if any. + The Unix timestamp (in seconds) for when the run step was cancelled. - - `output: Optional[str]` + - `completed_at: Optional[int]` - The output from the tool call. + The Unix timestamp (in seconds) for when the run step completed. - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `created_at: int` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The Unix timestamp (in seconds) for when the run step was created. - - `"in_progress"` + - `expired_at: Optional[int]` - - `"completed"` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `"incomplete"` + - `failed_at: Optional[int]` - - `"calling"` + The Unix timestamp (in seconds) for when the run step failed. - - `"failed"` + - `last_error: Optional[LastError]` - - `class BetaResponseCustomToolCallItem: …` + The last error associated with this run step. Will be `null` if there are no errors. - A call to a custom tool created by the model. + - `code: Literal["server_error", "rate_limit_exceeded"]` - - `id: str` + One of `server_error` or `rate_limit_exceeded`. - The unique ID of the custom tool call item. + - `"server_error"` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `"rate_limit_exceeded"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `message: str` - - `"in_progress"` + A human-readable description of the error. - - `"completed"` + - `metadata: Optional[Metadata]` - - `"incomplete"` + 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. - - `created_by: Optional[str]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The identifier of the actor that created the item. + - `object: Literal["thread.run.step"]` - - `class BetaResponseCustomToolCallOutputItem: …` + The object type, which is always `thread.run.step`. - The output of a custom tool call from your code, being sent back to the model. + - `"thread.run.step"` - - `id: str` + - `run_id: str` - The unique ID of the custom tool call output item. + 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", "completed", "incomplete"]` + - `status: Literal["in_progress", "cancelled", "failed", 2 more]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - `"in_progress"` - - `"completed"` - - - `"incomplete"` - - - `created_by: Optional[str]` - - The identifier of the actor that created the item. - - - `first_id: str` - - The ID of the first item in the list. + - `"cancelled"` - - `has_more: bool` + - `"failed"` - Whether there are more items available. + - `"completed"` - - `last_id: str` + - `"expired"` - The ID of the last item in the list. + - `step_details: StepDetails` - - `object: Literal["list"]` + The details of the run step. - The type of object returned, must be `list`. + - `class MessageCreationStepDetails: …` - - `"list"` + Details of the message creation by the run step. -# Input Tokens + - `message_creation: MessageCreation` -## Get input token counts + - `message_id: str` -`beta.responses.input_tokens.count(InputTokenCountParams**kwargs) -> InputTokenCountResponse` + The ID of the message that was created by this run step. -**post** `/responses/input_tokens?beta=true` + - `type: Literal["message_creation"]` -Get input token counts + Always `message_creation`. -### Parameters + - `"message_creation"` -- `conversation: Optional[Conversation]` + - `class ToolCallsStepDetails: …` - The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. - Input items and output items from this response are automatically added to this conversation after this response completes. + Details of the tool call. - - `str` + - `tool_calls: List[ToolCall]` - The unique ID of the conversation. + 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 BetaResponseConversationParam: …` + - `class CodeInterpreterToolCall: …` - The conversation that this response belongs to. + Details of the Code Interpreter tool call the run step was involved in. - `id: str` - The unique ID of the conversation. - -- `input: Optional[Union[str, Iterable[BetaResponseInputItemParam], null]]` + The ID of the tool call. - Text, image, or file inputs to the model, used to generate a response + - `code_interpreter: CodeInterpreter` - - `str` + The Code Interpreter tool call definition. - A text input to the model, equivalent to a text input with the `user` role. + - `input: str` - - `Iterable[BetaResponseInputItemParam]` + The input to the Code Interpreter tool call. - A list of one or many input items to the model, containing different content types. + - `outputs: List[CodeInterpreterOutput]` - - `class BetaEasyInputMessage: …` + 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. - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `class CodeInterpreterOutputLogs: …` - - `content: Union[str, BetaResponseInputMessageContentList]` + Text output from the Code Interpreter tool call as part of a run step. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `logs: str` - - `str` + The text output from the Code Interpreter tool call. - A text input to the model. + - `type: Literal["logs"]` - - `List[BetaResponseInputContent]` + Always `logs`. - - `class BetaResponseInputText: …` + - `"logs"` - A text input to the model. + - `class CodeInterpreterOutputImage: …` - - `text: str` + - `image: CodeInterpreterOutputImageImage` - The text input to the model. + - `file_id: str` - - `type: Literal["input_text"]` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The type of the input item. Always `input_text`. + - `type: Literal["image"]` - - `"input_text"` + Always `image`. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `"image"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: Literal["code_interpreter"]` - - `mode: Literal["explicit"]` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The breakpoint mode. Always `explicit`. + - `"code_interpreter"` - - `"explicit"` + - `class FileSearchToolCall: …` - - `class BetaResponseInputImage: …` + - `id: str` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The ID of the tool call object. - - `detail: Literal["low", "high", "auto", "original"]` + - `file_search: FileSearch` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + For now, this is always going to be an empty object. - - `"low"` + - `ranking_options: Optional[FileSearchRankingOptions]` - - `"high"` + The ranking options for the file search. - - `"auto"` + - `ranker: Literal["auto", "default_2024_08_21"]` - - `"original"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `type: Literal["input_image"]` + - `"auto"` - The type of the input item. Always `input_image`. + - `"default_2024_08_21"` - - `"input_image"` + - `score_threshold: float` - - `file_id: Optional[str]` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The ID of the file to be sent to the model. + - `results: Optional[List[FileSearchResult]]` - - `image_url: Optional[str]` + The results of the file search. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `file_id: str` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The ID of the file that result was found in. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `file_name: str` - - `mode: Literal["explicit"]` + The name of the file that result was found in. - The breakpoint mode. Always `explicit`. + - `score: float` - - `"explicit"` + The score of the result. All values must be a floating point number between 0 and 1. - - `class BetaResponseInputFile: …` + - `content: Optional[List[FileSearchResultContent]]` - A file input to the model. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `type: Literal["input_file"]` + - `text: Optional[str]` - The type of the input item. Always `input_file`. + The text content of the file. - - `"input_file"` + - `type: Optional[Literal["text"]]` - - `detail: Optional[Literal["auto", "low", "high"]]` + The type of the content. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"text"` - - `"auto"` + - `type: Literal["file_search"]` - - `"low"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `"high"` + - `"file_search"` - - `file_data: Optional[str]` + - `class FunctionToolCall: …` - The content of the file to be sent to the model. + - `id: str` - - `file_id: Optional[str]` + The ID of the tool call object. - The ID of the file to be sent to the model. + - `function: Function` - - `file_url: Optional[str]` + The definition of the function that was called. - The URL of the file to be sent to the model. + - `arguments: str` - - `filename: Optional[str]` + The arguments passed to the function. - The name of the file to be sent to the model. + - `name: str` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The name of the function. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `output: Optional[str]` - - `mode: Literal["explicit"]` + 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. - The breakpoint mode. Always `explicit`. + - `type: Literal["function"]` - - `"explicit"` + The type of tool call. This is always going to be `function` for this type of tool call. - - `role: Literal["user", "assistant", "system", "developer"]` + - `"function"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `type: Literal["tool_calls"]` - - `"user"` + Always `tool_calls`. - - `"assistant"` + - `"tool_calls"` - - `"system"` + - `thread_id: str` - - `"developer"` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `phase: Optional[Literal["commentary"]]` + - `type: Literal["message_creation", "tool_calls"]` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `"commentary"` + - `"message_creation"` - - `type: Optional[Literal["message"]]` + - `"tool_calls"` - The type of the message input. Always `message`. + - `usage: Optional[Usage]` - - `"message"` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `class Message: …` + - `completion_tokens: int` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + Number of completion tokens used over the course of the run step. - - `content: BetaResponseInputMessageContentList` + - `prompt_tokens: int` - A list of one or many input items to the model, containing different content - types. + Number of prompt tokens used over the course of the run step. - - `class BetaResponseInputText: …` + - `total_tokens: int` - A text input to the model. + Total number of tokens used (prompt + completion). - - `class BetaResponseInputImage: …` +### Run Step Delta - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). +- `class RunStepDelta: …` - - `class BetaResponseInputFile: …` + The delta containing the fields that have changed on the run step. - A file input to the model. + - `step_details: Optional[StepDetails]` - - `role: Literal["user", "system", "developer"]` + The details of the run step. - The role of the message input. One of `user`, `system`, or `developer`. + - `class RunStepDeltaMessageDelta: …` - - `"user"` + Details of the message creation by the run step. - - `"system"` + - `type: Literal["message_creation"]` - - `"developer"` + Always `message_creation`. - - `agent: Optional[MessageAgent]` + - `"message_creation"` - The agent that produced this item. + - `message_creation: Optional[MessageCreation]` - - `agent_name: str` + - `message_id: Optional[str]` - The canonical name of the agent that produced this item. + The ID of the message that was created by this run step. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `class ToolCallDeltaObject: …` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Details of the tool call. - - `"in_progress"` + - `type: Literal["tool_calls"]` - - `"completed"` + Always `tool_calls`. - - `"incomplete"` + - `"tool_calls"` - - `type: Optional[Literal["message"]]` + - `tool_calls: Optional[List[ToolCallDelta]]` - The type of the message input. Always set to `message`. + 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`. - - `"message"` + - `class CodeInterpreterToolCallDelta: …` - - `class BetaResponseOutputMessage: …` + Details of the Code Interpreter tool call the run step was involved in. - An output message from the model. + - `index: int` - - `id: str` + The index of the tool call in the tool calls array. - The unique ID of the output message. + - `type: Literal["code_interpreter"]` - - `content: List[Content]` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The content of the output message. + - `"code_interpreter"` - - `class BetaResponseOutputText: …` + - `id: Optional[str]` - A text output from the model. + The ID of the tool call. - - `annotations: List[Annotation]` + - `code_interpreter: Optional[CodeInterpreter]` - The annotations of the text output. + The Code Interpreter tool call definition. - - `class AnnotationFileCitation: …` + - `input: Optional[str]` - A citation to a file. + The input to the Code Interpreter tool call. - - `file_id: str` + - `outputs: Optional[List[CodeInterpreterOutput]]` - The ID of the file. + 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. - - `filename: str` + - `class CodeInterpreterLogs: …` - The filename of the file cited. + Text output from the Code Interpreter tool call as part of a run step. - `index: int` - The index of the file in the list of files. + The index of the output in the outputs array. - - `type: Literal["file_citation"]` + - `type: Literal["logs"]` - The type of the file citation. Always `file_citation`. + Always `logs`. - - `"file_citation"` + - `"logs"` - - `class AnnotationURLCitation: …` + - `logs: Optional[str]` - A citation for a web resource used to generate a model response. + The text output from the Code Interpreter tool call. - - `end_index: int` + - `class CodeInterpreterOutputImage: …` - The index of the last character of the URL citation in the message. + - `index: int` - - `start_index: int` + The index of the output in the outputs array. - The index of the first character of the URL citation in the message. + - `type: Literal["image"]` - - `title: str` + Always `image`. - The title of the web resource. + - `"image"` - - `type: Literal["url_citation"]` + - `image: Optional[Image]` - The type of the URL citation. Always `url_citation`. + - `file_id: Optional[str]` - - `"url_citation"` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `url: str` + - `class FileSearchToolCallDelta: …` - The URL of the web resource. + - `file_search: object` - - `class AnnotationContainerFileCitation: …` + For now, this is always going to be an empty object. - A citation for a container file used to generate a model response. + - `index: int` - - `container_id: str` + The index of the tool call in the tool calls array. - The ID of the container file. + - `type: Literal["file_search"]` - - `end_index: int` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The index of the last character of the container file citation in the message. + - `"file_search"` - - `file_id: str` + - `id: Optional[str]` - The ID of the file. + The ID of the tool call object. - - `filename: str` + - `class FunctionToolCallDelta: …` - The filename of the container file cited. + - `index: int` - - `start_index: int` + The index of the tool call in the tool calls array. - The index of the first character of the container file citation in the message. + - `type: Literal["function"]` - - `type: Literal["container_file_citation"]` + The type of tool call. This is always going to be `function` for this type of tool call. - The type of the container file citation. Always `container_file_citation`. + - `"function"` - - `"container_file_citation"` + - `id: Optional[str]` - - `class AnnotationFilePath: …` + The ID of the tool call object. - A path to a file. + - `function: Optional[Function]` - - `file_id: str` + The definition of the function that was called. - The ID of the file. + - `arguments: Optional[str]` - - `index: int` + The arguments passed to the function. - The index of the file in the list of files. + - `name: Optional[str]` - - `type: Literal["file_path"]` + The name of the function. - The type of the file path. Always `file_path`. + - `output: Optional[str]` - - `"file_path"` + 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. - - `text: str` +### Run Step Delta Event - The text output from the model. +- `class RunStepDeltaEvent: …` - - `type: Literal["output_text"]` + Represents a run step delta i.e. any changed fields on a run step during streaming. - The type of the output text. Always `output_text`. + - `id: str` - - `"output_text"` + The identifier of the run step, which can be referenced in API endpoints. - - `logprobs: Optional[List[Logprob]]` + - `delta: RunStepDelta` - - `token: str` + The delta containing the fields that have changed on the run step. - - `bytes: List[int]` + - `step_details: Optional[StepDetails]` - - `logprob: float` + The details of the run step. - - `top_logprobs: List[LogprobTopLogprob]` + - `class RunStepDeltaMessageDelta: …` - - `token: str` + Details of the message creation by the run step. - - `bytes: List[int]` + - `type: Literal["message_creation"]` - - `logprob: float` + Always `message_creation`. - - `class BetaResponseOutputRefusal: …` + - `"message_creation"` - A refusal from the model. + - `message_creation: Optional[MessageCreation]` - - `refusal: str` + - `message_id: Optional[str]` - The refusal explanation from the model. + The ID of the message that was created by this run step. - - `type: Literal["refusal"]` + - `class ToolCallDeltaObject: …` - The type of the refusal. Always `refusal`. + Details of the tool call. - - `"refusal"` + - `type: Literal["tool_calls"]` - - `role: Literal["assistant"]` + Always `tool_calls`. - The role of the output message. Always `assistant`. + - `"tool_calls"` - - `"assistant"` + - `tool_calls: Optional[List[ToolCallDelta]]` - - `status: Literal["in_progress", "completed", "incomplete"]` + 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`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `class CodeInterpreterToolCallDelta: …` - - `"in_progress"` + Details of the Code Interpreter tool call the run step was involved in. - - `"completed"` + - `index: int` - - `"incomplete"` + The index of the tool call in the tool calls array. - - `type: Literal["message"]` + - `type: Literal["code_interpreter"]` - The type of the output message. Always `message`. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `"message"` + - `"code_interpreter"` - - `agent: Optional[Agent]` + - `id: Optional[str]` - The agent that produced this item. + The ID of the tool call. - - `agent_name: str` + - `code_interpreter: Optional[CodeInterpreter]` - The canonical name of the agent that produced this item. + The Code Interpreter tool call definition. - - `phase: Optional[Literal["commentary"]]` + - `input: Optional[str]` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The input to the Code Interpreter tool call. - - `"commentary"` + - `outputs: Optional[List[CodeInterpreterOutput]]` - - `class BetaResponseFileSearchToolCall: …` + 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. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `class CodeInterpreterLogs: …` - - `id: str` + Text output from the Code Interpreter tool call as part of a run step. - The unique ID of the file search tool call. + - `index: int` - - `queries: List[str]` + The index of the output in the outputs array. - The queries used to search for files. + - `type: Literal["logs"]` - - `status: Literal["in_progress", "searching", "completed", 2 more]` + Always `logs`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"logs"` - - `"in_progress"` + - `logs: Optional[str]` - - `"searching"` + The text output from the Code Interpreter tool call. - - `"completed"` + - `class CodeInterpreterOutputImage: …` - - `"incomplete"` + - `index: int` - - `"failed"` + The index of the output in the outputs array. - - `type: Literal["file_search_call"]` + - `type: Literal["image"]` - The type of the file search tool call. Always `file_search_call`. + Always `image`. - - `"file_search_call"` + - `"image"` - - `agent: Optional[Agent]` + - `image: Optional[Image]` - The agent that produced this item. + - `file_id: Optional[str]` - - `agent_name: str` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The canonical name of the agent that produced this item. + - `class FileSearchToolCallDelta: …` - - `results: Optional[List[Result]]` + - `file_search: object` - The results of the file search tool call. + For now, this is always going to be an empty object. - - `attributes: Optional[Dict[str, Union[str, float, bool]]]` + - `index: int` - 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, booleans, or numbers. + The index of the tool call in the tool calls array. - - `str` + - `type: Literal["file_search"]` - - `float` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `bool` + - `"file_search"` - - `file_id: Optional[str]` + - `id: Optional[str]` - The unique ID of the file. + The ID of the tool call object. - - `filename: Optional[str]` + - `class FunctionToolCallDelta: …` - The name of the file. + - `index: int` - - `score: Optional[float]` + The index of the tool call in the tool calls array. - The relevance score of the file - a value between 0 and 1. + - `type: Literal["function"]` - - `text: Optional[str]` + The type of tool call. This is always going to be `function` for this type of tool call. - The text that was retrieved from the file. + - `"function"` - - `class BetaResponseComputerToolCall: …` + - `id: Optional[str]` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The ID of the tool call object. - - `id: str` + - `function: Optional[Function]` - The unique ID of the computer call. + The definition of the function that was called. - - `call_id: str` + - `arguments: Optional[str]` - An identifier used when responding to the tool call with output. + The arguments passed to the function. - - `pending_safety_checks: List[PendingSafetyCheck]` + - `name: Optional[str]` - The pending safety checks for the computer call. + The name of the function. - - `id: str` + - `output: Optional[str]` - The ID of the pending safety check. + 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. - - `code: Optional[str]` + - `object: Literal["thread.run.step.delta"]` - The type of the pending safety check. + The object type, which is always `thread.run.step.delta`. - - `message: Optional[str]` + - `"thread.run.step.delta"` - Details about the pending safety check. +### Run Step Delta Message Delta - - `status: Literal["in_progress", "completed", "incomplete"]` +- `class RunStepDeltaMessageDelta: …` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Details of the message creation by the run step. - - `"in_progress"` + - `type: Literal["message_creation"]` - - `"completed"` + Always `message_creation`. - - `"incomplete"` + - `"message_creation"` - - `type: Literal["computer_call"]` + - `message_creation: Optional[MessageCreation]` - The type of the computer call. Always `computer_call`. + - `message_id: Optional[str]` - - `"computer_call"` + The ID of the message that was created by this run step. - - `action: Optional[BetaComputerAction]` +### Run Step Include - A click action. +- `Literal["step_details.tool_calls[*].file_search.results[*].content"]` - - `class Click: …` + - `"step_details.tool_calls[*].file_search.results[*].content"` - A click action. +### Tool Call - - `button: Literal["left", "right", "wheel", 2 more]` +- `ToolCall` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + Details of the Code Interpreter tool call the run step was involved in. - - `"left"` + - `class CodeInterpreterToolCall: …` - - `"right"` + Details of the Code Interpreter tool call the run step was involved in. - - `"wheel"` + - `id: str` - - `"back"` + The ID of the tool call. - - `"forward"` + - `code_interpreter: CodeInterpreter` - - `type: Literal["click"]` + The Code Interpreter tool call definition. - Specifies the event type. For a click action, this property is always `click`. + - `input: str` - - `"click"` + The input to the Code Interpreter tool call. - - `x: int` + - `outputs: List[CodeInterpreterOutput]` - The x-coordinate where the click occurred. + 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. - - `y: int` + - `class CodeInterpreterOutputLogs: …` - The y-coordinate where the click occurred. + Text output from the Code Interpreter tool call as part of a run step. - - `keys: Optional[List[str]]` + - `logs: str` - The keys being held while clicking. + The text output from the Code Interpreter tool call. - - `class DoubleClick: …` + - `type: Literal["logs"]` - A double click action. + Always `logs`. - - `keys: Optional[List[str]]` + - `"logs"` - The keys being held while double-clicking. + - `class CodeInterpreterOutputImage: …` - - `type: Literal["double_click"]` + - `image: CodeInterpreterOutputImageImage` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `file_id: str` - - `"double_click"` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `x: int` + - `type: Literal["image"]` - The x-coordinate where the double click occurred. + Always `image`. - - `y: int` + - `"image"` - The y-coordinate where the double click occurred. + - `type: Literal["code_interpreter"]` - - `class Drag: …` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - A drag action. + - `"code_interpreter"` - - `path: List[DragPath]` + - `class FileSearchToolCall: …` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `id: str` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The ID of the tool call object. - - `x: int` + - `file_search: FileSearch` - The x-coordinate. + For now, this is always going to be an empty object. - - `y: int` + - `ranking_options: Optional[FileSearchRankingOptions]` - The y-coordinate. + The ranking options for the file search. - - `type: Literal["drag"]` + - `ranker: Literal["auto", "default_2024_08_21"]` - Specifies the event type. For a drag action, this property is always set to `drag`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"drag"` + - `"auto"` - - `keys: Optional[List[str]]` + - `"default_2024_08_21"` - The keys being held while dragging the mouse. + - `score_threshold: float` - - `class Keypress: …` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - A collection of keypresses the model would like to perform. + - `results: Optional[List[FileSearchResult]]` - - `keys: List[str]` + The results of the file search. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `file_id: str` - - `type: Literal["keypress"]` + The ID of the file that result was found in. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `file_name: str` - - `"keypress"` + The name of the file that result was found in. - - `class Move: …` + - `score: float` - A mouse move action. + The score of the result. All values must be a floating point number between 0 and 1. - - `type: Literal["move"]` + - `content: Optional[List[FileSearchResultContent]]` - Specifies the event type. For a move action, this property is always set to `move`. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `"move"` + - `text: Optional[str]` - - `x: int` + The text content of the file. - The x-coordinate to move to. + - `type: Optional[Literal["text"]]` - - `y: int` + The type of the content. - The y-coordinate to move to. + - `"text"` - - `keys: Optional[List[str]]` + - `type: Literal["file_search"]` - The keys being held while moving the mouse. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `class Screenshot: …` + - `"file_search"` - A screenshot action. + - `class FunctionToolCall: …` - - `type: Literal["screenshot"]` + - `id: str` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The ID of the tool call object. - - `"screenshot"` + - `function: Function` - - `class Scroll: …` + The definition of the function that was called. - A scroll action. + - `arguments: str` - - `scroll_x: int` + The arguments passed to the function. - The horizontal scroll distance. + - `name: str` - - `scroll_y: int` + The name of the function. - The vertical scroll distance. + - `output: Optional[str]` - - `type: Literal["scroll"]` + 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. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `type: Literal["function"]` - - `"scroll"` + The type of tool call. This is always going to be `function` for this type of tool call. - - `x: int` + - `"function"` - The x-coordinate where the scroll occurred. +### Tool Call Delta - - `y: int` +- `ToolCallDelta` - The y-coordinate where the scroll occurred. + Details of the Code Interpreter tool call the run step was involved in. - - `keys: Optional[List[str]]` + - `class CodeInterpreterToolCallDelta: …` - The keys being held while scrolling. + Details of the Code Interpreter tool call the run step was involved in. - - `class Type: …` + - `index: int` - An action to type in text. + The index of the tool call in the tool calls array. - - `text: str` + - `type: Literal["code_interpreter"]` - The text to type. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `type: Literal["type"]` + - `"code_interpreter"` - Specifies the event type. For a type action, this property is always set to `type`. + - `id: Optional[str]` - - `"type"` + The ID of the tool call. - - `class Wait: …` + - `code_interpreter: Optional[CodeInterpreter]` - A wait action. + The Code Interpreter tool call definition. - - `type: Literal["wait"]` + - `input: Optional[str]` - Specifies the event type. For a wait action, this property is always set to `wait`. + The input to the Code Interpreter tool call. - - `"wait"` + - `outputs: Optional[List[CodeInterpreterOutput]]` - - `actions: Optional[BetaComputerActionList]` + 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. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `class CodeInterpreterLogs: …` - - `class Click: …` + Text output from the Code Interpreter tool call as part of a run step. - A click action. + - `index: int` - - `class DoubleClick: …` + The index of the output in the outputs array. - A double click action. + - `type: Literal["logs"]` - - `class Drag: …` + Always `logs`. - A drag action. + - `"logs"` - - `class Keypress: …` + - `logs: Optional[str]` - A collection of keypresses the model would like to perform. + The text output from the Code Interpreter tool call. - - `class Move: …` + - `class CodeInterpreterOutputImage: …` - A mouse move action. + - `index: int` - - `class Screenshot: …` + The index of the output in the outputs array. - A screenshot action. + - `type: Literal["image"]` - - `class Scroll: …` + Always `image`. - A scroll action. + - `"image"` - - `class Type: …` + - `image: Optional[Image]` - An action to type in text. + - `file_id: Optional[str]` - - `class Wait: …` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - A wait action. + - `class FileSearchToolCallDelta: …` - - `agent: Optional[Agent]` + - `file_search: object` - The agent that produced this item. + For now, this is always going to be an empty object. - - `agent_name: str` + - `index: int` - The canonical name of the agent that produced this item. + The index of the tool call in the tool calls array. - - `class ComputerCallOutput: …` + - `type: Literal["file_search"]` - The output of a computer tool call. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `call_id: str` + - `"file_search"` - The ID of the computer tool call that produced the output. + - `id: Optional[str]` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The ID of the tool call object. - A computer screenshot image used with the computer use tool. + - `class FunctionToolCallDelta: …` - - `type: Literal["computer_screenshot"]` + - `index: int` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The index of the tool call in the tool calls array. - - `"computer_screenshot"` + - `type: Literal["function"]` - - `file_id: Optional[str]` + The type of tool call. This is always going to be `function` for this type of tool call. - The identifier of an uploaded file that contains the screenshot. + - `"function"` - - `image_url: Optional[str]` + - `id: Optional[str]` - The URL of the screenshot image. + The ID of the tool call object. - - `type: Literal["computer_call_output"]` + - `function: Optional[Function]` - The type of the computer tool call output. Always `computer_call_output`. + The definition of the function that was called. - - `"computer_call_output"` + - `arguments: Optional[str]` - - `id: Optional[str]` + The arguments passed to the function. - The ID of the computer tool call output. + - `name: Optional[str]` - - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` + The name of the function. - The safety checks reported by the API that have been acknowledged by the developer. + - `output: Optional[str]` - - `id: 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. - The ID of the pending safety check. +### Tool Call Delta Object - - `code: Optional[str]` +- `class ToolCallDeltaObject: …` - The type of the pending safety check. + Details of the tool call. - - `message: Optional[str]` + - `type: Literal["tool_calls"]` - Details about the pending safety check. + Always `tool_calls`. - - `agent: Optional[ComputerCallOutputAgent]` + - `"tool_calls"` - The agent that produced this item. + - `tool_calls: Optional[List[ToolCallDelta]]` - - `agent_name: str` + 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`. - The canonical name of the agent that produced this item. + - `class CodeInterpreterToolCallDelta: …` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + Details of the Code Interpreter tool call the run step was involved in. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `index: int` - - `"in_progress"` + The index of the tool call in the tool calls array. - - `"completed"` + - `type: Literal["code_interpreter"]` - - `"incomplete"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `class BetaResponseFunctionWebSearch: …` + - `"code_interpreter"` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `id: Optional[str]` - - `id: str` + The ID of the tool call. - The unique ID of the web search tool call. + - `code_interpreter: Optional[CodeInterpreter]` - - `action: Action` + The Code Interpreter tool call definition. - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `input: Optional[str]` - - `class ActionSearch: …` + The input to the Code Interpreter tool call. - Action type "search" - Performs a web search query. + - `outputs: Optional[List[CodeInterpreterOutput]]` - - `type: Literal["search"]` + 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. - The action type. + - `class CodeInterpreterLogs: …` - - `"search"` + Text output from the Code Interpreter tool call as part of a run step. - - `queries: Optional[List[str]]` + - `index: int` - The search queries. + The index of the output in the outputs array. - - `query: Optional[str]` + - `type: Literal["logs"]` - The search query. + Always `logs`. - - `sources: Optional[List[ActionSearchSource]]` + - `"logs"` - The sources used in the search. + - `logs: Optional[str]` - - `type: Literal["url"]` + The text output from the Code Interpreter tool call. - The type of source. Always `url`. + - `class CodeInterpreterOutputImage: …` - - `"url"` + - `index: int` - - `url: str` + The index of the output in the outputs array. - The URL of the source. + - `type: Literal["image"]` - - `class ActionOpenPage: …` + Always `image`. - Action type "open_page" - Opens a specific URL from search results. + - `"image"` - - `type: Literal["open_page"]` + - `image: Optional[Image]` - The action type. + - `file_id: Optional[str]` - - `"open_page"` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `url: Optional[str]` + - `class FileSearchToolCallDelta: …` - The URL opened by the model. + - `file_search: object` - - `class ActionFindInPage: …` + For now, this is always going to be an empty object. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `index: int` - - `pattern: str` + The index of the tool call in the tool calls array. - The pattern or text to search for within the page. + - `type: Literal["file_search"]` - - `type: Literal["find_in_page"]` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The action type. + - `"file_search"` - - `"find_in_page"` + - `id: Optional[str]` - - `url: str` + The ID of the tool call object. - The URL of the page searched for the pattern. + - `class FunctionToolCallDelta: …` - - `status: Literal["in_progress", "searching", "completed", "failed"]` + - `index: int` - The status of the web search tool call. + The index of the tool call in the tool calls array. - - `"in_progress"` + - `type: Literal["function"]` - - `"searching"` + The type of tool call. This is always going to be `function` for this type of tool call. - - `"completed"` + - `"function"` - - `"failed"` + - `id: Optional[str]` - - `type: Literal["web_search_call"]` + The ID of the tool call object. - The type of the web search tool call. Always `web_search_call`. + - `function: Optional[Function]` - - `"web_search_call"` + The definition of the function that was called. - - `agent: Optional[Agent]` + - `arguments: Optional[str]` - The agent that produced this item. + The arguments passed to the function. - - `agent_name: str` + - `name: Optional[str]` - The canonical name of the agent that produced this item. + The name of the function. - - `class BetaResponseFunctionToolCall: …` + - `output: Optional[str]` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + 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. - - `arguments: str` +### Tool Calls Step Details - A JSON string of the arguments to pass to the function. +- `class ToolCallsStepDetails: …` - - `call_id: str` + Details of the tool call. - The unique ID of the function tool call generated by the model. + - `tool_calls: List[ToolCall]` - - `name: str` + 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`. - The name of the function to run. + - `class CodeInterpreterToolCall: …` - - `type: Literal["function_call"]` + Details of the Code Interpreter tool call the run step was involved in. - The type of the function tool call. Always `function_call`. + - `id: str` - - `"function_call"` + The ID of the tool call. - - `id: Optional[str]` + - `code_interpreter: CodeInterpreter` - The unique ID of the function tool call. + The Code Interpreter tool call definition. - - `agent: Optional[Agent]` + - `input: str` - The agent that produced this item. + The input to the Code Interpreter tool call. - - `agent_name: str` + - `outputs: List[CodeInterpreterOutput]` - The canonical name of the agent that produced this item. + 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. - - `caller: Optional[Caller]` + - `class CodeInterpreterOutputLogs: …` - The execution context that produced this tool call. + Text output from the Code Interpreter tool call as part of a run step. - - `class CallerDirect: …` + - `logs: str` - - `type: Literal["direct"]` + The text output from the Code Interpreter tool call. - - `"direct"` + - `type: Literal["logs"]` - - `class CallerProgram: …` + Always `logs`. - - `caller_id: str` + - `"logs"` - The call ID of the program item that produced this tool call. + - `class CodeInterpreterOutputImage: …` - - `type: Literal["program"]` + - `image: CodeInterpreterOutputImageImage` - - `"program"` + - `file_id: str` - - `namespace: Optional[str]` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The namespace of the function to run. + - `type: Literal["image"]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + Always `image`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"image"` - - `"in_progress"` + - `type: Literal["code_interpreter"]` - - `"completed"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `"incomplete"` + - `"code_interpreter"` - - `class FunctionCallOutput: …` + - `class FileSearchToolCall: …` - The output of a function tool call. + - `id: str` - - `call_id: str` + The ID of the tool call object. - The unique ID of the function tool call generated by the model. + - `file_search: FileSearch` - - `output: Union[str, BetaResponseFunctionCallOutputItemList]` + For now, this is always going to be an empty object. - Text, image, or file output of the function tool call. + - `ranking_options: Optional[FileSearchRankingOptions]` - - `str` + The ranking options for the file search. - A JSON string of the output of the function tool call. + - `ranker: Literal["auto", "default_2024_08_21"]` - - `List[BetaResponseFunctionCallOutputItem]` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `class BetaResponseInputTextContent: …` + - `"auto"` - A text input to the model. + - `"default_2024_08_21"` - - `text: str` + - `score_threshold: float` - The text input to the model. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: Literal["input_text"]` + - `results: Optional[List[FileSearchResult]]` - The type of the input item. Always `input_text`. + The results of the file search. - - `"input_text"` + - `file_id: str` - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + The ID of the file that result was found in. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `file_name: str` - - `mode: Literal["explicit"]` + The name of the file that result was found in. - The breakpoint mode. Always `explicit`. + - `score: float` - - `"explicit"` + The score of the result. All values must be a floating point number between 0 and 1. - - `class BetaResponseInputImageContent: …` + - `content: Optional[List[FileSearchResultContent]]` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The content of the result that was found. The content is only included if requested via the include query parameter. - - `type: Literal["input_image"]` + - `text: Optional[str]` - The type of the input item. Always `input_image`. + The text content of the file. - - `"input_image"` + - `type: Optional[Literal["text"]]` - - `detail: Optional[Literal["low", "high", "auto", "original"]]` + The type of the content. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"text"` - - `"low"` + - `type: Literal["file_search"]` - - `"high"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `"auto"` + - `"file_search"` - - `"original"` + - `class FunctionToolCall: …` - - `file_id: Optional[str]` + - `id: str` - The ID of the file to be sent to the model. + The ID of the tool call object. - - `image_url: Optional[str]` + - `function: Function` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The definition of the function that was called. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` + - `arguments: str` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The arguments passed to the function. - - `mode: Literal["explicit"]` + - `name: str` - The breakpoint mode. Always `explicit`. + The name of the function. - - `"explicit"` + - `output: Optional[str]` - - `class BetaResponseInputFileContent: …` + 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. - A file input to the model. + - `type: Literal["function"]` - - `type: Literal["input_file"]` + The type of tool call. This is always going to be `function` for this type of tool call. - The type of the input item. Always `input_file`. + - `"function"` - - `"input_file"` + - `type: Literal["tool_calls"]` - - `detail: Optional[Literal["auto", "low", "high"]]` + Always `tool_calls`. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"tool_calls"` - - `"auto"` +# Messages - - `"low"` +## List messages - - `"high"` +`beta.threads.messages.list(strthread_id, MessageListParams**kwargs) -> SyncCursorPage[Message]` - - `file_data: Optional[str]` +**get** `/threads/{thread_id}/messages` - The base64-encoded data of the file to be sent to the model. +Returns a list of messages for a given thread. - - `file_id: Optional[str]` +### Parameters - The ID of the file to be sent to the model. +- `thread_id: str` - - `file_url: Optional[str]` +- `after: Optional[str]` - The URL of the file to be sent to the model. + 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. - - `filename: Optional[str]` +- `before: Optional[str]` - The name of the file to be sent to the model. + 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. - - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` +- `limit: Optional[int]` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `mode: Literal["explicit"]` +- `order: Optional[Literal["asc", "desc"]]` - The breakpoint mode. Always `explicit`. + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `"explicit"` + - `"asc"` - - `type: Literal["function_call_output"]` + - `"desc"` - The type of the function tool call output. Always `function_call_output`. +- `run_id: Optional[str]` - - `"function_call_output"` + Filter messages by the run ID that generated them. - - `id: Optional[str]` +### Returns - The unique ID of the function tool call output. Populated when this item is returned via API. +- `class Message: …` - - `agent: Optional[FunctionCallOutputAgent]` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - The agent that produced this item. + - `id: str` - - `agent_name: str` + The identifier, which can be referenced in API endpoints. - The canonical name of the agent that produced this item. + - `assistant_id: Optional[str]` - - `caller: Optional[FunctionCallOutputCaller]` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - The execution context that produced this tool call. + - `attachments: Optional[List[Attachment]]` - - `class FunctionCallOutputCallerDirect: …` + A list of files attached to the message, and the tools they were added to. - - `type: Literal["direct"]` + - `file_id: Optional[str]` - The caller type. Always `direct`. + The ID of the file to attach to the message. - - `"direct"` + - `tools: Optional[List[AttachmentTool]]` - - `class FunctionCallOutputCallerProgram: …` + The tools to add this file to. - - `caller_id: str` + - `class CodeInterpreterTool: …` - The call ID of the program item that produced this tool call. + - `type: Literal["code_interpreter"]` - - `type: Literal["program"]` + The type of tool being defined: `code_interpreter` - The caller type. Always `program`. + - `"code_interpreter"` - - `"program"` + - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `type: Literal["file_search"]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The type of tool being defined: `file_search` - - `"in_progress"` + - `"file_search"` - - `"completed"` + - `completed_at: Optional[int]` - - `"incomplete"` + The Unix timestamp (in seconds) for when the message was completed. - - `class AgentMessage: …` + - `content: List[MessageContent]` - A message routed between agents. + The content of the message in array of text and/or images. - - `author: str` + - `class ImageFileContentBlock: …` - The sending agent identity. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `content: List[AgentMessageContent]` + - `image_file: ImageFile` - Plaintext, image, or encrypted content sent between agents. + - `file_id: str` - - `class BetaResponseInputTextContent: …` + 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. - A text input to the model. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `class BetaResponseInputImageContent: …` + 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`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"auto"` - - `class AgentMessageContentEncryptedContent: …` + - `"low"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"high"` - - `encrypted_content: str` + - `type: Literal["image_file"]` - Opaque encrypted content. + Always `image_file`. - - `type: Literal["encrypted_content"]` + - `"image_file"` - The type of the input item. Always `encrypted_content`. + - `class ImageURLContentBlock: …` - - `"encrypted_content"` + References an image URL in the content of a message. - - `recipient: str` + - `image_url: ImageURL` - The destination agent identity. + - `url: str` - - `type: Literal["agent_message"]` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The item type. Always `agent_message`. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"agent_message"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `id: Optional[str]` + - `"auto"` - The unique ID of this agent message item. + - `"low"` - - `agent: Optional[AgentMessageAgent]` + - `"high"` - The agent that produced this item. + - `type: Literal["image_url"]` - - `agent_name: str` + The type of the content part. - The canonical name of the agent that produced this item. + - `"image_url"` - - `class MultiAgentCall: …` + - `class TextContentBlock: …` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + The text content that is part of a message. - The multi-agent action that was executed. + - `text: Text` - - `"spawn_agent"` + - `annotations: List[Annotation]` - - `"interrupt_agent"` + - `class FileCitationAnnotation: …` - - `"list_agents"` + 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. - - `"send_message"` + - `end_index: int` - - `"followup_task"` + - `file_citation: FileCitation` - - `"wait_agent"` + - `file_id: str` - - `arguments: str` + The ID of the specific File the citation is from. - The action arguments as a JSON string. + - `start_index: int` - - `call_id: str` + - `text: str` - The unique ID linking this call to its output. + The text in the message content that needs to be replaced. - - `type: Literal["multi_agent_call"]` + - `type: Literal["file_citation"]` - The item type. Always `multi_agent_call`. + Always `file_citation`. - - `"multi_agent_call"` + - `"file_citation"` - - `id: Optional[str]` + - `class FilePathAnnotation: …` - The unique ID of this multi-agent call. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `agent: Optional[MultiAgentCallAgent]` + - `end_index: int` - The agent that produced this item. + - `file_path: FilePath` - - `agent_name: str` + - `file_id: str` - The canonical name of the agent that produced this item. + The ID of the file that was generated. - - `class MultiAgentCallOutput: …` + - `start_index: int` - - `action: Literal["spawn_agent", "interrupt_agent", "list_agents", 3 more]` + - `text: str` - The multi-agent action that produced this result. + The text in the message content that needs to be replaced. - - `"spawn_agent"` + - `type: Literal["file_path"]` - - `"interrupt_agent"` + Always `file_path`. - - `"list_agents"` + - `"file_path"` - - `"send_message"` + - `value: str` - - `"followup_task"` + The data that makes up the text. - - `"wait_agent"` + - `type: Literal["text"]` - - `call_id: str` + Always `text`. - The unique ID of the multi-agent call. + - `"text"` - - `output: List[MultiAgentCallOutputOutput]` + - `class RefusalContentBlock: …` - Text output returned by the multi-agent action. + The refusal content generated by the assistant. - - `text: str` + - `refusal: str` - The text content. + - `type: Literal["refusal"]` - - `type: Literal["output_text"]` + Always `refusal`. - The content type. Always `output_text`. + - `"refusal"` - - `"output_text"` + - `created_at: int` - - `annotations: Optional[Union[List[MultiAgentCallOutputOutputAnnotationsUnionMember0], List[MultiAgentCallOutputOutputAnnotationsUnionMember1], List[MultiAgentCallOutputOutputAnnotationsUnionMember2], null]]` + The Unix timestamp (in seconds) for when the message was created. - Citations associated with the text content. + - `incomplete_at: Optional[int]` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember0]` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `file_id: str` + - `incomplete_details: Optional[IncompleteDetails]` - The ID of the file. + On an incomplete message, details about why the message is incomplete. - - `filename: str` + - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` - The filename of the file cited. + The reason the message is incomplete. - - `index: int` + - `"content_filter"` - The index of the file in the list of files. + - `"max_tokens"` - - `type: Literal["file_citation"]` + - `"run_cancelled"` - The citation type. Always `file_citation`. + - `"run_expired"` - - `"file_citation"` + - `"run_failed"` - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember1]` + - `metadata: Optional[Metadata]` - - `end_index: int` + 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. - The index of the last character of the citation in the message. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `start_index: int` + - `object: Literal["thread.message"]` - The index of the first character of the citation in the message. + The object type, which is always `thread.message`. - - `title: str` + - `"thread.message"` - The title of the cited resource. + - `role: Literal["user", "assistant"]` - - `type: Literal["url_citation"]` + The entity that produced the message. One of `user` or `assistant`. - The citation type. Always `url_citation`. + - `"user"` - - `"url_citation"` + - `"assistant"` - - `url: str` + - `run_id: Optional[str]` - The URL of the cited resource. + 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. - - `List[MultiAgentCallOutputOutputAnnotationsUnionMember2]` + - `status: Literal["in_progress", "incomplete", "completed"]` - - `container_id: str` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - The ID of the container. + - `"in_progress"` - - `end_index: int` + - `"incomplete"` - The index of the last character of the citation in the message. + - `"completed"` - - `file_id: str` + - `thread_id: str` - The ID of the container file. + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `filename: str` +### Example - The filename of the container file cited. +```python +import os +from openai import OpenAI - - `start_index: int` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +page = client.beta.threads.messages.list( + thread_id="thread_id", +) +page = page.data[0] +print(page.id) +``` - The index of the first character of the citation in the message. +#### Response - - `type: Literal["container_file_citation"]` +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" + } + ], + "first_id": "msg_abc123", + "has_more": false, + "last_id": "msg_abc123", + "object": "list" +} +``` - The citation type. Always `container_file_citation`. +### Example - - `"container_file_citation"` +```python +from openai import OpenAI +client = OpenAI() - - `type: Literal["multi_agent_call_output"]` +thread_messages = client.beta.threads.messages.list("thread_abc123") +print(thread_messages.data) +``` - The item type. Always `multi_agent_call_output`. +#### Response - - `"multi_agent_call_output"` +```json +{ + "object": "list", + "data": [ + { + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699016383, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + }, + { + "id": "msg_abc456", + "object": "thread.message", + "created_at": 1699016383, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "Hello, what is AI?", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc456", + "has_more": false +} +``` - - `id: Optional[str]` +## Create message - The unique ID of this multi-agent call output. +`beta.threads.messages.create(strthread_id, MessageCreateParams**kwargs) -> Message` - - `agent: Optional[MultiAgentCallOutputAgent]` +**post** `/threads/{thread_id}/messages` - The agent that produced this item. +Create a message. - - `agent_name: str` +### Parameters - The canonical name of the agent that produced this item. +- `thread_id: str` - - `class ToolSearchCall: …` +- `content: Union[str, Iterable[MessageContentPartParam]]` - - `arguments: object` + The text contents of the message. - The arguments supplied to the tool search call. + - `str` - - `type: Literal["tool_search_call"]` + The text contents of the message. - The item type. Always `tool_search_call`. + - `Iterable[MessageContentPartParam]` - - `"tool_search_call"` + An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](https://platform.openai.com/docs/models). - - `id: Optional[str]` + - `class ImageFileContentBlock: …` - The unique ID of this tool search call. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `agent: Optional[ToolSearchCallAgent]` + - `image_file: ImageFile` - The agent that produced this item. + - `file_id: str` - - `agent_name: 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. - The canonical name of the agent that produced this item. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `call_id: Optional[str]` + 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`. - The unique ID of the tool search call generated by the model. + - `"auto"` - - `execution: Optional[Literal["server", "client"]]` + - `"low"` - Whether tool search was executed by the server or by the client. + - `"high"` - - `"server"` + - `type: Literal["image_file"]` - - `"client"` + Always `image_file`. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"image_file"` - The status of the tool search call. + - `class ImageURLContentBlock: …` - - `"in_progress"` + References an image URL in the content of a message. - - `"completed"` + - `image_url: ImageURL` - - `"incomplete"` + - `url: str` - - `class BetaResponseToolSearchOutputItemParam: …` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `tools: List[BetaTool]` + - `detail: Optional[Literal["auto", "low", "high"]]` - The loaded tool definitions returned by the tool search output. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `class BetaFunctionTool: …` + - `"auto"` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `"low"` - - `name: str` + - `"high"` - The name of the function to call. + - `type: Literal["image_url"]` - - `parameters: Optional[Dict[str, object]]` + The type of the content part. - A JSON schema object describing the parameters of the function. + - `"image_url"` - - `strict: Optional[bool]` + - `class TextContentBlockParam: …` - Whether strict parameter validation is enforced for this function tool. + The text content that is part of a message. - - `type: Literal["function"]` + - `text: str` - The type of the function tool. Always `function`. + Text content to be sent to the model - - `"function"` + - `type: Literal["text"]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + Always `text`. - The tool invocation context(s). + - `"text"` - - `"direct"` +- `role: Literal["user", "assistant"]` - - `"programmatic"` + The role of the entity that is creating the message. Allowed values include: - - `defer_loading: Optional[bool]` + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. - Whether this function is deferred and loaded via tool search. + - `"user"` - - `description: Optional[str]` + - `"assistant"` - A description of the function. Used by the model to determine whether or not to call the function. +- `attachments: Optional[Iterable[Attachment]]` - - `output_schema: Optional[Dict[str, object]]` + A list of files attached to the message, and the tools they should be added to. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `file_id: Optional[str]` - - `class BetaFileSearchTool: …` + The ID of the file to attach to the message. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `tools: Optional[Iterable[AttachmentTool]]` - - `type: Literal["file_search"]` + The tools to add this file to. - The type of the file search tool. Always `file_search`. + - `class CodeInterpreterTool: …` - - `"file_search"` + - `type: Literal["code_interpreter"]` - - `vector_store_ids: List[str]` + The type of tool being defined: `code_interpreter` - The IDs of the vector stores to search. + - `"code_interpreter"` - - `filters: Optional[Filters]` + - `class AttachmentToolFileSearch: …` - A filter to apply. + - `type: Literal["file_search"]` - - `class FiltersComparisonFilter: …` + The type of tool being defined: `file_search` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"file_search"` - - `key: str` +- `metadata: Optional[Metadata]` - The key to compare against the value. + 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. - - `type: Literal["eq", "ne", "gt", 5 more]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. +### Returns - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in +- `class Message: …` - - `"eq"` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"ne"` + - `id: str` - - `"gt"` + The identifier, which can be referenced in API endpoints. - - `"gte"` + - `assistant_id: Optional[str]` - - `"lt"` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `"lte"` + - `attachments: Optional[List[Attachment]]` - - `"in"` + A list of files attached to the message, and the tools they were added to. - - `"nin"` + - `file_id: Optional[str]` - - `value: Union[str, float, bool, List[object]]` + The ID of the file to attach to the message. - The value to compare against the attribute key; supports string, number, or boolean types. + - `tools: Optional[List[AttachmentTool]]` - - `str` + The tools to add this file to. - - `float` + - `class CodeInterpreterTool: …` - - `bool` + - `type: Literal["code_interpreter"]` - - `List[object]` + The type of tool being defined: `code_interpreter` - - `class FiltersCompoundFilter: …` + - `"code_interpreter"` - Combine multiple filters using `and` or `or`. + - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` - - `filters: List[FiltersCompoundFilterFilter]` + - `type: Literal["file_search"]` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The type of tool being defined: `file_search` - - `class FiltersCompoundFilterFilterComparisonFilter: …` + - `"file_search"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `completed_at: Optional[int]` - - `key: str` + The Unix timestamp (in seconds) for when the message was completed. - The key to compare against the value. + - `content: List[MessageContent]` - - `type: Literal["eq", "ne", "gt", 5 more]` + The content of the message in array of text and/or images. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `class ImageFileContentBlock: …` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `"eq"` + - `image_file: ImageFile` - - `"ne"` + - `file_id: str` - - `"gt"` + 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. - - `"gte"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"lt"` + 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`. - - `"lte"` + - `"auto"` - - `"in"` + - `"low"` - - `"nin"` + - `"high"` - - `value: Union[str, float, bool, List[object]]` + - `type: Literal["image_file"]` - The value to compare against the attribute key; supports string, number, or boolean types. + Always `image_file`. - - `str` + - `"image_file"` - - `float` + - `class ImageURLContentBlock: …` - - `bool` + References an image URL in the content of a message. - - `List[object]` + - `image_url: ImageURL` - - `object` + - `url: str` - - `type: Literal["and", "or"]` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Type of operation: `and` or `or`. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"and"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `"or"` + - `"auto"` - - `max_num_results: Optional[int]` + - `"low"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"high"` - - `ranking_options: Optional[RankingOptions]` + - `type: Literal["image_url"]` - Ranking options for search. + The type of the content part. - - `hybrid_search: Optional[RankingOptionsHybridSearch]` + - `"image_url"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `class TextContentBlock: …` - - `embedding_weight: float` + The text content that is part of a message. - The weight of the embedding in the reciprocal ranking fusion. + - `text: Text` - - `text_weight: float` + - `annotations: List[Annotation]` - The weight of the text in the reciprocal ranking fusion. + - `class FileCitationAnnotation: …` - - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` + 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. - The ranker to use for the file search. + - `end_index: int` - - `"auto"` + - `file_citation: FileCitation` - - `"default-2024-11-15"` + - `file_id: str` - - `score_threshold: Optional[float]` + The ID of the specific File the citation is from. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `start_index: int` - - `class BetaComputerTool: …` + - `text: str` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The text in the message content that needs to be replaced. - - `type: Literal["computer"]` + - `type: Literal["file_citation"]` - The type of the computer tool. Always `computer`. + Always `file_citation`. - - `"computer"` + - `"file_citation"` - - `class BetaComputerUsePreviewTool: …` + - `class FilePathAnnotation: …` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `display_height: int` + - `end_index: int` - The height of the computer display. + - `file_path: FilePath` - - `display_width: int` + - `file_id: str` - The width of the computer display. + The ID of the file that was generated. - - `environment: Literal["windows", "mac", "linux", 2 more]` + - `start_index: int` - The type of computer environment to control. + - `text: str` - - `"windows"` + The text in the message content that needs to be replaced. - - `"mac"` + - `type: Literal["file_path"]` - - `"linux"` + Always `file_path`. - - `"ubuntu"` + - `"file_path"` - - `"browser"` + - `value: str` - - `type: Literal["computer_use_preview"]` + The data that makes up the text. - The type of the computer use tool. Always `computer_use_preview`. + - `type: Literal["text"]` - - `"computer_use_preview"` + Always `text`. - - `class BetaWebSearchTool: …` + - `"text"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class RefusalContentBlock: …` - - `type: Literal["web_search", "web_search_2025_08_26"]` + The refusal content generated by the assistant. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `refusal: str` - - `"web_search"` + - `type: Literal["refusal"]` - - `"web_search_2025_08_26"` + Always `refusal`. - - `filters: Optional[Filters]` + - `"refusal"` - Filters for the search. + - `created_at: int` - - `allowed_domains: Optional[List[str]]` + The Unix timestamp (in seconds) for when the message was created. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `incomplete_at: Optional[int]` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + - `incomplete_details: Optional[IncompleteDetails]` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + On an incomplete message, details about why the message is incomplete. - - `"low"` + - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` - - `"medium"` + The reason the message is incomplete. - - `"high"` + - `"content_filter"` - - `user_location: Optional[UserLocation]` + - `"max_tokens"` - The approximate location of the user. + - `"run_cancelled"` - - `city: Optional[str]` + - `"run_expired"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"run_failed"` - - `country: Optional[str]` + - `metadata: Optional[Metadata]` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + 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. - - `region: Optional[str]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Free text input for the region of the user, e.g. `California`. + - `object: Literal["thread.message"]` - - `timezone: Optional[str]` + The object type, which is always `thread.message`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"thread.message"` - - `type: Optional[Literal["approximate"]]` + - `role: Literal["user", "assistant"]` - The type of location approximation. Always `approximate`. + The entity that produced the message. One of `user` or `assistant`. - - `"approximate"` + - `"user"` - - `class Mcp: …` + - `"assistant"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `run_id: Optional[str]` - - `server_label: 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. - A label for this MCP server, used to identify it in tool calls. + - `status: Literal["in_progress", "incomplete", "completed"]` - - `type: Literal["mcp"]` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - The type of the MCP tool. Always `mcp`. + - `"in_progress"` - - `"mcp"` + - `"incomplete"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `"completed"` - The tool invocation context(s). + - `thread_id: str` - - `"direct"` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `"programmatic"` +### Example - - `allowed_tools: Optional[McpAllowedTools]` +```python +import os +from openai import OpenAI - List of allowed tool names or a filter object. +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +message = client.beta.threads.messages.create( + thread_id="thread_id", + content="string", + role="user", +) +print(message.id) +``` - - `List[str]` +#### Response - A string array of allowed tool names +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` - - `class McpAllowedToolsMcpToolFilter: …` +### Example - A filter object to specify which tools are allowed. +```python +from openai import OpenAI +client = OpenAI() - - `read_only: Optional[bool]` +thread_message = client.beta.threads.messages.create( + "thread_abc123", + role="user", + content="How does AI work? Explain it in simple terms.", +) +print(thread_message) +``` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. +#### Response - - `tool_names: Optional[List[str]]` +```json +{ + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1713226573, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} +} +``` - List of allowed tool names. +## Modify message - - `authorization: Optional[str]` +`beta.threads.messages.update(strmessage_id, MessageUpdateParams**kwargs) -> Message` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. +**post** `/threads/{thread_id}/messages/{message_id}` - - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` +Modifies a message. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). +### Parameters - Currently supported `connector_id` values are: +- `thread_id: str` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` +- `message_id: str` - - `"connector_dropbox"` +- `metadata: Optional[Metadata]` - - `"connector_gmail"` + 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. - - `"connector_googlecalendar"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"connector_googledrive"` +### Returns - - `"connector_microsoftteams"` +- `class Message: …` - - `"connector_outlookcalendar"` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"connector_outlookemail"` + - `id: str` - - `"connector_sharepoint"` + The identifier, which can be referenced in API endpoints. - - `defer_loading: Optional[bool]` + - `assistant_id: Optional[str]` - Whether this MCP tool is deferred and discovered via tool search. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `headers: Optional[Dict[str, str]]` + - `attachments: Optional[List[Attachment]]` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + A list of files attached to the message, and the tools they were added to. - - `require_approval: Optional[McpRequireApproval]` + - `file_id: Optional[str]` - Specify which of the MCP server's tools require approval. + The ID of the file to attach to the message. - - `class McpRequireApprovalMcpToolApprovalFilter: …` + - `tools: Optional[List[AttachmentTool]]` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The tools to add this file to. - - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` + - `class CodeInterpreterTool: …` - A filter object to specify which tools are allowed. + - `type: Literal["code_interpreter"]` - - `read_only: Optional[bool]` + The type of tool being defined: `code_interpreter` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"code_interpreter"` - - `tool_names: Optional[List[str]]` + - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` - List of allowed tool names. + - `type: Literal["file_search"]` - - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` + The type of tool being defined: `file_search` - A filter object to specify which tools are allowed. + - `"file_search"` - - `read_only: Optional[bool]` + - `completed_at: Optional[int]` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The Unix timestamp (in seconds) for when the message was completed. - - `tool_names: Optional[List[str]]` + - `content: List[MessageContent]` - List of allowed tool names. + The content of the message in array of text and/or images. - - `Literal["always", "never"]` + - `class ImageFileContentBlock: …` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `"always"` + - `image_file: ImageFile` - - `"never"` + - `file_id: str` - - `server_description: 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. - Optional description of the MCP server, used to provide more context. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `server_url: Optional[str]` + 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`. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"auto"` - - `tunnel_id: Optional[str]` + - `"low"` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `"high"` - - `class CodeInterpreter: …` + - `type: Literal["image_file"]` - A tool that runs Python code to help generate a response to a prompt. + Always `image_file`. - - `container: CodeInterpreterContainer` + - `"image_file"` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `class ImageURLContentBlock: …` - - `str` + References an image URL in the content of a message. - The container ID. + - `image_url: ImageURL` - - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` + - `url: str` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `type: Literal["auto"]` + - `detail: Optional[Literal["auto", "low", "high"]]` - Always `auto`. + 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"` - - `file_ids: Optional[List[str]]` - - An optional list of uploaded files to make available to your code. + - `"low"` - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `"high"` - The memory limit for the code interpreter container. + - `type: Literal["image_url"]` - - `"1g"` + The type of the content part. - - `"4g"` + - `"image_url"` - - `"16g"` + - `class TextContentBlock: …` - - `"64g"` + The text content that is part of a message. - - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` + - `text: Text` - Network access policy for the container. + - `annotations: List[Annotation]` - - `class BetaContainerNetworkPolicyDisabled: …` + - `class FileCitationAnnotation: …` - - `type: Literal["disabled"]` + 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. - Disable outbound network access. Always `disabled`. + - `end_index: int` - - `"disabled"` + - `file_citation: FileCitation` - - `class BetaContainerNetworkPolicyAllowlist: …` + - `file_id: str` - - `allowed_domains: List[str]` + The ID of the specific File the citation is from. - A list of allowed domains when type is `allowlist`. + - `start_index: int` - - `type: Literal["allowlist"]` + - `text: str` - Allow outbound network access only to specified domains. Always `allowlist`. + The text in the message content that needs to be replaced. - - `"allowlist"` + - `type: Literal["file_citation"]` - - `domain_secrets: Optional[List[BetaContainerNetworkPolicyDomainSecret]]` + Always `file_citation`. - Optional domain-scoped secrets for allowlisted domains. + - `"file_citation"` - - `domain: str` + - `class FilePathAnnotation: …` - The domain associated with the secret. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `name: str` + - `end_index: int` - The name of the secret to inject for the domain. + - `file_path: FilePath` - - `value: str` + - `file_id: str` - The secret value to inject for the domain. + The ID of the file that was generated. - - `type: Literal["code_interpreter"]` + - `start_index: int` - The type of the code interpreter tool. Always `code_interpreter`. + - `text: str` - - `"code_interpreter"` + The text in the message content that needs to be replaced. - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `type: Literal["file_path"]` - The tool invocation context(s). + Always `file_path`. - - `"direct"` + - `"file_path"` - - `"programmatic"` + - `value: str` - - `class ProgrammaticToolCalling: …` + The data that makes up the text. - - `type: Literal["programmatic_tool_calling"]` + - `type: Literal["text"]` - The type of the tool. Always `programmatic_tool_calling`. + Always `text`. - - `"programmatic_tool_calling"` + - `"text"` - - `class ImageGeneration: …` + - `class RefusalContentBlock: …` - A tool that generates images using the GPT image models. + The refusal content generated by the assistant. - - `type: Literal["image_generation"]` + - `refusal: str` - The type of the image generation tool. Always `image_generation`. + - `type: Literal["refusal"]` - - `"image_generation"` + Always `refusal`. - - `action: Optional[Literal["generate", "edit", "auto"]]` + - `"refusal"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `created_at: int` - - `"generate"` + The Unix timestamp (in seconds) for when the message was created. - - `"edit"` + - `incomplete_at: Optional[int]` - - `"auto"` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `background: Optional[Literal["transparent", "opaque", "auto"]]` + - `incomplete_details: Optional[IncompleteDetails]` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + On an incomplete message, details about why the message is incomplete. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The reason the message is incomplete. - - `"transparent"` + - `"content_filter"` - - `"opaque"` + - `"max_tokens"` - - `"auto"` + - `"run_cancelled"` - - `input_fidelity: Optional[Literal["high", "low"]]` + - `"run_expired"` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `"run_failed"` - - `"high"` + - `metadata: Optional[Metadata]` - - `"low"` + 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. - - `input_image_mask: Optional[ImageGenerationInputImageMask]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `object: Literal["thread.message"]` - - `file_id: Optional[str]` + The object type, which is always `thread.message`. - File ID for the mask image. + - `"thread.message"` - - `image_url: Optional[str]` + - `role: Literal["user", "assistant"]` - Base64-encoded mask image. + The entity that produced the message. One of `user` or `assistant`. - - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more], null]]` + - `"user"` - The image generation model to use. Default: `gpt-image-1`. + - `"assistant"` - - `str` + - `run_id: Optional[str]` - - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 3 more]` + 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. - The image generation model to use. Default: `gpt-image-1`. + - `status: Literal["in_progress", "incomplete", "completed"]` - - `"gpt-image-1"` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `"gpt-image-1-mini"` + - `"in_progress"` - - `"gpt-image-2"` + - `"incomplete"` - - `"gpt-image-2-2026-04-21"` + - `"completed"` - - `"gpt-image-1.5"` + - `thread_id: str` - - `"chatgpt-image-latest"` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `moderation: Optional[Literal["auto", "low"]]` +### Example - Moderation level for the generated image. Default: `auto`. +```python +import os +from openai import OpenAI - - `"auto"` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +message = client.beta.threads.messages.update( + message_id="message_id", + thread_id="thread_id", +) +print(message.id) +``` - - `"low"` +#### Response - - `output_compression: Optional[int]` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` - Compression level for the output image. Default: 100. +### Example - - `output_format: Optional[Literal["png", "webp", "jpeg"]]` +```python +from openai import OpenAI +client = OpenAI() - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. +message = client.beta.threads.messages.update( + message_id="msg_abc12", + thread_id="thread_abc123", + metadata={ + "modified": "true", + "user": "abc123", + }, +) +print(message) +``` - - `"png"` +#### Response - - `"webp"` +```json +{ + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "file_ids": [], + "metadata": { + "modified": "true", + "user": "abc123" + } +} +``` - - `"jpeg"` +## Retrieve message - - `partial_images: Optional[int]` +`beta.threads.messages.retrieve(strmessage_id, MessageRetrieveParams**kwargs) -> Message` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. +**get** `/threads/{thread_id}/messages/{message_id}` - - `quality: Optional[Literal["low", "medium", "high", "auto"]]` +Retrieve a message. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. +### Parameters - - `"low"` +- `thread_id: str` - - `"medium"` +- `message_id: str` - - `"high"` +### Returns - - `"auto"` +- `class Message: …` - - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `id: str` - - `str` + The identifier, which can be referenced in API endpoints. - - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` + - `assistant_id: Optional[str]` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `"1024x1024"` + - `attachments: Optional[List[Attachment]]` - - `"1024x1536"` + A list of files attached to the message, and the tools they were added to. - - `"1536x1024"` + - `file_id: Optional[str]` - - `"auto"` + The ID of the file to attach to the message. - - `class LocalShell: …` + - `tools: Optional[List[AttachmentTool]]` - A tool that allows the model to execute shell commands in a local environment. + The tools to add this file to. - - `type: Literal["local_shell"]` + - `class CodeInterpreterTool: …` - The type of the local shell tool. Always `local_shell`. + - `type: Literal["code_interpreter"]` - - `"local_shell"` + The type of tool being defined: `code_interpreter` - - `class BetaFunctionShellTool: …` + - `"code_interpreter"` - A tool that allows the model to execute shell commands. + - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` - - `type: Literal["shell"]` + - `type: Literal["file_search"]` - The type of the shell tool. Always `shell`. + The type of tool being defined: `file_search` - - `"shell"` + - `"file_search"` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `completed_at: Optional[int]` - The tool invocation context(s). + The Unix timestamp (in seconds) for when the message was completed. - - `"direct"` + - `content: List[MessageContent]` - - `"programmatic"` + The content of the message in array of text and/or images. - - `environment: Optional[Environment]` + - `class ImageFileContentBlock: …` - - `class BetaContainerAuto: …` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `type: Literal["container_auto"]` + - `image_file: ImageFile` - Automatically creates a container for this request + - `file_id: str` - - `"container_auto"` + 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. - - `file_ids: Optional[List[str]]` + - `detail: Optional[Literal["auto", "low", "high"]]` - An optional list of uploaded files to make available to your code. + 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`. - - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` + - `"auto"` - The memory limit for the container. + - `"low"` - - `"1g"` + - `"high"` - - `"4g"` + - `type: Literal["image_file"]` - - `"16g"` + Always `image_file`. - - `"64g"` + - `"image_file"` - - `network_policy: Optional[NetworkPolicy]` + - `class ImageURLContentBlock: …` - Network access policy for the container. + References an image URL in the content of a message. - - `class BetaContainerNetworkPolicyDisabled: …` + - `image_url: ImageURL` - - `class BetaContainerNetworkPolicyAllowlist: …` + - `url: str` - - `skills: Optional[List[Skill]]` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - An optional list of skills referenced by id or inline data. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `class BetaSkillReference: …` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `skill_id: str` + - `"auto"` - The ID of the referenced skill. + - `"low"` - - `type: Literal["skill_reference"]` + - `"high"` - References a skill created with the /v1/skills endpoint. + - `type: Literal["image_url"]` - - `"skill_reference"` + The type of the content part. - - `version: Optional[str]` + - `"image_url"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `class TextContentBlock: …` - - `class BetaInlineSkill: …` + The text content that is part of a message. - - `description: str` + - `text: Text` - The description of the skill. + - `annotations: List[Annotation]` - - `name: str` + - `class FileCitationAnnotation: …` - The name of the skill. + 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. - - `source: BetaInlineSkillSource` + - `end_index: int` - Inline skill payload + - `file_citation: FileCitation` - - `data: str` + - `file_id: str` - Base64-encoded skill zip bundle. + The ID of the specific File the citation is from. - - `media_type: Literal["application/zip"]` + - `start_index: int` - The media type of the inline skill payload. Must be `application/zip`. + - `text: str` - - `"application/zip"` + The text in the message content that needs to be replaced. - - `type: Literal["base64"]` + - `type: Literal["file_citation"]` - The type of the inline skill source. Must be `base64`. + Always `file_citation`. - - `"base64"` + - `"file_citation"` - - `type: Literal["inline"]` + - `class FilePathAnnotation: …` - Defines an inline skill for this request. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"inline"` + - `end_index: int` - - `class BetaLocalEnvironment: …` + - `file_path: FilePath` - - `type: Literal["local"]` + - `file_id: str` - Use a local computer environment. + The ID of the file that was generated. - - `"local"` + - `start_index: int` - - `skills: Optional[List[BetaLocalSkill]]` + - `text: str` - An optional list of skills. + The text in the message content that needs to be replaced. - - `description: str` + - `type: Literal["file_path"]` - The description of the skill. + Always `file_path`. - - `name: str` + - `"file_path"` - The name of the skill. + - `value: str` - - `path: str` + The data that makes up the text. - The path to the directory containing the skill. + - `type: Literal["text"]` - - `class BetaContainerReference: …` + Always `text`. - - `container_id: str` + - `"text"` - The ID of the referenced container. + - `class RefusalContentBlock: …` - - `type: Literal["container_reference"]` + The refusal content generated by the assistant. - References a container created with the /v1/containers endpoint + - `refusal: str` - - `"container_reference"` + - `type: Literal["refusal"]` - - `class BetaCustomTool: …` + Always `refusal`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `"refusal"` - - `name: str` + - `created_at: int` - The name of the custom tool, used to identify it in tool calls. + The Unix timestamp (in seconds) for when the message was created. - - `type: Literal["custom"]` + - `incomplete_at: Optional[int]` - The type of the custom tool. Always `custom`. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `"custom"` + - `incomplete_details: Optional[IncompleteDetails]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + On an incomplete message, details about why the message is incomplete. - The tool invocation context(s). + - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` - - `"direct"` + The reason the message is incomplete. - - `"programmatic"` + - `"content_filter"` - - `defer_loading: Optional[bool]` + - `"max_tokens"` - Whether this tool should be deferred and discovered via tool search. + - `"run_cancelled"` - - `description: Optional[str]` + - `"run_expired"` - Optional description of the custom tool, used to provide more context. + - `"run_failed"` - - `format: Optional[Format]` + - `metadata: Optional[Metadata]` - The input format for the custom tool. Default is unconstrained text. + 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. - - `class FormatText: …` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Unconstrained free-form text. + - `object: Literal["thread.message"]` - - `type: Literal["text"]` + The object type, which is always `thread.message`. - Unconstrained text format. Always `text`. + - `"thread.message"` - - `"text"` + - `role: Literal["user", "assistant"]` - - `class FormatGrammar: …` + The entity that produced the message. One of `user` or `assistant`. - A grammar defined by the user. + - `"user"` - - `definition: str` + - `"assistant"` - The grammar definition. + - `run_id: Optional[str]` - - `syntax: Literal["lark", "regex"]` + 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. - The syntax of the grammar definition. One of `lark` or `regex`. + - `status: Literal["in_progress", "incomplete", "completed"]` - - `"lark"` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `"regex"` + - `"in_progress"` - - `type: Literal["grammar"]` + - `"incomplete"` - Grammar format. Always `grammar`. + - `"completed"` - - `"grammar"` + - `thread_id: str` - - `class BetaNamespaceTool: …` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - Groups function/custom tools under a shared namespace. +### Example - - `description: str` +```python +import os +from openai import OpenAI - A description of the namespace shown to the model. +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +message = client.beta.threads.messages.retrieve( + message_id="message_id", + thread_id="thread_id", +) +print(message.id) +``` - - `name: str` +#### Response - The namespace name used in tool calls (for example, `crm`). +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` - - `tools: List[Tool]` +### Example - The function/custom tools available inside this namespace. +```python +from openai import OpenAI +client = OpenAI() - - `class ToolFunction: …` +message = client.beta.threads.messages.retrieve( + message_id="msg_abc123", + thread_id="thread_abc123", +) +print(message) +``` - - `name: str` +#### Response - - `type: Literal["function"]` +```json +{ + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} +} +``` - - `"function"` +## Delete message - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` +`beta.threads.messages.delete(strmessage_id, MessageDeleteParams**kwargs) -> MessageDeleted` - The tool invocation context(s). +**delete** `/threads/{thread_id}/messages/{message_id}` - - `"direct"` +Deletes a message. - - `"programmatic"` +### Parameters - - `defer_loading: Optional[bool]` +- `thread_id: str` - Whether this function should be deferred and discovered via tool search. +- `message_id: str` - - `description: Optional[str]` +### Returns - - `output_schema: Optional[Dict[str, object]]` +- `class MessageDeleted: …` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `id: str` - - `parameters: Optional[object]` + - `deleted: bool` - - `strict: Optional[bool]` + - `object: Literal["thread.message.deleted"]` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `"thread.message.deleted"` - - `class BetaCustomTool: …` +### Example - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) +```python +import os +from openai import OpenAI - - `type: Literal["namespace"]` +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +message_deleted = client.beta.threads.messages.delete( + message_id="message_id", + thread_id="thread_id", +) +print(message_deleted.id) +``` - The type of the tool. Always `namespace`. +#### Response - - `"namespace"` +```json +{ + "id": "id", + "deleted": true, + "object": "thread.message.deleted" +} +``` - - `class BetaToolSearchTool: …` +### Example - Hosted or BYOT tool search configuration for deferred tools. +```python +from openai import OpenAI +client = OpenAI() - - `type: Literal["tool_search"]` +deleted_message = client.beta.threads.messages.delete( + message_id="msg_abc12", + thread_id="thread_abc123", +) +print(deleted_message) +``` - The type of the tool. Always `tool_search`. +#### Response - - `"tool_search"` +```json +{ + "id": "msg_abc123", + "object": "thread.message.deleted", + "deleted": true +} +``` - - `description: Optional[str]` +## Domain Types - Description shown to the model for a client-executed tool search tool. +### Annotation - - `execution: Optional[Literal["server", "client"]]` +- `Annotation` - Whether tool search is executed by the server or by the client. + 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. - - `"server"` + - `class FileCitationAnnotation: …` - - `"client"` + 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. - - `parameters: Optional[object]` + - `end_index: int` - Parameter schema for a client-executed tool search tool. + - `file_citation: FileCitation` - - `class BetaWebSearchPreviewTool: …` + - `file_id: str` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The ID of the specific File the citation is from. - - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` + - `start_index: int` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `text: str` - - `"web_search_preview"` + The text in the message content that needs to be replaced. - - `"web_search_preview_2025_03_11"` + - `type: Literal["file_citation"]` - - `search_content_types: Optional[List[Literal["text", "image"]]]` + Always `file_citation`. - - `"text"` + - `"file_citation"` - - `"image"` + - `class FilePathAnnotation: …` - - `search_context_size: Optional[Literal["low", "medium", "high"]]` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `end_index: int` - - `"low"` + - `file_path: FilePath` - - `"medium"` + - `file_id: str` - - `"high"` + The ID of the file that was generated. - - `user_location: Optional[UserLocation]` + - `start_index: int` - The user's location. + - `text: str` - - `type: Literal["approximate"]` + The text in the message content that needs to be replaced. - The type of location approximation. Always `approximate`. + - `type: Literal["file_path"]` - - `"approximate"` + Always `file_path`. - - `city: Optional[str]` + - `"file_path"` - Free text input for the city of the user, e.g. `San Francisco`. +### Annotation Delta - - `country: Optional[str]` +- `AnnotationDelta` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + 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. - - `region: Optional[str]` + - `class FileCitationDeltaAnnotation: …` - Free text input for the region of the user, e.g. `California`. + 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. - - `timezone: Optional[str]` + - `index: int` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The index of the annotation in the text content part. - - `class BetaApplyPatchTool: …` + - `type: Literal["file_citation"]` - Allows the assistant to create, delete, or update files using unified diffs. + Always `file_citation`. - - `type: Literal["apply_patch"]` + - `"file_citation"` - The type of the tool. Always `apply_patch`. + - `end_index: Optional[int]` - - `"apply_patch"` + - `file_citation: Optional[FileCitation]` - - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` + - `file_id: Optional[str]` - The tool invocation context(s). + The ID of the specific File the citation is from. - - `"direct"` + - `quote: Optional[str]` - - `"programmatic"` + The specific quote in the file. - - `type: Literal["tool_search_output"]` + - `start_index: Optional[int]` - The item type. Always `tool_search_output`. + - `text: Optional[str]` - - `"tool_search_output"` + The text in the message content that needs to be replaced. - - `id: Optional[str]` + - `class FilePathDeltaAnnotation: …` - The unique ID of this tool search output. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `agent: Optional[Agent]` + - `index: int` - The agent that produced this item. + The index of the annotation in the text content part. - - `agent_name: str` + - `type: Literal["file_path"]` - The canonical name of the agent that produced this item. + Always `file_path`. - - `call_id: Optional[str]` + - `"file_path"` - The unique ID of the tool search call generated by the model. + - `end_index: Optional[int]` - - `execution: Optional[Literal["server", "client"]]` + - `file_path: Optional[FilePath]` - Whether tool search was executed by the server or by the client. + - `file_id: Optional[str]` - - `"server"` + The ID of the file that was generated. - - `"client"` + - `start_index: Optional[int]` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `text: Optional[str]` - The status of the tool search output. + The text in the message content that needs to be replaced. - - `"in_progress"` +### File Citation Annotation - - `"completed"` +- `class FileCitationAnnotation: …` - - `"incomplete"` + 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. - - `class AdditionalTools: …` + - `end_index: int` - - `role: Literal["developer"]` + - `file_citation: FileCitation` - The role that provided the additional tools. Only `developer` is supported. + - `file_id: str` - - `"developer"` + The ID of the specific File the citation is from. - - `tools: List[BetaTool]` + - `start_index: int` - A list of additional tools made available at this item. + - `text: str` - - `class BetaFunctionTool: …` + The text in the message content that needs to be replaced. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `type: Literal["file_citation"]` - - `class BetaFileSearchTool: …` + Always `file_citation`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `"file_citation"` - - `class BetaComputerTool: …` +### File Citation Delta Annotation - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +- `class FileCitationDeltaAnnotation: …` - - `class BetaComputerUsePreviewTool: …` + 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. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `index: int` - - `class BetaWebSearchTool: …` + The index of the annotation in the text content part. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `type: Literal["file_citation"]` - - `class Mcp: …` + Always `file_citation`. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"file_citation"` - - `class CodeInterpreter: …` + - `end_index: Optional[int]` - A tool that runs Python code to help generate a response to a prompt. + - `file_citation: Optional[FileCitation]` - - `class ProgrammaticToolCalling: …` + - `file_id: Optional[str]` - - `class ImageGeneration: …` + The ID of the specific File the citation is from. - A tool that generates images using the GPT image models. + - `quote: Optional[str]` - - `class LocalShell: …` + The specific quote in the file. - A tool that allows the model to execute shell commands in a local environment. + - `start_index: Optional[int]` - - `class BetaFunctionShellTool: …` + - `text: Optional[str]` - A tool that allows the model to execute shell commands. + The text in the message content that needs to be replaced. - - `class BetaCustomTool: …` +### File Path Annotation - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) +- `class FilePathAnnotation: …` - - `class BetaNamespaceTool: …` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - Groups function/custom tools under a shared namespace. + - `end_index: int` - - `class BetaToolSearchTool: …` + - `file_path: FilePath` - Hosted or BYOT tool search configuration for deferred tools. + - `file_id: str` - - `class BetaWebSearchPreviewTool: …` + The ID of the file that was generated. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `start_index: int` - - `class BetaApplyPatchTool: …` + - `text: str` - Allows the assistant to create, delete, or update files using unified diffs. + The text in the message content that needs to be replaced. - - `type: Literal["additional_tools"]` + - `type: Literal["file_path"]` - The item type. Always `additional_tools`. + Always `file_path`. - - `"additional_tools"` + - `"file_path"` - - `id: Optional[str]` +### File Path Delta Annotation - The unique ID of this additional tools item. +- `class FilePathDeltaAnnotation: …` - - `agent: Optional[AdditionalToolsAgent]` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The agent that produced this item. + - `index: int` - - `agent_name: str` + The index of the annotation in the text content part. - The canonical name of the agent that produced this item. + - `type: Literal["file_path"]` - - `class BetaResponseReasoningItem: …` + Always `file_path`. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `"file_path"` - - `id: str` + - `end_index: Optional[int]` - The unique identifier of the reasoning content. + - `file_path: Optional[FilePath]` - - `summary: List[Summary]` + - `file_id: Optional[str]` - Reasoning summary content. + The ID of the file that was generated. - - `text: str` + - `start_index: Optional[int]` - A summary of the reasoning output from the model so far. + - `text: Optional[str]` - - `type: Literal["summary_text"]` + The text in the message content that needs to be replaced. - The type of the object. Always `summary_text`. +### Image File - - `"summary_text"` +- `class ImageFile: …` - - `type: Literal["reasoning"]` + - `file_id: str` - The type of the object. Always `reasoning`. + 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. - - `"reasoning"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `agent: Optional[Agent]` + 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`. - The agent that produced this item. + - `"auto"` - - `agent_name: str` + - `"low"` - The canonical name of the agent that produced this item. + - `"high"` - - `content: Optional[List[Content]]` +### Image File Content Block - Reasoning text content. +- `class ImageFileContentBlock: …` - - `text: str` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The reasoning text from the model. + - `image_file: ImageFile` - - `type: Literal["reasoning_text"]` + - `file_id: str` - The type of the reasoning text. Always `reasoning_text`. + 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. - - `"reasoning_text"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `encrypted_content: Optional[str]` + 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`. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"auto"` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"low"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"high"` - - `"in_progress"` + - `type: Literal["image_file"]` - - `"completed"` + Always `image_file`. - - `"incomplete"` + - `"image_file"` - - `class BetaResponseCompactionItemParam: …` +### Image File Delta - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). +- `class ImageFileDelta: …` - - `encrypted_content: str` + - `detail: Optional[Literal["auto", "low", "high"]]` - The encrypted content of the compaction summary. + 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`. - - `type: Literal["compaction"]` + - `"auto"` - The type of the item. Always `compaction`. + - `"low"` - - `"compaction"` + - `"high"` - - `id: Optional[str]` + - `file_id: Optional[str]` - The ID of the compaction item. + 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. - - `agent: Optional[Agent]` +### Image File Delta Block - The agent that produced this item. +- `class ImageFileDeltaBlock: …` - - `agent_name: str` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The canonical name of the agent that produced this item. + - `index: int` - - `class ImageGenerationCall: …` + The index of the content part in the message. - An image generation request made by the model. + - `type: Literal["image_file"]` - - `id: str` + Always `image_file`. - The unique ID of the image generation call. + - `"image_file"` - - `result: Optional[str]` + - `image_file: Optional[ImageFileDelta]` - The generated image encoded in base64. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `status: Literal["in_progress", "completed", "generating", "failed"]` + 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`. - The status of the image generation call. + - `"auto"` - - `"in_progress"` + - `"low"` - - `"completed"` + - `"high"` - - `"generating"` + - `file_id: Optional[str]` - - `"failed"` + 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. - - `type: Literal["image_generation_call"]` +### Image URL - The type of the image generation call. Always `image_generation_call`. +- `class ImageURL: …` - - `"image_generation_call"` + - `url: str` - - `agent: Optional[ImageGenerationCallAgent]` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The agent that produced this item. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `agent_name: str` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - The canonical name of the agent that produced this item. + - `"auto"` - - `class BetaResponseCodeInterpreterToolCall: …` + - `"low"` - A tool call to run code. + - `"high"` - - `id: str` +### Image URL Content Block - The unique ID of the code interpreter tool call. +- `class ImageURLContentBlock: …` - - `code: Optional[str]` + References an image URL in the content of a message. - The code to run, or null if not available. + - `image_url: ImageURL` - - `container_id: str` + - `url: str` - The ID of the container used to run the code. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `outputs: Optional[List[Output]]` + - `detail: Optional[Literal["auto", "low", "high"]]` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `class OutputLogs: …` + - `"auto"` - The logs output from the code interpreter. + - `"low"` - - `logs: str` + - `"high"` - The logs output from the code interpreter. + - `type: Literal["image_url"]` - - `type: Literal["logs"]` + The type of the content part. - The type of the output. Always `logs`. + - `"image_url"` - - `"logs"` +### Image URL Delta - - `class OutputImage: …` +- `class ImageURLDelta: …` - The image output from the code interpreter. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `type: Literal["image"]` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The type of the output. Always `image`. + - `"auto"` - - `"image"` + - `"low"` - - `url: str` + - `"high"` - The URL of the image output from the code interpreter. + - `url: Optional[str]` - - `status: Literal["in_progress", "completed", "incomplete", 2 more]` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. +### Image URL Delta Block - - `"in_progress"` +- `class ImageURLDeltaBlock: …` - - `"completed"` + References an image URL in the content of a message. - - `"incomplete"` + - `index: int` - - `"interpreting"` + The index of the content part in the message. - - `"failed"` + - `type: Literal["image_url"]` - - `type: Literal["code_interpreter_call"]` + Always `image_url`. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `"image_url"` - - `"code_interpreter_call"` + - `image_url: Optional[ImageURLDelta]` - - `agent: Optional[Agent]` + - `detail: Optional[Literal["auto", "low", "high"]]` - The agent that produced this item. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `agent_name: str` + - `"auto"` - The canonical name of the agent that produced this item. + - `"low"` - - `class LocalShellCall: …` + - `"high"` - A tool call to run a command on the local shell. + - `url: Optional[str]` - - `id: str` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The unique ID of the local shell call. +### Message - - `action: LocalShellCallAction` +- `class Message: …` - Execute a shell command on the server. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `command: List[str]` + - `id: str` - The command to run. + The identifier, which can be referenced in API endpoints. - - `env: Dict[str, str]` + - `assistant_id: Optional[str]` - Environment variables to set for the command. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `type: Literal["exec"]` + - `attachments: Optional[List[Attachment]]` - The type of the local shell action. Always `exec`. + A list of files attached to the message, and the tools they were added to. - - `"exec"` + - `file_id: Optional[str]` - - `timeout_ms: Optional[int]` + The ID of the file to attach to the message. - Optional timeout in milliseconds for the command. + - `tools: Optional[List[AttachmentTool]]` - - `user: Optional[str]` + The tools to add this file to. - Optional user to run the command as. + - `class CodeInterpreterTool: …` - - `working_directory: Optional[str]` + - `type: Literal["code_interpreter"]` - Optional working directory to run the command in. + The type of tool being defined: `code_interpreter` - - `call_id: str` + - `"code_interpreter"` - The unique ID of the local shell tool call generated by the model. + - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` - - `status: Literal["in_progress", "completed", "incomplete"]` + - `type: Literal["file_search"]` - The status of the local shell call. + The type of tool being defined: `file_search` - - `"in_progress"` + - `"file_search"` - - `"completed"` + - `completed_at: Optional[int]` - - `"incomplete"` + The Unix timestamp (in seconds) for when the message was completed. - - `type: Literal["local_shell_call"]` + - `content: List[MessageContent]` - The type of the local shell call. Always `local_shell_call`. + The content of the message in array of text and/or images. - - `"local_shell_call"` + - `class ImageFileContentBlock: …` - - `agent: Optional[LocalShellCallAgent]` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The agent that produced this item. + - `image_file: ImageFile` - - `agent_name: str` + - `file_id: str` - The canonical name of the agent that produced this item. + 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 LocalShellCallOutput: …` + - `detail: Optional[Literal["auto", "low", "high"]]` - The output of a local shell tool call. + 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`. - - `id: str` + - `"auto"` - The unique ID of the local shell tool call generated by the model. + - `"low"` - - `output: str` + - `"high"` - A JSON string of the output of the local shell tool call. + - `type: Literal["image_file"]` - - `type: Literal["local_shell_call_output"]` + Always `image_file`. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `"image_file"` - - `"local_shell_call_output"` + - `class ImageURLContentBlock: …` - - `agent: Optional[LocalShellCallOutputAgent]` + References an image URL in the content of a message. - The agent that produced this item. + - `image_url: ImageURL` - - `agent_name: str` + - `url: str` - The canonical name of the agent that produced this item. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `detail: Optional[Literal["auto", "low", "high"]]` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `"in_progress"` + - `"auto"` - - `"completed"` + - `"low"` - - `"incomplete"` + - `"high"` - - `class ShellCall: …` + - `type: Literal["image_url"]` - A tool representing a request to execute one or more shell commands. + The type of the content part. - - `action: ShellCallAction` + - `"image_url"` - The shell commands and limits that describe how to run the tool call. + - `class TextContentBlock: …` - - `commands: List[str]` + The text content that is part of a message. - Ordered shell commands for the execution environment to run. + - `text: Text` - - `max_output_length: Optional[int]` + - `annotations: List[Annotation]` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `class FileCitationAnnotation: …` - - `timeout_ms: Optional[int]` + 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. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `end_index: int` - - `call_id: str` + - `file_citation: FileCitation` - The unique ID of the shell tool call generated by the model. + - `file_id: str` - - `type: Literal["shell_call"]` + The ID of the specific File the citation is from. - The type of the item. Always `shell_call`. + - `start_index: int` - - `"shell_call"` + - `text: str` - - `id: Optional[str]` + The text in the message content that needs to be replaced. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `type: Literal["file_citation"]` - - `agent: Optional[ShellCallAgent]` + Always `file_citation`. - The agent that produced this item. + - `"file_citation"` - - `agent_name: str` + - `class FilePathAnnotation: …` - The canonical name of the agent that produced this item. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `caller: Optional[ShellCallCaller]` + - `end_index: int` - The execution context that produced this tool call. + - `file_path: FilePath` - - `class ShellCallCallerDirect: …` + - `file_id: str` - - `type: Literal["direct"]` + The ID of the file that was generated. - The caller type. Always `direct`. + - `start_index: int` - - `"direct"` + - `text: str` - - `class ShellCallCallerProgram: …` + The text in the message content that needs to be replaced. - - `caller_id: str` + - `type: Literal["file_path"]` - The call ID of the program item that produced this tool call. + Always `file_path`. - - `type: Literal["program"]` + - `"file_path"` - The caller type. Always `program`. + - `value: str` - - `"program"` + The data that makes up the text. - - `environment: Optional[ShellCallEnvironment]` + - `type: Literal["text"]` - The environment to execute the shell commands in. + Always `text`. - - `class BetaLocalEnvironment: …` + - `"text"` - - `class BetaContainerReference: …` + - `class RefusalContentBlock: …` - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + The refusal content generated by the assistant. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `refusal: str` - - `"in_progress"` + - `type: Literal["refusal"]` - - `"completed"` + Always `refusal`. - - `"incomplete"` + - `"refusal"` - - `class ShellCallOutput: …` + - `created_at: int` - The streamed output items emitted by a shell tool call. + The Unix timestamp (in seconds) for when the message was created. - - `call_id: str` + - `incomplete_at: Optional[int]` - The unique ID of the shell tool call generated by the model. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `output: List[BetaResponseFunctionShellCallOutputContent]` + - `incomplete_details: Optional[IncompleteDetails]` - Captured chunks of stdout and stderr output, along with their associated outcomes. + On an incomplete message, details about why the message is incomplete. - - `outcome: Outcome` + - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` - The exit or timeout outcome associated with this shell call. + The reason the message is incomplete. - - `class OutcomeTimeout: …` + - `"content_filter"` - Indicates that the shell call exceeded its configured time limit. + - `"max_tokens"` - - `type: Literal["timeout"]` + - `"run_cancelled"` - The outcome type. Always `timeout`. + - `"run_expired"` - - `"timeout"` + - `"run_failed"` - - `class OutcomeExit: …` + - `metadata: Optional[Metadata]` - Indicates that the shell commands finished and returned an exit code. + 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. - - `exit_code: int` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The exit code returned by the shell process. + - `object: Literal["thread.message"]` - - `type: Literal["exit"]` + The object type, which is always `thread.message`. - The outcome type. Always `exit`. + - `"thread.message"` - - `"exit"` + - `role: Literal["user", "assistant"]` - - `stderr: str` + The entity that produced the message. One of `user` or `assistant`. - Captured stderr output for the shell call. + - `"user"` - - `stdout: str` + - `"assistant"` - Captured stdout output for the shell call. + - `run_id: Optional[str]` - - `type: Literal["shell_call_output"]` + 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. - The type of the item. Always `shell_call_output`. + - `status: Literal["in_progress", "incomplete", "completed"]` - - `"shell_call_output"` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `id: Optional[str]` + - `"in_progress"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"incomplete"` - - `agent: Optional[ShellCallOutputAgent]` + - `"completed"` - The agent that produced this item. + - `thread_id: str` - - `agent_name: str` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - The canonical name of the agent that produced this item. +### Message Content - - `caller: Optional[ShellCallOutputCaller]` +- `MessageContent` - The execution context that produced this tool call. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `class ShellCallOutputCallerDirect: …` + - `class ImageFileContentBlock: …` - - `type: Literal["direct"]` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The caller type. Always `direct`. + - `image_file: ImageFile` - - `"direct"` + - `file_id: str` - - `class ShellCallOutputCallerProgram: …` + 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. - - `caller_id: str` + - `detail: Optional[Literal["auto", "low", "high"]]` - The call ID of the program item that produced this tool call. + 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`. - - `type: Literal["program"]` + - `"auto"` - The caller type. Always `program`. + - `"low"` - - `"program"` + - `"high"` - - `max_output_length: Optional[int]` + - `type: Literal["image_file"]` - The maximum number of UTF-8 characters captured for this shell call's combined output. + Always `image_file`. - - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` + - `"image_file"` - The status of the shell call output. + - `class ImageURLContentBlock: …` - - `"in_progress"` + References an image URL in the content of a message. - - `"completed"` + - `image_url: ImageURL` - - `"incomplete"` + - `url: str` - - `class ApplyPatchCall: …` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - A tool call representing a request to create, delete, or update files using diff patches. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `call_id: str` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - The unique ID of the apply patch tool call generated by the model. + - `"auto"` - - `operation: ApplyPatchCallOperation` + - `"low"` - The specific create, delete, or update instruction for the apply_patch tool call. + - `"high"` - - `class ApplyPatchCallOperationCreateFile: …` + - `type: Literal["image_url"]` - Instruction for creating a new file via the apply_patch tool. + The type of the content part. - - `diff: str` + - `"image_url"` - Unified diff content to apply when creating the file. + - `class TextContentBlock: …` - - `path: str` + The text content that is part of a message. - Path of the file to create relative to the workspace root. + - `text: Text` - - `type: Literal["create_file"]` + - `annotations: List[Annotation]` - The operation type. Always `create_file`. + - `class FileCitationAnnotation: …` - - `"create_file"` + 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. - - `class ApplyPatchCallOperationDeleteFile: …` + - `end_index: int` - Instruction for deleting an existing file via the apply_patch tool. + - `file_citation: FileCitation` - - `path: str` + - `file_id: str` - Path of the file to delete relative to the workspace root. + The ID of the specific File the citation is from. - - `type: Literal["delete_file"]` + - `start_index: int` - The operation type. Always `delete_file`. + - `text: str` - - `"delete_file"` + The text in the message content that needs to be replaced. - - `class ApplyPatchCallOperationUpdateFile: …` + - `type: Literal["file_citation"]` - Instruction for updating an existing file via the apply_patch tool. + Always `file_citation`. - - `diff: str` + - `"file_citation"` - Unified diff content to apply to the existing file. + - `class FilePathAnnotation: …` - - `path: str` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - Path of the file to update relative to the workspace root. + - `end_index: int` - - `type: Literal["update_file"]` + - `file_path: FilePath` - The operation type. Always `update_file`. + - `file_id: str` - - `"update_file"` + The ID of the file that was generated. - - `status: Literal["in_progress", "completed"]` + - `start_index: int` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `text: str` - - `"in_progress"` + The text in the message content that needs to be replaced. - - `"completed"` + - `type: Literal["file_path"]` - - `type: Literal["apply_patch_call"]` + Always `file_path`. - The type of the item. Always `apply_patch_call`. + - `"file_path"` - - `"apply_patch_call"` + - `value: str` - - `id: Optional[str]` + The data that makes up the text. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `type: Literal["text"]` - - `agent: Optional[ApplyPatchCallAgent]` + Always `text`. - The agent that produced this item. + - `"text"` - - `agent_name: str` + - `class RefusalContentBlock: …` - The canonical name of the agent that produced this item. + The refusal content generated by the assistant. - - `caller: Optional[ApplyPatchCallCaller]` + - `refusal: str` - The execution context that produced this tool call. + - `type: Literal["refusal"]` - - `class ApplyPatchCallCallerDirect: …` + Always `refusal`. - - `type: Literal["direct"]` + - `"refusal"` - The caller type. Always `direct`. +### Message Content Delta - - `"direct"` +- `MessageContentDelta` - - `class ApplyPatchCallCallerProgram: …` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `caller_id: str` + - `class ImageFileDeltaBlock: …` - The call ID of the program item that produced this tool call. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `type: Literal["program"]` + - `index: int` - The caller type. Always `program`. + The index of the content part in the message. - - `"program"` + - `type: Literal["image_file"]` - - `class ApplyPatchCallOutput: …` + Always `image_file`. - The streamed output emitted by an apply patch tool call. + - `"image_file"` - - `call_id: str` + - `image_file: Optional[ImageFileDelta]` - The unique ID of the apply patch tool call generated by the model. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `status: Literal["completed", "failed"]` + 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`. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"auto"` - - `"completed"` + - `"low"` - - `"failed"` + - `"high"` - - `type: Literal["apply_patch_call_output"]` + - `file_id: Optional[str]` - The type of the item. Always `apply_patch_call_output`. + 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. - - `"apply_patch_call_output"` + - `class TextDeltaBlock: …` - - `id: Optional[str]` + The text content that is part of a message. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `index: int` - - `agent: Optional[ApplyPatchCallOutputAgent]` + The index of the content part in the message. - The agent that produced this item. + - `type: Literal["text"]` - - `agent_name: str` + Always `text`. - The canonical name of the agent that produced this item. + - `"text"` - - `caller: Optional[ApplyPatchCallOutputCaller]` + - `text: Optional[TextDelta]` - The execution context that produced this tool call. + - `annotations: Optional[List[AnnotationDelta]]` - - `class ApplyPatchCallOutputCallerDirect: …` + - `class FileCitationDeltaAnnotation: …` - - `type: Literal["direct"]` + 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. - The caller type. Always `direct`. + - `index: int` - - `"direct"` + The index of the annotation in the text content part. - - `class ApplyPatchCallOutputCallerProgram: …` + - `type: Literal["file_citation"]` - - `caller_id: str` + Always `file_citation`. - The call ID of the program item that produced this tool call. + - `"file_citation"` - - `type: Literal["program"]` + - `end_index: Optional[int]` - The caller type. Always `program`. + - `file_citation: Optional[FileCitation]` - - `"program"` + - `file_id: Optional[str]` - - `output: Optional[str]` + The ID of the specific File the citation is from. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `quote: Optional[str]` - - `class McpListTools: …` + The specific quote in the file. - A list of tools available on an MCP server. + - `start_index: Optional[int]` - - `id: str` + - `text: Optional[str]` - The unique ID of the list. + The text in the message content that needs to be replaced. - - `server_label: str` + - `class FilePathDeltaAnnotation: …` - The label of the MCP server. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `tools: List[McpListToolsTool]` + - `index: int` - The tools available on the server. + The index of the annotation in the text content part. - - `input_schema: object` + - `type: Literal["file_path"]` - The JSON schema describing the tool's input. + Always `file_path`. - - `name: str` + - `"file_path"` - The name of the tool. + - `end_index: Optional[int]` - - `annotations: Optional[object]` + - `file_path: Optional[FilePath]` - Additional annotations about the tool. + - `file_id: Optional[str]` - - `description: Optional[str]` + The ID of the file that was generated. - The description of the tool. + - `start_index: Optional[int]` - - `type: Literal["mcp_list_tools"]` + - `text: Optional[str]` - The type of the item. Always `mcp_list_tools`. + The text in the message content that needs to be replaced. - - `"mcp_list_tools"` + - `value: Optional[str]` - - `agent: Optional[McpListToolsAgent]` + The data that makes up the text. - The agent that produced this item. + - `class RefusalDeltaBlock: …` - - `agent_name: str` + The refusal content that is part of a message. - The canonical name of the agent that produced this item. + - `index: int` - - `error: Optional[str]` + The index of the refusal part in the message. - Error message if the server could not list tools. + - `type: Literal["refusal"]` - - `class McpApprovalRequest: …` + Always `refusal`. - A request for human approval of a tool invocation. + - `"refusal"` - - `id: str` + - `refusal: Optional[str]` - The unique ID of the approval request. + - `class ImageURLDeltaBlock: …` - - `arguments: str` + References an image URL in the content of a message. - A JSON string of arguments for the tool. + - `index: int` - - `name: str` + The index of the content part in the message. - The name of the tool to run. + - `type: Literal["image_url"]` - - `server_label: str` + Always `image_url`. - The label of the MCP server making the request. + - `"image_url"` - - `type: Literal["mcp_approval_request"]` + - `image_url: Optional[ImageURLDelta]` - The type of the item. Always `mcp_approval_request`. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"mcp_approval_request"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `agent: Optional[McpApprovalRequestAgent]` + - `"auto"` - The agent that produced this item. + - `"low"` - - `agent_name: str` + - `"high"` - The canonical name of the agent that produced this item. + - `url: Optional[str]` - - `class McpApprovalResponse: …` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - A response to an MCP approval request. +### Message Content Part Param - - `approval_request_id: str` +- `MessageContentPartParam` - The ID of the approval request being answered. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `approve: bool` + - `class ImageFileContentBlock: …` - Whether the request was approved. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `type: Literal["mcp_approval_response"]` + - `image_file: ImageFile` - The type of the item. Always `mcp_approval_response`. + - `file_id: str` - - `"mcp_approval_response"` + 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. - - `id: Optional[str]` + - `detail: Optional[Literal["auto", "low", "high"]]` - The unique ID of the approval response + 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`. - - `agent: Optional[McpApprovalResponseAgent]` + - `"auto"` - The agent that produced this item. + - `"low"` - - `agent_name: str` + - `"high"` - The canonical name of the agent that produced this item. + - `type: Literal["image_file"]` - - `reason: Optional[str]` + Always `image_file`. - Optional reason for the decision. + - `"image_file"` - - `class McpCall: …` + - `class ImageURLContentBlock: …` - An invocation of a tool on an MCP server. + References an image URL in the content of a message. - - `id: str` + - `image_url: ImageURL` - The unique ID of the tool call. + - `url: str` - - `arguments: str` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - A JSON string of the arguments passed to the tool. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `name: str` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - The name of the tool that was run. + - `"auto"` - - `server_label: str` + - `"low"` - The label of the MCP server running the tool. + - `"high"` - - `type: Literal["mcp_call"]` + - `type: Literal["image_url"]` - The type of the item. Always `mcp_call`. + The type of the content part. - - `"mcp_call"` + - `"image_url"` - - `agent: Optional[McpCallAgent]` + - `class TextContentBlockParam: …` - The agent that produced this item. + The text content that is part of a message. - - `agent_name: str` + - `text: str` - The canonical name of the agent that produced this item. + Text content to be sent to the model - - `approval_request_id: Optional[str]` + - `type: Literal["text"]` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + Always `text`. - - `error: Optional[str]` + - `"text"` - The error from the tool call, if any. +### Message Deleted - - `output: Optional[str]` +- `class MessageDeleted: …` - The output from the tool call. + - `id: str` - - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` + - `deleted: bool` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `object: Literal["thread.message.deleted"]` - - `"in_progress"` + - `"thread.message.deleted"` - - `"completed"` +### Message Delta - - `"incomplete"` +- `class MessageDelta: …` - - `"calling"` + The delta containing the fields that have changed on the Message. - - `"failed"` + - `content: Optional[List[MessageContentDelta]]` - - `class BetaResponseCustomToolCallOutput: …` + The content of the message in array of text and/or images. - The output of a custom tool call from your code, being sent back to the model. + - `class ImageFileDeltaBlock: …` - - `call_id: str` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The call ID, used to map this custom tool call output to a custom tool call. + - `index: int` - - `output: Union[str, List[OutputOutputContentList]]` + The index of the content part in the message. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `type: Literal["image_file"]` - - `str` + Always `image_file`. - A string of the output of the custom tool call. + - `"image_file"` - - `List[OutputOutputContentList]` + - `image_file: Optional[ImageFileDelta]` - Text, image, or file output of the custom tool call. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `class BetaResponseInputText: …` + 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`. - A text input to the model. + - `"auto"` - - `class BetaResponseInputImage: …` + - `"low"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"high"` - - `class BetaResponseInputFile: …` + - `file_id: Optional[str]` - A file input to the model. + 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. - - `type: Literal["custom_tool_call_output"]` + - `class TextDeltaBlock: …` - The type of the custom tool call output. Always `custom_tool_call_output`. + The text content that is part of a message. - - `"custom_tool_call_output"` + - `index: int` - - `id: Optional[str]` + The index of the content part in the message. - The unique ID of the custom tool call output in the OpenAI platform. + - `type: Literal["text"]` - - `agent: Optional[Agent]` + Always `text`. - The agent that produced this item. + - `"text"` - - `agent_name: str` + - `text: Optional[TextDelta]` - The canonical name of the agent that produced this item. + - `annotations: Optional[List[AnnotationDelta]]` - - `caller: Optional[Caller]` + - `class FileCitationDeltaAnnotation: …` - The execution context that produced this tool call. + 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. - - `class CallerDirect: …` + - `index: int` - - `type: Literal["direct"]` + The index of the annotation in the text content part. - The caller type. Always `direct`. + - `type: Literal["file_citation"]` - - `"direct"` + Always `file_citation`. - - `class CallerProgram: …` + - `"file_citation"` - - `caller_id: str` + - `end_index: Optional[int]` - The call ID of the program item that produced this tool call. + - `file_citation: Optional[FileCitation]` - - `type: Literal["program"]` + - `file_id: Optional[str]` - The caller type. Always `program`. + The ID of the specific File the citation is from. - - `"program"` + - `quote: Optional[str]` - - `class BetaResponseCustomToolCall: …` + The specific quote in the file. - A call to a custom tool created by the model. + - `start_index: Optional[int]` - - `call_id: str` + - `text: Optional[str]` - An identifier used to map this custom tool call to a tool call output. + The text in the message content that needs to be replaced. - - `input: str` + - `class FilePathDeltaAnnotation: …` - The input for the custom tool call generated by the model. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `name: str` + - `index: int` - The name of the custom tool being called. + The index of the annotation in the text content part. - - `type: Literal["custom_tool_call"]` + - `type: Literal["file_path"]` - The type of the custom tool call. Always `custom_tool_call`. + Always `file_path`. - - `"custom_tool_call"` + - `"file_path"` - - `id: Optional[str]` + - `end_index: Optional[int]` - The unique ID of the custom tool call in the OpenAI platform. + - `file_path: Optional[FilePath]` - - `agent: Optional[Agent]` + - `file_id: Optional[str]` - The agent that produced this item. + The ID of the file that was generated. - - `agent_name: str` + - `start_index: Optional[int]` - The canonical name of the agent that produced this item. + - `text: Optional[str]` - - `caller: Optional[Caller]` + The text in the message content that needs to be replaced. - The execution context that produced this tool call. + - `value: Optional[str]` - - `class CallerDirect: …` + The data that makes up the text. - - `type: Literal["direct"]` + - `class RefusalDeltaBlock: …` - - `"direct"` + The refusal content that is part of a message. - - `class CallerProgram: …` + - `index: int` - - `caller_id: str` + The index of the refusal part in the message. - The call ID of the program item that produced this tool call. + - `type: Literal["refusal"]` - - `type: Literal["program"]` + Always `refusal`. - - `"program"` + - `"refusal"` - - `namespace: Optional[str]` + - `refusal: Optional[str]` - The namespace of the custom tool being called. + - `class ImageURLDeltaBlock: …` - - `class CompactionTrigger: …` + References an image URL in the content of a message. - Compacts the current context. Must be the final input item. + - `index: int` - - `type: Literal["compaction_trigger"]` + The index of the content part in the message. - The type of the item. Always `compaction_trigger`. + - `type: Literal["image_url"]` - - `"compaction_trigger"` + Always `image_url`. - - `agent: Optional[CompactionTriggerAgent]` + - `"image_url"` - The agent that produced this item. + - `image_url: Optional[ImageURLDelta]` - - `agent_name: str` + - `detail: Optional[Literal["auto", "low", "high"]]` - The canonical name of the agent that produced this item. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `class ItemReference: …` + - `"auto"` - An internal identifier for an item to reference. + - `"low"` - - `id: str` + - `"high"` - The ID of the item to reference. + - `url: Optional[str]` - - `agent: Optional[ItemReferenceAgent]` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The agent that produced this item. + - `role: Optional[Literal["user", "assistant"]]` - - `agent_name: str` + The entity that produced the message. One of `user` or `assistant`. - The canonical name of the agent that produced this item. + - `"user"` - - `type: Optional[Literal["item_reference"]]` + - `"assistant"` - The type of item to reference. Always `item_reference`. +### Message Delta Event - - `"item_reference"` +- `class MessageDeltaEvent: …` - - `class Program: …` + Represents a message delta i.e. any changed fields on a message during streaming. - `id: str` - The unique ID of this program item. + The identifier of the message, which can be referenced in API endpoints. - - `call_id: str` + - `delta: MessageDelta` - The stable call ID of the program item. + The delta containing the fields that have changed on the Message. - - `code: str` + - `content: Optional[List[MessageContentDelta]]` - The JavaScript source executed by programmatic tool calling. + The content of the message in array of text and/or images. - - `fingerprint: str` + - `class ImageFileDeltaBlock: …` - Opaque program replay fingerprint that must be round-tripped. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `type: Literal["program"]` + - `index: int` - The item type. Always `program`. + The index of the content part in the message. - - `"program"` + - `type: Literal["image_file"]` - - `agent: Optional[ProgramAgent]` + Always `image_file`. - The agent that produced this item. + - `"image_file"` - - `agent_name: str` + - `image_file: Optional[ImageFileDelta]` - The canonical name of the agent that produced this item. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `class ProgramOutput: …` + 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`. - - `id: str` + - `"auto"` - The unique ID of this program output item. + - `"low"` - - `call_id: str` + - `"high"` - The call ID of the program item. + - `file_id: Optional[str]` - - `result: 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. - The result produced by the program item. + - `class TextDeltaBlock: …` - - `status: Literal["completed", "incomplete"]` + The text content that is part of a message. - The terminal status of the program output. + - `index: int` - - `"completed"` + The index of the content part in the message. - - `"incomplete"` + - `type: Literal["text"]` - - `type: Literal["program_output"]` + Always `text`. - The item type. Always `program_output`. + - `"text"` - - `"program_output"` + - `text: Optional[TextDelta]` - - `agent: Optional[ProgramOutputAgent]` + - `annotations: Optional[List[AnnotationDelta]]` - The agent that produced this item. + - `class FileCitationDeltaAnnotation: …` - - `agent_name: str` + 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. - The canonical name of the agent that produced this item. + - `index: int` -- `instructions: Optional[str]` + The index of the annotation in the text content part. - A system (or developer) message inserted into the model's context. - When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + - `type: Literal["file_citation"]` -- `model: Optional[str]` + Always `file_citation`. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. + - `"file_citation"` -- `parallel_tool_calls: Optional[bool]` + - `end_index: Optional[int]` - Whether to allow the model to run tool calls in parallel. + - `file_citation: Optional[FileCitation]` -- `personality: Optional[Union[str, Literal["friendly", "pragmatic"]]]` + - `file_id: Optional[str]` - A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. + The ID of the specific File the citation is from. - - `str` + - `quote: Optional[str]` - - `Literal["friendly", "pragmatic"]` + The specific quote in the file. - A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. + - `start_index: Optional[int]` - - `"friendly"` + - `text: Optional[str]` - - `"pragmatic"` + The text in the message content that needs to be replaced. -- `previous_response_id: Optional[str]` + - `class FilePathDeltaAnnotation: …` - The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. -- `reasoning: Optional[Reasoning]` + - `index: int` - **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The index of the annotation in the text content part. - - `context: Optional[Literal["auto", "current_turn", "all_turns"]]` + - `type: Literal["file_path"]` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + Always `file_path`. - - `"auto"` + - `"file_path"` - - `"current_turn"` + - `end_index: Optional[int]` - - `"all_turns"` + - `file_path: Optional[FilePath]` - - `effort: Optional[Literal["none", "minimal", "low", 4 more]]` + - `file_id: Optional[str]` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The ID of the file that was generated. - - `"none"` + - `start_index: Optional[int]` - - `"minimal"` + - `text: Optional[str]` - - `"low"` + The text in the message content that needs to be replaced. - - `"medium"` + - `value: Optional[str]` - - `"high"` + The data that makes up the text. - - `"xhigh"` + - `class RefusalDeltaBlock: …` - - `"max"` + The refusal content that is part of a message. - - `generate_summary: Optional[Literal["auto", "concise", "detailed"]]` + - `index: int` - **Deprecated:** use `summary` instead. + The index of the refusal part in the message. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `type: Literal["refusal"]` - - `"auto"` + Always `refusal`. - - `"concise"` + - `"refusal"` - - `"detailed"` + - `refusal: Optional[str]` - - `mode: Optional[Union[str, Literal["standard", "pro"]]]` + - `class ImageURLDeltaBlock: …` - Controls the reasoning execution mode for the request. + References an image URL in the content of a message. - When returned on a response, this is the effective execution mode. + - `index: int` - - `str` + The index of the content part in the message. - - `Literal["standard", "pro"]` + - `type: Literal["image_url"]` - Controls the reasoning execution mode for the request. + Always `image_url`. - When returned on a response, this is the effective execution mode. + - `"image_url"` - - `"standard"` + - `image_url: Optional[ImageURLDelta]` - - `"pro"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `summary: Optional[Literal["auto", "concise", "detailed"]]` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"auto"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `"low"` - - `"auto"` + - `"high"` - - `"concise"` + - `url: Optional[str]` - - `"detailed"` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. -- `text: Optional[Text]` + - `role: Optional[Literal["user", "assistant"]]` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The entity that produced the message. One of `user` or `assistant`. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `"user"` - - `format: Optional[BetaResponseFormatTextConfigParam]` + - `"assistant"` - An object specifying the format that the model must output. + - `object: Literal["thread.message.delta"]` - Configuring `{ "type": "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). + The object type, which is always `thread.message.delta`. - The default format is `{ "type": "text" }` with no additional options. + - `"thread.message.delta"` - **Not recommended for gpt-4o and newer models:** +### Refusal Content Block - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. +- `class RefusalContentBlock: …` - - `class Text: …` + The refusal content generated by the assistant. - Default response format. Used to generate text responses. + - `refusal: str` - - `type: Literal["text"]` + - `type: Literal["refusal"]` - The type of response format being defined. Always `text`. + Always `refusal`. - - `"text"` + - `"refusal"` - - `class BetaResponseFormatTextJSONSchemaConfig: …` +### Refusal Delta Block - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). +- `class RefusalDeltaBlock: …` - - `name: str` + The refusal content that is part of a message. - 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. + - `index: int` - - `schema: Dict[str, object]` + The index of the refusal part in the message. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `type: Literal["refusal"]` - - `type: Literal["json_schema"]` + Always `refusal`. - The type of response format being defined. Always `json_schema`. + - `"refusal"` - - `"json_schema"` + - `refusal: Optional[str]` - - `description: Optional[str]` +### Text - A description of what the response format is for, used by the model to - determine how to respond in the format. +- `class Text: …` - - `strict: Optional[bool]` + - `annotations: List[Annotation]` - 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). + - `class FileCitationAnnotation: …` - - `class JSONObject: …` + 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. - 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. + - `end_index: int` - - `type: Literal["json_object"]` + - `file_citation: FileCitation` - The type of response format being defined. Always `json_object`. + - `file_id: str` - - `"json_object"` + The ID of the specific File the citation is from. - - `verbosity: Optional[Literal["low", "medium", "high"]]` + - `start_index: int` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `text: str` - - `"low"` + The text in the message content that needs to be replaced. - - `"medium"` + - `type: Literal["file_citation"]` - - `"high"` + Always `file_citation`. -- `tool_choice: Optional[ToolChoice]` + - `"file_citation"` - Controls which tool the model should use, if any. + - `class FilePathAnnotation: …` - - `Literal["none", "auto", "required"]` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"none"` + - `end_index: int` - - `"auto"` + - `file_path: FilePath` - - `"required"` + - `file_id: str` - - `class BetaToolChoiceAllowed: …` + The ID of the file that was generated. - Constrains the tools available to the model to a pre-defined set. + - `start_index: int` - - `mode: Literal["auto", "required"]` + - `text: str` - Constrains the tools available to the model to a pre-defined set. + The text in the message content that needs to be replaced. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `type: Literal["file_path"]` - `required` requires the model to call one or more of the allowed tools. + Always `file_path`. - - `"auto"` + - `"file_path"` - - `"required"` + - `value: str` - - `tools: List[Dict[str, object]]` + The data that makes up the text. - A list of tool definitions that the model should be allowed to call. +### Text Content Block - For the Responses API, the list of tool definitions might look like: +- `class TextContentBlock: …` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The text content that is part of a message. - - `type: Literal["allowed_tools"]` + - `text: Text` - Allowed tool configuration type. Always `allowed_tools`. + - `annotations: List[Annotation]` - - `"allowed_tools"` + - `class FileCitationAnnotation: …` - - `class BetaToolChoiceTypes: …` + 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. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `end_index: int` - - `type: Literal["file_search", "web_search_preview", "computer", 5 more]` + - `file_citation: FileCitation` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `file_id: str` - Allowed values are: + The ID of the specific File the citation is from. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `start_index: int` - - `"file_search"` + - `text: str` - - `"web_search_preview"` + The text in the message content that needs to be replaced. - - `"computer"` + - `type: Literal["file_citation"]` - - `"computer_use_preview"` + Always `file_citation`. - - `"computer_use"` + - `"file_citation"` - - `"web_search_preview_2025_03_11"` + - `class FilePathAnnotation: …` - - `"image_generation"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"code_interpreter"` + - `end_index: int` - - `class BetaToolChoiceFunction: …` + - `file_path: FilePath` - Use this option to force the model to call a specific function. + - `file_id: str` - - `name: str` + The ID of the file that was generated. - The name of the function to call. + - `start_index: int` - - `type: Literal["function"]` + - `text: str` - For function calling, the type is always `function`. + The text in the message content that needs to be replaced. - - `"function"` + - `type: Literal["file_path"]` - - `class BetaToolChoiceMcp: …` + Always `file_path`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `"file_path"` - - `server_label: str` + - `value: str` - The label of the MCP server to use. + The data that makes up the text. - - `type: Literal["mcp"]` + - `type: Literal["text"]` - For MCP tools, the type is always `mcp`. + Always `text`. - - `"mcp"` + - `"text"` - - `name: Optional[str]` +### Text Content Block Param - The name of the tool to call on the server. +- `class TextContentBlockParam: …` - - `class BetaToolChoiceCustom: …` + The text content that is part of a message. - Use this option to force the model to call a specific custom tool. + - `text: str` - - `name: str` + Text content to be sent to the model - The name of the custom tool to call. + - `type: Literal["text"]` - - `type: Literal["custom"]` + Always `text`. - For custom tool calling, the type is always `custom`. + - `"text"` - - `"custom"` +### Text Delta - - `class ToolChoiceBetaSpecificProgrammaticToolCallingParam: …` +- `class TextDelta: …` - - `type: Literal["programmatic_tool_calling"]` + - `annotations: Optional[List[AnnotationDelta]]` - The tool to call. Always `programmatic_tool_calling`. + - `class FileCitationDeltaAnnotation: …` - - `"programmatic_tool_calling"` + 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. - - `class BetaToolChoiceApplyPatch: …` + - `index: int` - Forces the model to call the apply_patch tool when executing a tool call. + The index of the annotation in the text content part. - - `type: Literal["apply_patch"]` + - `type: Literal["file_citation"]` - The tool to call. Always `apply_patch`. + Always `file_citation`. - - `"apply_patch"` + - `"file_citation"` - - `class BetaToolChoiceShell: …` + - `end_index: Optional[int]` - Forces the model to call the shell tool when a tool call is required. + - `file_citation: Optional[FileCitation]` - - `type: Literal["shell"]` + - `file_id: Optional[str]` - The tool to call. Always `shell`. + The ID of the specific File the citation is from. - - `"shell"` + - `quote: Optional[str]` -- `tools: Optional[Iterable[BetaToolParam]]` + The specific quote in the file. - An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. + - `start_index: Optional[int]` - - `class BetaFunctionTool: …` + - `text: Optional[str]` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The text in the message content that needs to be replaced. - - `class BetaFileSearchTool: …` + - `class FilePathDeltaAnnotation: …` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `class BetaComputerTool: …` + - `index: int` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The index of the annotation in the text content part. - - `class BetaComputerUsePreviewTool: …` + - `type: Literal["file_path"]` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Always `file_path`. - - `class BetaWebSearchTool: …` + - `"file_path"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `end_index: Optional[int]` - - `class Mcp: …` + - `file_path: Optional[FilePath]` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `file_id: Optional[str]` - - `class CodeInterpreter: …` + The ID of the file that was generated. - A tool that runs Python code to help generate a response to a prompt. + - `start_index: Optional[int]` - - `class ProgrammaticToolCalling: …` + - `text: Optional[str]` - - `class ImageGeneration: …` + The text in the message content that needs to be replaced. - A tool that generates images using the GPT image models. + - `value: Optional[str]` - - `class LocalShell: …` + The data that makes up the text. - A tool that allows the model to execute shell commands in a local environment. +### Text Delta Block - - `class BetaFunctionShellTool: …` +- `class TextDeltaBlock: …` - A tool that allows the model to execute shell commands. + The text content that is part of a message. - - `class BetaCustomTool: …` + - `index: int` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The index of the content part in the message. - - `class BetaNamespaceTool: …` + - `type: Literal["text"]` - Groups function/custom tools under a shared namespace. + Always `text`. - - `class BetaToolSearchTool: …` + - `"text"` - Hosted or BYOT tool search configuration for deferred tools. + - `text: Optional[TextDelta]` - - `class BetaWebSearchPreviewTool: …` + - `annotations: Optional[List[AnnotationDelta]]` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class FileCitationDeltaAnnotation: …` - - `class BetaApplyPatchTool: …` + 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. - Allows the assistant to create, delete, or update files using unified diffs. + - `index: int` -- `truncation: Optional[Literal["auto", "disabled"]]` + The index of the annotation in the text content part. - The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error. + - `type: Literal["file_citation"]` - - `"auto"` + Always `file_citation`. - - `"disabled"` + - `"file_citation"` -- `betas: Optional[List[Literal["responses_multi_agent=v1"]]]` + - `end_index: Optional[int]` - - `"responses_multi_agent=v1"` + - `file_citation: Optional[FileCitation]` -### Returns + - `file_id: Optional[str]` -- `class InputTokenCountResponse: …` + The ID of the specific File the citation is from. - - `input_tokens: int` + - `quote: Optional[str]` - - `object: Literal["response.input_tokens"]` + The specific quote in the file. - - `"response.input_tokens"` + - `start_index: Optional[int]` -### Example + - `text: Optional[str]` -```python -import os -from openai import OpenAI + The text in the message content that needs to be replaced. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -response = client.beta.responses.input_tokens.count() -print(response.input_tokens) -``` + - `class FilePathDeltaAnnotation: …` -#### Response + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. -```json -{ - "input_tokens": 123, - "object": "response.input_tokens" -} -``` + - `index: int` -### Example + The index of the annotation in the text content part. -```python -from openai import OpenAI + - `type: Literal["file_path"]` -client = OpenAI() + Always `file_path`. -response = client.responses.input_tokens.count( - model="gpt-5", - input="Tell me a joke." -) -print(response.input_tokens) -``` + - `"file_path"` -#### Response + - `end_index: Optional[int]` -```json -{ - "object": "response.input_tokens", - "input_tokens": 11 -} -``` + - `file_path: Optional[FilePath]` -## Domain Types + - `file_id: Optional[str]` -### Input Token Count Response + The ID of the file that was generated. -- `class InputTokenCountResponse: …` + - `start_index: Optional[int]` - - `input_tokens: int` + - `text: Optional[str]` - - `object: Literal["response.input_tokens"]` + The text in the message content that needs to be replaced. - - `"response.input_tokens"` + - `value: Optional[str]` + + The data that makes up the text.