From 6c397d5d281d6061e88b4a0120fab335ec862a89 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 9 Jul 2026 16:59:37 +0000 Subject: [PATCH 1/2] feat(api): gpt-5.6-sol updates --- .stats.yml | 8 +- MIGRATION.md | 5 + api.md | 183 + examples/responses/multi-agent-streaming.ts | 39 + examples/responses/multi-agent-websocket.ts | 50 + scripts/detect-breaking-changes | 6 +- src/lib/responses/ResponseInputItems.ts | 2 + src/resources/beta/assistants.ts | 38 +- src/resources/beta/beta.ts | 332 +- src/resources/beta/index.ts | 163 + src/resources/beta/responses.ts | 3 + src/resources/beta/responses/index.ts | 169 + src/resources/beta/responses/input-items.ts | 105 + src/resources/beta/responses/input-tokens.ts | 245 + src/resources/beta/responses/internal-base.ts | 117 + src/resources/beta/responses/responses.ts | 12632 ++++++++++++++++ src/resources/beta/responses/ws-base.ts | 615 + src/resources/beta/responses/ws.ts | 38 + src/resources/beta/threads/runs/runs.ts | 19 +- src/resources/chat/completions/completions.ts | 185 +- src/resources/completions.ts | 5 + src/resources/conversations/conversations.ts | 21 + src/resources/conversations/items.ts | 56 + src/resources/evals/runs/runs.ts | 209 +- src/resources/graders/grader-models.ts | 19 +- src/resources/realtime/calls.ts | 2 + src/resources/realtime/client-secrets.ts | 7 + src/resources/realtime/realtime.ts | 12 + src/resources/responses/input-tokens.ts | 8 + src/resources/responses/responses.ts | 965 +- src/resources/shared.ts | 50 +- src/resources/webhooks/api.md | 1 + src/resources/webhooks/webhooks.ts | 66 +- .../beta/responses/input-items.test.ts | 39 + .../beta/responses/input-tokens.test.ts | 66 + .../beta/responses/responses.test.ts | 119 + .../beta/threads/runs/runs.test.ts | 2 +- .../beta/threads/threads.test.ts | 2 +- .../chat/completions/completions.test.ts | 9 +- .../responses/input-tokens.test.ts | 3 + .../api-resources/responses/responses.test.ts | 5 +- tests/lib/ResponseInputItems.test.ts | 28 + tests/lib/ResponsesParser.test.ts | 22 + tests/responsesTools.test.ts | 117 + 44 files changed, 16521 insertions(+), 266 deletions(-) create mode 100644 examples/responses/multi-agent-streaming.ts create mode 100644 examples/responses/multi-agent-websocket.ts create mode 100644 src/resources/beta/responses.ts create mode 100644 src/resources/beta/responses/index.ts create mode 100644 src/resources/beta/responses/input-items.ts create mode 100644 src/resources/beta/responses/input-tokens.ts create mode 100644 src/resources/beta/responses/internal-base.ts create mode 100644 src/resources/beta/responses/responses.ts create mode 100644 src/resources/beta/responses/ws-base.ts create mode 100644 src/resources/beta/responses/ws.ts create mode 100644 tests/api-resources/beta/responses/input-items.test.ts create mode 100644 tests/api-resources/beta/responses/input-tokens.test.ts create mode 100644 tests/api-resources/beta/responses/responses.test.ts create mode 100644 tests/responsesTools.test.ts diff --git a/.stats.yml b/.stats.yml index fe88e03e38..4e142c3c37 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ -configured_endpoints: 263 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai/openai-b5b621065906a2579dc180db1236ee3b08a4fca9539accc2fbbf88da0ca3923f.yml -openapi_spec_hash: 45b1b4692b26e714008d8120ccfc7433 -config_hash: ef3ce17315a31703e7af0567b3e9738c +configured_endpoints: 270 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai/openai-356010b9b9fd6228b457b8fcfa376cf4928a8f3bd4728e7ba5e4b6b5ef4f5843.yml +openapi_spec_hash: 885864ae98a443166f585f856c464fb2 +config_hash: 1f1e3b4050e2cb4bc780ce0b70e2b3e6 diff --git a/MIGRATION.md b/MIGRATION.md index 778f9fc95c..695fcdc4cd 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -155,6 +155,11 @@ client.example.list(undefined, { headers: { ... } }); - `client.fineTuning.checkpoints.permissions.list()` - `client.vectorStores.list()` - `client.vectorStores.files.list()` +- `client.beta.responses.retrieve()` +- `client.beta.responses.delete()` +- `client.beta.responses.cancel()` +- `client.beta.responses.inputItems.list()` +- `client.beta.responses.inputTokens.count()` - `client.beta.chatkit.threads.list()` - `client.beta.chatkit.threads.listItems()` - `client.beta.assistants.list()` diff --git a/api.md b/api.md index c9dadbcdfd..e11f9ec502 100644 --- a/api.md +++ b/api.md @@ -377,6 +377,189 @@ Methods: # Beta +## Responses + +Types: + +- BetaApplyPatchTool +- BetaCompactedResponse +- BetaComputerAction +- BetaComputerActionList +- BetaComputerTool +- BetaComputerUsePreviewTool +- BetaContainerAuto +- BetaContainerNetworkPolicyAllowlist +- BetaContainerNetworkPolicyDisabled +- BetaContainerNetworkPolicyDomainSecret +- BetaContainerReference +- BetaCustomTool +- BetaEasyInputMessage +- BetaFileSearchTool +- BetaFunctionShellTool +- BetaFunctionTool +- BetaInlineSkill +- BetaInlineSkillSource +- BetaLocalEnvironment +- BetaLocalSkill +- BetaNamespaceTool +- BetaResponse +- BetaResponseApplyPatchToolCall +- BetaResponseApplyPatchToolCallOutput +- BetaResponseAudioDeltaEvent +- BetaResponseAudioDoneEvent +- BetaResponseAudioTranscriptDeltaEvent +- BetaResponseAudioTranscriptDoneEvent +- BetaResponseCodeInterpreterCallCodeDeltaEvent +- BetaResponseCodeInterpreterCallCodeDoneEvent +- BetaResponseCodeInterpreterCallCompletedEvent +- BetaResponseCodeInterpreterCallInProgressEvent +- BetaResponseCodeInterpreterCallInterpretingEvent +- BetaResponseCodeInterpreterToolCall +- BetaResponseCompactionItem +- BetaResponseCompactionItemParam +- BetaResponseCompletedEvent +- BetaResponseComputerToolCall +- BetaResponseComputerToolCallOutputItem +- BetaResponseComputerToolCallOutputScreenshot +- BetaResponseContainerReference +- BetaResponseContent +- BetaResponseContentPartAddedEvent +- BetaResponseContentPartDoneEvent +- BetaResponseConversationParam +- BetaResponseCreatedEvent +- BetaResponseCustomToolCall +- BetaResponseCustomToolCallInputDeltaEvent +- BetaResponseCustomToolCallInputDoneEvent +- BetaResponseCustomToolCallItem +- BetaResponseCustomToolCallOutput +- BetaResponseCustomToolCallOutputItem +- BetaResponseError +- BetaResponseErrorEvent +- BetaResponseFailedEvent +- BetaResponseFileSearchCallCompletedEvent +- BetaResponseFileSearchCallInProgressEvent +- BetaResponseFileSearchCallSearchingEvent +- BetaResponseFileSearchToolCall +- BetaResponseFormatTextConfig +- BetaResponseFormatTextJSONSchemaConfig +- BetaResponseFunctionCallArgumentsDeltaEvent +- BetaResponseFunctionCallArgumentsDoneEvent +- BetaResponseFunctionCallOutputItem +- BetaResponseFunctionCallOutputItemList +- BetaResponseFunctionShellCallOutputContent +- BetaResponseFunctionShellToolCall +- BetaResponseFunctionShellToolCallOutput +- BetaResponseFunctionToolCall +- BetaResponseFunctionToolCallItem +- BetaResponseFunctionToolCallOutputItem +- BetaResponseFunctionWebSearch +- BetaResponseImageGenCallCompletedEvent +- BetaResponseImageGenCallGeneratingEvent +- BetaResponseImageGenCallInProgressEvent +- BetaResponseImageGenCallPartialImageEvent +- BetaResponseInProgressEvent +- BetaResponseIncludable +- BetaResponseIncompleteEvent +- BetaResponseInjectCreatedEvent +- BetaResponseInjectEvent +- BetaResponseInjectFailedEvent +- BetaResponseInput +- BetaResponseInputAudio +- BetaResponseInputContent +- BetaResponseInputFile +- BetaResponseInputFileContent +- BetaResponseInputImage +- BetaResponseInputImageContent +- BetaResponseInputItem +- BetaResponseInputMessageContentList +- BetaResponseInputMessageItem +- BetaResponseInputText +- BetaResponseInputTextContent +- BetaResponseItem +- BetaResponseLocalEnvironment +- BetaResponseMcpCallArgumentsDeltaEvent +- BetaResponseMcpCallArgumentsDoneEvent +- BetaResponseMcpCallCompletedEvent +- BetaResponseMcpCallFailedEvent +- BetaResponseMcpCallInProgressEvent +- BetaResponseMcpListToolsCompletedEvent +- BetaResponseMcpListToolsFailedEvent +- BetaResponseMcpListToolsInProgressEvent +- BetaResponseOutputAudio +- BetaResponseOutputItem +- BetaResponseOutputItemAddedEvent +- BetaResponseOutputItemDoneEvent +- BetaResponseOutputMessage +- BetaResponseOutputRefusal +- BetaResponseOutputText +- BetaResponseOutputTextAnnotationAddedEvent +- BetaResponsePrompt +- BetaResponseQueuedEvent +- BetaResponseReasoningItem +- BetaResponseReasoningSummaryPartAddedEvent +- BetaResponseReasoningSummaryPartDoneEvent +- BetaResponseReasoningSummaryTextDeltaEvent +- BetaResponseReasoningSummaryTextDoneEvent +- BetaResponseReasoningTextDeltaEvent +- BetaResponseReasoningTextDoneEvent +- BetaResponseRefusalDeltaEvent +- BetaResponseRefusalDoneEvent +- BetaResponseStatus +- BetaResponseStreamEvent +- BetaResponseTextConfig +- BetaResponseTextDeltaEvent +- BetaResponseTextDoneEvent +- BetaResponseToolSearchCall +- BetaResponseToolSearchOutputItem +- BetaResponseToolSearchOutputItemParam +- BetaResponseUsage +- BetaResponseWebSearchCallCompletedEvent +- BetaResponseWebSearchCallInProgressEvent +- BetaResponseWebSearchCallSearchingEvent +- BetaResponsesClientEvent +- BetaResponsesServerEvent +- BetaSkillReference +- BetaTool +- BetaToolChoiceAllowed +- BetaToolChoiceApplyPatch +- BetaToolChoiceCustom +- BetaToolChoiceFunction +- BetaToolChoiceMcp +- BetaToolChoiceOptions +- BetaToolChoiceShell +- BetaToolChoiceTypes +- BetaToolSearchTool +- BetaWebSearchPreviewTool +- BetaWebSearchTool + +Methods: + +- client.beta.responses.create({ ...params }) -> BetaResponse +- client.beta.responses.retrieve(responseID, { ...params }) -> BetaResponse +- client.beta.responses.delete(responseID, { ...params }) -> void +- client.beta.responses.cancel(responseID, { ...params }) -> BetaResponse +- client.beta.responses.compact({ ...params }) -> BetaCompactedResponse + +### InputItems + +Types: + +- BetaResponseItemList + +Methods: + +- client.beta.responses.inputItems.list(responseID, { ...params }) -> BetaResponseItemsPage + +### InputTokens + +Types: + +- InputTokenCountResponse + +Methods: + +- client.beta.responses.inputTokens.count({ ...params }) -> InputTokenCountResponse + ## ChatKit Types: diff --git a/examples/responses/multi-agent-streaming.ts b/examples/responses/multi-agent-streaming.ts new file mode 100644 index 0000000000..c7156b7bd6 --- /dev/null +++ b/examples/responses/multi-agent-streaming.ts @@ -0,0 +1,39 @@ +#!/usr/bin/env -S npm run tsn -- -T + +import OpenAI from 'openai'; + +const client = new OpenAI(); + +const input = `Proposal Alpha: launch in 2 weeks for $40k using a managed vendor with a 99.9% SLA; data leaves our VPC. +Proposal Beta: launch in 6 weeks for $70k using a self-hosted system with a 99.5% target; data stays in our VPC. +Delegate each proposal to a separate agent, then compare speed, cost, reliability, and security and recommend one.`; + +async function main() { + const stream = await client.beta.responses.create({ + model: 'gpt-5.6-sol', + input, + multi_agent: { enabled: true }, + stream: true, + betas: ['responses_multi_agent=v1'], + }); + + const agents = new Map(); + let currentItemID: string | undefined; + for await (const event of stream) { + if (event.type === 'response.output_item.added' && event.item.type === 'message') { + agents.set(event.item.id, event.item.agent?.agent_name ?? '/root'); + } else if (event.type === 'response.output_text.delta') { + if (currentItemID !== event.item_id) { + const separator = currentItemID === undefined ? '' : '\n\n'; + currentItemID = event.item_id; + const name = agents.get(event.item_id) ?? '/root'; + const role = name === '/root' ? 'Coordinator' : 'Agent'; + process.stdout.write(`${separator}━━━ ${role}: ${name} ━━━\n\n`); + } + process.stdout.write(event.delta); + } + } + process.stdout.write('\n'); +} + +main(); diff --git a/examples/responses/multi-agent-websocket.ts b/examples/responses/multi-agent-websocket.ts new file mode 100644 index 0000000000..835af091c1 --- /dev/null +++ b/examples/responses/multi-agent-websocket.ts @@ -0,0 +1,50 @@ +#!/usr/bin/env -S npm run tsn -- -T + +import OpenAI from 'openai'; +import { ResponsesWS } from 'openai/resources/beta/responses/ws'; + +const client = new OpenAI(); + +const input = `Proposal Alpha: launch in 2 weeks for $40k using a managed vendor with a 99.9% SLA; data leaves our VPC. +Proposal Beta: launch in 6 weeks for $70k using a self-hosted system with a 99.5% target; data stays in our VPC. +Delegate each proposal to a separate agent, then compare speed, cost, reliability, and security and recommend one.`; + +async function main() { + const ws = new ResponsesWS(client, { + headers: { 'OpenAI-Beta': 'responses_multi_agent=v1' }, + }); + + ws.send({ + type: 'response.create', + model: 'gpt-5.6-sol', + input, + multi_agent: { enabled: true }, + }); + + const agents = new Map(); + let currentItemID: string | undefined; + for await (const message of ws) { + if (message.type === 'error') throw message.error; + if (message.type !== 'message') continue; + + const event = message.message; + if (event.type === 'response.output_item.added' && event.item.type === 'message') { + agents.set(event.item.id, event.item.agent?.agent_name ?? '/root'); + } else if (event.type === 'response.output_text.delta') { + if (currentItemID !== event.item_id) { + const separator = currentItemID === undefined ? '' : '\n\n'; + currentItemID = event.item_id; + const name = agents.get(event.item_id) ?? '/root'; + const role = name === '/root' ? 'Coordinator' : 'Agent'; + process.stdout.write(`${separator}━━━ ${role}: ${name} ━━━\n\n`); + } + process.stdout.write(event.delta); + } else if (event.type === 'response.completed') { + process.stdout.write('\n'); + ws.close(); + break; + } + } +} + +main(); diff --git a/scripts/detect-breaking-changes b/scripts/detect-breaking-changes index bf44dd7651..2be5c94848 100755 --- a/scripts/detect-breaking-changes +++ b/scripts/detect-breaking-changes @@ -31,9 +31,9 @@ TEST_PATHS=( tests/api-resources/vector-stores/files.test.ts tests/api-resources/vector-stores/file-batches.test.ts tests/api-resources/beta/beta.test.ts - tests/api-resources/beta/realtime/realtime.test.ts - tests/api-resources/beta/realtime/sessions.test.ts - tests/api-resources/beta/realtime/transcription-sessions.test.ts + tests/api-resources/beta/responses/responses.test.ts + tests/api-resources/beta/responses/input-items.test.ts + tests/api-resources/beta/responses/input-tokens.test.ts tests/api-resources/beta/chatkit/chatkit.test.ts tests/api-resources/beta/chatkit/sessions.test.ts tests/api-resources/beta/chatkit/threads.test.ts diff --git a/src/lib/responses/ResponseInputItems.ts b/src/lib/responses/ResponseInputItems.ts index eb09a397f5..b1ddf9d703 100644 --- a/src/lib/responses/ResponseInputItems.ts +++ b/src/lib/responses/ResponseInputItems.ts @@ -96,6 +96,8 @@ export function toResponseInputItem(item: ResponseInputItemLike): ResponseInputI case 'mcp_call': case 'mcp_list_tools': case 'message': + case 'program': + case 'program_output': case 'reasoning': case 'shell_call': case 'tool_search_call': diff --git a/src/resources/beta/assistants.ts b/src/resources/beta/assistants.ts index ead0b3f6ff..6c91883110 100644 --- a/src/resources/beta/assistants.ts +++ b/src/resources/beta/assistants.ts @@ -1141,19 +1141,12 @@ export interface AssistantCreateParams { name?: string | null; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; @@ -1403,19 +1396,12 @@ export interface AssistantUpdateParams { name?: string | null; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; diff --git a/src/resources/beta/beta.ts b/src/resources/beta/beta.ts index 7bbca11a61..78ad1d8d67 100644 --- a/src/resources/beta/beta.ts +++ b/src/resources/beta/beta.ts @@ -75,6 +75,169 @@ import { } from './realtime/realtime'; import * as ChatKitAPI from './chatkit/chatkit'; import { ChatKit, ChatKitWorkflow } from './chatkit/chatkit'; +import * as ResponsesAPI from './responses/responses'; +import { + BetaApplyPatchTool, + BetaCompactedResponse, + BetaComputerAction, + BetaComputerActionList, + BetaComputerTool, + BetaComputerUsePreviewTool, + BetaContainerAuto, + BetaContainerNetworkPolicyAllowlist, + BetaContainerNetworkPolicyDisabled, + BetaContainerNetworkPolicyDomainSecret, + BetaContainerReference, + BetaCustomTool, + BetaEasyInputMessage, + BetaFileSearchTool, + BetaFunctionShellTool, + BetaFunctionTool, + BetaInlineSkill, + BetaInlineSkillSource, + BetaLocalEnvironment, + BetaLocalSkill, + BetaNamespaceTool, + BetaResponse, + BetaResponseApplyPatchToolCall, + BetaResponseApplyPatchToolCallOutput, + BetaResponseAudioDeltaEvent, + BetaResponseAudioDoneEvent, + BetaResponseAudioTranscriptDeltaEvent, + BetaResponseAudioTranscriptDoneEvent, + BetaResponseCodeInterpreterCallCodeDeltaEvent, + BetaResponseCodeInterpreterCallCodeDoneEvent, + BetaResponseCodeInterpreterCallCompletedEvent, + BetaResponseCodeInterpreterCallInProgressEvent, + BetaResponseCodeInterpreterCallInterpretingEvent, + BetaResponseCodeInterpreterToolCall, + BetaResponseCompactionItem, + BetaResponseCompactionItemParam, + BetaResponseCompletedEvent, + BetaResponseComputerToolCall, + BetaResponseComputerToolCallOutputItem, + BetaResponseComputerToolCallOutputScreenshot, + BetaResponseContainerReference, + BetaResponseContent, + BetaResponseContentPartAddedEvent, + BetaResponseContentPartDoneEvent, + BetaResponseConversationParam, + BetaResponseCreatedEvent, + BetaResponseCustomToolCall, + BetaResponseCustomToolCallInputDeltaEvent, + BetaResponseCustomToolCallInputDoneEvent, + BetaResponseCustomToolCallItem, + BetaResponseCustomToolCallOutput, + BetaResponseCustomToolCallOutputItem, + BetaResponseError, + BetaResponseErrorEvent, + BetaResponseFailedEvent, + BetaResponseFileSearchCallCompletedEvent, + BetaResponseFileSearchCallInProgressEvent, + BetaResponseFileSearchCallSearchingEvent, + BetaResponseFileSearchToolCall, + BetaResponseFormatTextConfig, + BetaResponseFormatTextJSONSchemaConfig, + BetaResponseFunctionCallArgumentsDeltaEvent, + BetaResponseFunctionCallArgumentsDoneEvent, + BetaResponseFunctionCallOutputItem, + BetaResponseFunctionCallOutputItemList, + BetaResponseFunctionShellCallOutputContent, + BetaResponseFunctionShellToolCall, + BetaResponseFunctionShellToolCallOutput, + BetaResponseFunctionToolCall, + BetaResponseFunctionToolCallItem, + BetaResponseFunctionToolCallOutputItem, + BetaResponseFunctionWebSearch, + BetaResponseImageGenCallCompletedEvent, + BetaResponseImageGenCallGeneratingEvent, + BetaResponseImageGenCallInProgressEvent, + BetaResponseImageGenCallPartialImageEvent, + BetaResponseInProgressEvent, + BetaResponseIncludable, + BetaResponseIncompleteEvent, + BetaResponseInjectCreatedEvent, + BetaResponseInjectEvent, + BetaResponseInjectFailedEvent, + BetaResponseInput, + BetaResponseInputAudio, + BetaResponseInputContent, + BetaResponseInputFile, + BetaResponseInputFileContent, + BetaResponseInputImage, + BetaResponseInputImageContent, + BetaResponseInputItem, + BetaResponseInputMessageContentList, + BetaResponseInputMessageItem, + BetaResponseInputText, + BetaResponseInputTextContent, + BetaResponseItem, + BetaResponseLocalEnvironment, + BetaResponseMcpCallArgumentsDeltaEvent, + BetaResponseMcpCallArgumentsDoneEvent, + BetaResponseMcpCallCompletedEvent, + BetaResponseMcpCallFailedEvent, + BetaResponseMcpCallInProgressEvent, + BetaResponseMcpListToolsCompletedEvent, + BetaResponseMcpListToolsFailedEvent, + BetaResponseMcpListToolsInProgressEvent, + BetaResponseOutputAudio, + BetaResponseOutputItem, + BetaResponseOutputItemAddedEvent, + BetaResponseOutputItemDoneEvent, + BetaResponseOutputMessage, + BetaResponseOutputRefusal, + BetaResponseOutputText, + BetaResponseOutputTextAnnotationAddedEvent, + BetaResponsePrompt, + BetaResponseQueuedEvent, + BetaResponseReasoningItem, + BetaResponseReasoningSummaryPartAddedEvent, + BetaResponseReasoningSummaryPartDoneEvent, + BetaResponseReasoningSummaryTextDeltaEvent, + BetaResponseReasoningSummaryTextDoneEvent, + BetaResponseReasoningTextDeltaEvent, + BetaResponseReasoningTextDoneEvent, + BetaResponseRefusalDeltaEvent, + BetaResponseRefusalDoneEvent, + BetaResponseStatus, + BetaResponseStreamEvent, + BetaResponseTextConfig, + BetaResponseTextDeltaEvent, + BetaResponseTextDoneEvent, + BetaResponseToolSearchCall, + BetaResponseToolSearchOutputItem, + BetaResponseToolSearchOutputItemParam, + BetaResponseUsage, + BetaResponseWebSearchCallCompletedEvent, + BetaResponseWebSearchCallInProgressEvent, + BetaResponseWebSearchCallSearchingEvent, + BetaResponsesClientEvent, + BetaResponsesServerEvent, + BetaSkillReference, + BetaTool, + BetaToolChoiceAllowed, + BetaToolChoiceApplyPatch, + BetaToolChoiceCustom, + BetaToolChoiceFunction, + BetaToolChoiceMcp, + BetaToolChoiceOptions, + BetaToolChoiceShell, + BetaToolChoiceTypes, + BetaToolSearchTool, + BetaWebSearchPreviewTool, + BetaWebSearchTool, + ResponseCancelParams, + ResponseCompactParams, + ResponseCreateParams, + ResponseCreateParamsNonStreaming, + ResponseCreateParamsStreaming, + ResponseDeleteParams, + ResponseRetrieveParams, + ResponseRetrieveParamsNonStreaming, + ResponseRetrieveParamsStreaming, + Responses, +} from './responses/responses'; import * as ThreadsAPI from './threads/threads'; import { AssistantResponseFormatOption, @@ -95,12 +258,14 @@ import { export class Beta extends APIResource { realtime: RealtimeAPI.Realtime = new RealtimeAPI.Realtime(this._client); + responses: ResponsesAPI.Responses = new ResponsesAPI.Responses(this._client); chatkit: ChatKitAPI.ChatKit = new ChatKitAPI.ChatKit(this._client); assistants: AssistantsAPI.Assistants = new AssistantsAPI.Assistants(this._client); threads: ThreadsAPI.Threads = new ThreadsAPI.Threads(this._client); } Beta.Realtime = Realtime; +Beta.Responses = Responses; Beta.ChatKit = ChatKit; Beta.Assistants = Assistants; Beta.Threads = Threads; @@ -157,10 +322,173 @@ export declare namespace Beta { type SessionUpdatedEvent as SessionUpdatedEvent, type TranscriptionSessionUpdate as TranscriptionSessionUpdate, type TranscriptionSessionUpdatedEvent as TranscriptionSessionUpdatedEvent, - ChatKit as ChatKit, - type ChatKitWorkflow as ChatKitWorkflow, }; + export { + Responses as Responses, + type BetaApplyPatchTool as BetaApplyPatchTool, + type BetaCompactedResponse as BetaCompactedResponse, + type BetaComputerAction as BetaComputerAction, + type BetaComputerActionList as BetaComputerActionList, + type BetaComputerTool as BetaComputerTool, + type BetaComputerUsePreviewTool as BetaComputerUsePreviewTool, + type BetaContainerAuto as BetaContainerAuto, + type BetaContainerNetworkPolicyAllowlist as BetaContainerNetworkPolicyAllowlist, + type BetaContainerNetworkPolicyDisabled as BetaContainerNetworkPolicyDisabled, + type BetaContainerNetworkPolicyDomainSecret as BetaContainerNetworkPolicyDomainSecret, + type BetaContainerReference as BetaContainerReference, + type BetaCustomTool as BetaCustomTool, + type BetaEasyInputMessage as BetaEasyInputMessage, + type BetaFileSearchTool as BetaFileSearchTool, + type BetaFunctionShellTool as BetaFunctionShellTool, + type BetaFunctionTool as BetaFunctionTool, + type BetaInlineSkill as BetaInlineSkill, + type BetaInlineSkillSource as BetaInlineSkillSource, + type BetaLocalEnvironment as BetaLocalEnvironment, + type BetaLocalSkill as BetaLocalSkill, + type BetaNamespaceTool as BetaNamespaceTool, + type BetaResponse as BetaResponse, + type BetaResponseApplyPatchToolCall as BetaResponseApplyPatchToolCall, + type BetaResponseApplyPatchToolCallOutput as BetaResponseApplyPatchToolCallOutput, + type BetaResponseAudioDeltaEvent as BetaResponseAudioDeltaEvent, + type BetaResponseAudioDoneEvent as BetaResponseAudioDoneEvent, + type BetaResponseAudioTranscriptDeltaEvent as BetaResponseAudioTranscriptDeltaEvent, + type BetaResponseAudioTranscriptDoneEvent as BetaResponseAudioTranscriptDoneEvent, + type BetaResponseCodeInterpreterCallCodeDeltaEvent as BetaResponseCodeInterpreterCallCodeDeltaEvent, + type BetaResponseCodeInterpreterCallCodeDoneEvent as BetaResponseCodeInterpreterCallCodeDoneEvent, + type BetaResponseCodeInterpreterCallCompletedEvent as BetaResponseCodeInterpreterCallCompletedEvent, + type BetaResponseCodeInterpreterCallInProgressEvent as BetaResponseCodeInterpreterCallInProgressEvent, + type BetaResponseCodeInterpreterCallInterpretingEvent as BetaResponseCodeInterpreterCallInterpretingEvent, + type BetaResponseCodeInterpreterToolCall as BetaResponseCodeInterpreterToolCall, + type BetaResponseCompactionItem as BetaResponseCompactionItem, + type BetaResponseCompactionItemParam as BetaResponseCompactionItemParam, + type BetaResponseCompletedEvent as BetaResponseCompletedEvent, + type BetaResponseComputerToolCall as BetaResponseComputerToolCall, + type BetaResponseComputerToolCallOutputItem as BetaResponseComputerToolCallOutputItem, + type BetaResponseComputerToolCallOutputScreenshot as BetaResponseComputerToolCallOutputScreenshot, + type BetaResponseContainerReference as BetaResponseContainerReference, + type BetaResponseContent as BetaResponseContent, + type BetaResponseContentPartAddedEvent as BetaResponseContentPartAddedEvent, + type BetaResponseContentPartDoneEvent as BetaResponseContentPartDoneEvent, + type BetaResponseConversationParam as BetaResponseConversationParam, + type BetaResponseCreatedEvent as BetaResponseCreatedEvent, + type BetaResponseCustomToolCall as BetaResponseCustomToolCall, + type BetaResponseCustomToolCallInputDeltaEvent as BetaResponseCustomToolCallInputDeltaEvent, + type BetaResponseCustomToolCallInputDoneEvent as BetaResponseCustomToolCallInputDoneEvent, + type BetaResponseCustomToolCallItem as BetaResponseCustomToolCallItem, + type BetaResponseCustomToolCallOutput as BetaResponseCustomToolCallOutput, + type BetaResponseCustomToolCallOutputItem as BetaResponseCustomToolCallOutputItem, + type BetaResponseError as BetaResponseError, + type BetaResponseErrorEvent as BetaResponseErrorEvent, + type BetaResponseFailedEvent as BetaResponseFailedEvent, + type BetaResponseFileSearchCallCompletedEvent as BetaResponseFileSearchCallCompletedEvent, + type BetaResponseFileSearchCallInProgressEvent as BetaResponseFileSearchCallInProgressEvent, + type BetaResponseFileSearchCallSearchingEvent as BetaResponseFileSearchCallSearchingEvent, + type BetaResponseFileSearchToolCall as BetaResponseFileSearchToolCall, + type BetaResponseFormatTextConfig as BetaResponseFormatTextConfig, + type BetaResponseFormatTextJSONSchemaConfig as BetaResponseFormatTextJSONSchemaConfig, + type BetaResponseFunctionCallArgumentsDeltaEvent as BetaResponseFunctionCallArgumentsDeltaEvent, + type BetaResponseFunctionCallArgumentsDoneEvent as BetaResponseFunctionCallArgumentsDoneEvent, + type BetaResponseFunctionCallOutputItem as BetaResponseFunctionCallOutputItem, + type BetaResponseFunctionCallOutputItemList as BetaResponseFunctionCallOutputItemList, + type BetaResponseFunctionShellCallOutputContent as BetaResponseFunctionShellCallOutputContent, + type BetaResponseFunctionShellToolCall as BetaResponseFunctionShellToolCall, + type BetaResponseFunctionShellToolCallOutput as BetaResponseFunctionShellToolCallOutput, + type BetaResponseFunctionToolCall as BetaResponseFunctionToolCall, + type BetaResponseFunctionToolCallItem as BetaResponseFunctionToolCallItem, + type BetaResponseFunctionToolCallOutputItem as BetaResponseFunctionToolCallOutputItem, + type BetaResponseFunctionWebSearch as BetaResponseFunctionWebSearch, + type BetaResponseImageGenCallCompletedEvent as BetaResponseImageGenCallCompletedEvent, + type BetaResponseImageGenCallGeneratingEvent as BetaResponseImageGenCallGeneratingEvent, + type BetaResponseImageGenCallInProgressEvent as BetaResponseImageGenCallInProgressEvent, + type BetaResponseImageGenCallPartialImageEvent as BetaResponseImageGenCallPartialImageEvent, + type BetaResponseInProgressEvent as BetaResponseInProgressEvent, + type BetaResponseIncludable as BetaResponseIncludable, + type BetaResponseIncompleteEvent as BetaResponseIncompleteEvent, + type BetaResponseInjectCreatedEvent as BetaResponseInjectCreatedEvent, + type BetaResponseInjectEvent as BetaResponseInjectEvent, + type BetaResponseInjectFailedEvent as BetaResponseInjectFailedEvent, + type BetaResponseInput as BetaResponseInput, + type BetaResponseInputAudio as BetaResponseInputAudio, + type BetaResponseInputContent as BetaResponseInputContent, + type BetaResponseInputFile as BetaResponseInputFile, + type BetaResponseInputFileContent as BetaResponseInputFileContent, + type BetaResponseInputImage as BetaResponseInputImage, + type BetaResponseInputImageContent as BetaResponseInputImageContent, + type BetaResponseInputItem as BetaResponseInputItem, + type BetaResponseInputMessageContentList as BetaResponseInputMessageContentList, + type BetaResponseInputMessageItem as BetaResponseInputMessageItem, + type BetaResponseInputText as BetaResponseInputText, + type BetaResponseInputTextContent as BetaResponseInputTextContent, + type BetaResponseItem as BetaResponseItem, + type BetaResponseLocalEnvironment as BetaResponseLocalEnvironment, + type BetaResponseMcpCallArgumentsDeltaEvent as BetaResponseMcpCallArgumentsDeltaEvent, + type BetaResponseMcpCallArgumentsDoneEvent as BetaResponseMcpCallArgumentsDoneEvent, + type BetaResponseMcpCallCompletedEvent as BetaResponseMcpCallCompletedEvent, + type BetaResponseMcpCallFailedEvent as BetaResponseMcpCallFailedEvent, + type BetaResponseMcpCallInProgressEvent as BetaResponseMcpCallInProgressEvent, + type BetaResponseMcpListToolsCompletedEvent as BetaResponseMcpListToolsCompletedEvent, + type BetaResponseMcpListToolsFailedEvent as BetaResponseMcpListToolsFailedEvent, + type BetaResponseMcpListToolsInProgressEvent as BetaResponseMcpListToolsInProgressEvent, + type BetaResponseOutputAudio as BetaResponseOutputAudio, + type BetaResponseOutputItem as BetaResponseOutputItem, + type BetaResponseOutputItemAddedEvent as BetaResponseOutputItemAddedEvent, + type BetaResponseOutputItemDoneEvent as BetaResponseOutputItemDoneEvent, + type BetaResponseOutputMessage as BetaResponseOutputMessage, + type BetaResponseOutputRefusal as BetaResponseOutputRefusal, + type BetaResponseOutputText as BetaResponseOutputText, + type BetaResponseOutputTextAnnotationAddedEvent as BetaResponseOutputTextAnnotationAddedEvent, + type BetaResponsePrompt as BetaResponsePrompt, + type BetaResponseQueuedEvent as BetaResponseQueuedEvent, + type BetaResponseReasoningItem as BetaResponseReasoningItem, + type BetaResponseReasoningSummaryPartAddedEvent as BetaResponseReasoningSummaryPartAddedEvent, + type BetaResponseReasoningSummaryPartDoneEvent as BetaResponseReasoningSummaryPartDoneEvent, + type BetaResponseReasoningSummaryTextDeltaEvent as BetaResponseReasoningSummaryTextDeltaEvent, + type BetaResponseReasoningSummaryTextDoneEvent as BetaResponseReasoningSummaryTextDoneEvent, + type BetaResponseReasoningTextDeltaEvent as BetaResponseReasoningTextDeltaEvent, + type BetaResponseReasoningTextDoneEvent as BetaResponseReasoningTextDoneEvent, + type BetaResponseRefusalDeltaEvent as BetaResponseRefusalDeltaEvent, + type BetaResponseRefusalDoneEvent as BetaResponseRefusalDoneEvent, + type BetaResponseStatus as BetaResponseStatus, + type BetaResponseStreamEvent as BetaResponseStreamEvent, + type BetaResponseTextConfig as BetaResponseTextConfig, + type BetaResponseTextDeltaEvent as BetaResponseTextDeltaEvent, + type BetaResponseTextDoneEvent as BetaResponseTextDoneEvent, + type BetaResponseToolSearchCall as BetaResponseToolSearchCall, + type BetaResponseToolSearchOutputItem as BetaResponseToolSearchOutputItem, + type BetaResponseToolSearchOutputItemParam as BetaResponseToolSearchOutputItemParam, + type BetaResponseUsage as BetaResponseUsage, + type BetaResponseWebSearchCallCompletedEvent as BetaResponseWebSearchCallCompletedEvent, + type BetaResponseWebSearchCallInProgressEvent as BetaResponseWebSearchCallInProgressEvent, + type BetaResponseWebSearchCallSearchingEvent as BetaResponseWebSearchCallSearchingEvent, + type BetaResponsesClientEvent as BetaResponsesClientEvent, + type BetaResponsesServerEvent as BetaResponsesServerEvent, + type BetaSkillReference as BetaSkillReference, + type BetaTool as BetaTool, + type BetaToolChoiceAllowed as BetaToolChoiceAllowed, + type BetaToolChoiceApplyPatch as BetaToolChoiceApplyPatch, + type BetaToolChoiceCustom as BetaToolChoiceCustom, + type BetaToolChoiceFunction as BetaToolChoiceFunction, + type BetaToolChoiceMcp as BetaToolChoiceMcp, + type BetaToolChoiceOptions as BetaToolChoiceOptions, + type BetaToolChoiceShell as BetaToolChoiceShell, + type BetaToolChoiceTypes as BetaToolChoiceTypes, + type BetaToolSearchTool as BetaToolSearchTool, + type BetaWebSearchPreviewTool as BetaWebSearchPreviewTool, + type BetaWebSearchTool as BetaWebSearchTool, + type ResponseCreateParams as ResponseCreateParams, + type ResponseCreateParamsNonStreaming as ResponseCreateParamsNonStreaming, + type ResponseCreateParamsStreaming as ResponseCreateParamsStreaming, + type ResponseRetrieveParams as ResponseRetrieveParams, + type ResponseRetrieveParamsNonStreaming as ResponseRetrieveParamsNonStreaming, + type ResponseRetrieveParamsStreaming as ResponseRetrieveParamsStreaming, + type ResponseDeleteParams as ResponseDeleteParams, + type ResponseCancelParams as ResponseCancelParams, + type ResponseCompactParams as ResponseCompactParams, + }; + + export { ChatKit as ChatKit, type ChatKitWorkflow as ChatKitWorkflow }; + export { Assistants as Assistants, type Assistant as Assistant, diff --git a/src/resources/beta/index.ts b/src/resources/beta/index.ts index f42fb8f725..9d45e0f4c6 100644 --- a/src/resources/beta/index.ts +++ b/src/resources/beta/index.ts @@ -21,6 +21,169 @@ export { export { Beta } from './beta'; export { Realtime } from './realtime/index'; export { ChatKit, type ChatKitWorkflow } from './chatkit/index'; +export { + Responses, + type BetaApplyPatchTool, + type BetaCompactedResponse, + type BetaComputerAction, + type BetaComputerActionList, + type BetaComputerTool, + type BetaComputerUsePreviewTool, + type BetaContainerAuto, + type BetaContainerNetworkPolicyAllowlist, + type BetaContainerNetworkPolicyDisabled, + type BetaContainerNetworkPolicyDomainSecret, + type BetaContainerReference, + type BetaCustomTool, + type BetaEasyInputMessage, + type BetaFileSearchTool, + type BetaFunctionShellTool, + type BetaFunctionTool, + type BetaInlineSkill, + type BetaInlineSkillSource, + type BetaLocalEnvironment, + type BetaLocalSkill, + type BetaNamespaceTool, + type BetaResponse, + type BetaResponseApplyPatchToolCall, + type BetaResponseApplyPatchToolCallOutput, + type BetaResponseAudioDeltaEvent, + type BetaResponseAudioDoneEvent, + type BetaResponseAudioTranscriptDeltaEvent, + type BetaResponseAudioTranscriptDoneEvent, + type BetaResponseCodeInterpreterCallCodeDeltaEvent, + type BetaResponseCodeInterpreterCallCodeDoneEvent, + type BetaResponseCodeInterpreterCallCompletedEvent, + type BetaResponseCodeInterpreterCallInProgressEvent, + type BetaResponseCodeInterpreterCallInterpretingEvent, + type BetaResponseCodeInterpreterToolCall, + type BetaResponseCompactionItem, + type BetaResponseCompactionItemParam, + type BetaResponseCompletedEvent, + type BetaResponseComputerToolCall, + type BetaResponseComputerToolCallOutputItem, + type BetaResponseComputerToolCallOutputScreenshot, + type BetaResponseContainerReference, + type BetaResponseContent, + type BetaResponseContentPartAddedEvent, + type BetaResponseContentPartDoneEvent, + type BetaResponseConversationParam, + type BetaResponseCreatedEvent, + type BetaResponseCustomToolCall, + type BetaResponseCustomToolCallInputDeltaEvent, + type BetaResponseCustomToolCallInputDoneEvent, + type BetaResponseCustomToolCallItem, + type BetaResponseCustomToolCallOutput, + type BetaResponseCustomToolCallOutputItem, + type BetaResponseError, + type BetaResponseErrorEvent, + type BetaResponseFailedEvent, + type BetaResponseFileSearchCallCompletedEvent, + type BetaResponseFileSearchCallInProgressEvent, + type BetaResponseFileSearchCallSearchingEvent, + type BetaResponseFileSearchToolCall, + type BetaResponseFormatTextConfig, + type BetaResponseFormatTextJSONSchemaConfig, + type BetaResponseFunctionCallArgumentsDeltaEvent, + type BetaResponseFunctionCallArgumentsDoneEvent, + type BetaResponseFunctionCallOutputItem, + type BetaResponseFunctionCallOutputItemList, + type BetaResponseFunctionShellCallOutputContent, + type BetaResponseFunctionShellToolCall, + type BetaResponseFunctionShellToolCallOutput, + type BetaResponseFunctionToolCall, + type BetaResponseFunctionToolCallItem, + type BetaResponseFunctionToolCallOutputItem, + type BetaResponseFunctionWebSearch, + type BetaResponseImageGenCallCompletedEvent, + type BetaResponseImageGenCallGeneratingEvent, + type BetaResponseImageGenCallInProgressEvent, + type BetaResponseImageGenCallPartialImageEvent, + type BetaResponseInProgressEvent, + type BetaResponseIncludable, + type BetaResponseIncompleteEvent, + type BetaResponseInjectCreatedEvent, + type BetaResponseInjectEvent, + type BetaResponseInjectFailedEvent, + type BetaResponseInput, + type BetaResponseInputAudio, + type BetaResponseInputContent, + type BetaResponseInputFile, + type BetaResponseInputFileContent, + type BetaResponseInputImage, + type BetaResponseInputImageContent, + type BetaResponseInputItem, + type BetaResponseInputMessageContentList, + type BetaResponseInputMessageItem, + type BetaResponseInputText, + type BetaResponseInputTextContent, + type BetaResponseItem, + type BetaResponseLocalEnvironment, + type BetaResponseMcpCallArgumentsDeltaEvent, + type BetaResponseMcpCallArgumentsDoneEvent, + type BetaResponseMcpCallCompletedEvent, + type BetaResponseMcpCallFailedEvent, + type BetaResponseMcpCallInProgressEvent, + type BetaResponseMcpListToolsCompletedEvent, + type BetaResponseMcpListToolsFailedEvent, + type BetaResponseMcpListToolsInProgressEvent, + type BetaResponseOutputAudio, + type BetaResponseOutputItem, + type BetaResponseOutputItemAddedEvent, + type BetaResponseOutputItemDoneEvent, + type BetaResponseOutputMessage, + type BetaResponseOutputRefusal, + type BetaResponseOutputText, + type BetaResponseOutputTextAnnotationAddedEvent, + type BetaResponsePrompt, + type BetaResponseQueuedEvent, + type BetaResponseReasoningItem, + type BetaResponseReasoningSummaryPartAddedEvent, + type BetaResponseReasoningSummaryPartDoneEvent, + type BetaResponseReasoningSummaryTextDeltaEvent, + type BetaResponseReasoningSummaryTextDoneEvent, + type BetaResponseReasoningTextDeltaEvent, + type BetaResponseReasoningTextDoneEvent, + type BetaResponseRefusalDeltaEvent, + type BetaResponseRefusalDoneEvent, + type BetaResponseStatus, + type BetaResponseStreamEvent, + type BetaResponseTextConfig, + type BetaResponseTextDeltaEvent, + type BetaResponseTextDoneEvent, + type BetaResponseToolSearchCall, + type BetaResponseToolSearchOutputItem, + type BetaResponseToolSearchOutputItemParam, + type BetaResponseUsage, + type BetaResponseWebSearchCallCompletedEvent, + type BetaResponseWebSearchCallInProgressEvent, + type BetaResponseWebSearchCallSearchingEvent, + type BetaResponsesClientEvent, + type BetaResponsesServerEvent, + type BetaSkillReference, + type BetaTool, + type BetaToolChoiceAllowed, + type BetaToolChoiceApplyPatch, + type BetaToolChoiceCustom, + type BetaToolChoiceFunction, + type BetaToolChoiceMcp, + type BetaToolChoiceOptions, + type BetaToolChoiceShell, + type BetaToolChoiceTypes, + type BetaToolSearchTool, + type BetaWebSearchPreviewTool, + type BetaWebSearchTool, + type ResponseCreateParams, + type ResponseCreateParamsNonStreaming, + type ResponseCreateParamsStreaming, + type ResponseRetrieveParams, + type ResponseRetrieveParamsNonStreaming, + type ResponseRetrieveParamsStreaming, + type ResponseDeleteParams, + type ResponseCancelParams, + type ResponseCompactParams, + type BetaResponseItemsPage, +} from './responses/index'; export { Threads, type AssistantResponseFormatOption, diff --git a/src/resources/beta/responses.ts b/src/resources/beta/responses.ts new file mode 100644 index 0000000000..9d26aac0c6 --- /dev/null +++ b/src/resources/beta/responses.ts @@ -0,0 +1,3 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export * from './responses/index'; diff --git a/src/resources/beta/responses/index.ts b/src/resources/beta/responses/index.ts new file mode 100644 index 0000000000..36283425bf --- /dev/null +++ b/src/resources/beta/responses/index.ts @@ -0,0 +1,169 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export { InputItems, type BetaResponseItemList, type InputItemListParams } from './input-items'; +export { InputTokens, type InputTokenCountResponse, type InputTokenCountParams } from './input-tokens'; +export { + Responses, + type BetaApplyPatchTool, + type BetaCompactedResponse, + type BetaComputerAction, + type BetaComputerActionList, + type BetaComputerTool, + type BetaComputerUsePreviewTool, + type BetaContainerAuto, + type BetaContainerNetworkPolicyAllowlist, + type BetaContainerNetworkPolicyDisabled, + type BetaContainerNetworkPolicyDomainSecret, + type BetaContainerReference, + type BetaCustomTool, + type BetaEasyInputMessage, + type BetaFileSearchTool, + type BetaFunctionShellTool, + type BetaFunctionTool, + type BetaInlineSkill, + type BetaInlineSkillSource, + type BetaLocalEnvironment, + type BetaLocalSkill, + type BetaNamespaceTool, + type BetaResponse, + type BetaResponseApplyPatchToolCall, + type BetaResponseApplyPatchToolCallOutput, + type BetaResponseAudioDeltaEvent, + type BetaResponseAudioDoneEvent, + type BetaResponseAudioTranscriptDeltaEvent, + type BetaResponseAudioTranscriptDoneEvent, + type BetaResponseCodeInterpreterCallCodeDeltaEvent, + type BetaResponseCodeInterpreterCallCodeDoneEvent, + type BetaResponseCodeInterpreterCallCompletedEvent, + type BetaResponseCodeInterpreterCallInProgressEvent, + type BetaResponseCodeInterpreterCallInterpretingEvent, + type BetaResponseCodeInterpreterToolCall, + type BetaResponseCompactionItem, + type BetaResponseCompactionItemParam, + type BetaResponseCompletedEvent, + type BetaResponseComputerToolCall, + type BetaResponseComputerToolCallOutputItem, + type BetaResponseComputerToolCallOutputScreenshot, + type BetaResponseContainerReference, + type BetaResponseContent, + type BetaResponseContentPartAddedEvent, + type BetaResponseContentPartDoneEvent, + type BetaResponseConversationParam, + type BetaResponseCreatedEvent, + type BetaResponseCustomToolCall, + type BetaResponseCustomToolCallInputDeltaEvent, + type BetaResponseCustomToolCallInputDoneEvent, + type BetaResponseCustomToolCallItem, + type BetaResponseCustomToolCallOutput, + type BetaResponseCustomToolCallOutputItem, + type BetaResponseError, + type BetaResponseErrorEvent, + type BetaResponseFailedEvent, + type BetaResponseFileSearchCallCompletedEvent, + type BetaResponseFileSearchCallInProgressEvent, + type BetaResponseFileSearchCallSearchingEvent, + type BetaResponseFileSearchToolCall, + type BetaResponseFormatTextConfig, + type BetaResponseFormatTextJSONSchemaConfig, + type BetaResponseFunctionCallArgumentsDeltaEvent, + type BetaResponseFunctionCallArgumentsDoneEvent, + type BetaResponseFunctionCallOutputItem, + type BetaResponseFunctionCallOutputItemList, + type BetaResponseFunctionShellCallOutputContent, + type BetaResponseFunctionShellToolCall, + type BetaResponseFunctionShellToolCallOutput, + type BetaResponseFunctionToolCall, + type BetaResponseFunctionToolCallItem, + type BetaResponseFunctionToolCallOutputItem, + type BetaResponseFunctionWebSearch, + type BetaResponseImageGenCallCompletedEvent, + type BetaResponseImageGenCallGeneratingEvent, + type BetaResponseImageGenCallInProgressEvent, + type BetaResponseImageGenCallPartialImageEvent, + type BetaResponseInProgressEvent, + type BetaResponseIncludable, + type BetaResponseIncompleteEvent, + type BetaResponseInjectCreatedEvent, + type BetaResponseInjectEvent, + type BetaResponseInjectFailedEvent, + type BetaResponseInput, + type BetaResponseInputAudio, + type BetaResponseInputContent, + type BetaResponseInputFile, + type BetaResponseInputFileContent, + type BetaResponseInputImage, + type BetaResponseInputImageContent, + type BetaResponseInputItem, + type BetaResponseInputMessageContentList, + type BetaResponseInputMessageItem, + type BetaResponseInputText, + type BetaResponseInputTextContent, + type BetaResponseItem, + type BetaResponseLocalEnvironment, + type BetaResponseMcpCallArgumentsDeltaEvent, + type BetaResponseMcpCallArgumentsDoneEvent, + type BetaResponseMcpCallCompletedEvent, + type BetaResponseMcpCallFailedEvent, + type BetaResponseMcpCallInProgressEvent, + type BetaResponseMcpListToolsCompletedEvent, + type BetaResponseMcpListToolsFailedEvent, + type BetaResponseMcpListToolsInProgressEvent, + type BetaResponseOutputAudio, + type BetaResponseOutputItem, + type BetaResponseOutputItemAddedEvent, + type BetaResponseOutputItemDoneEvent, + type BetaResponseOutputMessage, + type BetaResponseOutputRefusal, + type BetaResponseOutputText, + type BetaResponseOutputTextAnnotationAddedEvent, + type BetaResponsePrompt, + type BetaResponseQueuedEvent, + type BetaResponseReasoningItem, + type BetaResponseReasoningSummaryPartAddedEvent, + type BetaResponseReasoningSummaryPartDoneEvent, + type BetaResponseReasoningSummaryTextDeltaEvent, + type BetaResponseReasoningSummaryTextDoneEvent, + type BetaResponseReasoningTextDeltaEvent, + type BetaResponseReasoningTextDoneEvent, + type BetaResponseRefusalDeltaEvent, + type BetaResponseRefusalDoneEvent, + type BetaResponseStatus, + type BetaResponseStreamEvent, + type BetaResponseTextConfig, + type BetaResponseTextDeltaEvent, + type BetaResponseTextDoneEvent, + type BetaResponseToolSearchCall, + type BetaResponseToolSearchOutputItem, + type BetaResponseToolSearchOutputItemParam, + type BetaResponseUsage, + type BetaResponseWebSearchCallCompletedEvent, + type BetaResponseWebSearchCallInProgressEvent, + type BetaResponseWebSearchCallSearchingEvent, + type BetaResponsesClientEvent, + type BetaResponsesServerEvent, + type BetaSkillReference, + type BetaTool, + type BetaToolChoiceAllowed, + type BetaToolChoiceApplyPatch, + type BetaToolChoiceCustom, + type BetaToolChoiceFunction, + type BetaToolChoiceMcp, + type BetaToolChoiceOptions, + type BetaToolChoiceShell, + type BetaToolChoiceTypes, + type BetaToolSearchTool, + type BetaWebSearchPreviewTool, + type BetaWebSearchTool, + type ResponseCreateParams, + type ResponseCreateParamsNonStreaming, + type ResponseCreateParamsStreaming, + type ResponseRetrieveParams, + type ResponseRetrieveParamsNonStreaming, + type ResponseRetrieveParamsStreaming, + type ResponseDeleteParams, + type ResponseCancelParams, + type ResponseCompactParams, + type BetaResponseItemsPage, +} from './responses'; +export { type ResponsesWSClientOptions } from './ws'; +export { type ResponsesWSReconnectOptions } from './ws-base'; diff --git a/src/resources/beta/responses/input-items.ts b/src/resources/beta/responses/input-items.ts new file mode 100644 index 0000000000..5c504636fc --- /dev/null +++ b/src/resources/beta/responses/input-items.ts @@ -0,0 +1,105 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../../../core/resource'; +import * as ResponsesAPI from './responses'; +import { BetaResponseItemsPage } from './responses'; +import { CursorPage, type CursorPageParams, PagePromise } from '../../../core/pagination'; +import { buildHeaders } from '../../../internal/headers'; +import { RequestOptions } from '../../../internal/request-options'; +import { path } from '../../../internal/utils/path'; + +export class InputItems extends APIResource { + /** + * Returns a list of input items for a given response. + * + * @example + * ```ts + * // Automatically fetches more pages as needed. + * for await (const betaResponseItem of client.beta.responses.inputItems.list( + * 'response_id', + * )) { + * // ... + * } + * ``` + */ + list( + responseID: string, + params: InputItemListParams | null | undefined = {}, + options?: RequestOptions, + ): PagePromise { + const { betas, ...query } = params ?? {}; + return this._client.getAPIList( + path`/responses/${responseID}/input_items?beta=true`, + CursorPage, + { + query, + ...options, + headers: buildHeaders([ + { ...(betas?.toString() != null ? { 'openai-beta': betas?.toString() } : undefined) }, + options?.headers, + ]), + __security: { bearerAuth: true }, + }, + ); + } +} + +/** + * A list of Response items. + */ +export interface BetaResponseItemList { + /** + * A list of items used to generate this response. + */ + data: Array; + + /** + * The ID of the first item in the list. + */ + first_id: string; + + /** + * Whether there are more items available. + */ + has_more: boolean; + + /** + * The ID of the last item in the list. + */ + last_id: string; + + /** + * The type of object returned, must be `list`. + */ + object: 'list'; +} + +export interface InputItemListParams extends CursorPageParams { + /** + * Query param: Additional fields to include in the response. See the `include` + * parameter for Response creation above for more information. + */ + include?: Array; + + /** + * Query param: The order to return the input items in. Default is `desc`. + * + * - `asc`: Return the input items in ascending order. + * - `desc`: Return the input items in descending order. + */ + order?: 'asc' | 'desc'; + + /** + * Header param: Optional beta features to enable for this request. + */ + betas?: Array<'responses_multi_agent=v1'>; +} + +export declare namespace InputItems { + export { + type BetaResponseItemList as BetaResponseItemList, + type InputItemListParams as InputItemListParams, + }; +} + +export { type BetaResponseItemsPage }; diff --git a/src/resources/beta/responses/input-tokens.ts b/src/resources/beta/responses/input-tokens.ts new file mode 100644 index 0000000000..3c971c0a62 --- /dev/null +++ b/src/resources/beta/responses/input-tokens.ts @@ -0,0 +1,245 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../../../core/resource'; +import * as ResponsesAPI from './responses'; +import { APIPromise } from '../../../core/api-promise'; +import { buildHeaders } from '../../../internal/headers'; +import { RequestOptions } from '../../../internal/request-options'; + +export class InputTokens extends APIResource { + /** + * Returns input token counts of the request. + * + * Returns an object with `object` set to `response.input_tokens` and an + * `input_tokens` count. + * + * @example + * ```ts + * const response = + * await client.beta.responses.inputTokens.count(); + * ``` + */ + count( + params: InputTokenCountParams | null | undefined = {}, + options?: RequestOptions, + ): APIPromise { + const { betas, ...body } = params ?? {}; + return this._client.post('/responses/input_tokens?beta=true', { + body, + ...options, + headers: buildHeaders([ + { ...(betas?.toString() != null ? { 'openai-beta': betas?.toString() } : undefined) }, + options?.headers, + ]), + __security: { bearerAuth: true }, + }); + } +} + +export interface InputTokenCountResponse { + input_tokens: number; + + object: 'response.input_tokens'; +} + +export interface InputTokenCountParams { + /** + * Body param: 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. + */ + conversation?: string | ResponsesAPI.BetaResponseConversationParam | null; + + /** + * Body param: Text, image, or file inputs to the model, used to generate a + * response + */ + input?: string | Array | null; + + /** + * Body param: 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. + */ + instructions?: string | null; + + /** + * Body param: 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. + */ + model?: string | null; + + /** + * Body param: Whether to allow the model to run tool calls in parallel. + */ + parallel_tool_calls?: boolean | null; + + /** + * Body param: 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. + */ + personality?: (string & {}) | 'friendly' | 'pragmatic'; + + /** + * Body param: 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`. + */ + previous_response_id?: string | null; + + /** + * Body param: **gpt-5 and o-series models only** Configuration options for + * [reasoning models](https://platform.openai.com/docs/guides/reasoning). + */ + reasoning?: InputTokenCountParams.Reasoning | null; + + /** + * Body param: 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) + */ + text?: InputTokenCountParams.Text | null; + + /** + * Body param: Controls which tool the model should use, if any. + */ + tool_choice?: + | ResponsesAPI.BetaToolChoiceOptions + | ResponsesAPI.BetaToolChoiceAllowed + | ResponsesAPI.BetaToolChoiceTypes + | ResponsesAPI.BetaToolChoiceFunction + | ResponsesAPI.BetaToolChoiceMcp + | ResponsesAPI.BetaToolChoiceCustom + | InputTokenCountParams.BetaSpecificProgrammaticToolCallingParam + | ResponsesAPI.BetaToolChoiceApplyPatch + | ResponsesAPI.BetaToolChoiceShell + | null; + + /** + * Body param: 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. + */ + tools?: Array | null; + + /** + * @deprecated Body param: 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. + */ + truncation?: 'auto' | 'disabled'; + + /** + * Header param: Optional beta features to enable for this request. + */ + betas?: Array<'responses_multi_agent=v1'>; +} + +export namespace InputTokenCountParams { + /** + * **gpt-5 and o-series models only** Configuration options for + * [reasoning models](https://platform.openai.com/docs/guides/reasoning). + */ + export interface Reasoning { + /** + * 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. + */ + context?: 'auto' | 'current_turn' | 'all_turns' | null; + + /** + * 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. + */ + effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null; + + /** + * @deprecated **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`. + */ + generate_summary?: 'auto' | 'concise' | 'detailed' | null; + + /** + * Controls the reasoning execution mode for the request. + * + * When returned on a response, this is the effective execution mode. + */ + mode?: (string & {}) | 'standard' | 'pro'; + + /** + * 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`. + */ + summary?: 'auto' | 'concise' | 'detailed' | null; + } + + /** + * 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) + */ + export interface Text { + /** + * 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. + */ + format?: ResponsesAPI.BetaResponseFormatTextConfig; + + /** + * 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`. + */ + verbosity?: 'low' | 'medium' | 'high' | null; + } + + export interface BetaSpecificProgrammaticToolCallingParam { + /** + * The tool to call. Always `programmatic_tool_calling`. + */ + type: 'programmatic_tool_calling'; + } +} + +export declare namespace InputTokens { + export { + type InputTokenCountResponse as InputTokenCountResponse, + type InputTokenCountParams as InputTokenCountParams, + }; +} diff --git a/src/resources/beta/responses/internal-base.ts b/src/resources/beta/responses/internal-base.ts new file mode 100644 index 0000000000..cb2bce10ed --- /dev/null +++ b/src/resources/beta/responses/internal-base.ts @@ -0,0 +1,117 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import * as ResponsesAPI from './responses'; +import { OpenAI } from '../../../client'; +import { EventEmitter } from '../../../core/EventEmitter'; +import { OpenAIError } from '../../../core/error'; + +import type { RawWebSocketData, ReconnectingEvent, UnsentMessage } from '../../../internal/ws'; + +export type ResponsesStreamMessage = + | { type: 'connecting' | 'open' | 'closing' } + | { + type: 'close'; + code: number; + reason: string; + unsent: UnsentMessage[]; + } + | { type: 'reconnecting'; reconnect: ReconnectingEvent } + | { type: 'reconnected' } + | { type: 'message'; message: ResponsesAPI.BetaResponsesServerEvent } + | { type: 'raw'; data: RawWebSocketData } + | { type: 'error'; error: WebSocketError }; + +export class WebSocketError extends OpenAIError { + /** + * The error data that the API sent back in an error event. + */ + error?: ResponsesAPI.BetaResponseErrorEvent | undefined; + + constructor(message: string, event: ResponsesAPI.BetaResponseErrorEvent | null) { + super(message); + + this.error = event ?? undefined; + } +} + +type Simplify = { [KeyType in keyof T]: T[KeyType] } & {}; + +type WebSocketEvents = Simplify< + { + event: (event: ResponsesAPI.BetaResponsesServerEvent) => void; + raw: (data: RawWebSocketData) => void; + error: (error: WebSocketError) => void; + close: ( + code: number, + reason: string, + unsent: UnsentMessage[], + ) => void; + reconnecting: (event: ReconnectingEvent) => void; + reconnected: () => void; + } & { + [EventType in Exclude, 'error'>]: ( + event: Extract, + ) => unknown; + } +>; + +export abstract class ResponsesEmitter extends EventEmitter { + /** + * Send an event to the API. + */ + abstract send(event: ResponsesAPI.BetaResponsesClientEvent): void; + + /** + * Send raw data over the WebSocket without JSON serialization. + */ + abstract sendRaw(data: RawWebSocketData): void; + + /** + * Close the WebSocket connection. + */ + abstract close(props?: { code: number; reason: string }): void; + + protected _onError(event: null, message: string, cause: any): void; + protected _onError(event: ResponsesAPI.BetaResponseErrorEvent, message?: string | undefined): void; + protected _onError( + event: ResponsesAPI.BetaResponseErrorEvent | null, + message?: string | undefined, + cause?: any, + ): void { + message = message ?? safeJSONStringify(event) ?? 'unknown error'; + + if (!this._hasListener('error')) { + const error = new WebSocketError( + message + + `\n\nTo resolve these unhandled rejection errors you should bind an \`error\` callback, e.g. \`ws.on('error', (error) => ...)\` `, + event, + ); + // @ts-ignore + error.cause = cause; + Promise.reject(error); + return; + } + + const error = new WebSocketError(message, event); + // @ts-ignore + error.cause = cause; + + this._emit('error', error); + } +} + +export function buildURL(client: OpenAI, parameters: Record): URL { + const { ...query } = parameters; + const endpoint = '/responses'; + const url = new URL(client.buildURL(endpoint, query, undefined)); + url.protocol = url.protocol === 'http:' || url.protocol === 'ws:' ? 'ws:' : 'wss:'; + return url; +} + +function safeJSONStringify(value: unknown): string | null { + try { + return JSON.stringify(value); + } catch { + return null; + } +} diff --git a/src/resources/beta/responses/responses.ts b/src/resources/beta/responses/responses.ts new file mode 100644 index 0000000000..5e8305bcfc --- /dev/null +++ b/src/resources/beta/responses/responses.ts @@ -0,0 +1,12632 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../../../core/resource'; +import * as ResponsesAPI from './responses'; +import * as InputItemsAPI from './input-items'; +import { BetaResponseItemList, InputItemListParams, InputItems } from './input-items'; +import * as InputTokensAPI from './input-tokens'; +import { InputTokenCountParams, InputTokenCountResponse, InputTokens } from './input-tokens'; +import { APIPromise } from '../../../core/api-promise'; +import { CursorPage } from '../../../core/pagination'; +import { Stream } from '../../../core/streaming'; +import { buildHeaders } from '../../../internal/headers'; +import { RequestOptions } from '../../../internal/request-options'; +import { path } from '../../../internal/utils/path'; + +export class Responses extends APIResource { + inputItems: InputItemsAPI.InputItems = new InputItemsAPI.InputItems(this._client); + inputTokens: InputTokensAPI.InputTokens = new InputTokensAPI.InputTokens(this._client); + + /** + * 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. + * + * @example + * ```ts + * const betaResponse = await client.beta.responses.create(); + * ``` + */ + create(params: ResponseCreateParamsNonStreaming, options?: RequestOptions): APIPromise; + create( + params: ResponseCreateParamsStreaming, + options?: RequestOptions, + ): APIPromise>; + create( + params: ResponseCreateParamsBase, + options?: RequestOptions, + ): APIPromise | BetaResponse>; + create( + params: ResponseCreateParams, + options?: RequestOptions, + ): APIPromise | APIPromise> { + const { betas, ...body } = params; + return this._client.post('/responses?beta=true', { + body, + ...options, + headers: buildHeaders([ + { ...(betas?.toString() != null ? { 'openai-beta': betas?.toString() } : undefined) }, + options?.headers, + ]), + stream: params.stream ?? false, + __security: { bearerAuth: true }, + }) as APIPromise | APIPromise>; + } + + /** + * Retrieves a model response with the given ID. + * + * @example + * ```ts + * const betaResponse = await client.beta.responses.retrieve( + * 'resp_677efb5139a88190b512bc3fef8e535d', + * ); + * ``` + */ + retrieve( + responseID: string, + params?: ResponseRetrieveParamsNonStreaming, + options?: RequestOptions, + ): APIPromise; + retrieve( + responseID: string, + params: ResponseRetrieveParamsStreaming, + options?: RequestOptions, + ): APIPromise>; + retrieve( + responseID: string, + params?: ResponseRetrieveParamsBase | undefined, + options?: RequestOptions, + ): APIPromise | BetaResponse>; + retrieve( + responseID: string, + params: ResponseRetrieveParams | undefined = {}, + options?: RequestOptions, + ): APIPromise | APIPromise> { + const { betas, ...query } = params ?? {}; + return this._client.get(path`/responses/${responseID}?beta=true`, { + query, + ...options, + headers: buildHeaders([ + { ...(betas?.toString() != null ? { 'openai-beta': betas?.toString() } : undefined) }, + options?.headers, + ]), + stream: params?.stream ?? false, + __security: { bearerAuth: true }, + }) as APIPromise | APIPromise>; + } + + /** + * Deletes a model response with the given ID. + * + * @example + * ```ts + * await client.beta.responses.delete( + * 'resp_677efb5139a88190b512bc3fef8e535d', + * ); + * ``` + */ + delete( + responseID: string, + params: ResponseDeleteParams | null | undefined = {}, + options?: RequestOptions, + ): APIPromise { + const { betas } = params ?? {}; + return this._client.delete(path`/responses/${responseID}?beta=true`, { + ...options, + headers: buildHeaders([ + { Accept: '*/*', ...(betas?.toString() != null ? { 'openai-beta': betas?.toString() } : undefined) }, + options?.headers, + ]), + __security: { bearerAuth: 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). + * + * @example + * ```ts + * const betaResponse = await client.beta.responses.cancel( + * 'resp_677efb5139a88190b512bc3fef8e535d', + * ); + * ``` + */ + cancel( + responseID: string, + params: ResponseCancelParams | null | undefined = {}, + options?: RequestOptions, + ): APIPromise { + const { betas } = params ?? {}; + return this._client.post(path`/responses/${responseID}/cancel?beta=true`, { + ...options, + headers: buildHeaders([ + { ...(betas?.toString() != null ? { 'openai-beta': betas?.toString() } : undefined) }, + options?.headers, + ]), + __security: { bearerAuth: true }, + }); + } + + /** + * Compact a conversation. Returns a compacted response object. + * + * 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). + * + * @example + * ```ts + * const betaCompactedResponse = + * await client.beta.responses.compact({ + * model: 'gpt-5.6-sol', + * }); + * ``` + */ + compact(params: ResponseCompactParams, options?: RequestOptions): APIPromise { + const { betas, ...body } = params; + return this._client.post('/responses/compact?beta=true', { + body, + ...options, + headers: buildHeaders([ + { ...(betas?.toString() != null ? { 'openai-beta': betas?.toString() } : undefined) }, + options?.headers, + ]), + __security: { bearerAuth: true }, + }); + } +} + +export type BetaResponseItemsPage = CursorPage; + +/** + * Allows the assistant to create, delete, or update files using unified diffs. + */ +export interface BetaApplyPatchTool { + /** + * The type of the tool. Always `apply_patch`. + */ + type: 'apply_patch'; + + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; +} + +export interface BetaCompactedResponse { + /** + * The unique identifier for the compacted response. + */ + id: string; + + /** + * Unix timestamp (in seconds) when the compacted conversation was created. + */ + created_at: number; + + /** + * The object type. Always `response.compaction`. + */ + object: 'response.compaction'; + + /** + * The compacted list of output items. This is a list of all user messages, + * followed by a single compaction item. + */ + output: Array; + + /** + * Token accounting for the compaction pass, including cached, reasoning, and total + * tokens. + */ + usage: BetaResponseUsage; +} + +/** + * A click action. + */ +export type BetaComputerAction = + | BetaComputerAction.Click + | BetaComputerAction.DoubleClick + | BetaComputerAction.Drag + | BetaComputerAction.Keypress + | BetaComputerAction.Move + | BetaComputerAction.Screenshot + | BetaComputerAction.Scroll + | BetaComputerAction.Type + | BetaComputerAction.Wait; + +export namespace BetaComputerAction { + /** + * A click action. + */ + export interface Click { + /** + * Indicates which mouse button was pressed during the click. One of `left`, + * `right`, `wheel`, `back`, or `forward`. + */ + button: 'left' | 'right' | 'wheel' | 'back' | 'forward'; + + /** + * Specifies the event type. For a click action, this property is always `click`. + */ + type: 'click'; + + /** + * The x-coordinate where the click occurred. + */ + x: number; + + /** + * The y-coordinate where the click occurred. + */ + y: number; + + /** + * The keys being held while clicking. + */ + keys?: Array | null; + } + + /** + * A double click action. + */ + export interface DoubleClick { + /** + * The keys being held while double-clicking. + */ + keys: Array | null; + + /** + * Specifies the event type. For a double click action, this property is always set + * to `double_click`. + */ + type: 'double_click'; + + /** + * The x-coordinate where the double click occurred. + */ + x: number; + + /** + * The y-coordinate where the double click occurred. + */ + y: number; + } + + /** + * A drag action. + */ + export interface Drag { + /** + * 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 } + * ] + * ``` + */ + path: Array; + + /** + * Specifies the event type. For a drag action, this property is always set to + * `drag`. + */ + type: 'drag'; + + /** + * The keys being held while dragging the mouse. + */ + keys?: Array | null; + } + + export namespace Drag { + /** + * An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`. + */ + export interface Path { + /** + * The x-coordinate. + */ + x: number; + + /** + * The y-coordinate. + */ + y: number; + } + } + + /** + * A collection of keypresses the model would like to perform. + */ + export interface Keypress { + /** + * The combination of keys the model is requesting to be pressed. This is an array + * of strings, each representing a key. + */ + keys: Array; + + /** + * Specifies the event type. For a keypress action, this property is always set to + * `keypress`. + */ + type: 'keypress'; + } + + /** + * A mouse move action. + */ + export interface Move { + /** + * Specifies the event type. For a move action, this property is always set to + * `move`. + */ + type: 'move'; + + /** + * The x-coordinate to move to. + */ + x: number; + + /** + * The y-coordinate to move to. + */ + y: number; + + /** + * The keys being held while moving the mouse. + */ + keys?: Array | null; + } + + /** + * A screenshot action. + */ + export interface Screenshot { + /** + * Specifies the event type. For a screenshot action, this property is always set + * to `screenshot`. + */ + type: 'screenshot'; + } + + /** + * A scroll action. + */ + export interface Scroll { + /** + * The horizontal scroll distance. + */ + scroll_x: number; + + /** + * The vertical scroll distance. + */ + scroll_y: number; + + /** + * Specifies the event type. For a scroll action, this property is always set to + * `scroll`. + */ + type: 'scroll'; + + /** + * The x-coordinate where the scroll occurred. + */ + x: number; + + /** + * The y-coordinate where the scroll occurred. + */ + y: number; + + /** + * The keys being held while scrolling. + */ + keys?: Array | null; + } + + /** + * An action to type in text. + */ + export interface Type { + /** + * The text to type. + */ + text: string; + + /** + * Specifies the event type. For a type action, this property is always set to + * `type`. + */ + type: 'type'; + } + + /** + * A wait action. + */ + export interface Wait { + /** + * Specifies the event type. For a wait action, this property is always set to + * `wait`. + */ + type: 'wait'; + } +} + +/** + * Flattened batched actions for `computer_use`. Each action includes an `type` + * discriminator and action-specific fields. + */ +export type BetaComputerActionList = Array; + +/** + * A tool that controls a virtual computer. Learn more about the + * [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + */ +export interface BetaComputerTool { + /** + * The type of the computer tool. Always `computer`. + */ + type: 'computer'; +} + +/** + * A tool that controls a virtual computer. Learn more about the + * [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + */ +export interface BetaComputerUsePreviewTool { + /** + * The height of the computer display. + */ + display_height: number; + + /** + * The width of the computer display. + */ + display_width: number; + + /** + * The type of computer environment to control. + */ + environment: 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser'; + + /** + * The type of the computer use tool. Always `computer_use_preview`. + */ + type: 'computer_use_preview'; +} + +export interface BetaContainerAuto { + /** + * Automatically creates a container for this request + */ + type: 'container_auto'; + + /** + * An optional list of uploaded files to make available to your code. + */ + file_ids?: Array; + + /** + * The memory limit for the container. + */ + memory_limit?: '1g' | '4g' | '16g' | '64g' | null; + + /** + * Network access policy for the container. + */ + network_policy?: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist; + + /** + * An optional list of skills referenced by id or inline data. + */ + skills?: Array; +} + +export interface BetaContainerNetworkPolicyAllowlist { + /** + * A list of allowed domains when type is `allowlist`. + */ + allowed_domains: Array; + + /** + * Allow outbound network access only to specified domains. Always `allowlist`. + */ + type: 'allowlist'; + + /** + * Optional domain-scoped secrets for allowlisted domains. + */ + domain_secrets?: Array; +} + +export interface BetaContainerNetworkPolicyDisabled { + /** + * Disable outbound network access. Always `disabled`. + */ + type: 'disabled'; +} + +export interface BetaContainerNetworkPolicyDomainSecret { + /** + * The domain associated with the secret. + */ + domain: string; + + /** + * The name of the secret to inject for the domain. + */ + name: string; + + /** + * The secret value to inject for the domain. + */ + value: string; +} + +export interface BetaContainerReference { + /** + * The ID of the referenced container. + */ + container_id: string; + + /** + * References a container created with the /v1/containers endpoint + */ + type: 'container_reference'; +} + +/** + * 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) + */ +export interface BetaCustomTool { + /** + * The name of the custom tool, used to identify it in tool calls. + */ + name: string; + + /** + * The type of the custom tool. Always `custom`. + */ + type: 'custom'; + + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + + /** + * Whether this tool should be deferred and discovered via tool search. + */ + defer_loading?: boolean; + + /** + * Optional description of the custom tool, used to provide more context. + */ + description?: string; + + /** + * The input format for the custom tool. Default is unconstrained text. + */ + format?: BetaCustomTool.Text | BetaCustomTool.Grammar; +} + +export namespace BetaCustomTool { + /** + * Unconstrained free-form text. + */ + export interface Text { + /** + * Unconstrained text format. Always `text`. + */ + type: 'text'; + } + + /** + * A grammar defined by the user. + */ + export interface Grammar { + /** + * The grammar definition. + */ + definition: string; + + /** + * The syntax of the grammar definition. One of `lark` or `regex`. + */ + syntax: 'lark' | 'regex'; + + /** + * Grammar format. Always `grammar`. + */ + type: 'grammar'; + } +} + +/** + * 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. + */ +export interface BetaEasyInputMessage { + /** + * Text, image, or audio input to the model, used to generate a response. Can also + * contain previous assistant responses. + */ + content: string | BetaResponseInputMessageContentList; + + /** + * The role of the message input. One of `user`, `assistant`, `system`, or + * `developer`. + */ + role: 'user' | 'assistant' | 'system' | 'developer'; + + /** + * 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. + */ + phase?: 'commentary' | 'final_answer' | null; + + /** + * The type of the message input. Always `message`. + */ + type?: '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). + */ +export interface BetaFileSearchTool { + /** + * The type of the file search tool. Always `file_search`. + */ + type: 'file_search'; + + /** + * The IDs of the vector stores to search. + */ + vector_store_ids: Array; + + /** + * A filter to apply. + */ + filters?: BetaFileSearchTool.ComparisonFilter | BetaFileSearchTool.CompoundFilter | null; + + /** + * The maximum number of results to return. This number should be between 1 and 50 + * inclusive. + */ + max_num_results?: number; + + /** + * Ranking options for search. + */ + ranking_options?: BetaFileSearchTool.RankingOptions; +} + +export namespace BetaFileSearchTool { + /** + * A filter used to compare a specified attribute key to a given value using a + * defined comparison operation. + */ + export interface ComparisonFilter { + /** + * The key to compare against the value. + */ + key: string; + + /** + * 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 + */ + type: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin'; + + /** + * The value to compare against the attribute key; supports string, number, or + * boolean types. + */ + value: string | number | boolean | Array; + } + + /** + * Combine multiple filters using `and` or `or`. + */ + export interface CompoundFilter { + /** + * Array of filters to combine. Items can be `ComparisonFilter` or + * `CompoundFilter`. + */ + filters: Array; + + /** + * Type of operation: `and` or `or`. + */ + type: 'and' | 'or'; + } + + export namespace CompoundFilter { + /** + * A filter used to compare a specified attribute key to a given value using a + * defined comparison operation. + */ + export interface ComparisonFilter { + /** + * The key to compare against the value. + */ + key: string; + + /** + * 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 + */ + type: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin'; + + /** + * The value to compare against the attribute key; supports string, number, or + * boolean types. + */ + value: string | number | boolean | Array; + } + } + + /** + * Ranking options for search. + */ + export interface RankingOptions { + /** + * Weights that control how reciprocal rank fusion balances semantic embedding + * matches versus sparse keyword matches when hybrid search is enabled. + */ + hybrid_search?: RankingOptions.HybridSearch; + + /** + * The ranker to use for the file search. + */ + ranker?: 'auto' | 'default-2024-11-15'; + + /** + * 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. + */ + score_threshold?: number; + } + + export namespace RankingOptions { + /** + * Weights that control how reciprocal rank fusion balances semantic embedding + * matches versus sparse keyword matches when hybrid search is enabled. + */ + export interface HybridSearch { + /** + * The weight of the embedding in the reciprocal ranking fusion. + */ + embedding_weight: number; + + /** + * The weight of the text in the reciprocal ranking fusion. + */ + text_weight: number; + } + } +} + +/** + * A tool that allows the model to execute shell commands. + */ +export interface BetaFunctionShellTool { + /** + * The type of the shell tool. Always `shell`. + */ + type: 'shell'; + + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + + environment?: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference | null; +} + +/** + * 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). + */ +export interface BetaFunctionTool { + /** + * The name of the function to call. + */ + name: string; + + /** + * A JSON schema object describing the parameters of the function. + */ + parameters: { [key: string]: unknown } | null; + + /** + * Whether strict parameter validation is enforced for this function tool. + */ + strict: boolean | null; + + /** + * The type of the function tool. Always `function`. + */ + type: 'function'; + + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + + /** + * Whether this function is deferred and loaded via tool search. + */ + defer_loading?: boolean; + + /** + * A description of the function. Used by the model to determine whether or not to + * call the function. + */ + description?: string | null; + + /** + * A JSON schema object describing the JSON value encoded in string outputs for + * this function. + */ + output_schema?: { [key: string]: unknown } | null; +} + +export interface BetaInlineSkill { + /** + * The description of the skill. + */ + description: string; + + /** + * The name of the skill. + */ + name: string; + + /** + * Inline skill payload + */ + source: BetaInlineSkillSource; + + /** + * Defines an inline skill for this request. + */ + type: 'inline'; +} + +/** + * Inline skill payload + */ +export interface BetaInlineSkillSource { + /** + * Base64-encoded skill zip bundle. + */ + data: string; + + /** + * The media type of the inline skill payload. Must be `application/zip`. + */ + media_type: 'application/zip'; + + /** + * The type of the inline skill source. Must be `base64`. + */ + type: 'base64'; +} + +export interface BetaLocalEnvironment { + /** + * Use a local computer environment. + */ + type: 'local'; + + /** + * An optional list of skills. + */ + skills?: Array; +} + +export interface BetaLocalSkill { + /** + * The description of the skill. + */ + description: string; + + /** + * The name of the skill. + */ + name: string; + + /** + * The path to the directory containing the skill. + */ + path: string; +} + +/** + * Groups function/custom tools under a shared namespace. + */ +export interface BetaNamespaceTool { + /** + * A description of the namespace shown to the model. + */ + description: string; + + /** + * The namespace name used in tool calls (for example, `crm`). + */ + name: string; + + /** + * The function/custom tools available inside this namespace. + */ + tools: Array; + + /** + * The type of the tool. Always `namespace`. + */ + type: 'namespace'; +} + +export namespace BetaNamespaceTool { + export interface Function { + name: string; + + type: 'function'; + + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + + /** + * Whether this function should be deferred and discovered via tool search. + */ + defer_loading?: boolean; + + description?: string | null; + + /** + * A JSON Schema describing the JSON value encoded in string outputs for this + * function tool. This does not describe content-array outputs. + */ + output_schema?: { [key: string]: unknown } | null; + + parameters?: unknown | null; + + /** + * 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. + */ + strict?: boolean | null; + } +} + +export interface BetaResponse { + /** + * Unique identifier for this Response. + */ + id: string; + + /** + * Unix timestamp (in seconds) of when this Response was created. + */ + created_at: number; + + /** + * An error object returned when the model fails to generate a Response. + */ + error: BetaResponseError | null; + + /** + * Details about why the response is incomplete. + */ + incomplete_details: BetaResponse.IncompleteDetails | 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. + */ + instructions: string | Array | null; + + /** + * 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. + */ + metadata: { [key: string]: string } | null; + + /** + * 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. + */ + model: + | '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' + | (string & {}); + + /** + * The object type of this resource - always set to `response`. + */ + object: 'response'; + + /** + * 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. + */ + output: Array; + + /** + * Whether to allow the model to run tool calls in parallel. + */ + parallel_tool_calls: boolean; + + /** + * 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. + */ + temperature: number | null; + + /** + * 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. + */ + tool_choice: + | BetaToolChoiceOptions + | BetaToolChoiceAllowed + | BetaToolChoiceTypes + | BetaToolChoiceFunction + | BetaToolChoiceMcp + | BetaToolChoiceCustom + | BetaResponse.BetaSpecificProgrammaticToolCallingParam + | BetaToolChoiceApplyPatch + | BetaToolChoiceShell; + + /** + * 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. + */ + tools: Array; + + /** + * 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. + */ + top_p: number | null; + + /** + * Whether to run the model response in the background. + * [Learn more](https://platform.openai.com/docs/guides/background). + */ + background?: boolean | null; + + /** + * Unix timestamp (in seconds) of when this Response was completed. Only present + * when the status is `completed`. + */ + completed_at?: number | null; + + /** + * The conversation that this response belonged to. Input items and output items + * from this response were automatically added to this conversation. + */ + conversation?: BetaResponse.Conversation | null; + + /** + * 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_output_tokens?: number | null; + + /** + * 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. + */ + max_tool_calls?: number | null; + + /** + * Moderation results for the response input and output, if moderated completions + * were requested. + */ + moderation?: BetaResponse.Moderation | null; + + /** + * 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`. + */ + previous_response_id?: string | null; + + /** + * Reference to a prompt template and its variables. + * [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + */ + prompt?: BetaResponsePrompt | null; + + /** + * 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_key?: string; + + /** + * The prompt-caching options that were applied to the response. Supported for + * `gpt-5.6` and later models. + */ + prompt_cache_options?: BetaResponse.PromptCacheOptions; + + /** + * @deprecated 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. + */ + prompt_cache_retention?: 'in_memory' | '24h' | null; + + /** + * **gpt-5 and o-series models only** + * + * Configuration options for + * [reasoning models](https://platform.openai.com/docs/guides/reasoning). + */ + reasoning?: BetaResponse.Reasoning | null; + + /** + * 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). + */ + safety_identifier?: string; + + /** + * 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. + */ + service_tier?: 'auto' | 'default' | 'flex' | 'scale' | 'priority' | null; + + /** + * The status of the response generation. One of `completed`, `failed`, + * `in_progress`, `cancelled`, `queued`, or `incomplete`. + */ + status?: BetaResponseStatus; + + /** + * 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) + */ + text?: BetaResponseTextConfig; + + /** + * 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_logprobs?: number | null; + + /** + * 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. + */ + truncation?: 'auto' | 'disabled' | null; + + /** + * Represents token usage details including input tokens, output tokens, a + * breakdown of output tokens, and the total tokens used. + */ + usage?: BetaResponseUsage; + + /** + * @deprecated 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). + */ + user?: string; +} + +export namespace BetaResponse { + /** + * Details about why the response is incomplete. + */ + export interface IncompleteDetails { + /** + * The reason why the response is incomplete. + */ + reason?: 'max_output_tokens' | 'content_filter'; + } + + export interface BetaSpecificProgrammaticToolCallingParam { + /** + * The tool to call. Always `programmatic_tool_calling`. + */ + type: 'programmatic_tool_calling'; + } + + /** + * The conversation that this response belonged to. Input items and output items + * from this response were automatically added to this conversation. + */ + export interface Conversation { + /** + * The unique ID of the conversation that this response was associated with. + */ + id: string; + } + + /** + * Moderation results for the response input and output, if moderated completions + * were requested. + */ + export interface Moderation { + /** + * Moderation for the response input. + */ + input: Moderation.ModerationResult | Moderation.Error; + + /** + * Moderation for the response output. + */ + output: Moderation.ModerationResult | Moderation.Error; + } + + export namespace Moderation { + /** + * A moderation result produced for the response input or output. + */ + export interface ModerationResult { + /** + * A dictionary of moderation categories to booleans, True if the input is flagged + * under this category. + */ + categories: { [key: string]: boolean }; + + /** + * Which modalities of input are reflected by the score for each category. + */ + category_applied_input_types: { [key: string]: Array<'text' | 'image'> }; + + /** + * A dictionary of moderation categories to scores. + */ + category_scores: { [key: string]: number }; + + /** + * A boolean indicating whether the content was flagged by any category. + */ + flagged: boolean; + + /** + * The moderation model that produced this result. + */ + model: string; + + /** + * The object type, which was always `moderation_result` for successful moderation + * results. + */ + type: 'moderation_result'; + } + + /** + * An error produced while attempting moderation for the response input or output. + */ + export interface Error { + /** + * The error code. + */ + code: string; + + /** + * The error message. + */ + message: string; + + /** + * The object type, which was always `error` for moderation failures. + */ + type: 'error'; + } + + /** + * A moderation result produced for the response input or output. + */ + export interface ModerationResult { + /** + * A dictionary of moderation categories to booleans, True if the input is flagged + * under this category. + */ + categories: { [key: string]: boolean }; + + /** + * Which modalities of input are reflected by the score for each category. + */ + category_applied_input_types: { [key: string]: Array<'text' | 'image'> }; + + /** + * A dictionary of moderation categories to scores. + */ + category_scores: { [key: string]: number }; + + /** + * A boolean indicating whether the content was flagged by any category. + */ + flagged: boolean; + + /** + * The moderation model that produced this result. + */ + model: string; + + /** + * The object type, which was always `moderation_result` for successful moderation + * results. + */ + type: 'moderation_result'; + } + + /** + * An error produced while attempting moderation for the response input or output. + */ + export interface Error { + /** + * The error code. + */ + code: string; + + /** + * The error message. + */ + message: string; + + /** + * The object type, which was always `error` for moderation failures. + */ + type: 'error'; + } + } + + /** + * The prompt-caching options that were applied to the response. Supported for + * `gpt-5.6` and later models. + */ + export interface PromptCacheOptions { + /** + * Whether implicit prompt-cache breakpoints were enabled. + */ + mode: 'implicit' | 'explicit'; + + /** + * The minimum lifetime applied to each cache breakpoint. + */ + ttl: '30m'; + } + + /** + * **gpt-5 and o-series models only** + * + * Configuration options for + * [reasoning models](https://platform.openai.com/docs/guides/reasoning). + */ + export interface Reasoning { + /** + * 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. + */ + context?: 'auto' | 'current_turn' | 'all_turns' | null; + + /** + * 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. + */ + effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null; + + /** + * @deprecated **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`. + */ + generate_summary?: 'auto' | 'concise' | 'detailed' | null; + + /** + * Controls the reasoning execution mode for the request. + * + * When returned on a response, this is the effective execution mode. + */ + mode?: (string & {}) | 'standard' | 'pro'; + + /** + * 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`. + */ + summary?: 'auto' | 'concise' | 'detailed' | null; + } +} + +/** + * A tool call that applies file diffs by creating, deleting, or updating files. + */ +export interface BetaResponseApplyPatchToolCall { + /** + * The unique ID of the apply patch tool call. Populated when this item is returned + * via API. + */ + id: string; + + /** + * The unique ID of the apply patch tool call generated by the model. + */ + call_id: string; + + /** + * One of the create_file, delete_file, or update_file operations applied via + * apply_patch. + */ + operation: + | BetaResponseApplyPatchToolCall.CreateFile + | BetaResponseApplyPatchToolCall.DeleteFile + | BetaResponseApplyPatchToolCall.UpdateFile; + + /** + * The status of the apply patch tool call. One of `in_progress` or `completed`. + */ + status: 'in_progress' | 'completed'; + + /** + * The type of the item. Always `apply_patch_call`. + */ + type: 'apply_patch_call'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseApplyPatchToolCall.Agent; + + /** + * The execution context that produced this tool call. + */ + caller?: BetaResponseApplyPatchToolCall.Direct | BetaResponseApplyPatchToolCall.Program | null; + + /** + * The ID of the entity that created this tool call. + */ + created_by?: string; +} + +export namespace BetaResponseApplyPatchToolCall { + /** + * Instruction describing how to create a file via the apply_patch tool. + */ + export interface CreateFile { + /** + * Diff to apply. + */ + diff: string; + + /** + * Path of the file to create. + */ + path: string; + + /** + * Create a new file with the provided diff. + */ + type: 'create_file'; + } + + /** + * Instruction describing how to delete a file via the apply_patch tool. + */ + export interface DeleteFile { + /** + * Path of the file to delete. + */ + path: string; + + /** + * Delete the specified file. + */ + type: 'delete_file'; + } + + /** + * Instruction describing how to update a file via the apply_patch tool. + */ + export interface UpdateFile { + /** + * Diff to apply. + */ + diff: string; + + /** + * Path of the file to update. + */ + path: string; + + /** + * Update an existing file with the provided diff. + */ + type: 'update_file'; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + type: 'program'; + } +} + +/** + * The output emitted by an apply patch tool call. + */ +export interface BetaResponseApplyPatchToolCallOutput { + /** + * The unique ID of the apply patch tool call output. Populated when this item is + * returned via API. + */ + id: string; + + /** + * The unique ID of the apply patch tool call generated by the model. + */ + call_id: string; + + /** + * The status of the apply patch tool call output. One of `completed` or `failed`. + */ + status: 'completed' | 'failed'; + + /** + * The type of the item. Always `apply_patch_call_output`. + */ + type: 'apply_patch_call_output'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseApplyPatchToolCallOutput.Agent; + + /** + * The execution context that produced this tool call. + */ + caller?: BetaResponseApplyPatchToolCallOutput.Direct | BetaResponseApplyPatchToolCallOutput.Program | null; + + /** + * The ID of the entity that created this tool call output. + */ + created_by?: string; + + /** + * Optional textual output returned by the apply patch tool. + */ + output?: string | null; +} + +export namespace BetaResponseApplyPatchToolCallOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + type: 'program'; + } +} + +/** + * Emitted when there is a partial audio response. + */ +export interface BetaResponseAudioDeltaEvent { + /** + * A chunk of Base64 encoded response audio bytes. + */ + delta: string; + + /** + * A sequence number for this chunk of the stream response. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.audio.delta`. + */ + type: 'response.audio.delta'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseAudioDeltaEvent.Agent | null; +} + +export namespace BetaResponseAudioDeltaEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when the audio response is complete. + */ +export interface BetaResponseAudioDoneEvent { + /** + * The sequence number of the delta. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.audio.done`. + */ + type: 'response.audio.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseAudioDoneEvent.Agent | null; +} + +export namespace BetaResponseAudioDoneEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when there is a partial transcript of audio. + */ +export interface BetaResponseAudioTranscriptDeltaEvent { + /** + * The partial transcript of the audio response. + */ + delta: string; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.audio.transcript.delta`. + */ + type: 'response.audio.transcript.delta'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseAudioTranscriptDeltaEvent.Agent | null; +} + +export namespace BetaResponseAudioTranscriptDeltaEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when the full audio transcript is completed. + */ +export interface BetaResponseAudioTranscriptDoneEvent { + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.audio.transcript.done`. + */ + type: 'response.audio.transcript.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseAudioTranscriptDoneEvent.Agent | null; +} + +export namespace BetaResponseAudioTranscriptDoneEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a partial code snippet is streamed by the code interpreter. + */ +export interface BetaResponseCodeInterpreterCallCodeDeltaEvent { + /** + * The partial code snippet being streamed by the code interpreter. + */ + delta: string; + + /** + * The unique identifier of the code interpreter tool call item. + */ + item_id: string; + + /** + * The index of the output item in the response for which the code is being + * streamed. + */ + output_index: number; + + /** + * The sequence number of this event, used to order streaming events. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.code_interpreter_call_code.delta`. + */ + type: 'response.code_interpreter_call_code.delta'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseCodeInterpreterCallCodeDeltaEvent.Agent | null; +} + +export namespace BetaResponseCodeInterpreterCallCodeDeltaEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when the code snippet is finalized by the code interpreter. + */ +export interface BetaResponseCodeInterpreterCallCodeDoneEvent { + /** + * The final code snippet output by the code interpreter. + */ + code: string; + + /** + * The unique identifier of the code interpreter tool call item. + */ + item_id: string; + + /** + * The index of the output item in the response for which the code is finalized. + */ + output_index: number; + + /** + * The sequence number of this event, used to order streaming events. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.code_interpreter_call_code.done`. + */ + type: 'response.code_interpreter_call_code.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseCodeInterpreterCallCodeDoneEvent.Agent | null; +} + +export namespace BetaResponseCodeInterpreterCallCodeDoneEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when the code interpreter call is completed. + */ +export interface BetaResponseCodeInterpreterCallCompletedEvent { + /** + * The unique identifier of the code interpreter tool call item. + */ + item_id: string; + + /** + * The index of the output item in the response for which the code interpreter call + * is completed. + */ + output_index: number; + + /** + * The sequence number of this event, used to order streaming events. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.code_interpreter_call.completed`. + */ + type: 'response.code_interpreter_call.completed'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseCodeInterpreterCallCompletedEvent.Agent | null; +} + +export namespace BetaResponseCodeInterpreterCallCompletedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a code interpreter call is in progress. + */ +export interface BetaResponseCodeInterpreterCallInProgressEvent { + /** + * The unique identifier of the code interpreter tool call item. + */ + item_id: string; + + /** + * The index of the output item in the response for which the code interpreter call + * is in progress. + */ + output_index: number; + + /** + * The sequence number of this event, used to order streaming events. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.code_interpreter_call.in_progress`. + */ + type: 'response.code_interpreter_call.in_progress'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseCodeInterpreterCallInProgressEvent.Agent | null; +} + +export namespace BetaResponseCodeInterpreterCallInProgressEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when the code interpreter is actively interpreting the code snippet. + */ +export interface BetaResponseCodeInterpreterCallInterpretingEvent { + /** + * The unique identifier of the code interpreter tool call item. + */ + item_id: string; + + /** + * The index of the output item in the response for which the code interpreter is + * interpreting code. + */ + output_index: number; + + /** + * The sequence number of this event, used to order streaming events. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.code_interpreter_call.interpreting`. + */ + type: 'response.code_interpreter_call.interpreting'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseCodeInterpreterCallInterpretingEvent.Agent | null; +} + +export namespace BetaResponseCodeInterpreterCallInterpretingEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * A tool call to run code. + */ +export interface BetaResponseCodeInterpreterToolCall { + /** + * The unique ID of the code interpreter tool call. + */ + id: string; + + /** + * The code to run, or null if not available. + */ + code: string | null; + + /** + * The ID of the container used to run the code. + */ + container_id: string; + + /** + * The outputs generated by the code interpreter, such as logs or images. Can be + * null if no outputs are available. + */ + outputs: Array | null; + + /** + * The status of the code interpreter tool call. Valid values are `in_progress`, + * `completed`, `incomplete`, `interpreting`, and `failed`. + */ + status: 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed'; + + /** + * The type of the code interpreter tool call. Always `code_interpreter_call`. + */ + type: 'code_interpreter_call'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseCodeInterpreterToolCall.Agent | null; +} + +export namespace BetaResponseCodeInterpreterToolCall { + /** + * The logs output from the code interpreter. + */ + export interface Logs { + /** + * The logs output from the code interpreter. + */ + logs: string; + + /** + * The type of the output. Always `logs`. + */ + type: 'logs'; + } + + /** + * The image output from the code interpreter. + */ + export interface Image { + /** + * The type of the output. Always `image`. + */ + type: 'image'; + + /** + * The URL of the image output from the code interpreter. + */ + url: string; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * A compaction item generated by the + * [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + */ +export interface BetaResponseCompactionItem { + /** + * The unique ID of the compaction item. + */ + id: string; + + /** + * The encrypted content that was produced by compaction. + */ + encrypted_content: string; + + /** + * The type of the item. Always `compaction`. + */ + type: 'compaction'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseCompactionItem.Agent; + + /** + * The identifier of the actor that created the item. + */ + created_by?: string; +} + +export namespace BetaResponseCompactionItem { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * A compaction item generated by the + * [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + */ +export interface BetaResponseCompactionItemParam { + /** + * The encrypted content of the compaction summary. + */ + encrypted_content: string; + + /** + * The type of the item. Always `compaction`. + */ + type: 'compaction'; + + /** + * The ID of the compaction item. + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseCompactionItemParam.Agent | null; +} + +export namespace BetaResponseCompactionItemParam { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when the model response is complete. + */ +export interface BetaResponseCompletedEvent { + /** + * Properties of the completed response. + */ + response: BetaResponse; + + /** + * The sequence number for this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.completed`. + */ + type: 'response.completed'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseCompletedEvent.Agent | null; +} + +export namespace BetaResponseCompletedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * 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. + */ +export interface BetaResponseComputerToolCall { + /** + * The unique ID of the computer call. + */ + id: string; + + /** + * An identifier used when responding to the tool call with output. + */ + call_id: string; + + /** + * The pending safety checks for the computer call. + */ + pending_safety_checks: Array; + + /** + * The status of the item. One of `in_progress`, `completed`, or `incomplete`. + * Populated when items are returned via API. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The type of the computer call. Always `computer_call`. + */ + type: 'computer_call'; + + /** + * A click action. + */ + action?: BetaComputerAction; + + /** + * Flattened batched actions for `computer_use`. Each action includes an `type` + * discriminator and action-specific fields. + */ + actions?: BetaComputerActionList; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseComputerToolCall.Agent | null; +} + +export namespace BetaResponseComputerToolCall { + /** + * A pending safety check for the computer call. + */ + export interface PendingSafetyCheck { + /** + * The ID of the pending safety check. + */ + id: string; + + /** + * The type of the pending safety check. + */ + code?: string | null; + + /** + * Details about the pending safety check. + */ + message?: string | null; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +export interface BetaResponseComputerToolCallOutputItem { + /** + * The unique ID of the computer call tool output. + */ + id: string; + + /** + * The ID of the computer tool call that produced the output. + */ + call_id: string; + + /** + * A computer screenshot image used with the computer use tool. + */ + output: BetaResponseComputerToolCallOutputScreenshot; + + /** + * The status of the message input. One of `in_progress`, `completed`, or + * `incomplete`. Populated when input items are returned via API. + */ + status: 'completed' | 'incomplete' | 'failed' | 'in_progress'; + + /** + * The type of the computer tool call output. Always `computer_call_output`. + */ + type: 'computer_call_output'; + + /** + * The safety checks reported by the API that have been acknowledged by the + * developer. + */ + acknowledged_safety_checks?: Array; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseComputerToolCallOutputItem.Agent | null; + + /** + * The identifier of the actor that created the item. + */ + created_by?: string; +} + +export namespace BetaResponseComputerToolCallOutputItem { + /** + * A pending safety check for the computer call. + */ + export interface AcknowledgedSafetyCheck { + /** + * The ID of the pending safety check. + */ + id: string; + + /** + * The type of the pending safety check. + */ + code?: string | null; + + /** + * Details about the pending safety check. + */ + message?: string | null; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * A computer screenshot image used with the computer use tool. + */ +export interface BetaResponseComputerToolCallOutputScreenshot { + /** + * Specifies the event type. For a computer screenshot, this property is always set + * to `computer_screenshot`. + */ + type: 'computer_screenshot'; + + /** + * The identifier of an uploaded file that contains the screenshot. + */ + file_id?: string; + + /** + * The URL of the screenshot image. + */ + image_url?: string; +} + +/** + * Represents a container created with /v1/containers. + */ +export interface BetaResponseContainerReference { + container_id: string; + + /** + * The environment type. Always `container_reference`. + */ + type: 'container_reference'; +} + +/** + * Multi-modal input and output contents. + */ +export type BetaResponseContent = + | BetaResponseInputText + | BetaResponseInputImage + | BetaResponseInputFile + | BetaResponseOutputText + | BetaResponseOutputRefusal + | BetaResponseContent.ReasoningText; + +export namespace BetaResponseContent { + /** + * Reasoning text from the model. + */ + export interface ReasoningText { + /** + * The reasoning text from the model. + */ + text: string; + + /** + * The type of the reasoning text. Always `reasoning_text`. + */ + type: 'reasoning_text'; + } +} + +/** + * Emitted when a new content part is added. + */ +export interface BetaResponseContentPartAddedEvent { + /** + * The index of the content part that was added. + */ + content_index: number; + + /** + * The ID of the output item that the content part was added to. + */ + item_id: string; + + /** + * The index of the output item that the content part was added to. + */ + output_index: number; + + /** + * The content part that was added. + */ + part: BetaResponseOutputText | BetaResponseOutputRefusal | BetaResponseContentPartAddedEvent.ReasoningText; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.content_part.added`. + */ + type: 'response.content_part.added'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseContentPartAddedEvent.Agent | null; +} + +export namespace BetaResponseContentPartAddedEvent { + /** + * Reasoning text from the model. + */ + export interface ReasoningText { + /** + * The reasoning text from the model. + */ + text: string; + + /** + * The type of the reasoning text. Always `reasoning_text`. + */ + type: 'reasoning_text'; + } + + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a content part is done. + */ +export interface BetaResponseContentPartDoneEvent { + /** + * The index of the content part that is done. + */ + content_index: number; + + /** + * The ID of the output item that the content part was added to. + */ + item_id: string; + + /** + * The index of the output item that the content part was added to. + */ + output_index: number; + + /** + * The content part that is done. + */ + part: BetaResponseOutputText | BetaResponseOutputRefusal | BetaResponseContentPartDoneEvent.ReasoningText; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.content_part.done`. + */ + type: 'response.content_part.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseContentPartDoneEvent.Agent | null; +} + +export namespace BetaResponseContentPartDoneEvent { + /** + * Reasoning text from the model. + */ + export interface ReasoningText { + /** + * The reasoning text from the model. + */ + text: string; + + /** + * The type of the reasoning text. Always `reasoning_text`. + */ + type: 'reasoning_text'; + } + + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * The conversation that this response belongs to. + */ +export interface BetaResponseConversationParam { + /** + * The unique ID of the conversation. + */ + id: string; +} + +/** + * An event that is emitted when a response is created. + */ +export interface BetaResponseCreatedEvent { + /** + * The response that was created. + */ + response: BetaResponse; + + /** + * The sequence number for this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.created`. + */ + type: 'response.created'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseCreatedEvent.Agent | null; +} + +export namespace BetaResponseCreatedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * A call to a custom tool created by the model. + */ +export interface BetaResponseCustomToolCall { + /** + * An identifier used to map this custom tool call to a tool call output. + */ + call_id: string; + + /** + * The input for the custom tool call generated by the model. + */ + input: string; + + /** + * The name of the custom tool being called. + */ + name: string; + + /** + * The type of the custom tool call. Always `custom_tool_call`. + */ + type: 'custom_tool_call'; + + /** + * The unique ID of the custom tool call in the OpenAI platform. + */ + id?: string; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseCustomToolCall.Agent | null; + + /** + * The execution context that produced this tool call. + */ + caller?: BetaResponseCustomToolCall.Direct | BetaResponseCustomToolCall.Program | null; + + /** + * The namespace of the custom tool being called. + */ + namespace?: string; +} + +export namespace BetaResponseCustomToolCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + type: 'program'; + } +} + +/** + * Event representing a delta (partial update) to the input of a custom tool call. + */ +export interface BetaResponseCustomToolCallInputDeltaEvent { + /** + * The incremental input data (delta) for the custom tool call. + */ + delta: string; + + /** + * Unique identifier for the API item associated with this event. + */ + item_id: string; + + /** + * The index of the output this delta applies to. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The event type identifier. + */ + type: 'response.custom_tool_call_input.delta'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseCustomToolCallInputDeltaEvent.Agent | null; +} + +export namespace BetaResponseCustomToolCallInputDeltaEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Event indicating that input for a custom tool call is complete. + */ +export interface BetaResponseCustomToolCallInputDoneEvent { + /** + * The complete input data for the custom tool call. + */ + input: string; + + /** + * Unique identifier for the API item associated with this event. + */ + item_id: string; + + /** + * The index of the output this event applies to. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The event type identifier. + */ + type: 'response.custom_tool_call_input.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseCustomToolCallInputDoneEvent.Agent | null; +} + +export namespace BetaResponseCustomToolCallInputDoneEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * A call to a custom tool created by the model. + */ +export interface BetaResponseCustomToolCallItem extends BetaResponseCustomToolCall { + /** + * The unique ID of the custom tool call item. + */ + id: string; + + /** + * The status of the item. One of `in_progress`, `completed`, or `incomplete`. + * Populated when items are returned via API. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The identifier of the actor that created the item. + */ + created_by?: string; +} + +/** + * The output of a custom tool call from your code, being sent back to the model. + */ +export interface BetaResponseCustomToolCallOutput { + /** + * The call ID, used to map this custom tool call output to a custom tool call. + */ + call_id: string; + + /** + * The output from the custom tool call generated by your code. Can be a string or + * an list of output content. + */ + output: string | Array; + + /** + * The type of the custom tool call output. Always `custom_tool_call_output`. + */ + type: 'custom_tool_call_output'; + + /** + * The unique ID of the custom tool call output in the OpenAI platform. + */ + id?: string; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseCustomToolCallOutput.Agent | null; + + /** + * The execution context that produced this tool call. + */ + caller?: BetaResponseCustomToolCallOutput.Direct | BetaResponseCustomToolCallOutput.Program | null; +} + +export namespace BetaResponseCustomToolCallOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } +} + +/** + * The output of a custom tool call from your code, being sent back to the model. + */ +export interface BetaResponseCustomToolCallOutputItem extends BetaResponseCustomToolCallOutput { + /** + * The unique ID of the custom tool call output item. + */ + id: string; + + /** + * The status of the item. One of `in_progress`, `completed`, or `incomplete`. + * Populated when items are returned via API. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The identifier of the actor that created the item. + */ + created_by?: string; +} + +/** + * An error object returned when the model fails to generate a Response. + */ +export interface BetaResponseError { + /** + * The error code for the response. + */ + code: + | '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'; + + /** + * A human-readable description of the error. + */ + message: string; +} + +/** + * Emitted when an error occurs. + */ +export interface BetaResponseErrorEvent { + /** + * The error code. + */ + code: string | null; + + /** + * The error message. + */ + message: string; + + /** + * The error parameter. + */ + param: string | null; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `error`. + */ + type: 'error'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseErrorEvent.Agent | null; +} + +export namespace BetaResponseErrorEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * An event that is emitted when a response fails. + */ +export interface BetaResponseFailedEvent { + /** + * The response that failed. + */ + response: BetaResponse; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.failed`. + */ + type: 'response.failed'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseFailedEvent.Agent | null; +} + +export namespace BetaResponseFailedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a file search call is completed (results found). + */ +export interface BetaResponseFileSearchCallCompletedEvent { + /** + * The ID of the output item that the file search call is initiated. + */ + item_id: string; + + /** + * The index of the output item that the file search call is initiated. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.file_search_call.completed`. + */ + type: 'response.file_search_call.completed'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseFileSearchCallCompletedEvent.Agent | null; +} + +export namespace BetaResponseFileSearchCallCompletedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a file search call is initiated. + */ +export interface BetaResponseFileSearchCallInProgressEvent { + /** + * The ID of the output item that the file search call is initiated. + */ + item_id: string; + + /** + * The index of the output item that the file search call is initiated. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.file_search_call.in_progress`. + */ + type: 'response.file_search_call.in_progress'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseFileSearchCallInProgressEvent.Agent | null; +} + +export namespace BetaResponseFileSearchCallInProgressEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a file search is currently searching. + */ +export interface BetaResponseFileSearchCallSearchingEvent { + /** + * The ID of the output item that the file search call is initiated. + */ + item_id: string; + + /** + * The index of the output item that the file search call is searching. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.file_search_call.searching`. + */ + type: 'response.file_search_call.searching'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseFileSearchCallSearchingEvent.Agent | null; +} + +export namespace BetaResponseFileSearchCallSearchingEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * 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. + */ +export interface BetaResponseFileSearchToolCall { + /** + * The unique ID of the file search tool call. + */ + id: string; + + /** + * The queries used to search for files. + */ + queries: Array; + + /** + * The status of the file search tool call. One of `in_progress`, `searching`, + * `incomplete` or `failed`, + */ + status: 'in_progress' | 'searching' | 'completed' | 'incomplete' | 'failed'; + + /** + * The type of the file search tool call. Always `file_search_call`. + */ + type: 'file_search_call'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseFileSearchToolCall.Agent | null; + + /** + * The results of the file search tool call. + */ + results?: Array | null; +} + +export namespace BetaResponseFileSearchToolCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Result { + /** + * 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. + */ + attributes?: { [key: string]: string | number | boolean } | null; + + /** + * The unique ID of the file. + */ + file_id?: string; + + /** + * The name of the file. + */ + filename?: string; + + /** + * The relevance score of the file - a value between 0 and 1. + */ + score?: number; + + /** + * The text that was retrieved from the file. + */ + text?: string; + } +} + +/** + * 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. + */ +export type BetaResponseFormatTextConfig = + | BetaResponseFormatTextConfig.Text + | BetaResponseFormatTextJSONSchemaConfig + | BetaResponseFormatTextConfig.JSONObject; + +export namespace BetaResponseFormatTextConfig { + /** + * Default response format. Used to generate text responses. + */ + export interface Text { + /** + * The type of response format being defined. Always `text`. + */ + type: 'text'; + } + + /** + * 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. + */ + export interface JSONObject { + /** + * The type of response format being defined. Always `json_object`. + */ + type: 'json_object'; + } +} + +/** + * JSON Schema response format. Used to generate structured JSON responses. Learn + * more about + * [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + */ +export interface BetaResponseFormatTextJSONSchemaConfig { + /** + * 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. + */ + name: string; + + /** + * The schema for the response format, described as a JSON Schema object. Learn how + * to build JSON schemas [here](https://json-schema.org/). + */ + schema: { [key: string]: unknown }; + + /** + * The type of response format being defined. Always `json_schema`. + */ + type: 'json_schema'; + + /** + * A description of what the response format is for, used by the model to determine + * how to respond in the format. + */ + description?: string; + + /** + * 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). + */ + strict?: boolean | null; +} + +/** + * Emitted when there is a partial function-call arguments delta. + */ +export interface BetaResponseFunctionCallArgumentsDeltaEvent { + /** + * The function-call arguments delta that is added. + */ + delta: string; + + /** + * The ID of the output item that the function-call arguments delta is added to. + */ + item_id: string; + + /** + * The index of the output item that the function-call arguments delta is added to. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.function_call_arguments.delta`. + */ + type: 'response.function_call_arguments.delta'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseFunctionCallArgumentsDeltaEvent.Agent | null; +} + +export namespace BetaResponseFunctionCallArgumentsDeltaEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when function-call arguments are finalized. + */ +export interface BetaResponseFunctionCallArgumentsDoneEvent { + /** + * The function-call arguments. + */ + arguments: string; + + /** + * The ID of the item. + */ + item_id: string; + + /** + * The name of the function that was called. + */ + name: string; + + /** + * The index of the output item. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + type: 'response.function_call_arguments.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseFunctionCallArgumentsDoneEvent.Agent | null; +} + +export namespace BetaResponseFunctionCallArgumentsDoneEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * A piece of message content, such as text, an image, or a file. + */ +export type BetaResponseFunctionCallOutputItem = + | BetaResponseInputTextContent + | BetaResponseInputImageContent + | BetaResponseInputFileContent; + +/** + * An array of content outputs (text, image, file) for the function tool call. + */ +export type BetaResponseFunctionCallOutputItemList = Array; + +/** + * Captured stdout and stderr for a portion of a shell tool call output. + */ +export interface BetaResponseFunctionShellCallOutputContent { + /** + * The exit or timeout outcome associated with this shell call. + */ + outcome: + | BetaResponseFunctionShellCallOutputContent.Timeout + | BetaResponseFunctionShellCallOutputContent.Exit; + + /** + * Captured stderr output for the shell call. + */ + stderr: string; + + /** + * Captured stdout output for the shell call. + */ + stdout: string; +} + +export namespace BetaResponseFunctionShellCallOutputContent { + /** + * Indicates that the shell call exceeded its configured time limit. + */ + export interface Timeout { + /** + * The outcome type. Always `timeout`. + */ + type: 'timeout'; + } + + /** + * Indicates that the shell commands finished and returned an exit code. + */ + export interface Exit { + /** + * The exit code returned by the shell process. + */ + exit_code: number; + + /** + * The outcome type. Always `exit`. + */ + type: 'exit'; + } +} + +/** + * A tool call that executes one or more shell commands in a managed environment. + */ +export interface BetaResponseFunctionShellToolCall { + /** + * The unique ID of the shell tool call. Populated when this item is returned via + * API. + */ + id: string; + + /** + * The shell commands and limits that describe how to run the tool call. + */ + action: BetaResponseFunctionShellToolCall.Action; + + /** + * The unique ID of the shell tool call generated by the model. + */ + call_id: string; + + /** + * Represents the use of a local environment to perform shell actions. + */ + environment: BetaResponseLocalEnvironment | BetaResponseContainerReference | null; + + /** + * The status of the shell call. One of `in_progress`, `completed`, or + * `incomplete`. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The type of the item. Always `shell_call`. + */ + type: 'shell_call'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseFunctionShellToolCall.Agent; + + /** + * The execution context that produced this tool call. + */ + caller?: BetaResponseFunctionShellToolCall.Direct | BetaResponseFunctionShellToolCall.Program | null; + + /** + * The ID of the entity that created this tool call. + */ + created_by?: string; +} + +export namespace BetaResponseFunctionShellToolCall { + /** + * The shell commands and limits that describe how to run the tool call. + */ + export interface Action { + commands: Array; + + /** + * Optional maximum number of characters to return from each command. + */ + max_output_length: number | null; + + /** + * Optional timeout in milliseconds for the commands. + */ + timeout_ms: number | null; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + type: 'program'; + } +} + +/** + * The output of a shell tool call that was emitted. + */ +export interface BetaResponseFunctionShellToolCallOutput { + /** + * The unique ID of the shell call output. Populated when this item is returned via + * API. + */ + id: string; + + /** + * The unique ID of the shell tool call generated by the model. + */ + call_id: string; + + /** + * The maximum length of the shell command output. This is generated by the model + * and should be passed back with the raw output. + */ + max_output_length: number | null; + + /** + * An array of shell call output contents + */ + output: Array; + + /** + * The status of the shell call output. One of `in_progress`, `completed`, or + * `incomplete`. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The type of the shell call output. Always `shell_call_output`. + */ + type: 'shell_call_output'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseFunctionShellToolCallOutput.Agent; + + /** + * The execution context that produced this tool call. + */ + caller?: + | BetaResponseFunctionShellToolCallOutput.Direct + | BetaResponseFunctionShellToolCallOutput.Program + | null; + + /** + * The identifier of the actor that created the item. + */ + created_by?: string; +} + +export namespace BetaResponseFunctionShellToolCallOutput { + /** + * The content of a shell tool call output that was emitted. + */ + export interface Output { + /** + * Represents either an exit outcome (with an exit code) or a timeout outcome for a + * shell call output chunk. + */ + outcome: Output.Timeout | Output.Exit; + + /** + * The standard error output that was captured. + */ + stderr: string; + + /** + * The standard output that was captured. + */ + stdout: string; + + /** + * The identifier of the actor that created the item. + */ + created_by?: string; + } + + export namespace Output { + /** + * Indicates that the shell call exceeded its configured time limit. + */ + export interface Timeout { + /** + * The outcome type. Always `timeout`. + */ + type: 'timeout'; + } + + /** + * Indicates that the shell commands finished and returned an exit code. + */ + export interface Exit { + /** + * Exit code from the shell process. + */ + exit_code: number; + + /** + * The outcome type. Always `exit`. + */ + type: 'exit'; + } + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + type: 'program'; + } +} + +/** + * A tool call to run a function. See the + * [function calling guide](https://platform.openai.com/docs/guides/function-calling) + * for more information. + */ +export interface BetaResponseFunctionToolCall { + /** + * A JSON string of the arguments to pass to the function. + */ + arguments: string; + + /** + * The unique ID of the function tool call generated by the model. + */ + call_id: string; + + /** + * The name of the function to run. + */ + name: string; + + /** + * The type of the function tool call. Always `function_call`. + */ + type: 'function_call'; + + /** + * The unique ID of the function tool call. + */ + id?: string; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseFunctionToolCall.Agent | null; + + /** + * The execution context that produced this tool call. + */ + caller?: BetaResponseFunctionToolCall.Direct | BetaResponseFunctionToolCall.Program | null; + + /** + * The namespace of the function to run. + */ + namespace?: string; + + /** + * The status of the item. One of `in_progress`, `completed`, or `incomplete`. + * Populated when items are returned via API. + */ + status?: 'in_progress' | 'completed' | 'incomplete'; +} + +export namespace BetaResponseFunctionToolCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + type: 'program'; + } +} + +/** + * A tool call to run a function. See the + * [function calling guide](https://platform.openai.com/docs/guides/function-calling) + * for more information. + */ +export interface BetaResponseFunctionToolCallItem extends BetaResponseFunctionToolCall { + /** + * The unique ID of the function tool call. + */ + id: string; + + /** + * The status of the item. One of `in_progress`, `completed`, or `incomplete`. + * Populated when items are returned via API. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The identifier of the actor that created the item. + */ + created_by?: string; +} + +export interface BetaResponseFunctionToolCallOutputItem { + /** + * The unique ID of the function call tool output. + */ + id: string; + + /** + * The unique ID of the function tool call generated by the model. + */ + call_id: string; + + /** + * The output from the function call generated by your code. Can be a string or an + * list of output content. + */ + output: string | Array; + + /** + * The status of the item. One of `in_progress`, `completed`, or `incomplete`. + * Populated when items are returned via API. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The type of the function tool call output. Always `function_call_output`. + */ + type: 'function_call_output'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseFunctionToolCallOutputItem.Agent | null; + + /** + * The execution context that produced this tool call. + */ + caller?: + | BetaResponseFunctionToolCallOutputItem.Direct + | BetaResponseFunctionToolCallOutputItem.Program + | null; + + /** + * The identifier of the actor that created the item. + */ + created_by?: string; +} + +export namespace BetaResponseFunctionToolCallOutputItem { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } +} + +/** + * 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. + */ +export interface BetaResponseFunctionWebSearch { + /** + * The unique ID of the web search tool call. + */ + id: string; + + /** + * 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). + */ + action: + | BetaResponseFunctionWebSearch.Search + | BetaResponseFunctionWebSearch.OpenPage + | BetaResponseFunctionWebSearch.FindInPage; + + /** + * The status of the web search tool call. + */ + status: 'in_progress' | 'searching' | 'completed' | 'failed'; + + /** + * The type of the web search tool call. Always `web_search_call`. + */ + type: 'web_search_call'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseFunctionWebSearch.Agent | null; +} + +export namespace BetaResponseFunctionWebSearch { + /** + * Action type "search" - Performs a web search query. + */ + export interface Search { + /** + * The action type. + */ + type: 'search'; + + /** + * The search queries. + */ + queries?: Array; + + /** + * @deprecated The search query. + */ + query?: string; + + /** + * The sources used in the search. + */ + sources?: Array; + } + + export namespace Search { + /** + * A source used in the search. + */ + export interface Source { + /** + * The type of source. Always `url`. + */ + type: 'url'; + + /** + * The URL of the source. + */ + url: string; + } + } + + /** + * Action type "open_page" - Opens a specific URL from search results. + */ + export interface OpenPage { + /** + * The action type. + */ + type: 'open_page'; + + /** + * The URL opened by the model. + */ + url?: string | null; + } + + /** + * Action type "find_in_page": Searches for a pattern within a loaded page. + */ + export interface FindInPage { + /** + * The pattern or text to search for within the page. + */ + pattern: string; + + /** + * The action type. + */ + type: 'find_in_page'; + + /** + * The URL of the page searched for the pattern. + */ + url: string; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when an image generation tool call has completed and the final image is + * available. + */ +export interface BetaResponseImageGenCallCompletedEvent { + /** + * The unique identifier of the image generation item being processed. + */ + item_id: string; + + /** + * The index of the output item in the response's output array. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.image_generation_call.completed'. + */ + type: 'response.image_generation_call.completed'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseImageGenCallCompletedEvent.Agent | null; +} + +export namespace BetaResponseImageGenCallCompletedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when an image generation tool call is actively generating an image + * (intermediate state). + */ +export interface BetaResponseImageGenCallGeneratingEvent { + /** + * The unique identifier of the image generation item being processed. + */ + item_id: string; + + /** + * The index of the output item in the response's output array. + */ + output_index: number; + + /** + * The sequence number of the image generation item being processed. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.image_generation_call.generating'. + */ + type: 'response.image_generation_call.generating'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseImageGenCallGeneratingEvent.Agent | null; +} + +export namespace BetaResponseImageGenCallGeneratingEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when an image generation tool call is in progress. + */ +export interface BetaResponseImageGenCallInProgressEvent { + /** + * The unique identifier of the image generation item being processed. + */ + item_id: string; + + /** + * The index of the output item in the response's output array. + */ + output_index: number; + + /** + * The sequence number of the image generation item being processed. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.image_generation_call.in_progress'. + */ + type: 'response.image_generation_call.in_progress'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseImageGenCallInProgressEvent.Agent | null; +} + +export namespace BetaResponseImageGenCallInProgressEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a partial image is available during image generation streaming. + */ +export interface BetaResponseImageGenCallPartialImageEvent { + /** + * The unique identifier of the image generation item being processed. + */ + item_id: string; + + /** + * The index of the output item in the response's output array. + */ + output_index: number; + + /** + * Base64-encoded partial image data, suitable for rendering as an image. + */ + partial_image_b64: string; + + /** + * 0-based index for the partial image (backend is 1-based, but this is 0-based for + * the user). + */ + partial_image_index: number; + + /** + * The sequence number of the image generation item being processed. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.image_generation_call.partial_image'. + */ + type: 'response.image_generation_call.partial_image'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseImageGenCallPartialImageEvent.Agent | null; +} + +export namespace BetaResponseImageGenCallPartialImageEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when the response is in progress. + */ +export interface BetaResponseInProgressEvent { + /** + * The response that is in progress. + */ + response: BetaResponse; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.in_progress`. + */ + type: 'response.in_progress'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseInProgressEvent.Agent | null; +} + +export namespace BetaResponseInProgressEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Specify additional output data to include in the model response. Currently + * supported values are: + * + * - `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). + */ +export type BetaResponseIncludable = + | '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'; + +/** + * An event that is emitted when a response finishes as incomplete. + */ +export interface BetaResponseIncompleteEvent { + /** + * The response that was incomplete. + */ + response: BetaResponse; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.incomplete`. + */ + type: 'response.incomplete'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseIncompleteEvent.Agent | null; +} + +export namespace BetaResponseIncompleteEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when all injected input items were validated and committed to the active + * response. + */ +export interface BetaResponseInjectCreatedEvent { + /** + * The ID of the response that accepted the input. + */ + response_id: string; + + /** + * The sequence number for this event. + */ + sequence_number: number; + + /** + * The event discriminator. Always `response.inject.created`. + */ + type: 'response.inject.created'; + + /** + * The multiplexed WebSocket stream that emitted the event. This field is present + * only when WebSocket multiplexing is enabled separately. + */ + stream_id?: string; +} + +/** + * 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. + */ +export interface BetaResponseInjectEvent { + /** + * Input items to inject into the active response. + */ + input: Array; + + /** + * The ID of the active response that should receive the input. + */ + response_id: string; + + /** + * The event discriminator. Always `response.inject`. + */ + type: 'response.inject'; +} + +/** + * 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. + */ +export interface BetaResponseInjectFailedEvent { + /** + * Information about why the input was not committed. + */ + error: BetaResponseInjectFailedEvent.Error; + + /** + * The raw input items that were not committed. + */ + input: Array; + + /** + * The ID of the response that rejected the input. + */ + response_id: string; + + /** + * The sequence number for this event. + */ + sequence_number: number; + + /** + * The event discriminator. Always `response.inject.failed`. + */ + type: 'response.inject.failed'; + + /** + * The multiplexed WebSocket stream that emitted the event. This field is present + * only when WebSocket multiplexing is enabled separately. + */ + stream_id?: string; +} + +export namespace BetaResponseInjectFailedEvent { + /** + * Information about why the input was not committed. + */ + export interface Error { + /** + * A machine-readable error code. + */ + code: 'response_already_completed' | 'response_not_found'; + + /** + * A human-readable description of the error. + */ + message: string; + } +} + +/** + * A list of one or many input items to the model, containing different content + * types. + */ +export type BetaResponseInput = Array; + +/** + * An audio input to the model. + */ +export interface BetaResponseInputAudio { + input_audio: BetaResponseInputAudio.InputAudio; + + /** + * The type of the input item. Always `input_audio`. + */ + type: 'input_audio'; +} + +export namespace BetaResponseInputAudio { + export interface InputAudio { + /** + * Base64-encoded audio data. + */ + data: string; + + /** + * The format of the audio data. Currently supported formats are `mp3` and `wav`. + */ + format: 'mp3' | 'wav'; + } +} + +/** + * A text input to the model. + */ +export type BetaResponseInputContent = BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile; + +/** + * A file input to the model. + */ +export interface BetaResponseInputFile { + /** + * The type of the input item. Always `input_file`. + */ + type: 'input_file'; + + /** + * 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`. + */ + detail?: 'auto' | 'low' | 'high'; + + /** + * The content of the file to be sent to the model. + */ + file_data?: string; + + /** + * The ID of the file to be sent to the model. + */ + file_id?: string | null; + + /** + * The URL of the file to be sent to the model. + */ + file_url?: string; + + /** + * The name of the file to be sent to the model. + */ + filename?: string; + + /** + * Marks the exact end of a reusable 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_cache_breakpoint?: BetaResponseInputFile.PromptCacheBreakpoint; +} + +export namespace 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. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } +} + +/** + * A file input to the model. + */ +export interface BetaResponseInputFileContent { + /** + * The type of the input item. Always `input_file`. + */ + type: 'input_file'; + + /** + * 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`. + */ + detail?: 'auto' | 'low' | 'high'; + + /** + * The base64-encoded data of the file to be sent to the model. + */ + file_data?: string | null; + + /** + * The ID of the file to be sent to the model. + */ + file_id?: string | null; + + /** + * The URL of the file to be sent to the model. + */ + file_url?: string | null; + + /** + * The name of the file to be sent to the model. + */ + filename?: string | 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. + */ + prompt_cache_breakpoint?: BetaResponseInputFileContent.PromptCacheBreakpoint | null; +} + +export namespace BetaResponseInputFileContent { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } +} + +/** + * An image input to the model. Learn about + * [image inputs](https://platform.openai.com/docs/guides/vision). + */ +export interface BetaResponseInputImage { + /** + * The detail level of the image to be sent to the model. One of `high`, `low`, + * `auto`, or `original`. Defaults to `auto`. + */ + detail: 'low' | 'high' | 'auto' | 'original'; + + /** + * The type of the input item. Always `input_image`. + */ + type: 'input_image'; + + /** + * The ID of the file to be sent to the model. + */ + file_id?: string | null; + + /** + * The URL of the image to be sent to the model. A fully qualified URL or base64 + * encoded image in a data URL. + */ + image_url?: string | 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. + */ + prompt_cache_breakpoint?: BetaResponseInputImage.PromptCacheBreakpoint; +} + +export namespace BetaResponseInputImage { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } +} + +/** + * An image input to the model. Learn about + * [image inputs](https://platform.openai.com/docs/guides/vision) + */ +export interface BetaResponseInputImageContent { + /** + * The type of the input item. Always `input_image`. + */ + type: 'input_image'; + + /** + * The detail level of the image to be sent to the model. One of `high`, `low`, + * `auto`, or `original`. Defaults to `auto`. + */ + detail?: 'low' | 'high' | 'auto' | 'original' | null; + + /** + * The ID of the file to be sent to the model. + */ + file_id?: string | null; + + /** + * The URL of the image to be sent to the model. A fully qualified URL or base64 + * encoded image in a data URL. + */ + image_url?: string | 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. + */ + prompt_cache_breakpoint?: BetaResponseInputImageContent.PromptCacheBreakpoint | null; +} + +export namespace BetaResponseInputImageContent { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } +} + +/** + * 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. + */ +export type BetaResponseInputItem = + | BetaEasyInputMessage + | BetaResponseInputItem.Message + | BetaResponseOutputMessage + | BetaResponseFileSearchToolCall + | BetaResponseComputerToolCall + | BetaResponseInputItem.ComputerCallOutput + | BetaResponseFunctionWebSearch + | BetaResponseFunctionToolCall + | BetaResponseInputItem.FunctionCallOutput + | BetaResponseInputItem.AgentMessage + | BetaResponseInputItem.MultiAgentCall + | BetaResponseInputItem.MultiAgentCallOutput + | BetaResponseInputItem.ToolSearchCall + | BetaResponseToolSearchOutputItemParam + | BetaResponseInputItem.AdditionalTools + | BetaResponseReasoningItem + | BetaResponseCompactionItemParam + | BetaResponseInputItem.ImageGenerationCall + | BetaResponseCodeInterpreterToolCall + | BetaResponseInputItem.LocalShellCall + | BetaResponseInputItem.LocalShellCallOutput + | BetaResponseInputItem.ShellCall + | BetaResponseInputItem.ShellCallOutput + | BetaResponseInputItem.ApplyPatchCall + | BetaResponseInputItem.ApplyPatchCallOutput + | BetaResponseInputItem.McpListTools + | BetaResponseInputItem.McpApprovalRequest + | BetaResponseInputItem.McpApprovalResponse + | BetaResponseInputItem.McpCall + | BetaResponseCustomToolCallOutput + | BetaResponseCustomToolCall + | BetaResponseInputItem.CompactionTrigger + | BetaResponseInputItem.ItemReference + | BetaResponseInputItem.Program + | BetaResponseInputItem.ProgramOutput; + +export namespace BetaResponseInputItem { + /** + * 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. + */ + export interface Message { + /** + * A list of one or many input items to the model, containing different content + * types. + */ + content: ResponsesAPI.BetaResponseInputMessageContentList; + + /** + * The role of the message input. One of `user`, `system`, or `developer`. + */ + role: 'user' | 'system' | 'developer'; + + /** + * The agent that produced this item. + */ + agent?: Message.Agent | null; + + /** + * The status of item. One of `in_progress`, `completed`, or `incomplete`. + * Populated when items are returned via API. + */ + status?: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The type of the message input. Always set to `message`. + */ + type?: 'message'; + } + + export namespace Message { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * The output of a computer tool call. + */ + export interface ComputerCallOutput { + /** + * The ID of the computer tool call that produced the output. + */ + call_id: string; + + /** + * A computer screenshot image used with the computer use tool. + */ + output: ResponsesAPI.BetaResponseComputerToolCallOutputScreenshot; + + /** + * The type of the computer tool call output. Always `computer_call_output`. + */ + type: 'computer_call_output'; + + /** + * The ID of the computer tool call output. + */ + id?: string | null; + + /** + * The safety checks reported by the API that have been acknowledged by the + * developer. + */ + acknowledged_safety_checks?: Array | null; + + /** + * The agent that produced this item. + */ + agent?: ComputerCallOutput.Agent | null; + + /** + * The status of the message input. One of `in_progress`, `completed`, or + * `incomplete`. Populated when input items are returned via API. + */ + status?: 'in_progress' | 'completed' | 'incomplete' | null; + } + + export namespace ComputerCallOutput { + /** + * A pending safety check for the computer call. + */ + export interface AcknowledgedSafetyCheck { + /** + * The ID of the pending safety check. + */ + id: string; + + /** + * The type of the pending safety check. + */ + code?: string | null; + + /** + * Details about the pending safety check. + */ + message?: string | null; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * The output of a function tool call. + */ + export interface FunctionCallOutput { + /** + * The unique ID of the function tool call generated by the model. + */ + call_id: string; + + /** + * Text, image, or file output of the function tool call. + */ + output: string | ResponsesAPI.BetaResponseFunctionCallOutputItemList; + + /** + * The type of the function tool call output. Always `function_call_output`. + */ + type: 'function_call_output'; + + /** + * The unique ID of the function tool call output. Populated when this item is + * returned via API. + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: FunctionCallOutput.Agent | null; + + /** + * The execution context that produced this tool call. + */ + caller?: FunctionCallOutput.Direct | FunctionCallOutput.Program | null; + + /** + * The status of the item. One of `in_progress`, `completed`, or `incomplete`. + * Populated when items are returned via API. + */ + status?: 'in_progress' | 'completed' | 'incomplete' | null; + } + + export namespace FunctionCallOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } + } + + /** + * A message routed between agents. + */ + export interface AgentMessage { + /** + * The sending agent identity. + */ + author: string; + + /** + * Plaintext, image, or encrypted content sent between agents. + */ + content: Array< + | ResponsesAPI.BetaResponseInputTextContent + | ResponsesAPI.BetaResponseInputImageContent + | AgentMessage.EncryptedContent + >; + + /** + * The destination agent identity. + */ + recipient: string; + + /** + * The item type. Always `agent_message`. + */ + type: 'agent_message'; + + /** + * The unique ID of this agent message item. + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: AgentMessage.Agent | null; + } + + export namespace AgentMessage { + /** + * Opaque encrypted content that Responses API decrypts inside trusted model + * execution. + */ + export interface EncryptedContent { + /** + * Opaque encrypted content. + */ + encrypted_content: string; + + /** + * The type of the input item. Always `encrypted_content`. + */ + type: 'encrypted_content'; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface MultiAgentCall { + /** + * The multi-agent action that was executed. + */ + action: + | 'spawn_agent' + | 'interrupt_agent' + | 'list_agents' + | 'send_message' + | 'followup_task' + | 'wait_agent'; + + /** + * The action arguments as a JSON string. + */ + arguments: string; + + /** + * The unique ID linking this call to its output. + */ + call_id: string; + + /** + * The item type. Always `multi_agent_call`. + */ + type: 'multi_agent_call'; + + /** + * The unique ID of this multi-agent call. + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: MultiAgentCall.Agent | null; + } + + export namespace MultiAgentCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface MultiAgentCallOutput { + /** + * The multi-agent action that produced this result. + */ + action: + | 'spawn_agent' + | 'interrupt_agent' + | 'list_agents' + | 'send_message' + | 'followup_task' + | 'wait_agent'; + + /** + * The unique ID of the multi-agent call. + */ + call_id: string; + + /** + * Text output returned by the multi-agent action. + */ + output: Array; + + /** + * The item type. Always `multi_agent_call_output`. + */ + type: 'multi_agent_call_output'; + + /** + * The unique ID of this multi-agent call output. + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: MultiAgentCallOutput.Agent | null; + } + + export namespace MultiAgentCallOutput { + export interface Output { + /** + * The text content. + */ + text: string; + + /** + * The content type. Always `output_text`. + */ + type: 'output_text'; + + /** + * Citations associated with the text content. + */ + annotations?: Array | Array | Array; + } + + export namespace Output { + export interface UnionMember0 { + /** + * The ID of the file. + */ + file_id: string; + + /** + * The filename of the file cited. + */ + filename: string; + + /** + * The index of the file in the list of files. + */ + index: number; + + /** + * The citation type. Always `file_citation`. + */ + type: 'file_citation'; + } + + export interface UnionMember1 { + /** + * The index of the last character of the citation in the message. + */ + end_index: number; + + /** + * The index of the first character of the citation in the message. + */ + start_index: number; + + /** + * The title of the cited resource. + */ + title: string; + + /** + * The citation type. Always `url_citation`. + */ + type: 'url_citation'; + + /** + * The URL of the cited resource. + */ + url: string; + } + + export interface UnionMember2 { + /** + * The ID of the container. + */ + container_id: string; + + /** + * The index of the last character of the citation in the message. + */ + end_index: number; + + /** + * The ID of the container file. + */ + file_id: string; + + /** + * The filename of the container file cited. + */ + filename: string; + + /** + * The index of the first character of the citation in the message. + */ + start_index: number; + + /** + * The citation type. Always `container_file_citation`. + */ + type: 'container_file_citation'; + } + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface ToolSearchCall { + /** + * The arguments supplied to the tool search call. + */ + arguments: unknown; + + /** + * The item type. Always `tool_search_call`. + */ + type: 'tool_search_call'; + + /** + * The unique ID of this tool search call. + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: ToolSearchCall.Agent | null; + + /** + * The unique ID of the tool search call generated by the model. + */ + call_id?: string | null; + + /** + * Whether tool search was executed by the server or by the client. + */ + execution?: 'server' | 'client'; + + /** + * The status of the tool search call. + */ + status?: 'in_progress' | 'completed' | 'incomplete' | null; + } + + export namespace ToolSearchCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface AdditionalTools { + /** + * The role that provided the additional tools. Only `developer` is supported. + */ + role: 'developer'; + + /** + * A list of additional tools made available at this item. + */ + tools: Array; + + /** + * The item type. Always `additional_tools`. + */ + type: 'additional_tools'; + + /** + * The unique ID of this additional tools item. + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: AdditionalTools.Agent | null; + } + + export namespace AdditionalTools { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * An image generation request made by the model. + */ + export interface ImageGenerationCall { + /** + * The unique ID of the image generation call. + */ + id: string; + + /** + * The generated image encoded in base64. + */ + result: string | null; + + /** + * The status of the image generation call. + */ + status: 'in_progress' | 'completed' | 'generating' | 'failed'; + + /** + * The type of the image generation call. Always `image_generation_call`. + */ + type: 'image_generation_call'; + + /** + * The agent that produced this item. + */ + agent?: ImageGenerationCall.Agent | null; + } + + export namespace ImageGenerationCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * A tool call to run a command on the local shell. + */ + export interface LocalShellCall { + /** + * The unique ID of the local shell call. + */ + id: string; + + /** + * Execute a shell command on the server. + */ + action: LocalShellCall.Action; + + /** + * The unique ID of the local shell tool call generated by the model. + */ + call_id: string; + + /** + * The status of the local shell call. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The type of the local shell call. Always `local_shell_call`. + */ + type: 'local_shell_call'; + + /** + * The agent that produced this item. + */ + agent?: LocalShellCall.Agent | null; + } + + export namespace LocalShellCall { + /** + * Execute a shell command on the server. + */ + export interface Action { + /** + * The command to run. + */ + command: Array; + + /** + * Environment variables to set for the command. + */ + env: { [key: string]: string }; + + /** + * The type of the local shell action. Always `exec`. + */ + type: 'exec'; + + /** + * Optional timeout in milliseconds for the command. + */ + timeout_ms?: number | null; + + /** + * Optional user to run the command as. + */ + user?: string | null; + + /** + * Optional working directory to run the command in. + */ + working_directory?: string | null; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * The output of a local shell tool call. + */ + export interface LocalShellCallOutput { + /** + * The unique ID of the local shell tool call generated by the model. + */ + id: string; + + /** + * A JSON string of the output of the local shell tool call. + */ + output: string; + + /** + * The type of the local shell tool call output. Always `local_shell_call_output`. + */ + type: 'local_shell_call_output'; + + /** + * The agent that produced this item. + */ + agent?: LocalShellCallOutput.Agent | null; + + /** + * The status of the item. One of `in_progress`, `completed`, or `incomplete`. + */ + status?: 'in_progress' | 'completed' | 'incomplete' | null; + } + + export namespace LocalShellCallOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * A tool representing a request to execute one or more shell commands. + */ + export interface ShellCall { + /** + * The shell commands and limits that describe how to run the tool call. + */ + action: ShellCall.Action; + + /** + * The unique ID of the shell tool call generated by the model. + */ + call_id: string; + + /** + * The type of the item. Always `shell_call`. + */ + type: 'shell_call'; + + /** + * The unique ID of the shell tool call. Populated when this item is returned via + * API. + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: ShellCall.Agent | null; + + /** + * The execution context that produced this tool call. + */ + caller?: ShellCall.Direct | ShellCall.Program | null; + + /** + * The environment to execute the shell commands in. + */ + environment?: ResponsesAPI.BetaLocalEnvironment | ResponsesAPI.BetaContainerReference | null; + + /** + * The status of the shell call. One of `in_progress`, `completed`, or + * `incomplete`. + */ + status?: 'in_progress' | 'completed' | 'incomplete' | null; + } + + export namespace ShellCall { + /** + * The shell commands and limits that describe how to run the tool call. + */ + export interface Action { + /** + * Ordered shell commands for the execution environment to run. + */ + commands: Array; + + /** + * Maximum number of UTF-8 characters to capture from combined stdout and stderr + * output. + */ + max_output_length?: number | null; + + /** + * Maximum wall-clock time in milliseconds to allow the shell commands to run. + */ + timeout_ms?: number | null; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } + } + + /** + * The streamed output items emitted by a shell tool call. + */ + export interface ShellCallOutput { + /** + * The unique ID of the shell tool call generated by the model. + */ + call_id: string; + + /** + * Captured chunks of stdout and stderr output, along with their associated + * outcomes. + */ + output: Array; + + /** + * The type of the item. Always `shell_call_output`. + */ + type: 'shell_call_output'; + + /** + * The unique ID of the shell tool call output. Populated when this item is + * returned via API. + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: ShellCallOutput.Agent | null; + + /** + * The execution context that produced this tool call. + */ + caller?: ShellCallOutput.Direct | ShellCallOutput.Program | null; + + /** + * The maximum number of UTF-8 characters captured for this shell call's combined + * output. + */ + max_output_length?: number | null; + + /** + * The status of the shell call output. + */ + status?: 'in_progress' | 'completed' | 'incomplete' | null; + } + + export namespace ShellCallOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } + } + + /** + * A tool call representing a request to create, delete, or update files using diff + * patches. + */ + export interface ApplyPatchCall { + /** + * The unique ID of the apply patch tool call generated by the model. + */ + call_id: string; + + /** + * The specific create, delete, or update instruction for the apply_patch tool + * call. + */ + operation: ApplyPatchCall.CreateFile | ApplyPatchCall.DeleteFile | ApplyPatchCall.UpdateFile; + + /** + * The status of the apply patch tool call. One of `in_progress` or `completed`. + */ + status: 'in_progress' | 'completed'; + + /** + * The type of the item. Always `apply_patch_call`. + */ + type: 'apply_patch_call'; + + /** + * The unique ID of the apply patch tool call. Populated when this item is returned + * via API. + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: ApplyPatchCall.Agent | null; + + /** + * The execution context that produced this tool call. + */ + caller?: ApplyPatchCall.Direct | ApplyPatchCall.Program | null; + } + + export namespace ApplyPatchCall { + /** + * Instruction for creating a new file via the apply_patch tool. + */ + export interface CreateFile { + /** + * Unified diff content to apply when creating the file. + */ + diff: string; + + /** + * Path of the file to create relative to the workspace root. + */ + path: string; + + /** + * The operation type. Always `create_file`. + */ + type: 'create_file'; + } + + /** + * Instruction for deleting an existing file via the apply_patch tool. + */ + export interface DeleteFile { + /** + * Path of the file to delete relative to the workspace root. + */ + path: string; + + /** + * The operation type. Always `delete_file`. + */ + type: 'delete_file'; + } + + /** + * Instruction for updating an existing file via the apply_patch tool. + */ + export interface UpdateFile { + /** + * Unified diff content to apply to the existing file. + */ + diff: string; + + /** + * Path of the file to update relative to the workspace root. + */ + path: string; + + /** + * The operation type. Always `update_file`. + */ + type: 'update_file'; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } + } + + /** + * The streamed output emitted by an apply patch tool call. + */ + export interface ApplyPatchCallOutput { + /** + * The unique ID of the apply patch tool call generated by the model. + */ + call_id: string; + + /** + * The status of the apply patch tool call output. One of `completed` or `failed`. + */ + status: 'completed' | 'failed'; + + /** + * The type of the item. Always `apply_patch_call_output`. + */ + type: 'apply_patch_call_output'; + + /** + * The unique ID of the apply patch tool call output. Populated when this item is + * returned via API. + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: ApplyPatchCallOutput.Agent | null; + + /** + * The execution context that produced this tool call. + */ + caller?: ApplyPatchCallOutput.Direct | ApplyPatchCallOutput.Program | null; + + /** + * Optional human-readable log text from the apply patch tool (e.g., patch results + * or errors). + */ + output?: string | null; + } + + export namespace ApplyPatchCallOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } + } + + /** + * A list of tools available on an MCP server. + */ + export interface McpListTools { + /** + * The unique ID of the list. + */ + id: string; + + /** + * The label of the MCP server. + */ + server_label: string; + + /** + * The tools available on the server. + */ + tools: Array; + + /** + * The type of the item. Always `mcp_list_tools`. + */ + type: 'mcp_list_tools'; + + /** + * The agent that produced this item. + */ + agent?: McpListTools.Agent | null; + + /** + * Error message if the server could not list tools. + */ + error?: string | null; + } + + export namespace McpListTools { + /** + * A tool available on an MCP server. + */ + export interface Tool { + /** + * The JSON schema describing the tool's input. + */ + input_schema: unknown; + + /** + * The name of the tool. + */ + name: string; + + /** + * Additional annotations about the tool. + */ + annotations?: unknown | null; + + /** + * The description of the tool. + */ + description?: string | null; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * A request for human approval of a tool invocation. + */ + export interface McpApprovalRequest { + /** + * The unique ID of the approval request. + */ + id: string; + + /** + * A JSON string of arguments for the tool. + */ + arguments: string; + + /** + * The name of the tool to run. + */ + name: string; + + /** + * The label of the MCP server making the request. + */ + server_label: string; + + /** + * The type of the item. Always `mcp_approval_request`. + */ + type: 'mcp_approval_request'; + + /** + * The agent that produced this item. + */ + agent?: McpApprovalRequest.Agent | null; + } + + export namespace McpApprovalRequest { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * A response to an MCP approval request. + */ + export interface McpApprovalResponse { + /** + * The ID of the approval request being answered. + */ + approval_request_id: string; + + /** + * Whether the request was approved. + */ + approve: boolean; + + /** + * The type of the item. Always `mcp_approval_response`. + */ + type: 'mcp_approval_response'; + + /** + * The unique ID of the approval response + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: McpApprovalResponse.Agent | null; + + /** + * Optional reason for the decision. + */ + reason?: string | null; + } + + export namespace McpApprovalResponse { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * An invocation of a tool on an MCP server. + */ + export interface McpCall { + /** + * The unique ID of the tool call. + */ + id: string; + + /** + * A JSON string of the arguments passed to the tool. + */ + arguments: string; + + /** + * The name of the tool that was run. + */ + name: string; + + /** + * The label of the MCP server running the tool. + */ + server_label: string; + + /** + * The type of the item. Always `mcp_call`. + */ + type: 'mcp_call'; + + /** + * The agent that produced this item. + */ + agent?: McpCall.Agent | null; + + /** + * 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. + */ + approval_request_id?: string | null; + + /** + * The error from the tool call, if any. + */ + error?: string | null; + + /** + * The output from the tool call. + */ + output?: string | null; + + /** + * The status of the tool call. One of `in_progress`, `completed`, `incomplete`, + * `calling`, or `failed`. + */ + status?: 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed'; + } + + export namespace McpCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * Compacts the current context. Must be the final input item. + */ + export interface CompactionTrigger { + /** + * The type of the item. Always `compaction_trigger`. + */ + type: 'compaction_trigger'; + + /** + * The agent that produced this item. + */ + agent?: CompactionTrigger.Agent | null; + } + + export namespace CompactionTrigger { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * An internal identifier for an item to reference. + */ + export interface ItemReference { + /** + * The ID of the item to reference. + */ + id: string; + + /** + * The agent that produced this item. + */ + agent?: ItemReference.Agent | null; + + /** + * The type of item to reference. Always `item_reference`. + */ + type?: 'item_reference' | null; + } + + export namespace ItemReference { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface Program { + /** + * The unique ID of this program item. + */ + id: string; + + /** + * The stable call ID of the program item. + */ + call_id: string; + + /** + * The JavaScript source executed by programmatic tool calling. + */ + code: string; + + /** + * Opaque program replay fingerprint that must be round-tripped. + */ + fingerprint: string; + + /** + * The item type. Always `program`. + */ + type: 'program'; + + /** + * The agent that produced this item. + */ + agent?: Program.Agent | null; + } + + export namespace Program { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface ProgramOutput { + /** + * The unique ID of this program output item. + */ + id: string; + + /** + * The call ID of the program item. + */ + call_id: string; + + /** + * The result produced by the program item. + */ + result: string; + + /** + * The terminal status of the program output. + */ + status: 'completed' | 'incomplete'; + + /** + * The item type. Always `program_output`. + */ + type: 'program_output'; + + /** + * The agent that produced this item. + */ + agent?: ProgramOutput.Agent | null; + } + + export namespace ProgramOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } +} + +/** + * A list of one or many input items to the model, containing different content + * types. + */ +export type BetaResponseInputMessageContentList = Array; + +export interface BetaResponseInputMessageItem { + /** + * The unique ID of the message input. + */ + id: string; + + /** + * A list of one or many input items to the model, containing different content + * types. + */ + content: BetaResponseInputMessageContentList; + + /** + * The role of the message input. One of `user`, `system`, or `developer`. + */ + role: 'user' | 'system' | 'developer'; + + /** + * The type of the message input. Always set to `message`. + */ + type: 'message'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseInputMessageItem.Agent | null; + + /** + * The status of item. One of `in_progress`, `completed`, or `incomplete`. + * Populated when items are returned via API. + */ + status?: 'in_progress' | 'completed' | 'incomplete'; +} + +export namespace BetaResponseInputMessageItem { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * A text input to the model. + */ +export interface BetaResponseInputText { + /** + * The text input to the model. + */ + text: string; + + /** + * The type of the input item. Always `input_text`. + */ + type: 'input_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. + */ + prompt_cache_breakpoint?: BetaResponseInputText.PromptCacheBreakpoint; +} + +export namespace BetaResponseInputText { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } +} + +/** + * A text input to the model. + */ +export interface BetaResponseInputTextContent { + /** + * The text input to the model. + */ + text: string; + + /** + * The type of the input item. Always `input_text`. + */ + type: 'input_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. + */ + prompt_cache_breakpoint?: BetaResponseInputTextContent.PromptCacheBreakpoint | null; +} + +export namespace BetaResponseInputTextContent { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } +} + +/** + * Content item used to generate a response. + */ +export type BetaResponseItem = + | BetaResponseInputMessageItem + | BetaResponseOutputMessage + | BetaResponseFileSearchToolCall + | BetaResponseComputerToolCall + | BetaResponseComputerToolCallOutputItem + | BetaResponseFunctionWebSearch + | BetaResponseFunctionToolCallItem + | BetaResponseFunctionToolCallOutputItem + | BetaResponseItem.AgentMessage + | BetaResponseItem.MultiAgentCall + | BetaResponseItem.MultiAgentCallOutput + | BetaResponseToolSearchCall + | BetaResponseToolSearchOutputItem + | BetaResponseItem.AdditionalTools + | BetaResponseReasoningItem + | BetaResponseItem.Program + | BetaResponseItem.ProgramOutput + | BetaResponseCompactionItem + | BetaResponseItem.ImageGenerationCall + | BetaResponseCodeInterpreterToolCall + | BetaResponseItem.LocalShellCall + | BetaResponseItem.LocalShellCallOutput + | BetaResponseFunctionShellToolCall + | BetaResponseFunctionShellToolCallOutput + | BetaResponseApplyPatchToolCall + | BetaResponseApplyPatchToolCallOutput + | BetaResponseItem.McpListTools + | BetaResponseItem.McpApprovalRequest + | BetaResponseItem.McpApprovalResponse + | BetaResponseItem.McpCall + | BetaResponseCustomToolCallItem + | BetaResponseCustomToolCallOutputItem; + +export namespace BetaResponseItem { + export interface AgentMessage { + /** + * The unique ID of the agent message. + */ + id: string; + + /** + * The sending agent identity. + */ + author: string; + + /** + * Encrypted content sent between agents. + */ + content: Array< + | ResponsesAPI.BetaResponseInputText + | ResponsesAPI.BetaResponseOutputText + | AgentMessage.Text + | AgentMessage.SummaryText + | AgentMessage.ReasoningText + | ResponsesAPI.BetaResponseOutputRefusal + | ResponsesAPI.BetaResponseInputImage + | AgentMessage.ComputerScreenshot + | ResponsesAPI.BetaResponseInputFile + | AgentMessage.EncryptedContent + >; + + /** + * The destination agent identity. + */ + recipient: string; + + /** + * The type of the item. Always `agent_message`. + */ + type: 'agent_message'; + + /** + * The agent that produced this item. + */ + agent?: AgentMessage.Agent; + } + + export namespace AgentMessage { + /** + * A text content. + */ + export interface Text { + text: string; + + type: 'text'; + } + + /** + * A summary text from the model. + */ + export interface SummaryText { + /** + * A summary of the reasoning output from the model so far. + */ + text: string; + + /** + * The type of the object. Always `summary_text`. + */ + type: 'summary_text'; + } + + /** + * Reasoning text from the model. + */ + export interface ReasoningText { + /** + * The reasoning text from the model. + */ + text: string; + + /** + * The type of the reasoning text. Always `reasoning_text`. + */ + type: 'reasoning_text'; + } + + /** + * A screenshot of a computer. + */ + export interface ComputerScreenshot { + /** + * The detail level of the screenshot image to be sent to the model. One of `high`, + * `low`, `auto`, or `original`. Defaults to `auto`. + */ + detail: 'low' | 'high' | 'auto' | 'original'; + + /** + * The identifier of an uploaded file that contains the screenshot. + */ + file_id: string | null; + + /** + * The URL of the screenshot image. + */ + image_url: string | null; + + /** + * Specifies the event type. For a computer screenshot, this property is always set + * to `computer_screenshot`. + */ + type: 'computer_screenshot'; + + /** + * Marks the exact end of a reusable 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_cache_breakpoint?: ComputerScreenshot.PromptCacheBreakpoint; + } + + export namespace ComputerScreenshot { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } + } + + /** + * Opaque encrypted content that Responses API decrypts inside trusted model + * execution. + */ + export interface EncryptedContent { + /** + * Opaque encrypted content. + */ + encrypted_content: string; + + /** + * The type of the input item. Always `encrypted_content`. + */ + type: 'encrypted_content'; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface MultiAgentCall { + /** + * The unique ID of the multi-agent call item. + */ + id: string; + + /** + * The multi-agent action to execute. + */ + action: + | 'spawn_agent' + | 'interrupt_agent' + | 'list_agents' + | 'send_message' + | 'followup_task' + | 'wait_agent'; + + /** + * The JSON string of arguments generated for the action. + */ + arguments: string; + + /** + * The unique ID linking this call to its output. + */ + call_id: string; + + /** + * The type of the multi-agent call. Always `multi_agent_call`. + */ + type: 'multi_agent_call'; + + /** + * The agent that produced this item. + */ + agent?: MultiAgentCall.Agent; + } + + export namespace MultiAgentCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface MultiAgentCallOutput { + /** + * The unique ID of the multi-agent call output item. + */ + id: string; + + /** + * The multi-agent action that produced this result. + */ + action: + | 'spawn_agent' + | 'interrupt_agent' + | 'list_agents' + | 'send_message' + | 'followup_task' + | 'wait_agent'; + + /** + * The unique ID of the multi-agent call. + */ + call_id: string; + + /** + * Text output returned by the multi-agent action. + */ + output: Array; + + /** + * The type of the multi-agent result. Always `multi_agent_call_output`. + */ + type: 'multi_agent_call_output'; + + /** + * The agent that produced this item. + */ + agent?: MultiAgentCallOutput.Agent; + } + + export namespace MultiAgentCallOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface AdditionalTools { + /** + * The unique ID of the additional tools item. + */ + id: string; + + /** + * The role that provided the additional tools. + */ + role: 'unknown' | 'user' | 'assistant' | 'system' | 'critic' | 'discriminator' | 'developer' | 'tool'; + + /** + * The additional tool definitions made available at this item. + */ + tools: Array; + + /** + * The type of the item. Always `additional_tools`. + */ + type: 'additional_tools'; + + /** + * The agent that produced this item. + */ + agent?: AdditionalTools.Agent; + } + + export namespace AdditionalTools { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface Program { + /** + * The unique ID of the program item. + */ + id: string; + + /** + * The stable call ID of the program item. + */ + call_id: string; + + /** + * The JavaScript source executed by programmatic tool calling. + */ + code: string; + + /** + * Opaque program replay fingerprint that must be round-tripped. + */ + fingerprint: string; + + /** + * The type of the item. Always `program`. + */ + type: 'program'; + + /** + * The agent that produced this item. + */ + agent?: Program.Agent; + } + + export namespace Program { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface ProgramOutput { + /** + * The unique ID of the program output item. + */ + id: string; + + /** + * The call ID of the program item. + */ + call_id: string; + + /** + * The result produced by the program item. + */ + result: string; + + /** + * The terminal status of the program output item. + */ + status: 'completed' | 'incomplete'; + + /** + * The type of the item. Always `program_output`. + */ + type: 'program_output'; + + /** + * The agent that produced this item. + */ + agent?: ProgramOutput.Agent; + } + + export namespace ProgramOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * An image generation request made by the model. + */ + export interface ImageGenerationCall { + /** + * The unique ID of the image generation call. + */ + id: string; + + /** + * The generated image encoded in base64. + */ + result: string | null; + + /** + * The status of the image generation call. + */ + status: 'in_progress' | 'completed' | 'generating' | 'failed'; + + /** + * The type of the image generation call. Always `image_generation_call`. + */ + type: 'image_generation_call'; + + /** + * The agent that produced this item. + */ + agent?: ImageGenerationCall.Agent | null; + } + + export namespace ImageGenerationCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * A tool call to run a command on the local shell. + */ + export interface LocalShellCall { + /** + * The unique ID of the local shell call. + */ + id: string; + + /** + * Execute a shell command on the server. + */ + action: LocalShellCall.Action; + + /** + * The unique ID of the local shell tool call generated by the model. + */ + call_id: string; + + /** + * The status of the local shell call. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The type of the local shell call. Always `local_shell_call`. + */ + type: 'local_shell_call'; + + /** + * The agent that produced this item. + */ + agent?: LocalShellCall.Agent | null; + } + + export namespace LocalShellCall { + /** + * Execute a shell command on the server. + */ + export interface Action { + /** + * The command to run. + */ + command: Array; + + /** + * Environment variables to set for the command. + */ + env: { [key: string]: string }; + + /** + * The type of the local shell action. Always `exec`. + */ + type: 'exec'; + + /** + * Optional timeout in milliseconds for the command. + */ + timeout_ms?: number | null; + + /** + * Optional user to run the command as. + */ + user?: string | null; + + /** + * Optional working directory to run the command in. + */ + working_directory?: string | null; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * The output of a local shell tool call. + */ + export interface LocalShellCallOutput { + /** + * The unique ID of the local shell tool call generated by the model. + */ + id: string; + + /** + * A JSON string of the output of the local shell tool call. + */ + output: string; + + /** + * The type of the local shell tool call output. Always `local_shell_call_output`. + */ + type: 'local_shell_call_output'; + + /** + * The agent that produced this item. + */ + agent?: LocalShellCallOutput.Agent | null; + + /** + * The status of the item. One of `in_progress`, `completed`, or `incomplete`. + */ + status?: 'in_progress' | 'completed' | 'incomplete' | null; + } + + export namespace LocalShellCallOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * A list of tools available on an MCP server. + */ + export interface McpListTools { + /** + * The unique ID of the list. + */ + id: string; + + /** + * The label of the MCP server. + */ + server_label: string; + + /** + * The tools available on the server. + */ + tools: Array; + + /** + * The type of the item. Always `mcp_list_tools`. + */ + type: 'mcp_list_tools'; + + /** + * The agent that produced this item. + */ + agent?: McpListTools.Agent | null; + + /** + * Error message if the server could not list tools. + */ + error?: string | null; + } + + export namespace McpListTools { + /** + * A tool available on an MCP server. + */ + export interface Tool { + /** + * The JSON schema describing the tool's input. + */ + input_schema: unknown; + + /** + * The name of the tool. + */ + name: string; + + /** + * Additional annotations about the tool. + */ + annotations?: unknown | null; + + /** + * The description of the tool. + */ + description?: string | null; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * A request for human approval of a tool invocation. + */ + export interface McpApprovalRequest { + /** + * The unique ID of the approval request. + */ + id: string; + + /** + * A JSON string of arguments for the tool. + */ + arguments: string; + + /** + * The name of the tool to run. + */ + name: string; + + /** + * The label of the MCP server making the request. + */ + server_label: string; + + /** + * The type of the item. Always `mcp_approval_request`. + */ + type: 'mcp_approval_request'; + + /** + * The agent that produced this item. + */ + agent?: McpApprovalRequest.Agent | null; + } + + export namespace McpApprovalRequest { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * A response to an MCP approval request. + */ + export interface McpApprovalResponse { + /** + * The unique ID of the approval response + */ + id: string; + + /** + * The ID of the approval request being answered. + */ + approval_request_id: string; + + /** + * Whether the request was approved. + */ + approve: boolean; + + /** + * The type of the item. Always `mcp_approval_response`. + */ + type: 'mcp_approval_response'; + + /** + * The agent that produced this item. + */ + agent?: McpApprovalResponse.Agent | null; + + /** + * Optional reason for the decision. + */ + reason?: string | null; + } + + export namespace McpApprovalResponse { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * An invocation of a tool on an MCP server. + */ + export interface McpCall { + /** + * The unique ID of the tool call. + */ + id: string; + + /** + * A JSON string of the arguments passed to the tool. + */ + arguments: string; + + /** + * The name of the tool that was run. + */ + name: string; + + /** + * The label of the MCP server running the tool. + */ + server_label: string; + + /** + * The type of the item. Always `mcp_call`. + */ + type: 'mcp_call'; + + /** + * The agent that produced this item. + */ + agent?: McpCall.Agent | null; + + /** + * 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. + */ + approval_request_id?: string | null; + + /** + * The error from the tool call, if any. + */ + error?: string | null; + + /** + * The output from the tool call. + */ + output?: string | null; + + /** + * The status of the tool call. One of `in_progress`, `completed`, `incomplete`, + * `calling`, or `failed`. + */ + status?: 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed'; + } + + export namespace McpCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } +} + +/** + * Represents the use of a local environment to perform shell actions. + */ +export interface BetaResponseLocalEnvironment { + /** + * The environment type. Always `local`. + */ + type: 'local'; +} + +/** + * Emitted when there is a delta (partial update) to the arguments of an MCP tool + * call. + */ +export interface BetaResponseMcpCallArgumentsDeltaEvent { + /** + * A JSON string containing the partial update to the arguments for the MCP tool + * call. + */ + delta: string; + + /** + * The unique identifier of the MCP tool call item being processed. + */ + item_id: string; + + /** + * The index of the output item in the response's output array. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.mcp_call_arguments.delta'. + */ + type: 'response.mcp_call_arguments.delta'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseMcpCallArgumentsDeltaEvent.Agent | null; +} + +export namespace BetaResponseMcpCallArgumentsDeltaEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when the arguments for an MCP tool call are finalized. + */ +export interface BetaResponseMcpCallArgumentsDoneEvent { + /** + * A JSON string containing the finalized arguments for the MCP tool call. + */ + arguments: string; + + /** + * The unique identifier of the MCP tool call item being processed. + */ + item_id: string; + + /** + * The index of the output item in the response's output array. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.mcp_call_arguments.done'. + */ + type: 'response.mcp_call_arguments.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseMcpCallArgumentsDoneEvent.Agent | null; +} + +export namespace BetaResponseMcpCallArgumentsDoneEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when an MCP tool call has completed successfully. + */ +export interface BetaResponseMcpCallCompletedEvent { + /** + * The ID of the MCP tool call item that completed. + */ + item_id: string; + + /** + * The index of the output item that completed. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.mcp_call.completed'. + */ + type: 'response.mcp_call.completed'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseMcpCallCompletedEvent.Agent | null; +} + +export namespace BetaResponseMcpCallCompletedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when an MCP tool call has failed. + */ +export interface BetaResponseMcpCallFailedEvent { + /** + * The ID of the MCP tool call item that failed. + */ + item_id: string; + + /** + * The index of the output item that failed. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.mcp_call.failed'. + */ + type: 'response.mcp_call.failed'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseMcpCallFailedEvent.Agent | null; +} + +export namespace BetaResponseMcpCallFailedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when an MCP tool call is in progress. + */ +export interface BetaResponseMcpCallInProgressEvent { + /** + * The unique identifier of the MCP tool call item being processed. + */ + item_id: string; + + /** + * The index of the output item in the response's output array. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.mcp_call.in_progress'. + */ + type: 'response.mcp_call.in_progress'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseMcpCallInProgressEvent.Agent | null; +} + +export namespace BetaResponseMcpCallInProgressEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when the list of available MCP tools has been successfully retrieved. + */ +export interface BetaResponseMcpListToolsCompletedEvent { + /** + * The ID of the MCP tool call item that produced this output. + */ + item_id: string; + + /** + * The index of the output item that was processed. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.mcp_list_tools.completed'. + */ + type: 'response.mcp_list_tools.completed'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseMcpListToolsCompletedEvent.Agent | null; +} + +export namespace BetaResponseMcpListToolsCompletedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when the attempt to list available MCP tools has failed. + */ +export interface BetaResponseMcpListToolsFailedEvent { + /** + * The ID of the MCP tool call item that failed. + */ + item_id: string; + + /** + * The index of the output item that failed. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.mcp_list_tools.failed'. + */ + type: 'response.mcp_list_tools.failed'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseMcpListToolsFailedEvent.Agent | null; +} + +export namespace BetaResponseMcpListToolsFailedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when the system is in the process of retrieving the list of available + * MCP tools. + */ +export interface BetaResponseMcpListToolsInProgressEvent { + /** + * The ID of the MCP tool call item that is being processed. + */ + item_id: string; + + /** + * The index of the output item that is being processed. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.mcp_list_tools.in_progress'. + */ + type: 'response.mcp_list_tools.in_progress'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseMcpListToolsInProgressEvent.Agent | null; +} + +export namespace BetaResponseMcpListToolsInProgressEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * An audio output from the model. + */ +export interface BetaResponseOutputAudio { + /** + * Base64-encoded audio data from the model. + */ + data: string; + + /** + * The transcript of the audio data from the model. + */ + transcript: string; + + /** + * The type of the output audio. Always `output_audio`. + */ + type: 'output_audio'; +} + +/** + * An output message from the model. + */ +export type BetaResponseOutputItem = + | BetaResponseOutputMessage + | BetaResponseFileSearchToolCall + | BetaResponseFunctionToolCall + | BetaResponseFunctionToolCallOutputItem + | BetaResponseOutputItem.AgentMessage + | BetaResponseOutputItem.MultiAgentCall + | BetaResponseOutputItem.MultiAgentCallOutput + | BetaResponseFunctionWebSearch + | BetaResponseComputerToolCall + | BetaResponseComputerToolCallOutputItem + | BetaResponseReasoningItem + | BetaResponseOutputItem.Program + | BetaResponseOutputItem.ProgramOutput + | BetaResponseToolSearchCall + | BetaResponseToolSearchOutputItem + | BetaResponseOutputItem.AdditionalTools + | BetaResponseCompactionItem + | BetaResponseOutputItem.ImageGenerationCall + | BetaResponseCodeInterpreterToolCall + | BetaResponseOutputItem.LocalShellCall + | BetaResponseOutputItem.LocalShellCallOutput + | BetaResponseFunctionShellToolCall + | BetaResponseFunctionShellToolCallOutput + | BetaResponseApplyPatchToolCall + | BetaResponseApplyPatchToolCallOutput + | BetaResponseOutputItem.McpCall + | BetaResponseOutputItem.McpListTools + | BetaResponseOutputItem.McpApprovalRequest + | BetaResponseOutputItem.McpApprovalResponse + | BetaResponseCustomToolCall + | BetaResponseCustomToolCallOutputItem; + +export namespace BetaResponseOutputItem { + export interface AgentMessage { + /** + * The unique ID of the agent message. + */ + id: string; + + /** + * The sending agent identity. + */ + author: string; + + /** + * Encrypted content sent between agents. + */ + content: Array< + | ResponsesAPI.BetaResponseInputText + | ResponsesAPI.BetaResponseOutputText + | AgentMessage.Text + | AgentMessage.SummaryText + | AgentMessage.ReasoningText + | ResponsesAPI.BetaResponseOutputRefusal + | ResponsesAPI.BetaResponseInputImage + | AgentMessage.ComputerScreenshot + | ResponsesAPI.BetaResponseInputFile + | AgentMessage.EncryptedContent + >; + + /** + * The destination agent identity. + */ + recipient: string; + + /** + * The type of the item. Always `agent_message`. + */ + type: 'agent_message'; + + /** + * The agent that produced this item. + */ + agent?: AgentMessage.Agent; + } + + export namespace AgentMessage { + /** + * A text content. + */ + export interface Text { + text: string; + + type: 'text'; + } + + /** + * A summary text from the model. + */ + export interface SummaryText { + /** + * A summary of the reasoning output from the model so far. + */ + text: string; + + /** + * The type of the object. Always `summary_text`. + */ + type: 'summary_text'; + } + + /** + * Reasoning text from the model. + */ + export interface ReasoningText { + /** + * The reasoning text from the model. + */ + text: string; + + /** + * The type of the reasoning text. Always `reasoning_text`. + */ + type: 'reasoning_text'; + } + + /** + * A screenshot of a computer. + */ + export interface ComputerScreenshot { + /** + * The detail level of the screenshot image to be sent to the model. One of `high`, + * `low`, `auto`, or `original`. Defaults to `auto`. + */ + detail: 'low' | 'high' | 'auto' | 'original'; + + /** + * The identifier of an uploaded file that contains the screenshot. + */ + file_id: string | null; + + /** + * The URL of the screenshot image. + */ + image_url: string | null; + + /** + * Specifies the event type. For a computer screenshot, this property is always set + * to `computer_screenshot`. + */ + type: 'computer_screenshot'; + + /** + * Marks the exact end of a reusable 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_cache_breakpoint?: ComputerScreenshot.PromptCacheBreakpoint; + } + + export namespace ComputerScreenshot { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } + } + + /** + * Opaque encrypted content that Responses API decrypts inside trusted model + * execution. + */ + export interface EncryptedContent { + /** + * Opaque encrypted content. + */ + encrypted_content: string; + + /** + * The type of the input item. Always `encrypted_content`. + */ + type: 'encrypted_content'; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface MultiAgentCall { + /** + * The unique ID of the multi-agent call item. + */ + id: string; + + /** + * The multi-agent action to execute. + */ + action: + | 'spawn_agent' + | 'interrupt_agent' + | 'list_agents' + | 'send_message' + | 'followup_task' + | 'wait_agent'; + + /** + * The JSON string of arguments generated for the action. + */ + arguments: string; + + /** + * The unique ID linking this call to its output. + */ + call_id: string; + + /** + * The type of the multi-agent call. Always `multi_agent_call`. + */ + type: 'multi_agent_call'; + + /** + * The agent that produced this item. + */ + agent?: MultiAgentCall.Agent; + } + + export namespace MultiAgentCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface MultiAgentCallOutput { + /** + * The unique ID of the multi-agent call output item. + */ + id: string; + + /** + * The multi-agent action that produced this result. + */ + action: + | 'spawn_agent' + | 'interrupt_agent' + | 'list_agents' + | 'send_message' + | 'followup_task' + | 'wait_agent'; + + /** + * The unique ID of the multi-agent call. + */ + call_id: string; + + /** + * Text output returned by the multi-agent action. + */ + output: Array; + + /** + * The type of the multi-agent result. Always `multi_agent_call_output`. + */ + type: 'multi_agent_call_output'; + + /** + * The agent that produced this item. + */ + agent?: MultiAgentCallOutput.Agent; + } + + export namespace MultiAgentCallOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface Program { + /** + * The unique ID of the program item. + */ + id: string; + + /** + * The stable call ID of the program item. + */ + call_id: string; + + /** + * The JavaScript source executed by programmatic tool calling. + */ + code: string; + + /** + * Opaque program replay fingerprint that must be round-tripped. + */ + fingerprint: string; + + /** + * The type of the item. Always `program`. + */ + type: 'program'; + + /** + * The agent that produced this item. + */ + agent?: Program.Agent; + } + + export namespace Program { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface ProgramOutput { + /** + * The unique ID of the program output item. + */ + id: string; + + /** + * The call ID of the program item. + */ + call_id: string; + + /** + * The result produced by the program item. + */ + result: string; + + /** + * The terminal status of the program output item. + */ + status: 'completed' | 'incomplete'; + + /** + * The type of the item. Always `program_output`. + */ + type: 'program_output'; + + /** + * The agent that produced this item. + */ + agent?: ProgramOutput.Agent; + } + + export namespace ProgramOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + export interface AdditionalTools { + /** + * The unique ID of the additional tools item. + */ + id: string; + + /** + * The role that provided the additional tools. + */ + role: 'unknown' | 'user' | 'assistant' | 'system' | 'critic' | 'discriminator' | 'developer' | 'tool'; + + /** + * The additional tool definitions made available at this item. + */ + tools: Array; + + /** + * The type of the item. Always `additional_tools`. + */ + type: 'additional_tools'; + + /** + * The agent that produced this item. + */ + agent?: AdditionalTools.Agent; + } + + export namespace AdditionalTools { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * An image generation request made by the model. + */ + export interface ImageGenerationCall { + /** + * The unique ID of the image generation call. + */ + id: string; + + /** + * The generated image encoded in base64. + */ + result: string | null; + + /** + * The status of the image generation call. + */ + status: 'in_progress' | 'completed' | 'generating' | 'failed'; + + /** + * The type of the image generation call. Always `image_generation_call`. + */ + type: 'image_generation_call'; + + /** + * The agent that produced this item. + */ + agent?: ImageGenerationCall.Agent | null; + } + + export namespace ImageGenerationCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * A tool call to run a command on the local shell. + */ + export interface LocalShellCall { + /** + * The unique ID of the local shell call. + */ + id: string; + + /** + * Execute a shell command on the server. + */ + action: LocalShellCall.Action; + + /** + * The unique ID of the local shell tool call generated by the model. + */ + call_id: string; + + /** + * The status of the local shell call. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The type of the local shell call. Always `local_shell_call`. + */ + type: 'local_shell_call'; + + /** + * The agent that produced this item. + */ + agent?: LocalShellCall.Agent | null; + } + + export namespace LocalShellCall { + /** + * Execute a shell command on the server. + */ + export interface Action { + /** + * The command to run. + */ + command: Array; + + /** + * Environment variables to set for the command. + */ + env: { [key: string]: string }; + + /** + * The type of the local shell action. Always `exec`. + */ + type: 'exec'; + + /** + * Optional timeout in milliseconds for the command. + */ + timeout_ms?: number | null; + + /** + * Optional user to run the command as. + */ + user?: string | null; + + /** + * Optional working directory to run the command in. + */ + working_directory?: string | null; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * The output of a local shell tool call. + */ + export interface LocalShellCallOutput { + /** + * The unique ID of the local shell tool call generated by the model. + */ + id: string; + + /** + * A JSON string of the output of the local shell tool call. + */ + output: string; + + /** + * The type of the local shell tool call output. Always `local_shell_call_output`. + */ + type: 'local_shell_call_output'; + + /** + * The agent that produced this item. + */ + agent?: LocalShellCallOutput.Agent | null; + + /** + * The status of the item. One of `in_progress`, `completed`, or `incomplete`. + */ + status?: 'in_progress' | 'completed' | 'incomplete' | null; + } + + export namespace LocalShellCallOutput { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * An invocation of a tool on an MCP server. + */ + export interface McpCall { + /** + * The unique ID of the tool call. + */ + id: string; + + /** + * A JSON string of the arguments passed to the tool. + */ + arguments: string; + + /** + * The name of the tool that was run. + */ + name: string; + + /** + * The label of the MCP server running the tool. + */ + server_label: string; + + /** + * The type of the item. Always `mcp_call`. + */ + type: 'mcp_call'; + + /** + * The agent that produced this item. + */ + agent?: McpCall.Agent | null; + + /** + * 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. + */ + approval_request_id?: string | null; + + /** + * The error from the tool call, if any. + */ + error?: string | null; + + /** + * The output from the tool call. + */ + output?: string | null; + + /** + * The status of the tool call. One of `in_progress`, `completed`, `incomplete`, + * `calling`, or `failed`. + */ + status?: 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed'; + } + + export namespace McpCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * A list of tools available on an MCP server. + */ + export interface McpListTools { + /** + * The unique ID of the list. + */ + id: string; + + /** + * The label of the MCP server. + */ + server_label: string; + + /** + * The tools available on the server. + */ + tools: Array; + + /** + * The type of the item. Always `mcp_list_tools`. + */ + type: 'mcp_list_tools'; + + /** + * The agent that produced this item. + */ + agent?: McpListTools.Agent | null; + + /** + * Error message if the server could not list tools. + */ + error?: string | null; + } + + export namespace McpListTools { + /** + * A tool available on an MCP server. + */ + export interface Tool { + /** + * The JSON schema describing the tool's input. + */ + input_schema: unknown; + + /** + * The name of the tool. + */ + name: string; + + /** + * Additional annotations about the tool. + */ + annotations?: unknown | null; + + /** + * The description of the tool. + */ + description?: string | null; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * A request for human approval of a tool invocation. + */ + export interface McpApprovalRequest { + /** + * The unique ID of the approval request. + */ + id: string; + + /** + * A JSON string of arguments for the tool. + */ + arguments: string; + + /** + * The name of the tool to run. + */ + name: string; + + /** + * The label of the MCP server making the request. + */ + server_label: string; + + /** + * The type of the item. Always `mcp_approval_request`. + */ + type: 'mcp_approval_request'; + + /** + * The agent that produced this item. + */ + agent?: McpApprovalRequest.Agent | null; + } + + export namespace McpApprovalRequest { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } + + /** + * A response to an MCP approval request. + */ + export interface McpApprovalResponse { + /** + * The unique ID of the approval response + */ + id: string; + + /** + * The ID of the approval request being answered. + */ + approval_request_id: string; + + /** + * Whether the request was approved. + */ + approve: boolean; + + /** + * The type of the item. Always `mcp_approval_response`. + */ + type: 'mcp_approval_response'; + + /** + * The agent that produced this item. + */ + agent?: McpApprovalResponse.Agent | null; + + /** + * Optional reason for the decision. + */ + reason?: string | null; + } + + export namespace McpApprovalResponse { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + } +} + +/** + * Emitted when a new output item is added. + */ +export interface BetaResponseOutputItemAddedEvent { + /** + * The output item that was added. + */ + item: BetaResponseOutputItem; + + /** + * The index of the output item that was added. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.output_item.added`. + */ + type: 'response.output_item.added'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseOutputItemAddedEvent.Agent | null; +} + +export namespace BetaResponseOutputItemAddedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when an output item is marked done. + */ +export interface BetaResponseOutputItemDoneEvent { + /** + * The output item that was marked done. + */ + item: BetaResponseOutputItem; + + /** + * The index of the output item that was marked done. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.output_item.done`. + */ + type: 'response.output_item.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseOutputItemDoneEvent.Agent | null; +} + +export namespace BetaResponseOutputItemDoneEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * An output message from the model. + */ +export interface BetaResponseOutputMessage { + /** + * The unique ID of the output message. + */ + id: string; + + /** + * The content of the output message. + */ + content: Array; + + /** + * The role of the output message. Always `assistant`. + */ + role: 'assistant'; + + /** + * The status of the message input. One of `in_progress`, `completed`, or + * `incomplete`. Populated when input items are returned via API. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The type of the output message. Always `message`. + */ + type: 'message'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseOutputMessage.Agent | null; + + /** + * 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. + */ + phase?: 'commentary' | 'final_answer' | null; +} + +export namespace BetaResponseOutputMessage { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * A refusal from the model. + */ +export interface BetaResponseOutputRefusal { + /** + * The refusal explanation from the model. + */ + refusal: string; + + /** + * The type of the refusal. Always `refusal`. + */ + type: 'refusal'; +} + +/** + * A text output from the model. + */ +export interface BetaResponseOutputText { + /** + * The annotations of the text output. + */ + annotations: Array< + | BetaResponseOutputText.FileCitation + | BetaResponseOutputText.URLCitation + | BetaResponseOutputText.ContainerFileCitation + | BetaResponseOutputText.FilePath + >; + + /** + * The text output from the model. + */ + text: string; + + /** + * The type of the output text. Always `output_text`. + */ + type: 'output_text'; + + logprobs?: Array; +} + +export namespace BetaResponseOutputText { + /** + * A citation to a file. + */ + export interface FileCitation { + /** + * The ID of the file. + */ + file_id: string; + + /** + * The filename of the file cited. + */ + filename: string; + + /** + * The index of the file in the list of files. + */ + index: number; + + /** + * The type of the file citation. Always `file_citation`. + */ + type: 'file_citation'; + } + + /** + * A citation for a web resource used to generate a model response. + */ + export interface URLCitation { + /** + * The index of the last character of the URL citation in the message. + */ + end_index: number; + + /** + * The index of the first character of the URL citation in the message. + */ + start_index: number; + + /** + * The title of the web resource. + */ + title: string; + + /** + * The type of the URL citation. Always `url_citation`. + */ + type: 'url_citation'; + + /** + * The URL of the web resource. + */ + url: string; + } + + /** + * A citation for a container file used to generate a model response. + */ + export interface ContainerFileCitation { + /** + * The ID of the container file. + */ + container_id: string; + + /** + * The index of the last character of the container file citation in the message. + */ + end_index: number; + + /** + * The ID of the file. + */ + file_id: string; + + /** + * The filename of the container file cited. + */ + filename: string; + + /** + * The index of the first character of the container file citation in the message. + */ + start_index: number; + + /** + * The type of the container file citation. Always `container_file_citation`. + */ + type: 'container_file_citation'; + } + + /** + * A path to a file. + */ + export interface FilePath { + /** + * The ID of the file. + */ + file_id: string; + + /** + * The index of the file in the list of files. + */ + index: number; + + /** + * The type of the file path. Always `file_path`. + */ + type: 'file_path'; + } + + /** + * The log probability of a token. + */ + export interface Logprob { + token: string; + + bytes: Array; + + logprob: number; + + top_logprobs: Array; + } + + export namespace Logprob { + /** + * The top log probability of a token. + */ + export interface TopLogprob { + token: string; + + bytes: Array; + + logprob: number; + } + } +} + +/** + * Emitted when an annotation is added to output text content. + */ +export interface BetaResponseOutputTextAnnotationAddedEvent { + /** + * The annotation object being added. (See annotation schema for details.) + */ + annotation: unknown; + + /** + * The index of the annotation within the content part. + */ + annotation_index: number; + + /** + * The index of the content part within the output item. + */ + content_index: number; + + /** + * The unique identifier of the item to which the annotation is being added. + */ + item_id: string; + + /** + * The index of the output item in the response's output array. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.output_text.annotation.added'. + */ + type: 'response.output_text.annotation.added'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseOutputTextAnnotationAddedEvent.Agent | null; +} + +export namespace BetaResponseOutputTextAnnotationAddedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Reference to a prompt template and its variables. + * [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + */ +export interface BetaResponsePrompt { + /** + * The unique identifier of the prompt template to use. + */ + id: string; + + /** + * 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. + */ + variables?: { + [key: string]: string | BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile; + } | null; + + /** + * Optional version of the prompt template. + */ + version?: string | null; +} + +/** + * Emitted when a response is queued and waiting to be processed. + */ +export interface BetaResponseQueuedEvent { + /** + * The full response object that is queued. + */ + response: BetaResponse; + + /** + * The sequence number for this event. + */ + sequence_number: number; + + /** + * The type of the event. Always 'response.queued'. + */ + type: 'response.queued'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseQueuedEvent.Agent | null; +} + +export namespace BetaResponseQueuedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * 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). + */ +export interface BetaResponseReasoningItem { + /** + * The unique identifier of the reasoning content. + */ + id: string; + + /** + * Reasoning summary content. + */ + summary: Array; + + /** + * The type of the object. Always `reasoning`. + */ + type: 'reasoning'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseReasoningItem.Agent | null; + + /** + * Reasoning text content. + */ + content?: Array; + + /** + * The encrypted content of the reasoning item - populated when a response is + * generated with `reasoning.encrypted_content` in the `include` parameter. + */ + encrypted_content?: string | null; + + /** + * The status of the item. One of `in_progress`, `completed`, or `incomplete`. + * Populated when items are returned via API. + */ + status?: 'in_progress' | 'completed' | 'incomplete'; +} + +export namespace BetaResponseReasoningItem { + /** + * A summary text from the model. + */ + export interface Summary { + /** + * A summary of the reasoning output from the model so far. + */ + text: string; + + /** + * The type of the object. Always `summary_text`. + */ + type: 'summary_text'; + } + + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } + + /** + * Reasoning text from the model. + */ + export interface Content { + /** + * The reasoning text from the model. + */ + text: string; + + /** + * The type of the reasoning text. Always `reasoning_text`. + */ + type: 'reasoning_text'; + } +} + +/** + * Emitted when a new reasoning summary part is added. + */ +export interface BetaResponseReasoningSummaryPartAddedEvent { + /** + * The ID of the item this summary part is associated with. + */ + item_id: string; + + /** + * The index of the output item this summary part is associated with. + */ + output_index: number; + + /** + * The summary part that was added. + */ + part: BetaResponseReasoningSummaryPartAddedEvent.Part; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The index of the summary part within the reasoning summary. + */ + summary_index: number; + + /** + * The type of the event. Always `response.reasoning_summary_part.added`. + */ + type: 'response.reasoning_summary_part.added'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseReasoningSummaryPartAddedEvent.Agent | null; +} + +export namespace BetaResponseReasoningSummaryPartAddedEvent { + /** + * The summary part that was added. + */ + export interface Part { + /** + * The text of the summary part. + */ + text: string; + + /** + * The type of the summary part. Always `summary_text`. + */ + type: 'summary_text'; + } + + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a reasoning summary part is completed. + */ +export interface BetaResponseReasoningSummaryPartDoneEvent { + /** + * The ID of the item this summary part is associated with. + */ + item_id: string; + + /** + * The index of the output item this summary part is associated with. + */ + output_index: number; + + /** + * The completed summary part. + */ + part: BetaResponseReasoningSummaryPartDoneEvent.Part; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The index of the summary part within the reasoning summary. + */ + summary_index: number; + + /** + * The type of the event. Always `response.reasoning_summary_part.done`. + */ + type: 'response.reasoning_summary_part.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseReasoningSummaryPartDoneEvent.Agent | null; + + /** + * The completion status of the summary part. Omitted when the part completed + * normally and set to `incomplete` when generation was interrupted. + */ + status?: 'incomplete'; +} + +export namespace BetaResponseReasoningSummaryPartDoneEvent { + /** + * The completed summary part. + */ + export interface Part { + /** + * The text of the summary part. + */ + text: string; + + /** + * The type of the summary part. Always `summary_text`. + */ + type: 'summary_text'; + } + + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a delta is added to a reasoning summary text. + */ +export interface BetaResponseReasoningSummaryTextDeltaEvent { + /** + * The text delta that was added to the summary. + */ + delta: string; + + /** + * The ID of the item this summary text delta is associated with. + */ + item_id: string; + + /** + * The index of the output item this summary text delta is associated with. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The index of the summary part within the reasoning summary. + */ + summary_index: number; + + /** + * The type of the event. Always `response.reasoning_summary_text.delta`. + */ + type: 'response.reasoning_summary_text.delta'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseReasoningSummaryTextDeltaEvent.Agent | null; +} + +export namespace BetaResponseReasoningSummaryTextDeltaEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a reasoning summary text is completed. + */ +export interface BetaResponseReasoningSummaryTextDoneEvent { + /** + * The ID of the item this summary text is associated with. + */ + item_id: string; + + /** + * The index of the output item this summary text is associated with. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The index of the summary part within the reasoning summary. + */ + summary_index: number; + + /** + * The full text of the completed reasoning summary. + */ + text: string; + + /** + * The type of the event. Always `response.reasoning_summary_text.done`. + */ + type: 'response.reasoning_summary_text.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseReasoningSummaryTextDoneEvent.Agent | null; +} + +export namespace BetaResponseReasoningSummaryTextDoneEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a delta is added to a reasoning text. + */ +export interface BetaResponseReasoningTextDeltaEvent { + /** + * The index of the reasoning content part this delta is associated with. + */ + content_index: number; + + /** + * The text delta that was added to the reasoning content. + */ + delta: string; + + /** + * The ID of the item this reasoning text delta is associated with. + */ + item_id: string; + + /** + * The index of the output item this reasoning text delta is associated with. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.reasoning_text.delta`. + */ + type: 'response.reasoning_text.delta'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseReasoningTextDeltaEvent.Agent | null; +} + +export namespace BetaResponseReasoningTextDeltaEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a reasoning text is completed. + */ +export interface BetaResponseReasoningTextDoneEvent { + /** + * The index of the reasoning content part. + */ + content_index: number; + + /** + * The ID of the item this reasoning text is associated with. + */ + item_id: string; + + /** + * The index of the output item this reasoning text is associated with. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The full text of the completed reasoning content. + */ + text: string; + + /** + * The type of the event. Always `response.reasoning_text.done`. + */ + type: 'response.reasoning_text.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseReasoningTextDoneEvent.Agent | null; +} + +export namespace BetaResponseReasoningTextDoneEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when there is a partial refusal text. + */ +export interface BetaResponseRefusalDeltaEvent { + /** + * The index of the content part that the refusal text is added to. + */ + content_index: number; + + /** + * The refusal text that is added. + */ + delta: string; + + /** + * The ID of the output item that the refusal text is added to. + */ + item_id: string; + + /** + * The index of the output item that the refusal text is added to. + */ + output_index: number; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.refusal.delta`. + */ + type: 'response.refusal.delta'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseRefusalDeltaEvent.Agent | null; +} + +export namespace BetaResponseRefusalDeltaEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when refusal text is finalized. + */ +export interface BetaResponseRefusalDoneEvent { + /** + * The index of the content part that the refusal text is finalized. + */ + content_index: number; + + /** + * The ID of the output item that the refusal text is finalized. + */ + item_id: string; + + /** + * The index of the output item that the refusal text is finalized. + */ + output_index: number; + + /** + * The refusal text that is finalized. + */ + refusal: string; + + /** + * The sequence number of this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.refusal.done`. + */ + type: 'response.refusal.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseRefusalDoneEvent.Agent | null; +} + +export namespace BetaResponseRefusalDoneEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * The status of the response generation. One of `completed`, `failed`, + * `in_progress`, `cancelled`, `queued`, or `incomplete`. + */ +export type BetaResponseStatus = + | 'completed' + | 'failed' + | 'in_progress' + | 'cancelled' + | 'queued' + | 'incomplete'; + +/** + * Emitted when there is a partial audio response. + */ +export type BetaResponseStreamEvent = + | BetaResponseAudioDeltaEvent + | BetaResponseAudioDoneEvent + | BetaResponseAudioTranscriptDeltaEvent + | BetaResponseAudioTranscriptDoneEvent + | BetaResponseCodeInterpreterCallCodeDeltaEvent + | BetaResponseCodeInterpreterCallCodeDoneEvent + | BetaResponseCodeInterpreterCallCompletedEvent + | BetaResponseCodeInterpreterCallInProgressEvent + | BetaResponseCodeInterpreterCallInterpretingEvent + | BetaResponseCompletedEvent + | BetaResponseContentPartAddedEvent + | BetaResponseContentPartDoneEvent + | BetaResponseCreatedEvent + | BetaResponseErrorEvent + | BetaResponseFileSearchCallCompletedEvent + | BetaResponseFileSearchCallInProgressEvent + | BetaResponseFileSearchCallSearchingEvent + | BetaResponseFunctionCallArgumentsDeltaEvent + | BetaResponseFunctionCallArgumentsDoneEvent + | BetaResponseInProgressEvent + | BetaResponseFailedEvent + | BetaResponseIncompleteEvent + | BetaResponseOutputItemAddedEvent + | BetaResponseOutputItemDoneEvent + | BetaResponseReasoningSummaryPartAddedEvent + | BetaResponseReasoningSummaryPartDoneEvent + | BetaResponseReasoningSummaryTextDeltaEvent + | BetaResponseReasoningSummaryTextDoneEvent + | BetaResponseReasoningTextDeltaEvent + | BetaResponseReasoningTextDoneEvent + | BetaResponseRefusalDeltaEvent + | BetaResponseRefusalDoneEvent + | BetaResponseTextDeltaEvent + | BetaResponseTextDoneEvent + | BetaResponseWebSearchCallCompletedEvent + | BetaResponseWebSearchCallInProgressEvent + | BetaResponseWebSearchCallSearchingEvent + | BetaResponseImageGenCallCompletedEvent + | BetaResponseImageGenCallGeneratingEvent + | BetaResponseImageGenCallInProgressEvent + | BetaResponseImageGenCallPartialImageEvent + | BetaResponseMcpCallArgumentsDeltaEvent + | BetaResponseMcpCallArgumentsDoneEvent + | BetaResponseMcpCallCompletedEvent + | BetaResponseMcpCallFailedEvent + | BetaResponseMcpCallInProgressEvent + | BetaResponseMcpListToolsCompletedEvent + | BetaResponseMcpListToolsFailedEvent + | BetaResponseMcpListToolsInProgressEvent + | BetaResponseOutputTextAnnotationAddedEvent + | BetaResponseQueuedEvent + | BetaResponseCustomToolCallInputDeltaEvent + | BetaResponseCustomToolCallInputDoneEvent; + +/** + * 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) + */ +export interface BetaResponseTextConfig { + /** + * 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. + */ + format?: BetaResponseFormatTextConfig; + + /** + * 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`. + */ + verbosity?: 'low' | 'medium' | 'high' | null; +} + +/** + * Emitted when there is an additional text delta. + */ +export interface BetaResponseTextDeltaEvent { + /** + * The index of the content part that the text delta was added to. + */ + content_index: number; + + /** + * The text delta that was added. + */ + delta: string; + + /** + * The ID of the output item that the text delta was added to. + */ + item_id: string; + + /** + * The log probabilities of the tokens in the delta. + */ + logprobs: Array; + + /** + * The index of the output item that the text delta was added to. + */ + output_index: number; + + /** + * The sequence number for this event. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.output_text.delta`. + */ + type: 'response.output_text.delta'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseTextDeltaEvent.Agent | null; +} + +export namespace BetaResponseTextDeltaEvent { + /** + * A logprob is the logarithmic probability that the model assigns to producing a + * particular token at a given position in the sequence. Less-negative (higher) + * logprob values indicate greater model confidence in that token choice. + */ + export interface Logprob { + /** + * A possible text token. + */ + token: string; + + /** + * The log probability of this token. + */ + logprob: number; + + /** + * The log probabilities of up to 20 of the most likely tokens. + */ + top_logprobs?: Array; + } + + export namespace Logprob { + export interface TopLogprob { + /** + * A possible text token. + */ + token?: string; + + /** + * The log probability of this token. + */ + logprob?: number; + } + } + + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when text content is finalized. + */ +export interface BetaResponseTextDoneEvent { + /** + * The index of the content part that the text content is finalized. + */ + content_index: number; + + /** + * The ID of the output item that the text content is finalized. + */ + item_id: string; + + /** + * The log probabilities of the tokens in the delta. + */ + logprobs: Array; + + /** + * The index of the output item that the text content is finalized. + */ + output_index: number; + + /** + * The sequence number for this event. + */ + sequence_number: number; + + /** + * The text content that is finalized. + */ + text: string; + + /** + * The type of the event. Always `response.output_text.done`. + */ + type: 'response.output_text.done'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseTextDoneEvent.Agent | null; +} + +export namespace BetaResponseTextDoneEvent { + /** + * A logprob is the logarithmic probability that the model assigns to producing a + * particular token at a given position in the sequence. Less-negative (higher) + * logprob values indicate greater model confidence in that token choice. + */ + export interface Logprob { + /** + * A possible text token. + */ + token: string; + + /** + * The log probability of this token. + */ + logprob: number; + + /** + * The log probabilities of up to 20 of the most likely tokens. + */ + top_logprobs?: Array; + } + + export namespace Logprob { + export interface TopLogprob { + /** + * A possible text token. + */ + token?: string; + + /** + * The log probability of this token. + */ + logprob?: number; + } + } + + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +export interface BetaResponseToolSearchCall { + /** + * The unique ID of the tool search call item. + */ + id: string; + + /** + * Arguments used for the tool search call. + */ + arguments: unknown; + + /** + * The unique ID of the tool search call generated by the model. + */ + call_id: string | null; + + /** + * Whether tool search was executed by the server or by the client. + */ + execution: 'server' | 'client'; + + /** + * The status of the tool search call item that was recorded. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The type of the item. Always `tool_search_call`. + */ + type: 'tool_search_call'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseToolSearchCall.Agent; + + /** + * The identifier of the actor that created the item. + */ + created_by?: string; +} + +export namespace BetaResponseToolSearchCall { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +export interface BetaResponseToolSearchOutputItem { + /** + * The unique ID of the tool search output item. + */ + id: string; + + /** + * The unique ID of the tool search call generated by the model. + */ + call_id: string | null; + + /** + * Whether tool search was executed by the server or by the client. + */ + execution: 'server' | 'client'; + + /** + * The status of the tool search output item that was recorded. + */ + status: 'in_progress' | 'completed' | 'incomplete'; + + /** + * The loaded tool definitions returned by tool search. + */ + tools: Array; + + /** + * The type of the item. Always `tool_search_output`. + */ + type: 'tool_search_output'; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseToolSearchOutputItem.Agent; + + /** + * The identifier of the actor that created the item. + */ + created_by?: string; +} + +export namespace BetaResponseToolSearchOutputItem { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +export interface BetaResponseToolSearchOutputItemParam { + /** + * The loaded tool definitions returned by the tool search output. + */ + tools: Array; + + /** + * The item type. Always `tool_search_output`. + */ + type: 'tool_search_output'; + + /** + * The unique ID of this tool search output. + */ + id?: string | null; + + /** + * The agent that produced this item. + */ + agent?: BetaResponseToolSearchOutputItemParam.Agent | null; + + /** + * The unique ID of the tool search call generated by the model. + */ + call_id?: string | null; + + /** + * Whether tool search was executed by the server or by the client. + */ + execution?: 'server' | 'client'; + + /** + * The status of the tool search output. + */ + status?: 'in_progress' | 'completed' | 'incomplete' | null; +} + +export namespace BetaResponseToolSearchOutputItemParam { + /** + * The agent that produced this item. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Represents token usage details including input tokens, output tokens, a + * breakdown of output tokens, and the total tokens used. + */ +export interface BetaResponseUsage { + /** + * The number of input tokens. + */ + input_tokens: number; + + /** + * A detailed breakdown of the input tokens. + */ + input_tokens_details: BetaResponseUsage.InputTokensDetails; + + /** + * The number of output tokens. + */ + output_tokens: number; + + /** + * A detailed breakdown of the output tokens. + */ + output_tokens_details: BetaResponseUsage.OutputTokensDetails; + + /** + * The total number of tokens used. + */ + total_tokens: number; +} + +export namespace BetaResponseUsage { + /** + * A detailed breakdown of the input tokens. + */ + export interface InputTokensDetails { + /** + * The number of input tokens that were written to the cache. + */ + cache_write_tokens: number; + + /** + * The number of tokens that were retrieved from the cache. + * [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + */ + cached_tokens: number; + } + + /** + * A detailed breakdown of the output tokens. + */ + export interface OutputTokensDetails { + /** + * The number of reasoning tokens. + */ + reasoning_tokens: number; + } +} + +/** + * Emitted when a web search call is completed. + */ +export interface BetaResponseWebSearchCallCompletedEvent { + /** + * Unique ID for the output item associated with the web search call. + */ + item_id: string; + + /** + * The index of the output item that the web search call is associated with. + */ + output_index: number; + + /** + * The sequence number of the web search call being processed. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.web_search_call.completed`. + */ + type: 'response.web_search_call.completed'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseWebSearchCallCompletedEvent.Agent | null; +} + +export namespace BetaResponseWebSearchCallCompletedEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a web search call is initiated. + */ +export interface BetaResponseWebSearchCallInProgressEvent { + /** + * Unique ID for the output item associated with the web search call. + */ + item_id: string; + + /** + * The index of the output item that the web search call is associated with. + */ + output_index: number; + + /** + * The sequence number of the web search call being processed. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.web_search_call.in_progress`. + */ + type: 'response.web_search_call.in_progress'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseWebSearchCallInProgressEvent.Agent | null; +} + +export namespace BetaResponseWebSearchCallInProgressEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Emitted when a web search call is executing. + */ +export interface BetaResponseWebSearchCallSearchingEvent { + /** + * Unique ID for the output item associated with the web search call. + */ + item_id: string; + + /** + * The index of the output item that the web search call is associated with. + */ + output_index: number; + + /** + * The sequence number of the web search call being processed. + */ + sequence_number: number; + + /** + * The type of the event. Always `response.web_search_call.searching`. + */ + type: 'response.web_search_call.searching'; + + /** + * The agent that owns this multi-agent streaming event. + */ + agent?: BetaResponseWebSearchCallSearchingEvent.Agent | null; +} + +export namespace BetaResponseWebSearchCallSearchingEvent { + /** + * The agent that owns this multi-agent streaming event. + */ + export interface Agent { + /** + * The canonical name of the agent that produced this item. + */ + agent_name: string; + } +} + +/** + * Client events accepted by the Responses WebSocket server. + */ +export type BetaResponsesClientEvent = BetaResponsesClientEvent.ResponseCreate | BetaResponseInjectEvent; + +export namespace BetaResponsesClientEvent { + /** + * Client event for creating a response over a persistent WebSocket connection. + * This payload uses the same top-level fields as `POST /v1/responses`. + * + * Notes: + * + * - `stream` is implicit over WebSocket and should not be sent. + * - `background` is not supported over WebSocket. + */ + export interface ResponseCreate { + /** + * The type of the client event. Always `response.create`. + */ + type: 'response.create'; + + /** + * Whether to run the model response in the background. + * [Learn more](https://platform.openai.com/docs/guides/background). + */ + background?: boolean | null; + + /** + * Context management configuration for this request. + */ + context_management?: Array | null; + + /** + * 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. + */ + conversation?: string | ResponsesAPI.BetaResponseConversationParam | null; + + /** + * Specify additional output data to include in the model response. Currently + * supported values are: + * + * - `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). + */ + include?: Array | null; + + /** + * Text, image, or file inputs to the model, used to generate a response. + * + * Learn more: + * + * - [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?: string | ResponsesAPI.BetaResponseInput; + + /** + * 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. + */ + instructions?: string | null; + + /** + * 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_output_tokens?: number | null; + + /** + * 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. + */ + max_tool_calls?: number | null; + + /** + * 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. + */ + metadata?: { [key: string]: string } | null; + + /** + * 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. + */ + model?: + | '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' + | (string & {}); + + /** + * Configuration for running moderation on the input and output of this response. + */ + moderation?: ResponseCreate.Moderation | null; + + /** + * Configuration for server-hosted multi-agent execution. + */ + multi_agent?: ResponseCreate.MultiAgent | null; + + /** + * Whether to allow the model to run tool calls in parallel. + */ + parallel_tool_calls?: boolean | null; + + /** + * 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`. + */ + previous_response_id?: string | null; + + /** + * Reference to a prompt template and its variables. + * [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + */ + prompt?: ResponsesAPI.BetaResponsePrompt | null; + + /** + * 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_key?: string; + + /** + * 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. + */ + prompt_cache_options?: ResponseCreate.PromptCacheOptions; + + /** + * @deprecated 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. + */ + prompt_cache_retention?: 'in_memory' | '24h' | null; + + /** + * **gpt-5 and o-series models only** + * + * Configuration options for + * [reasoning models](https://platform.openai.com/docs/guides/reasoning). + */ + reasoning?: ResponseCreate.Reasoning | null; + + /** + * 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). + */ + safety_identifier?: string; + + /** + * 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. + */ + service_tier?: 'auto' | 'default' | 'flex' | 'scale' | 'priority' | null; + + /** + * Whether to store the generated model response for later retrieval via API. + */ + store?: boolean | null; + + /** + * 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?: boolean | null; + + /** + * Options for streaming responses. Only set this when you set `stream: true`. + */ + stream_options?: ResponseCreate.StreamOptions | null; + + /** + * 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. + */ + temperature?: number | null; + + /** + * 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) + */ + text?: ResponsesAPI.BetaResponseTextConfig; + + /** + * 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. + */ + tool_choice?: + | ResponsesAPI.BetaToolChoiceOptions + | ResponsesAPI.BetaToolChoiceAllowed + | ResponsesAPI.BetaToolChoiceTypes + | ResponsesAPI.BetaToolChoiceFunction + | ResponsesAPI.BetaToolChoiceMcp + | ResponsesAPI.BetaToolChoiceCustom + | ResponseCreate.BetaSpecificProgrammaticToolCallingParam + | ResponsesAPI.BetaToolChoiceApplyPatch + | ResponsesAPI.BetaToolChoiceShell; + + /** + * 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. + */ + tools?: Array; + + /** + * 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_logprobs?: number | null; + + /** + * 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. + */ + top_p?: number | null; + + /** + * @deprecated 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. + */ + truncation?: 'auto' | 'disabled' | null; + + /** + * @deprecated 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). + */ + user?: string; + } + + export namespace ResponseCreate { + export interface ContextManagement { + /** + * The context management entry type. Currently only 'compaction' is supported. + */ + type: string; + + /** + * Token threshold at which compaction should be triggered for this entry. + */ + compact_threshold?: number | null; + } + + /** + * Configuration for running moderation on the input and output of this response. + */ + export interface Moderation { + /** + * The moderation model to use for moderated completions, e.g. + * 'omni-moderation-latest'. + */ + model: string; + + /** + * The policy to apply to moderated response input and output. + */ + policy?: Moderation.Policy | null; + } + + export namespace Moderation { + /** + * The policy to apply to moderated response input and output. + */ + export interface Policy { + /** + * The moderation policy for the response input. + */ + input?: Policy.Input | null; + + /** + * The moderation policy for the response output. + */ + output?: Policy.Output | null; + } + + export namespace Policy { + /** + * The moderation policy for the response input. + */ + export interface Input { + mode: 'score' | 'block'; + } + + /** + * The moderation policy for the response output. + */ + export interface Output { + mode: 'score' | 'block'; + } + } + } + + /** + * Configuration for server-hosted multi-agent execution. + */ + export interface MultiAgent { + /** + * Whether to enable server-hosted multi-agent execution for this response. + */ + enabled: boolean; + + /** + * `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. + */ + max_concurrent_subagents?: number; + } + + /** + * 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. + */ + export interface PromptCacheOptions { + /** + * 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. + */ + mode?: 'implicit' | 'explicit'; + + /** + * 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. + */ + ttl?: '30m'; + } + + /** + * **gpt-5 and o-series models only** + * + * Configuration options for + * [reasoning models](https://platform.openai.com/docs/guides/reasoning). + */ + export interface Reasoning { + /** + * 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. + */ + context?: 'auto' | 'current_turn' | 'all_turns' | null; + + /** + * 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. + */ + effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null; + + /** + * @deprecated **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`. + */ + generate_summary?: 'auto' | 'concise' | 'detailed' | null; + + /** + * Controls the reasoning execution mode for the request. + * + * When returned on a response, this is the effective execution mode. + */ + mode?: (string & {}) | 'standard' | 'pro'; + + /** + * 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`. + */ + summary?: 'auto' | 'concise' | 'detailed' | null; + } + + /** + * Options for streaming responses. Only set this when you set `stream: true`. + */ + export interface StreamOptions { + /** + * 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. + */ + include_obfuscation?: boolean; + } + + export interface BetaSpecificProgrammaticToolCallingParam { + /** + * The tool to call. Always `programmatic_tool_calling`. + */ + type: 'programmatic_tool_calling'; + } + } +} + +/** + * Server events emitted by the Responses WebSocket server. + */ +export type BetaResponsesServerEvent = + | BetaResponseAudioDeltaEvent + | BetaResponseAudioDoneEvent + | BetaResponseAudioTranscriptDeltaEvent + | BetaResponseAudioTranscriptDoneEvent + | BetaResponseCodeInterpreterCallCodeDeltaEvent + | BetaResponseCodeInterpreterCallCodeDoneEvent + | BetaResponseCodeInterpreterCallCompletedEvent + | BetaResponseCodeInterpreterCallInProgressEvent + | BetaResponseCodeInterpreterCallInterpretingEvent + | BetaResponseCompletedEvent + | BetaResponseContentPartAddedEvent + | BetaResponseContentPartDoneEvent + | BetaResponseCreatedEvent + | BetaResponseErrorEvent + | BetaResponseFileSearchCallCompletedEvent + | BetaResponseFileSearchCallInProgressEvent + | BetaResponseFileSearchCallSearchingEvent + | BetaResponseFunctionCallArgumentsDeltaEvent + | BetaResponseFunctionCallArgumentsDoneEvent + | BetaResponseInProgressEvent + | BetaResponseFailedEvent + | BetaResponseIncompleteEvent + | BetaResponseOutputItemAddedEvent + | BetaResponseOutputItemDoneEvent + | BetaResponseReasoningSummaryPartAddedEvent + | BetaResponseReasoningSummaryPartDoneEvent + | BetaResponseReasoningSummaryTextDeltaEvent + | BetaResponseReasoningSummaryTextDoneEvent + | BetaResponseReasoningTextDeltaEvent + | BetaResponseReasoningTextDoneEvent + | BetaResponseRefusalDeltaEvent + | BetaResponseRefusalDoneEvent + | BetaResponseTextDeltaEvent + | BetaResponseTextDoneEvent + | BetaResponseWebSearchCallCompletedEvent + | BetaResponseWebSearchCallInProgressEvent + | BetaResponseWebSearchCallSearchingEvent + | BetaResponseImageGenCallCompletedEvent + | BetaResponseImageGenCallGeneratingEvent + | BetaResponseImageGenCallInProgressEvent + | BetaResponseImageGenCallPartialImageEvent + | BetaResponseMcpCallArgumentsDeltaEvent + | BetaResponseMcpCallArgumentsDoneEvent + | BetaResponseMcpCallCompletedEvent + | BetaResponseMcpCallFailedEvent + | BetaResponseMcpCallInProgressEvent + | BetaResponseMcpListToolsCompletedEvent + | BetaResponseMcpListToolsFailedEvent + | BetaResponseMcpListToolsInProgressEvent + | BetaResponseOutputTextAnnotationAddedEvent + | BetaResponseQueuedEvent + | BetaResponseCustomToolCallInputDeltaEvent + | BetaResponseCustomToolCallInputDoneEvent + | BetaResponseInjectCreatedEvent + | BetaResponseInjectFailedEvent; + +export interface BetaSkillReference { + /** + * The ID of the referenced skill. + */ + skill_id: string; + + /** + * References a skill created with the /v1/skills endpoint. + */ + type: 'skill_reference'; + + /** + * Optional skill version. Use a positive integer or 'latest'. Omit for default. + */ + version?: string; +} + +/** + * A tool that can be used to generate a response. + */ +export type BetaTool = + | BetaFunctionTool + | BetaFileSearchTool + | BetaComputerTool + | BetaComputerUsePreviewTool + | BetaWebSearchTool + | BetaTool.Mcp + | BetaTool.CodeInterpreter + | BetaTool.ProgrammaticToolCalling + | BetaTool.ImageGeneration + | BetaTool.LocalShell + | BetaFunctionShellTool + | BetaCustomTool + | BetaNamespaceTool + | BetaToolSearchTool + | BetaWebSearchPreviewTool + | BetaApplyPatchTool; + +export namespace BetaTool { + /** + * 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). + */ + export interface Mcp { + /** + * A label for this MCP server, used to identify it in tool calls. + */ + server_label: string; + + /** + * The type of the MCP tool. Always `mcp`. + */ + type: 'mcp'; + + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + + /** + * List of allowed tool names or a filter object. + */ + allowed_tools?: Array | Mcp.McpToolFilter | null; + + /** + * 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. + */ + authorization?: string; + + /** + * 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_id?: + | 'connector_dropbox' + | 'connector_gmail' + | 'connector_googlecalendar' + | 'connector_googledrive' + | 'connector_microsoftteams' + | 'connector_outlookcalendar' + | 'connector_outlookemail' + | 'connector_sharepoint'; + + /** + * Whether this MCP tool is deferred and discovered via tool search. + */ + defer_loading?: boolean; + + /** + * Optional HTTP headers to send to the MCP server. Use for authentication or other + * purposes. + */ + headers?: { [key: string]: string } | null; + + /** + * Specify which of the MCP server's tools require approval. + */ + require_approval?: Mcp.McpToolApprovalFilter | 'always' | 'never' | null; + + /** + * Optional description of the MCP server, used to provide more context. + */ + server_description?: string; + + /** + * The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id` + * must be provided. + */ + server_url?: string; + + /** + * 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. + */ + tunnel_id?: string; + } + + export namespace Mcp { + /** + * A filter object to specify which tools are allowed. + */ + export interface McpToolFilter { + /** + * 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. + */ + read_only?: boolean; + + /** + * List of allowed tool names. + */ + tool_names?: Array; + } + + /** + * Specify which of the MCP server's tools require approval. Can be `always`, + * `never`, or a filter object associated with tools that require approval. + */ + export interface McpToolApprovalFilter { + /** + * A filter object to specify which tools are allowed. + */ + always?: McpToolApprovalFilter.Always; + + /** + * A filter object to specify which tools are allowed. + */ + never?: McpToolApprovalFilter.Never; + } + + export namespace McpToolApprovalFilter { + /** + * A filter object to specify which tools are allowed. + */ + export interface Always { + /** + * 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. + */ + read_only?: boolean; + + /** + * List of allowed tool names. + */ + tool_names?: Array; + } + + /** + * A filter object to specify which tools are allowed. + */ + export interface Never { + /** + * 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. + */ + read_only?: boolean; + + /** + * List of allowed tool names. + */ + tool_names?: Array; + } + } + } + + /** + * A tool that runs Python code to help generate a response to a prompt. + */ + export interface CodeInterpreter { + /** + * 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. + */ + container: string | CodeInterpreter.CodeInterpreterToolAuto; + + /** + * The type of the code interpreter tool. Always `code_interpreter`. + */ + type: 'code_interpreter'; + + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + } + + export namespace CodeInterpreter { + /** + * Configuration for a code interpreter container. Optionally specify the IDs of + * the files to run the code on. + */ + export interface CodeInterpreterToolAuto { + /** + * Always `auto`. + */ + type: 'auto'; + + /** + * An optional list of uploaded files to make available to your code. + */ + file_ids?: Array; + + /** + * The memory limit for the code interpreter container. + */ + memory_limit?: '1g' | '4g' | '16g' | '64g' | null; + + /** + * Network access policy for the container. + */ + network_policy?: + | ResponsesAPI.BetaContainerNetworkPolicyDisabled + | ResponsesAPI.BetaContainerNetworkPolicyAllowlist; + } + } + + export interface ProgrammaticToolCalling { + /** + * The type of the tool. Always `programmatic_tool_calling`. + */ + type: 'programmatic_tool_calling'; + } + + /** + * A tool that generates images using the GPT image models. + */ + export interface ImageGeneration { + /** + * The type of the image generation tool. Always `image_generation`. + */ + type: 'image_generation'; + + /** + * Whether to generate a new image or edit an existing image. Default: `auto`. + */ + action?: 'generate' | 'edit' | '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`. + */ + background?: 'transparent' | 'opaque' | '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`. + */ + input_fidelity?: 'high' | 'low' | null; + + /** + * Optional mask for inpainting. Contains `image_url` (string, optional) and + * `file_id` (string, optional). + */ + input_image_mask?: ImageGeneration.InputImageMask; + + /** + * The image generation model to use. Default: `gpt-image-1`. + */ + model?: + | (string & {}) + | 'gpt-image-1' + | 'gpt-image-1-mini' + | 'gpt-image-2' + | 'gpt-image-2-2026-04-21' + | 'gpt-image-1.5' + | 'chatgpt-image-latest'; + + /** + * Moderation level for the generated image. Default: `auto`. + */ + moderation?: 'auto' | 'low'; + + /** + * Compression level for the output image. Default: 100. + */ + output_compression?: number; + + /** + * The output format of the generated image. One of `png`, `webp`, or `jpeg`. + * Default: `png`. + */ + output_format?: 'png' | 'webp' | 'jpeg'; + + /** + * Number of partial images to generate in streaming mode, from 0 (default value) + * to 3. + */ + partial_images?: number; + + /** + * The quality of the generated image. One of `low`, `medium`, `high`, or `auto`. + * Default: `auto`. + */ + quality?: 'low' | 'medium' | 'high' | '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`. + */ + size?: (string & {}) | '1024x1024' | '1024x1536' | '1536x1024' | 'auto'; + } + + export namespace ImageGeneration { + /** + * Optional mask for inpainting. Contains `image_url` (string, optional) and + * `file_id` (string, optional). + */ + export interface InputImageMask { + /** + * File ID for the mask image. + */ + file_id?: string; + + /** + * Base64-encoded mask image. + */ + image_url?: string; + } + } + + /** + * A tool that allows the model to execute shell commands in a local environment. + */ + export interface LocalShell { + /** + * The type of the local shell tool. Always `local_shell`. + */ + type: 'local_shell'; + } +} + +/** + * Constrains the tools available to the model to a pre-defined set. + */ +export interface BetaToolChoiceAllowed { + /** + * 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. + */ + mode: 'auto' | 'required'; + + /** + * 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" } + * ] + * ``` + */ + tools: Array<{ [key: string]: unknown }>; + + /** + * Allowed tool configuration type. Always `allowed_tools`. + */ + type: 'allowed_tools'; +} + +/** + * Forces the model to call the apply_patch tool when executing a tool call. + */ +export interface BetaToolChoiceApplyPatch { + /** + * The tool to call. Always `apply_patch`. + */ + type: 'apply_patch'; +} + +/** + * Use this option to force the model to call a specific custom tool. + */ +export interface BetaToolChoiceCustom { + /** + * The name of the custom tool to call. + */ + name: string; + + /** + * For custom tool calling, the type is always `custom`. + */ + type: 'custom'; +} + +/** + * Use this option to force the model to call a specific function. + */ +export interface BetaToolChoiceFunction { + /** + * The name of the function to call. + */ + name: string; + + /** + * For function calling, the type is always `function`. + */ + type: 'function'; +} + +/** + * Use this option to force the model to call a specific tool on a remote MCP + * server. + */ +export interface BetaToolChoiceMcp { + /** + * The label of the MCP server to use. + */ + server_label: string; + + /** + * For MCP tools, the type is always `mcp`. + */ + type: 'mcp'; + + /** + * The name of the tool to call on the server. + */ + name?: string | null; +} + +/** + * Controls which (if any) tool is called by the model. + * + * `none` means the model will not call any tool 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. + */ +export type BetaToolChoiceOptions = 'none' | 'auto' | 'required'; + +/** + * Forces the model to call the shell tool when a tool call is required. + */ +export interface BetaToolChoiceShell { + /** + * The tool to call. Always `shell`. + */ + type: 'shell'; +} + +/** + * 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). + */ +export interface BetaToolChoiceTypes { + /** + * 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` + */ + type: + | 'file_search' + | 'web_search_preview' + | 'computer' + | 'computer_use_preview' + | 'computer_use' + | 'web_search_preview_2025_03_11' + | 'image_generation' + | 'code_interpreter'; +} + +/** + * Hosted or BYOT tool search configuration for deferred tools. + */ +export interface BetaToolSearchTool { + /** + * The type of the tool. Always `tool_search`. + */ + type: 'tool_search'; + + /** + * Description shown to the model for a client-executed tool search tool. + */ + description?: string | null; + + /** + * Whether tool search is executed by the server or by the client. + */ + execution?: 'server' | 'client'; + + /** + * Parameter schema for a client-executed tool search tool. + */ + parameters?: unknown | null; +} + +/** + * 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). + */ +export interface BetaWebSearchPreviewTool { + /** + * The type of the web search tool. One of `web_search_preview` or + * `web_search_preview_2025_03_11`. + */ + type: 'web_search_preview' | 'web_search_preview_2025_03_11'; + + search_content_types?: Array<'text' | '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. + */ + search_context_size?: 'low' | 'medium' | 'high'; + + /** + * The user's location. + */ + user_location?: BetaWebSearchPreviewTool.UserLocation | null; +} + +export namespace BetaWebSearchPreviewTool { + /** + * The user's location. + */ + export interface UserLocation { + /** + * The type of location approximation. Always `approximate`. + */ + type: 'approximate'; + + /** + * Free text input for the city of the user, e.g. `San Francisco`. + */ + city?: string | null; + + /** + * The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of + * the user, e.g. `US`. + */ + country?: string | null; + + /** + * Free text input for the region of the user, e.g. `California`. + */ + region?: string | null; + + /** + * The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the + * user, e.g. `America/Los_Angeles`. + */ + timezone?: string | null; + } +} + +/** + * 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). + */ +export interface BetaWebSearchTool { + /** + * The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + */ + type: 'web_search' | 'web_search_2025_08_26'; + + /** + * Filters for the search. + */ + filters?: BetaWebSearchTool.Filters | null; + + /** + * 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. + */ + search_context_size?: 'low' | 'medium' | 'high'; + + /** + * The approximate location of the user. + */ + user_location?: BetaWebSearchTool.UserLocation | null; +} + +export namespace BetaWebSearchTool { + /** + * Filters for the search. + */ + export interface Filters { + /** + * 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"]` + */ + allowed_domains?: Array | null; + } + + /** + * The approximate location of the user. + */ + export interface UserLocation { + /** + * Free text input for the city of the user, e.g. `San Francisco`. + */ + city?: string | null; + + /** + * The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of + * the user, e.g. `US`. + */ + country?: string | null; + + /** + * Free text input for the region of the user, e.g. `California`. + */ + region?: string | null; + + /** + * The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the + * user, e.g. `America/Los_Angeles`. + */ + timezone?: string | null; + + /** + * The type of location approximation. Always `approximate`. + */ + type?: 'approximate'; + } +} + +export type ResponseCreateParams = ResponseCreateParamsNonStreaming | ResponseCreateParamsStreaming; + +export interface ResponseCreateParamsBase { + /** + * Body param: Whether to run the model response in the background. + * [Learn more](https://platform.openai.com/docs/guides/background). + */ + background?: boolean | null; + + /** + * Body param: Context management configuration for this request. + */ + context_management?: Array | null; + + /** + * Body param: 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. + */ + conversation?: string | BetaResponseConversationParam | null; + + /** + * Body param: Specify additional output data to include in the model response. + * Currently supported values are: + * + * - `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). + */ + include?: Array | null; + + /** + * Body param: Text, image, or file inputs to the model, used to generate a + * response. + * + * Learn more: + * + * - [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?: string | BetaResponseInput; + + /** + * Body param: 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. + */ + instructions?: string | null; + + /** + * Body param: 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_output_tokens?: number | null; + + /** + * Body param: 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. + */ + max_tool_calls?: number | null; + + /** + * Body param: 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. + */ + metadata?: { [key: string]: string } | null; + + /** + * Body param: 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. + */ + model?: + | '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' + | (string & {}); + + /** + * Body param: Configuration for running moderation on the input and output of this + * response. + */ + moderation?: ResponseCreateParams.Moderation | null; + + /** + * Body param: Configuration for server-hosted multi-agent execution. + */ + multi_agent?: ResponseCreateParams.MultiAgent | null; + + /** + * Body param: Whether to allow the model to run tool calls in parallel. + */ + parallel_tool_calls?: boolean | null; + + /** + * Body param: 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`. + */ + previous_response_id?: string | null; + + /** + * Body param: Reference to a prompt template and its variables. + * [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + */ + prompt?: BetaResponsePrompt | null; + + /** + * Body param: 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_key?: string; + + /** + * Body param: 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. + */ + prompt_cache_options?: ResponseCreateParams.PromptCacheOptions; + + /** + * @deprecated Body param: 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. + */ + prompt_cache_retention?: 'in_memory' | '24h' | null; + + /** + * Body param: **gpt-5 and o-series models only** + * + * Configuration options for + * [reasoning models](https://platform.openai.com/docs/guides/reasoning). + */ + reasoning?: ResponseCreateParams.Reasoning | null; + + /** + * Body param: 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). + */ + safety_identifier?: string; + + /** + * Body param: 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. + */ + service_tier?: 'auto' | 'default' | 'flex' | 'scale' | 'priority' | null; + + /** + * Body param: Whether to store the generated model response for later retrieval + * via API. + */ + store?: boolean | null; + + /** + * Body param: 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?: boolean | null; + + /** + * Body param: Options for streaming responses. Only set this when you set + * `stream: true`. + */ + stream_options?: ResponseCreateParams.StreamOptions | null; + + /** + * Body param: 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. + */ + temperature?: number | null; + + /** + * Body param: 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) + */ + text?: BetaResponseTextConfig; + + /** + * Body param: 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. + */ + tool_choice?: + | BetaToolChoiceOptions + | BetaToolChoiceAllowed + | BetaToolChoiceTypes + | BetaToolChoiceFunction + | BetaToolChoiceMcp + | BetaToolChoiceCustom + | ResponseCreateParams.BetaSpecificProgrammaticToolCallingParam + | BetaToolChoiceApplyPatch + | BetaToolChoiceShell; + + /** + * Body param: 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. + */ + tools?: Array; + + /** + * Body param: 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_logprobs?: number | null; + + /** + * Body param: 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. + */ + top_p?: number | null; + + /** + * @deprecated Body param: 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. + */ + truncation?: 'auto' | 'disabled' | null; + + /** + * @deprecated Body param: 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). + */ + user?: string; + + /** + * Header param: Optional beta features to enable for this request. + */ + betas?: Array<'responses_multi_agent=v1'>; +} + +export namespace ResponseCreateParams { + export interface ContextManagement { + /** + * The context management entry type. Currently only 'compaction' is supported. + */ + type: string; + + /** + * Token threshold at which compaction should be triggered for this entry. + */ + compact_threshold?: number | null; + } + + /** + * Configuration for running moderation on the input and output of this response. + */ + export interface Moderation { + /** + * The moderation model to use for moderated completions, e.g. + * 'omni-moderation-latest'. + */ + model: string; + + /** + * The policy to apply to moderated response input and output. + */ + policy?: Moderation.Policy | null; + } + + export namespace Moderation { + /** + * The policy to apply to moderated response input and output. + */ + export interface Policy { + /** + * The moderation policy for the response input. + */ + input?: Policy.Input | null; + + /** + * The moderation policy for the response output. + */ + output?: Policy.Output | null; + } + + export namespace Policy { + /** + * The moderation policy for the response input. + */ + export interface Input { + mode: 'score' | 'block'; + } + + /** + * The moderation policy for the response output. + */ + export interface Output { + mode: 'score' | 'block'; + } + } + } + + /** + * Configuration for server-hosted multi-agent execution. + */ + export interface MultiAgent { + /** + * Whether to enable server-hosted multi-agent execution for this response. + */ + enabled: boolean; + + /** + * `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. + */ + max_concurrent_subagents?: number; + } + + /** + * 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. + */ + export interface PromptCacheOptions { + /** + * 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. + */ + mode?: 'implicit' | 'explicit'; + + /** + * 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. + */ + ttl?: '30m'; + } + + /** + * **gpt-5 and o-series models only** + * + * Configuration options for + * [reasoning models](https://platform.openai.com/docs/guides/reasoning). + */ + export interface Reasoning { + /** + * 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. + */ + context?: 'auto' | 'current_turn' | 'all_turns' | null; + + /** + * 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. + */ + effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null; + + /** + * @deprecated **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`. + */ + generate_summary?: 'auto' | 'concise' | 'detailed' | null; + + /** + * Controls the reasoning execution mode for the request. + * + * When returned on a response, this is the effective execution mode. + */ + mode?: (string & {}) | 'standard' | 'pro'; + + /** + * 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`. + */ + summary?: 'auto' | 'concise' | 'detailed' | null; + } + + /** + * Options for streaming responses. Only set this when you set `stream: true`. + */ + export interface StreamOptions { + /** + * 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. + */ + include_obfuscation?: boolean; + } + + export interface BetaSpecificProgrammaticToolCallingParam { + /** + * The tool to call. Always `programmatic_tool_calling`. + */ + type: 'programmatic_tool_calling'; + } + + export type ResponseCreateParamsNonStreaming = ResponsesAPI.ResponseCreateParamsNonStreaming; + export type ResponseCreateParamsStreaming = ResponsesAPI.ResponseCreateParamsStreaming; +} + +export interface ResponseCreateParamsNonStreaming extends ResponseCreateParamsBase { + /** + * Body param: 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?: false | null; +} + +export interface ResponseCreateParamsStreaming extends ResponseCreateParamsBase { + /** + * Body param: 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: true; +} + +export type ResponseRetrieveParams = ResponseRetrieveParamsNonStreaming | ResponseRetrieveParamsStreaming; + +export interface ResponseRetrieveParamsBase { + /** + * Query param: Additional fields to include in the response. See the `include` + * parameter for Response creation above for more information. + */ + include?: Array; + + /** + * Query param: 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. + */ + include_obfuscation?: boolean; + + /** + * Query param: The sequence number of the event after which to start streaming. + */ + starting_after?: number; + + /** + * Query param: 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?: boolean; + + /** + * Header param: Optional beta features to enable for this request. + */ + betas?: Array<'responses_multi_agent=v1'>; +} + +export namespace ResponseRetrieveParams { + export type ResponseRetrieveParamsNonStreaming = ResponsesAPI.ResponseRetrieveParamsNonStreaming; + export type ResponseRetrieveParamsStreaming = ResponsesAPI.ResponseRetrieveParamsStreaming; +} + +export interface ResponseRetrieveParamsNonStreaming extends ResponseRetrieveParamsBase { + /** + * Query param: 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?: false; +} + +export interface ResponseRetrieveParamsStreaming extends ResponseRetrieveParamsBase { + /** + * Query param: 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: true; +} + +export interface ResponseDeleteParams { + /** + * Optional beta features to enable for this request. + */ + betas?: Array<'responses_multi_agent=v1'>; +} + +export interface ResponseCancelParams { + /** + * Optional beta features to enable for this request. + */ + betas?: Array<'responses_multi_agent=v1'>; +} + +export interface ResponseCompactParams { + /** + * Body param: 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. + */ + model: + | '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' + | (string & {}) + | null; + + /** + * Body param: Text, image, or file inputs to the model, used to generate a + * response + */ + input?: string | Array | null; + + /** + * Body param: 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. + */ + instructions?: string | null; + + /** + * Body param: 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`. + */ + previous_response_id?: string | null; + + /** + * Body param: A key to use when reading from or writing to the prompt cache. + */ + prompt_cache_key?: string | null; + + /** + * Body param: 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. + */ + prompt_cache_options?: ResponseCompactParams.PromptCacheOptions | null; + + /** + * @deprecated Body param: How long to retain a prompt cache entry created by this + * request. + */ + prompt_cache_retention?: 'in_memory' | '24h' | null; + + /** + * Body param: The service tier to use for this request. + */ + service_tier?: 'auto' | 'default' | 'flex' | 'priority' | null; + + /** + * Header param: Optional beta features to enable for this request. + */ + betas?: Array<'responses_multi_agent=v1'>; +} + +export namespace ResponseCompactParams { + /** + * 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. + */ + export interface PromptCacheOptions { + /** + * 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. + */ + mode?: 'implicit' | 'explicit'; + + /** + * 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. + */ + ttl?: '30m'; + } +} + +Responses.InputItems = InputItems; +Responses.InputTokens = InputTokens; + +export declare namespace Responses { + export { + type BetaApplyPatchTool as BetaApplyPatchTool, + type BetaCompactedResponse as BetaCompactedResponse, + type BetaComputerAction as BetaComputerAction, + type BetaComputerActionList as BetaComputerActionList, + type BetaComputerTool as BetaComputerTool, + type BetaComputerUsePreviewTool as BetaComputerUsePreviewTool, + type BetaContainerAuto as BetaContainerAuto, + type BetaContainerNetworkPolicyAllowlist as BetaContainerNetworkPolicyAllowlist, + type BetaContainerNetworkPolicyDisabled as BetaContainerNetworkPolicyDisabled, + type BetaContainerNetworkPolicyDomainSecret as BetaContainerNetworkPolicyDomainSecret, + type BetaContainerReference as BetaContainerReference, + type BetaCustomTool as BetaCustomTool, + type BetaEasyInputMessage as BetaEasyInputMessage, + type BetaFileSearchTool as BetaFileSearchTool, + type BetaFunctionShellTool as BetaFunctionShellTool, + type BetaFunctionTool as BetaFunctionTool, + type BetaInlineSkill as BetaInlineSkill, + type BetaInlineSkillSource as BetaInlineSkillSource, + type BetaLocalEnvironment as BetaLocalEnvironment, + type BetaLocalSkill as BetaLocalSkill, + type BetaNamespaceTool as BetaNamespaceTool, + type BetaResponse as BetaResponse, + type BetaResponseApplyPatchToolCall as BetaResponseApplyPatchToolCall, + type BetaResponseApplyPatchToolCallOutput as BetaResponseApplyPatchToolCallOutput, + type BetaResponseAudioDeltaEvent as BetaResponseAudioDeltaEvent, + type BetaResponseAudioDoneEvent as BetaResponseAudioDoneEvent, + type BetaResponseAudioTranscriptDeltaEvent as BetaResponseAudioTranscriptDeltaEvent, + type BetaResponseAudioTranscriptDoneEvent as BetaResponseAudioTranscriptDoneEvent, + type BetaResponseCodeInterpreterCallCodeDeltaEvent as BetaResponseCodeInterpreterCallCodeDeltaEvent, + type BetaResponseCodeInterpreterCallCodeDoneEvent as BetaResponseCodeInterpreterCallCodeDoneEvent, + type BetaResponseCodeInterpreterCallCompletedEvent as BetaResponseCodeInterpreterCallCompletedEvent, + type BetaResponseCodeInterpreterCallInProgressEvent as BetaResponseCodeInterpreterCallInProgressEvent, + type BetaResponseCodeInterpreterCallInterpretingEvent as BetaResponseCodeInterpreterCallInterpretingEvent, + type BetaResponseCodeInterpreterToolCall as BetaResponseCodeInterpreterToolCall, + type BetaResponseCompactionItem as BetaResponseCompactionItem, + type BetaResponseCompactionItemParam as BetaResponseCompactionItemParam, + type BetaResponseCompletedEvent as BetaResponseCompletedEvent, + type BetaResponseComputerToolCall as BetaResponseComputerToolCall, + type BetaResponseComputerToolCallOutputItem as BetaResponseComputerToolCallOutputItem, + type BetaResponseComputerToolCallOutputScreenshot as BetaResponseComputerToolCallOutputScreenshot, + type BetaResponseContainerReference as BetaResponseContainerReference, + type BetaResponseContent as BetaResponseContent, + type BetaResponseContentPartAddedEvent as BetaResponseContentPartAddedEvent, + type BetaResponseContentPartDoneEvent as BetaResponseContentPartDoneEvent, + type BetaResponseConversationParam as BetaResponseConversationParam, + type BetaResponseCreatedEvent as BetaResponseCreatedEvent, + type BetaResponseCustomToolCall as BetaResponseCustomToolCall, + type BetaResponseCustomToolCallInputDeltaEvent as BetaResponseCustomToolCallInputDeltaEvent, + type BetaResponseCustomToolCallInputDoneEvent as BetaResponseCustomToolCallInputDoneEvent, + type BetaResponseCustomToolCallItem as BetaResponseCustomToolCallItem, + type BetaResponseCustomToolCallOutput as BetaResponseCustomToolCallOutput, + type BetaResponseCustomToolCallOutputItem as BetaResponseCustomToolCallOutputItem, + type BetaResponseError as BetaResponseError, + type BetaResponseErrorEvent as BetaResponseErrorEvent, + type BetaResponseFailedEvent as BetaResponseFailedEvent, + type BetaResponseFileSearchCallCompletedEvent as BetaResponseFileSearchCallCompletedEvent, + type BetaResponseFileSearchCallInProgressEvent as BetaResponseFileSearchCallInProgressEvent, + type BetaResponseFileSearchCallSearchingEvent as BetaResponseFileSearchCallSearchingEvent, + type BetaResponseFileSearchToolCall as BetaResponseFileSearchToolCall, + type BetaResponseFormatTextConfig as BetaResponseFormatTextConfig, + type BetaResponseFormatTextJSONSchemaConfig as BetaResponseFormatTextJSONSchemaConfig, + type BetaResponseFunctionCallArgumentsDeltaEvent as BetaResponseFunctionCallArgumentsDeltaEvent, + type BetaResponseFunctionCallArgumentsDoneEvent as BetaResponseFunctionCallArgumentsDoneEvent, + type BetaResponseFunctionCallOutputItem as BetaResponseFunctionCallOutputItem, + type BetaResponseFunctionCallOutputItemList as BetaResponseFunctionCallOutputItemList, + type BetaResponseFunctionShellCallOutputContent as BetaResponseFunctionShellCallOutputContent, + type BetaResponseFunctionShellToolCall as BetaResponseFunctionShellToolCall, + type BetaResponseFunctionShellToolCallOutput as BetaResponseFunctionShellToolCallOutput, + type BetaResponseFunctionToolCall as BetaResponseFunctionToolCall, + type BetaResponseFunctionToolCallItem as BetaResponseFunctionToolCallItem, + type BetaResponseFunctionToolCallOutputItem as BetaResponseFunctionToolCallOutputItem, + type BetaResponseFunctionWebSearch as BetaResponseFunctionWebSearch, + type BetaResponseImageGenCallCompletedEvent as BetaResponseImageGenCallCompletedEvent, + type BetaResponseImageGenCallGeneratingEvent as BetaResponseImageGenCallGeneratingEvent, + type BetaResponseImageGenCallInProgressEvent as BetaResponseImageGenCallInProgressEvent, + type BetaResponseImageGenCallPartialImageEvent as BetaResponseImageGenCallPartialImageEvent, + type BetaResponseInProgressEvent as BetaResponseInProgressEvent, + type BetaResponseIncludable as BetaResponseIncludable, + type BetaResponseIncompleteEvent as BetaResponseIncompleteEvent, + type BetaResponseInjectCreatedEvent as BetaResponseInjectCreatedEvent, + type BetaResponseInjectEvent as BetaResponseInjectEvent, + type BetaResponseInjectFailedEvent as BetaResponseInjectFailedEvent, + type BetaResponseInput as BetaResponseInput, + type BetaResponseInputAudio as BetaResponseInputAudio, + type BetaResponseInputContent as BetaResponseInputContent, + type BetaResponseInputFile as BetaResponseInputFile, + type BetaResponseInputFileContent as BetaResponseInputFileContent, + type BetaResponseInputImage as BetaResponseInputImage, + type BetaResponseInputImageContent as BetaResponseInputImageContent, + type BetaResponseInputItem as BetaResponseInputItem, + type BetaResponseInputMessageContentList as BetaResponseInputMessageContentList, + type BetaResponseInputMessageItem as BetaResponseInputMessageItem, + type BetaResponseInputText as BetaResponseInputText, + type BetaResponseInputTextContent as BetaResponseInputTextContent, + type BetaResponseItem as BetaResponseItem, + type BetaResponseLocalEnvironment as BetaResponseLocalEnvironment, + type BetaResponseMcpCallArgumentsDeltaEvent as BetaResponseMcpCallArgumentsDeltaEvent, + type BetaResponseMcpCallArgumentsDoneEvent as BetaResponseMcpCallArgumentsDoneEvent, + type BetaResponseMcpCallCompletedEvent as BetaResponseMcpCallCompletedEvent, + type BetaResponseMcpCallFailedEvent as BetaResponseMcpCallFailedEvent, + type BetaResponseMcpCallInProgressEvent as BetaResponseMcpCallInProgressEvent, + type BetaResponseMcpListToolsCompletedEvent as BetaResponseMcpListToolsCompletedEvent, + type BetaResponseMcpListToolsFailedEvent as BetaResponseMcpListToolsFailedEvent, + type BetaResponseMcpListToolsInProgressEvent as BetaResponseMcpListToolsInProgressEvent, + type BetaResponseOutputAudio as BetaResponseOutputAudio, + type BetaResponseOutputItem as BetaResponseOutputItem, + type BetaResponseOutputItemAddedEvent as BetaResponseOutputItemAddedEvent, + type BetaResponseOutputItemDoneEvent as BetaResponseOutputItemDoneEvent, + type BetaResponseOutputMessage as BetaResponseOutputMessage, + type BetaResponseOutputRefusal as BetaResponseOutputRefusal, + type BetaResponseOutputText as BetaResponseOutputText, + type BetaResponseOutputTextAnnotationAddedEvent as BetaResponseOutputTextAnnotationAddedEvent, + type BetaResponsePrompt as BetaResponsePrompt, + type BetaResponseQueuedEvent as BetaResponseQueuedEvent, + type BetaResponseReasoningItem as BetaResponseReasoningItem, + type BetaResponseReasoningSummaryPartAddedEvent as BetaResponseReasoningSummaryPartAddedEvent, + type BetaResponseReasoningSummaryPartDoneEvent as BetaResponseReasoningSummaryPartDoneEvent, + type BetaResponseReasoningSummaryTextDeltaEvent as BetaResponseReasoningSummaryTextDeltaEvent, + type BetaResponseReasoningSummaryTextDoneEvent as BetaResponseReasoningSummaryTextDoneEvent, + type BetaResponseReasoningTextDeltaEvent as BetaResponseReasoningTextDeltaEvent, + type BetaResponseReasoningTextDoneEvent as BetaResponseReasoningTextDoneEvent, + type BetaResponseRefusalDeltaEvent as BetaResponseRefusalDeltaEvent, + type BetaResponseRefusalDoneEvent as BetaResponseRefusalDoneEvent, + type BetaResponseStatus as BetaResponseStatus, + type BetaResponseStreamEvent as BetaResponseStreamEvent, + type BetaResponseTextConfig as BetaResponseTextConfig, + type BetaResponseTextDeltaEvent as BetaResponseTextDeltaEvent, + type BetaResponseTextDoneEvent as BetaResponseTextDoneEvent, + type BetaResponseToolSearchCall as BetaResponseToolSearchCall, + type BetaResponseToolSearchOutputItem as BetaResponseToolSearchOutputItem, + type BetaResponseToolSearchOutputItemParam as BetaResponseToolSearchOutputItemParam, + type BetaResponseUsage as BetaResponseUsage, + type BetaResponseWebSearchCallCompletedEvent as BetaResponseWebSearchCallCompletedEvent, + type BetaResponseWebSearchCallInProgressEvent as BetaResponseWebSearchCallInProgressEvent, + type BetaResponseWebSearchCallSearchingEvent as BetaResponseWebSearchCallSearchingEvent, + type BetaResponsesClientEvent as BetaResponsesClientEvent, + type BetaResponsesServerEvent as BetaResponsesServerEvent, + type BetaSkillReference as BetaSkillReference, + type BetaTool as BetaTool, + type BetaToolChoiceAllowed as BetaToolChoiceAllowed, + type BetaToolChoiceApplyPatch as BetaToolChoiceApplyPatch, + type BetaToolChoiceCustom as BetaToolChoiceCustom, + type BetaToolChoiceFunction as BetaToolChoiceFunction, + type BetaToolChoiceMcp as BetaToolChoiceMcp, + type BetaToolChoiceOptions as BetaToolChoiceOptions, + type BetaToolChoiceShell as BetaToolChoiceShell, + type BetaToolChoiceTypes as BetaToolChoiceTypes, + type BetaToolSearchTool as BetaToolSearchTool, + type BetaWebSearchPreviewTool as BetaWebSearchPreviewTool, + type BetaWebSearchTool as BetaWebSearchTool, + type ResponseCreateParams as ResponseCreateParams, + type ResponseCreateParamsNonStreaming as ResponseCreateParamsNonStreaming, + type ResponseCreateParamsStreaming as ResponseCreateParamsStreaming, + type ResponseRetrieveParams as ResponseRetrieveParams, + type ResponseRetrieveParamsNonStreaming as ResponseRetrieveParamsNonStreaming, + type ResponseRetrieveParamsStreaming as ResponseRetrieveParamsStreaming, + type ResponseDeleteParams as ResponseDeleteParams, + type ResponseCancelParams as ResponseCancelParams, + type ResponseCompactParams as ResponseCompactParams, + }; + + export { + InputItems as InputItems, + type BetaResponseItemList as BetaResponseItemList, + type InputItemListParams as InputItemListParams, + }; + + export { + InputTokens as InputTokens, + type InputTokenCountResponse as InputTokenCountResponse, + type InputTokenCountParams as InputTokenCountParams, + }; +} diff --git a/src/resources/beta/responses/ws-base.ts b/src/resources/beta/responses/ws-base.ts new file mode 100644 index 0000000000..7d2ccafd84 --- /dev/null +++ b/src/resources/beta/responses/ws-base.ts @@ -0,0 +1,615 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { ResponsesEmitter, ResponsesStreamMessage, WebSocketError, buildURL } from './internal-base'; +import { InternalEventEmitter } from '../../../core/EventEmitter'; +import { sleep } from '../../../internal/utils/sleep'; +import { type WebSocketLike, ReadyState } from '../../../internal/ws-adapter'; +import { + SendQueue, + flattenRawData, + isRecoverableClose, + type RawWebSocketData, + type ReconnectingEvent, + type ReconnectingOverrides, + type UnsentMessage, +} from '../../../internal/ws'; +import * as ResponsesAPI from './responses'; +import { OpenAI } from '../../../client'; +import { OpenAIError } from '../../../core/error'; + +export interface ResponsesWSReconnectOptions { + /** + * Called before each reconnect attempt. Return an object with + * `parameters` to override query parameters for the next connection. + */ + onReconnecting( + event: ReconnectingEvent>, + ): ReconnectingOverrides> | void; + + /** + * Maximum number of reconnection attempts. Default: 5. + * Set to 0 to disable reconnection entirely. + */ + maxRetries?: number; + + /** + * Initial backoff delay in milliseconds. Default: 500. + */ + initialDelay?: number; + + /** + * Maximum backoff delay in milliseconds. Default: 8000. + */ + maxDelay?: number; +} + +export interface ResponsesWSBaseOptions { + /** + * Options for automatic reconnection on recoverable close codes. + * Automatic reconnection is only enabled when this has a non-null value. + */ + reconnect?: ResponsesWSReconnectOptions | null | undefined; + + /** + * Maximum size of the outgoing message queue in bytes. + * Messages queued while the socket is connecting or reconnecting are held + * in memory up to this limit. Once the limit is reached, new messages are + * discarded and an `error` event is emitted. + * Default: 1 MB + */ + maxQueueSize?: number | undefined; +} + +export abstract class ResponsesWSBase extends ResponsesEmitter { + url!: URL; + socket!: TSocket; + + protected _client: OpenAI; + protected _parameters: Record | null | undefined; + private _reconnectOptions: ResponsesWSReconnectOptions | null; + private _sendQueue: SendQueue; + private _isReconnecting: boolean = false; + private _intentionallyClosed = false; + private _closeCode: number = 1000; + private _closeReason: string = 'OK'; + private _lastCloseCode: number = 1006; + private _lastCloseReason: string = ''; + + // Necessary to keep the public event interface clean while we manage reconnecting + private _internalEvents = new InternalEventEmitter<{ + socketSwap: (oldSocket: TSocket, newSocket: TSocket) => void; + reconnecting: (event: ReconnectingEvent>) => void; + reconnected: () => void; + close: ( + code: number, + reason: string, + unsent: UnsentMessage[], + ) => void; + }>(); + + constructor(client: OpenAI, options?: ResponsesWSBaseOptions | undefined) { + super(); + this._client = client; + this._parameters = undefined; + this._reconnectOptions = options?.reconnect ?? null; + this._sendQueue = new SendQueue(options?.maxQueueSize); + } + + /** Establishes the initial WebSocket connection. */ + protected _connectInitial(): void { + this.url = buildURL(this._client, {}); + this.socket = this._connect(); + } + + /** Creates a platform-specific WebSocket for the given URL and auth headers. */ + protected abstract _createSocket(url: URL, authHeaders: Record): TSocket; + + send(event: ResponsesAPI.BetaResponsesClientEvent) { + if (!this.socket) { + throw new OpenAIError('Internal error: failed to initialize socket. Please report this issue.'); + } + + if (this._isReconnecting || this.socket.readyState === ReadyState.CONNECTING) { + if (!this._sendQueue.enqueue(event)) { + this._onError(null, 'send queue is full, message discarded', undefined); + } + return; + } + if (this.socket.readyState !== ReadyState.OPEN) { + this._onError(null, 'cannot send on a closed WebSocket', undefined); + return; + } + try { + this.socket.send(JSON.stringify(event)); + } catch (err) { + this._onError(null, 'could not send data', err); + } + } + + sendRaw(data: RawWebSocketData) { + if (!this.socket) { + throw new OpenAIError('Internal error: failed to initialize socket. Please report this issue.'); + } + + if (this._isReconnecting || this.socket.readyState === ReadyState.CONNECTING) { + if (!this._sendQueue.enqueueRaw(data)) { + this._onError(null, 'send queue is full, message discarded', undefined); + } + return; + } + if (this.socket.readyState !== ReadyState.OPEN) { + this._onError(null, 'cannot send on a closed WebSocket', undefined); + return; + } + try { + this.socket.send(flattenRawData(data)); + } catch (err) { + this._onError(null, 'could not send data', err); + } + } + + close(props?: { code: number; reason: string }) { + if (!this.socket) { + throw new OpenAIError('Internal error: failed to initialize socket. Please report this issue.'); + } + + this._intentionallyClosed = true; + this._closeCode = props?.code ?? 1000; + this._closeReason = props?.reason ?? 'OK'; + try { + this.socket.close(this._closeCode, this._closeReason); + } catch (err) { + this._onError(null, 'could not close the connection', err); + } + } + + /** + * Returns an async iterator over WebSocket lifecycle and message events, + * providing an alternative to the event-based `.on()` API. + * The iterator will exit if the socket closes but exiting the iterator + * does not close the socket. + * + * @example + * ```ts + * for await (const event of client.stream()) { + * switch (event.type) { + * case 'message': + * console.log('received:', event.message); + * break; + * case 'error': + * console.error(event.error); + * break; + * case 'close': + * console.log('connection closed'); + * break; + * } + * } + * ``` + */ + stream(): AsyncIterableIterator { + return this[Symbol.asyncIterator](); + } + + [Symbol.asyncIterator](): AsyncIterableIterator { + if (!this.socket) { + throw new OpenAIError('Internal error: failed to initialize socket. Please report this issue.'); + } + + // Two-queue async iterator: `queue` buffers incoming messages, + // `resolvers` buffers waiting next() calls. A push wakes the + // oldest next(); a next() drains the oldest message. + const queue: ResponsesStreamMessage[] = []; + const resolvers: (() => void)[] = []; + let done = false; + let currentSocket = this.socket; + + const push = (msg: ResponsesStreamMessage) => { + queue.push(msg); + resolvers.shift()?.(); + }; + + const onEvent = (event: ResponsesAPI.BetaResponsesServerEvent) => { + if (event.type === 'error') return; // handled by onEmitterError + push({ type: 'message', message: event }); + }; + + const onRaw = (data: RawWebSocketData) => { + push({ type: 'raw', data }); + }; + + // All errors (API + socket) funnel through _onError → 'error' event + const onEmitterError = (err: WebSocketError) => { + push({ type: 'error', error: err }); + }; + + const onOpen = () => { + push({ type: 'open' }); + }; + + const onReconnecting = (evt: ReconnectingEvent>) => { + push({ type: 'reconnecting', reconnect: evt }); + }; + + const onReconnected = () => { + push({ type: 'reconnected' }); + }; + + const flushResolvers = () => { + for (let resolver = resolvers.shift(); resolver; resolver = resolvers.shift()) { + resolver(); + } + }; + + const onClose = ( + code: number, + reason: string, + unsent: UnsentMessage[], + ) => { + push({ type: 'close', code, reason, unsent }); + done = true; + flushResolvers(); + cleanup(); + }; + + const onSocketSwap = (oldSocket: TSocket, newSocket: TSocket) => { + oldSocket.off('open', onOpen); + newSocket.on('open', onOpen); + currentSocket = newSocket; + }; + + const cleanup = () => { + this.off('event', onEvent); + this.off('raw', onRaw); + this.off('error', onEmitterError); + currentSocket.off('open', onOpen); + this._internalEvents.off('close', onClose); + this._internalEvents.off('socketSwap', onSocketSwap); + this._internalEvents.off('reconnecting', onReconnecting); + this._internalEvents.off('reconnected', onReconnected); + }; + + this.on('event', onEvent); + this.on('raw', onRaw); + this.on('error', onEmitterError); + this.socket.on('open', onOpen); + this._internalEvents.on('close', onClose); + this._internalEvents.on('socketSwap', onSocketSwap); + this._internalEvents.on('reconnecting', onReconnecting); + this._internalEvents.on('reconnected', onReconnected); + + if (this._isReconnecting) { + // A reconnect is already in flight. The socket may be CLOSED but the + // instance is still alive. Emit 'reconnecting' so the iterator stays + // open and receives the upcoming reconnected/message events. + push({ + type: 'reconnecting', + reconnect: { attempt: 0, maxAttempts: 0, delay: 0, closeCode: 0, parameters: undefined }, + }); + } else { + switch (this.socket.readyState) { + case ReadyState.CONNECTING: + push({ type: 'connecting' }); + break; + case ReadyState.OPEN: + push({ type: 'open' }); + break; + case ReadyState.CLOSING: + push({ type: 'closing' }); + break; + case ReadyState.CLOSED: + push({ + type: 'close', + code: this._lastCloseCode, + reason: this._lastCloseReason, + unsent: this._sendQueue.drain(), + }); + done = true; + cleanup(); + break; + } + } + + const resolve = (res: (value: IteratorResult) => void) => { + if (queue.length > 0) { + res({ value: queue.shift()!, done: false }); + } else if (done) { + res({ value: undefined, done: true }); + } else { + return false; + } + return true; + }; + + const next = (): Promise> => + new Promise((res) => { + if (resolve(res)) return; + resolvers.push(() => { + resolve(res); + }); + }); + + return { + next, + return: (): Promise> => { + done = true; + cleanup(); + flushResolvers(); + return Promise.resolve({ value: undefined, done: true }); + }, + [Symbol.asyncIterator]() { + return this; + }, + }; + } + + private _connect(): TSocket { + this.url = buildURL(this._client, this._parameters ?? {}); + + const socket = this._createSocket(this.url, this._authHeaders()); + + socket.on('message', (data: string | ArrayBuffer | ArrayBufferView, isBinary: boolean) => { + if (isBinary) { + this._emit('raw', data); + return; + } + + // Coerce to string in case the adapter delivers a typed-array for text frames. + const text = typeof data === 'string' ? data : String(data); + + let event: ResponsesAPI.BetaResponsesServerEvent; + try { + event = JSON.parse(text) as ResponsesAPI.BetaResponsesServerEvent; + } catch { + this._emit('raw', data); + return; + } + + this._emit('event', event); + + if (event.type === 'error') { + this._onError(event); + } else { + // @ts-ignore TS isn't smart enough to get the relationship right here + this._emit(event.type, event); + } + }); + + socket.on('error', (err: Error) => { + // Suppress transient errors during reconnection — the retry loop + // already handles them and will surface a close if retries exhaust. + if (this._isReconnecting) return; + this._onError(null, err.message, err); + }); + + socket.on('open', () => { + this._flushSendQueue(); + }); + + socket.on('close', (code: number, reason: string) => { + // Ignore close events from superseded sockets — a stale socket's + // late close must not kick off a second reconnect loop. + if (socket !== this.socket) return; + if (!this._intentionallyClosed && this._canReconnect(code)) { + this._reconnect(code); + } else if (!this._isReconnecting) { + this._emitPermanentClose(code, reason); + } + }); + + return socket; + } + + // Reconnect is opt-in via onReconnecting so callers can pass + // state (e.g. session IDs) into the new connection. + private _canReconnect(code: number): boolean { + if (this._intentionallyClosed) return false; + if (!this._reconnectOptions) return false; + if (this._reconnectOptions.maxRetries === 0) return false; + if (!this._reconnectOptions.onReconnecting) return false; + return isRecoverableClose(code); + } + + private async _reconnect(closeCode: number): Promise { + if (!this.socket) { + throw new OpenAIError('Internal error: failed to initialize socket. Please report this issue.'); + } + + if (this._isReconnecting || !this._reconnectOptions) return; + this._isReconnecting = true; + + const maxRetries = this._reconnectOptions.maxRetries ?? 5; + const initialDelay = this._reconnectOptions.initialDelay ?? 500; + const maxDelay = this._reconnectOptions.maxDelay ?? 8000; + + for (let attempt = 1; attempt <= maxRetries; attempt++) { + if (!this._canReconnect(closeCode)) { + this._isReconnecting = false; + if (!this._intentionallyClosed) { + this._onError( + null, + `WebSocket reconnect aborted: non-recoverable close code ${closeCode}`, + undefined, + ); + } + this._emitPermanentClose( + this._intentionallyClosed ? this._closeCode : closeCode, + this._intentionallyClosed ? this._closeReason : 'reconnect aborted', + ); + return; + } + + const baseDelay = Math.min(initialDelay * Math.pow(2, attempt - 1), maxDelay); + // Jitter: rand [0.75, 1.0] to spread out connection attempts without over-delaying + const jitter = 0.75 + Math.random() * 0.25; + const actualDelay = Math.round(baseDelay * jitter); + + let reconnectingEvent: ReconnectingEvent> = { + attempt, + maxAttempts: maxRetries, + delay: actualDelay, + closeCode, + parameters: this._parameters ? { ...this._parameters } : undefined, + }; + + let overrides: ReconnectingOverrides> | void; + try { + overrides = this._reconnectOptions.onReconnecting(reconnectingEvent); + } catch (err) { + this._isReconnecting = false; + this._onError(null, 'onReconnecting callback threw', err); + this._emitPermanentClose(closeCode, 'onReconnecting callback threw'); + return; + } + + if (overrides && 'abort' in overrides && overrides.abort) { + this._isReconnecting = false; + this._emitPermanentClose(closeCode, 'reconnect aborted by handler'); + return; + } + + if (overrides && 'parameters' in overrides) { + this._parameters = overrides.parameters; + reconnectingEvent = { ...reconnectingEvent, parameters: this._parameters }; + } + + try { + this._emit('reconnecting', reconnectingEvent); + } catch (err) { + this._onError(null, 'onReconnecting callback threw', err); + } + this._internalEvents._emit('reconnecting', reconnectingEvent); + + if (!this._canReconnect(closeCode)) { + this._isReconnecting = false; + if (!this._intentionallyClosed) { + this._onError( + null, + `WebSocket reconnect aborted: non-recoverable close code ${closeCode}`, + undefined, + ); + } + this._emitPermanentClose( + this._intentionallyClosed ? this._closeCode : closeCode, + this._intentionallyClosed ? this._closeReason : 'reconnect aborted', + ); + return; + } + + await sleep(actualDelay); + + if (!this._canReconnect(closeCode)) { + this._isReconnecting = false; + if (!this._intentionallyClosed) { + this._onError( + null, + `WebSocket reconnect aborted: non-recoverable close code ${closeCode}`, + undefined, + ); + } + this._emitPermanentClose( + this._intentionallyClosed ? this._closeCode : closeCode, + this._intentionallyClosed ? this._closeReason : 'reconnect aborted', + ); + return; + } + + let closeCodePromise: Promise | undefined; + try { + const oldSocket = this.socket; + this.socket = this._connect(); + // Registered synchronously after _connect() and before any + // await so the code is captured even when ws emits 'close' + // in the same tick as 'error' (e.g. abortHandshake). + closeCodePromise = new Promise((resolve) => { + this.socket.once('close', resolve); + }); + + await this._awaitOpen(this.socket); + + this._internalEvents._emit('socketSwap', oldSocket, this.socket); + this._isReconnecting = false; + this._flushSendQueue(); + this._emit('reconnected'); + this._internalEvents._emit('reconnected'); + return; + } catch { + if (closeCodePromise) { + // ws may emit 'error' before 'close', so await the code + // rather than reading it synchronously. + closeCode = await closeCodePromise; + } + } + } + + // All retries exhausted — surface an error so consumers can + // distinguish retry failure from a clean close. + this._isReconnecting = false; + this._onError( + null, + `WebSocket reconnect failed after ${maxRetries} attempts (close code: ${closeCode})`, + undefined, + ); + this._emitPermanentClose(closeCode, `reconnect failed after ${maxRetries} attempts`); + } + + /** + * Resolves once the socket is open, rejects if it errors or closes first + */ + private _awaitOpen(socket: TSocket): Promise { + return new Promise((resolve, reject) => { + const cleanup = () => { + socket.off('open', onOpen); + socket.off('error', onError); + socket.off('close', onFail); + }; + const onOpen = () => { + cleanup(); + resolve(); + }; + const onError = (err: Error) => { + cleanup(); + reject(err); + }; + const onFail = () => { + cleanup(); + reject(new Error('socket closed before open')); + }; + socket.once('open', onOpen); + socket.once('error', onError); + socket.once('close', onFail); + }); + } + + private _flushSendQueue(): void { + if (!this.socket) { + throw new OpenAIError('Internal error: failed to initialize socket. Please report this issue.'); + } + + try { + this._sendQueue.flush((data) => this.socket.send(flattenRawData(data))); + } catch (err) { + this._onError(null, 'could not send queued data', err); + } + } + + /** + * Emits the public `close` event with unsent messages and the internal + * `close` event used by the async iterator. + */ + private _emitPermanentClose(code: number, reason: string): void { + this._lastCloseCode = code; + this._lastCloseReason = reason; + const unsent = this._sendQueue.drain(); + // Internal close fires first so the async iterator is guaranteed to + // terminate even if a public 'close' listener throws. + this._internalEvents._emit('close', code, reason, unsent); + this._emit('close', code, reason, unsent); + } + + protected _authHeaders(): Record { + if (this._client.apiKey) { + return { Authorization: `Bearer ${this._client.apiKey}` }; + } + return {}; + } +} diff --git a/src/resources/beta/responses/ws.ts b/src/resources/beta/responses/ws.ts new file mode 100644 index 0000000000..d5e90efbe5 --- /dev/null +++ b/src/resources/beta/responses/ws.ts @@ -0,0 +1,38 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import * as WS from 'ws'; +import { NodeWebSocket } from '../../../internal/ws-adapter-node'; +import { ResponsesWSBase, type ResponsesWSBaseOptions } from './ws-base'; +import { OpenAI } from '../../../client'; + +export type { ResponsesWSReconnectOptions } from './ws-base'; + +export interface ResponsesWSClientOptions extends WS.ClientOptions, ResponsesWSBaseOptions {} + +export class ResponsesWS extends ResponsesWSBase { + private _wsOptions: WS.ClientOptions | null | undefined; + + constructor(client: OpenAI, options?: ResponsesWSClientOptions | null | undefined) { + if (!WS?.WebSocket) { + throw new Error( + 'ResponsesWS from "openai/resources/beta/responses/ws" requires the "ws" package but it could not be loaded.', + ); + } + + const { reconnect, maxQueueSize, ...wsOptions } = options ?? {}; + super(client, { reconnect, maxQueueSize }); + this._wsOptions = wsOptions; + this._connectInitial(); + } + + protected _createSocket(url: URL, authHeaders: Record): NodeWebSocket { + const ws = new WS.WebSocket(url, { + ...this._wsOptions, + headers: { + ...authHeaders, + ...this._wsOptions?.headers, + }, + }); + return new NodeWebSocket(ws); + } +} diff --git a/src/resources/beta/threads/runs/runs.ts b/src/resources/beta/threads/runs/runs.ts index 5b70d0e1dc..53e4846ff5 100644 --- a/src/resources/beta/threads/runs/runs.ts +++ b/src/resources/beta/threads/runs/runs.ts @@ -733,19 +733,12 @@ export interface RunCreateParamsBase { parallel_tool_calls?: boolean; /** - * Body param: Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * Body param: 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. */ reasoning_effort?: Shared.ReasoningEffort | null; diff --git a/src/resources/chat/completions/completions.ts b/src/resources/chat/completions/completions.ts index 05cae402ec..73eb26021c 100644 --- a/src/resources/chat/completions/completions.ts +++ b/src/resources/chat/completions/completions.ts @@ -1129,6 +1129,13 @@ export namespace ChatCompletionContentPart { * The type of the content part. Always `file`. */ type: 'file'; + + /** + * Marks the exact end of a reusable 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_cache_breakpoint?: File.PromptCacheBreakpoint; } export namespace File { @@ -1149,6 +1156,18 @@ export namespace ChatCompletionContentPart { */ filename?: string; } + + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } } } @@ -1162,6 +1181,13 @@ export interface ChatCompletionContentPartImage { * The type of the content part. */ type: 'image_url'; + + /** + * Marks the exact end of a reusable 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_cache_breakpoint?: ChatCompletionContentPartImage.PromptCacheBreakpoint; } export namespace ChatCompletionContentPartImage { @@ -1177,6 +1203,18 @@ export namespace ChatCompletionContentPartImage { */ detail?: 'auto' | 'low' | '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. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } } /** @@ -1189,6 +1227,13 @@ export interface ChatCompletionContentPartInputAudio { * The type of the content part. Always `input_audio`. */ type: 'input_audio'; + + /** + * Marks the exact end of a reusable 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_cache_breakpoint?: ChatCompletionContentPartInputAudio.PromptCacheBreakpoint; } export namespace ChatCompletionContentPartInputAudio { @@ -1203,6 +1248,18 @@ export namespace ChatCompletionContentPartInputAudio { */ format: 'wav' | 'mp3'; } + + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } } export interface ChatCompletionContentPartRefusal { @@ -1231,6 +1288,27 @@ export interface ChatCompletionContentPartText { * The type of the content part. */ type: '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. + */ + prompt_cache_breakpoint?: ChatCompletionContentPartText.PromptCacheBreakpoint; +} + +export namespace ChatCompletionContentPartText { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } } /** @@ -2046,11 +2124,29 @@ export interface ChatCompletionCreateParamsBase { prompt_cache_key?: string; /** + * 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. + */ + prompt_cache_options?: ChatCompletionCreateParams.PromptCacheOptions; + + /** + * @deprecated 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). - * For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + * 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: @@ -2062,19 +2158,12 @@ export interface ChatCompletionCreateParamsBase { prompt_cache_retention?: 'in_memory' | '24h' | null; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; @@ -2276,6 +2365,74 @@ export namespace ChatCompletionCreateParams { * 'omni-moderation-latest'. */ model: string; + + /** + * The policy to apply to moderated response input and output. + */ + policy?: Moderation.Policy | null; + } + + export namespace Moderation { + /** + * The policy to apply to moderated response input and output. + */ + export interface Policy { + /** + * The moderation policy for the response input. + */ + input?: Policy.Input | null; + + /** + * The moderation policy for the response output. + */ + output?: Policy.Output | null; + } + + export namespace Policy { + /** + * The moderation policy for the response input. + */ + export interface Input { + mode: 'score' | 'block'; + } + + /** + * The moderation policy for the response output. + */ + export interface Output { + mode: 'score' | 'block'; + } + } + } + + /** + * 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. + */ + export interface PromptCacheOptions { + /** + * 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. + */ + mode?: 'implicit' | 'explicit'; + + /** + * 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. + */ + ttl?: '30m'; } /** diff --git a/src/resources/completions.ts b/src/resources/completions.ts index 5ae88abe85..30d6842c3d 100644 --- a/src/resources/completions.ts +++ b/src/resources/completions.ts @@ -185,6 +185,11 @@ export namespace CompletionUsage { */ audio_tokens?: number; + /** + * The unadjusted number of prompt tokens written to cache. + */ + cache_write_tokens?: number; + /** * Cached tokens present in the prompt. */ diff --git a/src/resources/conversations/conversations.ts b/src/resources/conversations/conversations.ts index eb0243e653..c5097cc86a 100644 --- a/src/resources/conversations/conversations.ts +++ b/src/resources/conversations/conversations.ts @@ -95,6 +95,27 @@ export interface ComputerScreenshotContent { * to `computer_screenshot`. */ type: 'computer_screenshot'; + + /** + * Marks the exact end of a reusable 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_cache_breakpoint?: ComputerScreenshotContent.PromptCacheBreakpoint; +} + +export namespace ComputerScreenshotContent { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } } export interface Conversation { diff --git a/src/resources/conversations/items.ts b/src/resources/conversations/items.ts index 0ef3f3ac81..8d5be1f182 100644 --- a/src/resources/conversations/items.ts +++ b/src/resources/conversations/items.ts @@ -100,6 +100,8 @@ export type ConversationItem = | ResponsesAPI.ResponseToolSearchOutputItem | ConversationItem.AdditionalTools | ResponsesAPI.ResponseReasoningItem + | ConversationItem.Program + | ConversationItem.ProgramOutput | ResponsesAPI.ResponseCompactionItem | ResponsesAPI.ResponseCodeInterpreterToolCall | ConversationItem.LocalShellCall @@ -163,6 +165,60 @@ export namespace ConversationItem { type: 'additional_tools'; } + export interface Program { + /** + * The unique ID of the program item. + */ + id: string; + + /** + * The stable call ID of the program item. + */ + call_id: string; + + /** + * The JavaScript source executed by programmatic tool calling. + */ + code: string; + + /** + * Opaque program replay fingerprint that must be round-tripped. + */ + fingerprint: string; + + /** + * The type of the item. Always `program`. + */ + type: 'program'; + } + + export interface ProgramOutput { + /** + * The unique ID of the program output item. + */ + id: string; + + /** + * The call ID of the program item. + */ + call_id: string; + + /** + * The result produced by the program item. + */ + result: string; + + /** + * The terminal status of the program output item. + */ + status: 'completed' | 'incomplete'; + + /** + * The type of the item. Always `program_output`. + */ + type: 'program_output'; + } + /** * A tool call to run a command on the local shell. */ diff --git a/src/resources/evals/runs/runs.ts b/src/resources/evals/runs/runs.ts index b8673c5ce7..eebd313540 100644 --- a/src/resources/evals/runs/runs.ts +++ b/src/resources/evals/runs/runs.ts @@ -305,19 +305,12 @@ export namespace CreateEvalCompletionsRunDataSource { max_completion_tokens?: number; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; @@ -614,19 +607,12 @@ export namespace RunCreateResponse { model?: string | null; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; @@ -767,19 +753,12 @@ export namespace RunCreateResponse { max_completion_tokens?: number; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; @@ -1117,19 +1096,12 @@ export namespace RunRetrieveResponse { model?: string | null; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; @@ -1270,19 +1242,12 @@ export namespace RunRetrieveResponse { max_completion_tokens?: number; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; @@ -1617,19 +1582,12 @@ export namespace RunListResponse { model?: string | null; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; @@ -1770,19 +1728,12 @@ export namespace RunListResponse { max_completion_tokens?: number; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; @@ -2128,19 +2079,12 @@ export namespace RunCancelResponse { model?: string | null; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; @@ -2281,19 +2225,12 @@ export namespace RunCancelResponse { max_completion_tokens?: number; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; @@ -2578,19 +2515,12 @@ export namespace RunCreateParams { model?: string | null; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; @@ -2731,19 +2661,12 @@ export namespace RunCreateParams { max_completion_tokens?: number; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; diff --git a/src/resources/graders/grader-models.ts b/src/resources/graders/grader-models.ts index fc4166b98c..9392dc45bf 100644 --- a/src/resources/graders/grader-models.ts +++ b/src/resources/graders/grader-models.ts @@ -331,19 +331,12 @@ export namespace ScoreModelGrader { max_completions_tokens?: number | null; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ reasoning_effort?: Shared.ReasoningEffort | null; diff --git a/src/resources/realtime/calls.ts b/src/resources/realtime/calls.ts index f7d25c38ca..21eac5a963 100644 --- a/src/resources/realtime/calls.ts +++ b/src/resources/realtime/calls.ts @@ -135,6 +135,8 @@ export interface CallAcceptParams { | 'gpt-realtime' | 'gpt-realtime-1.5' | 'gpt-realtime-2' + | 'gpt-realtime-2.1' + | 'gpt-realtime-2.1-mini' | 'gpt-realtime-2025-08-28' | 'gpt-4o-realtime-preview' | 'gpt-4o-realtime-preview-2024-10-01' diff --git a/src/resources/realtime/client-secrets.ts b/src/resources/realtime/client-secrets.ts index c81649c82a..c0fb133c1a 100644 --- a/src/resources/realtime/client-secrets.ts +++ b/src/resources/realtime/client-secrets.ts @@ -107,6 +107,8 @@ export interface RealtimeSessionCreateResponse { | 'gpt-realtime' | 'gpt-realtime-1.5' | 'gpt-realtime-2' + | 'gpt-realtime-2.1' + | 'gpt-realtime-2.1-mini' | 'gpt-realtime-2025-08-28' | 'gpt-4o-realtime-preview' | 'gpt-4o-realtime-preview-2024-10-01' @@ -407,6 +409,11 @@ export namespace RealtimeSessionCreateResponse { */ type: 'mcp'; + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + /** * List of allowed tool names or a filter object. */ diff --git a/src/resources/realtime/realtime.ts b/src/resources/realtime/realtime.ts index 4a4ee23a03..0ea6e524d8 100644 --- a/src/resources/realtime/realtime.ts +++ b/src/resources/realtime/realtime.ts @@ -2222,6 +2222,11 @@ export interface RealtimeResponseCreateMcpTool { */ type: 'mcp'; + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + /** * List of allowed tool names or a filter object. */ @@ -3146,6 +3151,8 @@ export interface RealtimeSessionCreateRequest { | 'gpt-realtime' | 'gpt-realtime-1.5' | 'gpt-realtime-2' + | 'gpt-realtime-2.1' + | 'gpt-realtime-2.1-mini' | 'gpt-realtime-2025-08-28' | 'gpt-4o-realtime-preview' | 'gpt-4o-realtime-preview-2024-10-01' @@ -3269,6 +3276,11 @@ export namespace RealtimeToolsConfigUnion { */ type: 'mcp'; + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + /** * List of allowed tool names or a filter object. */ diff --git a/src/resources/responses/input-tokens.ts b/src/resources/responses/input-tokens.ts index 7aebb94c91..38fff3772d 100644 --- a/src/resources/responses/input-tokens.ts +++ b/src/resources/responses/input-tokens.ts @@ -112,6 +112,7 @@ export interface InputTokenCountParams { | ResponsesAPI.ToolChoiceFunction | ResponsesAPI.ToolChoiceMcp | ResponsesAPI.ToolChoiceCustom + | InputTokenCountParams.SpecificProgrammaticToolCallingParam | ResponsesAPI.ToolChoiceApplyPatch | ResponsesAPI.ToolChoiceShell | null; @@ -166,6 +167,13 @@ export namespace InputTokenCountParams { */ verbosity?: 'low' | 'medium' | 'high' | null; } + + export interface SpecificProgrammaticToolCallingParam { + /** + * The tool to call. Always `programmatic_tool_calling`. + */ + type: 'programmatic_tool_calling'; + } } export declare namespace InputTokens { diff --git a/src/resources/responses/responses.ts b/src/resources/responses/responses.ts index a4fdb1a152..5f6aa6ac92 100644 --- a/src/resources/responses/responses.ts +++ b/src/resources/responses/responses.ts @@ -43,6 +43,8 @@ export type ParsedResponseOutputItem = | ResponseFunctionWebSearch | ResponseComputerToolCall | ResponseComputerToolCallOutputItem + | ResponseOutputItem.Program + | ResponseOutputItem.ProgramOutput | ResponseToolSearchCall | ResponseToolSearchOutputItem | ResponseOutputItem.AdditionalTools @@ -235,7 +237,7 @@ export class Responses extends APIResource { * @example * ```ts * const compactedResponse = await client.responses.compact({ - * model: 'gpt-5.4', + * model: 'gpt-5.6-sol', * }); * ``` */ @@ -254,6 +256,11 @@ export interface ApplyPatchTool { * The type of the tool. Always `apply_patch`. */ type: 'apply_patch'; + + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; } export interface CompactedResponse { @@ -659,6 +666,11 @@ export interface CustomTool { */ type: 'custom'; + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + /** * Whether this tool should be deferred and discovered via tool search. */ @@ -794,6 +806,11 @@ export interface FunctionShellTool { */ type: 'shell'; + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + environment?: ContainerAuto | LocalEnvironment | ContainerReference | null; } @@ -814,7 +831,7 @@ export interface FunctionTool { parameters: { [key: string]: unknown } | null; /** - * Whether to enforce strict parameter validation. Default `true`. + * Whether strict parameter validation is enforced for this function tool. */ strict: boolean | null; @@ -823,6 +840,11 @@ export interface FunctionTool { */ type: 'function'; + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + /** * Whether this function is deferred and loaded via tool search. */ @@ -833,6 +855,12 @@ export interface FunctionTool { * call the function. */ description?: string | null; + + /** + * A JSON schema object describing the JSON value encoded in string outputs for + * this function. + */ + output_schema?: { [key: string]: unknown } | null; } export interface InlineSkill { @@ -937,6 +965,11 @@ export namespace NamespaceTool { type: 'function'; + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + /** * Whether this function should be deferred and discovered via tool search. */ @@ -944,8 +977,19 @@ export namespace NamespaceTool { description?: string | null; + /** + * A JSON Schema describing the JSON value encoded in string outputs for this + * function tool. This does not describe content-array outputs. + */ + output_schema?: { [key: string]: unknown } | null; + parameters?: unknown | null; + /** + * 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. + */ strict?: boolean | null; } } @@ -1042,6 +1086,7 @@ export interface Response { | ToolChoiceFunction | ToolChoiceMcp | ToolChoiceCustom + | Response.SpecificProgrammaticToolCallingParam | ToolChoiceApplyPatch | ToolChoiceShell; @@ -1130,11 +1175,22 @@ export interface Response { prompt_cache_key?: string; /** + * The prompt-caching options that were applied to the response. Supported for + * `gpt-5.6` and later models. + */ + prompt_cache_options?: Response.PromptCacheOptions; + + /** + * @deprecated 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). - * For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + * 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: @@ -1243,6 +1299,13 @@ export namespace Response { reason?: 'max_output_tokens' | 'content_filter'; } + export interface SpecificProgrammaticToolCallingParam { + /** + * The tool to call. Always `programmatic_tool_calling`. + */ + type: 'programmatic_tool_calling'; + } + /** * The conversation that this response belonged to. Input items and output items * from this response were automatically added to this conversation. @@ -1385,6 +1448,22 @@ export namespace Response { type: 'error'; } } + + /** + * The prompt-caching options that were applied to the response. Supported for + * `gpt-5.6` and later models. + */ + export interface PromptCacheOptions { + /** + * Whether implicit prompt-cache breakpoints were enabled. + */ + mode: 'implicit' | 'explicit'; + + /** + * The minimum lifetime applied to each cache breakpoint. + */ + ttl: '30m'; + } } /** @@ -1421,6 +1500,11 @@ export interface ResponseApplyPatchToolCall { */ type: 'apply_patch_call'; + /** + * The execution context that produced this tool call. + */ + caller?: ResponseApplyPatchToolCall.Direct | ResponseApplyPatchToolCall.Program | null; + /** * The ID of the entity that created this tool call. */ @@ -1482,6 +1566,19 @@ export namespace ResponseApplyPatchToolCall { */ type: 'update_file'; } + + export interface Direct { + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + type: 'program'; + } } /** @@ -1509,6 +1606,11 @@ export interface ResponseApplyPatchToolCallOutput { */ type: 'apply_patch_call_output'; + /** + * The execution context that produced this tool call. + */ + caller?: ResponseApplyPatchToolCallOutput.Direct | ResponseApplyPatchToolCallOutput.Program | null; + /** * The ID of the entity that created this tool call output. */ @@ -1520,6 +1622,21 @@ export interface ResponseApplyPatchToolCallOutput { output?: string | null; } +export namespace ResponseApplyPatchToolCallOutput { + export interface Direct { + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + type: 'program'; + } +} + /** * Emitted when there is a partial audio response. */ @@ -2445,12 +2562,32 @@ export interface ResponseCustomToolCall { */ id?: string; + /** + * The execution context that produced this tool call. + */ + caller?: ResponseCustomToolCall.Direct | ResponseCustomToolCall.Program | null; + /** * The namespace of the custom tool being called. */ namespace?: string; } +export namespace ResponseCustomToolCall { + export interface Direct { + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + type: 'program'; + } +} + /** * Event representing a delta (partial update) to the input of a custom tool call. */ @@ -2556,6 +2693,32 @@ export interface ResponseCustomToolCallOutput { * The unique ID of the custom tool call output in the OpenAI platform. */ id?: string; + + /** + * The execution context that produced this tool call. + */ + caller?: ResponseCustomToolCallOutput.Direct | ResponseCustomToolCallOutput.Program | null; +} + +export namespace ResponseCustomToolCallOutput { + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } } /** @@ -2590,6 +2753,7 @@ export interface ResponseError { | 'server_error' | 'rate_limit_exceeded' | 'invalid_prompt' + | 'bio_policy' | 'vector_store_timeout' | 'invalid_image' | 'invalid_image_format' @@ -3020,6 +3184,11 @@ export interface ResponseFunctionShellToolCall { */ type: 'shell_call'; + /** + * The execution context that produced this tool call. + */ + caller?: ResponseFunctionShellToolCall.Direct | ResponseFunctionShellToolCall.Program | null; + /** * The ID of the entity that created this tool call. */ @@ -3043,6 +3212,19 @@ export namespace ResponseFunctionShellToolCall { */ timeout_ms: number | null; } + + export interface Direct { + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + type: 'program'; + } } /** @@ -3082,6 +3264,11 @@ export interface ResponseFunctionShellToolCallOutput { */ type: 'shell_call_output'; + /** + * The execution context that produced this tool call. + */ + caller?: ResponseFunctionShellToolCallOutput.Direct | ResponseFunctionShellToolCallOutput.Program | null; + /** * The identifier of the actor that created the item. */ @@ -3141,6 +3328,19 @@ export namespace ResponseFunctionShellToolCallOutput { type: 'exit'; } } + + export interface Direct { + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + type: 'program'; + } } /** @@ -3174,6 +3374,11 @@ export interface ResponseFunctionToolCall { */ id?: string; + /** + * The execution context that produced this tool call. + */ + caller?: ResponseFunctionToolCall.Direct | ResponseFunctionToolCall.Program | null; + /** * The namespace of the function to run. */ @@ -3186,6 +3391,21 @@ export interface ResponseFunctionToolCall { status?: 'in_progress' | 'completed' | 'incomplete'; } +export namespace ResponseFunctionToolCall { + export interface Direct { + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + type: 'program'; + } +} + /** * A tool call to run a function. See the * [function calling guide](https://platform.openai.com/docs/guides/function-calling) @@ -3237,12 +3457,38 @@ export interface ResponseFunctionToolCallOutputItem { */ type: 'function_call_output'; + /** + * The execution context that produced this tool call. + */ + caller?: ResponseFunctionToolCallOutputItem.Direct | ResponseFunctionToolCallOutputItem.Program | null; + /** * The identifier of the actor that created the item. */ created_by?: string; } +export namespace ResponseFunctionToolCallOutputItem { + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } +} + /** * The results of a web search tool call. See the * [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for @@ -3588,11 +3834,13 @@ export interface ResponseInputFile { type: 'input_file'; /** - * The detail level of the file to be sent to the model. Use `low` for the default - * rendering behavior, or `high` to render the file at higher quality. Defaults to - * `low`. + * 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`. */ - detail?: 'low' | 'high'; + detail?: 'auto' | 'low' | 'high'; /** * The content of the file to be sent to the model. @@ -3613,6 +3861,27 @@ export interface ResponseInputFile { * The name of the file to be sent to the model. */ filename?: string; + + /** + * Marks the exact end of a reusable 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_cache_breakpoint?: ResponseInputFile.PromptCacheBreakpoint; +} + +export namespace ResponseInputFile { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } } /** @@ -3625,11 +3894,13 @@ export interface ResponseInputFileContent { type: 'input_file'; /** - * The detail level of the file to be sent to the model. Use `low` for the default - * rendering behavior, or `high` to render the file at higher quality. Defaults to - * `low`. + * 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`. */ - detail?: 'low' | 'high'; + detail?: 'auto' | 'low' | 'high'; /** * The base64-encoded data of the file to be sent to the model. @@ -3650,6 +3921,27 @@ export interface ResponseInputFileContent { * The name of the file to be sent to the model. */ filename?: string | 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. + */ + prompt_cache_breakpoint?: ResponseInputFileContent.PromptCacheBreakpoint | null; +} + +export namespace ResponseInputFileContent { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } } /** @@ -3678,6 +3970,27 @@ export interface ResponseInputImage { * encoded image in a data URL. */ image_url?: string | 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. + */ + prompt_cache_breakpoint?: ResponseInputImage.PromptCacheBreakpoint; +} + +export namespace ResponseInputImage { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } } /** @@ -3706,6 +4019,27 @@ export interface ResponseInputImageContent { * encoded image in a data URL. */ image_url?: string | 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. + */ + prompt_cache_breakpoint?: ResponseInputImageContent.PromptCacheBreakpoint | null; +} + +export namespace ResponseInputImageContent { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } } /** @@ -3745,7 +4079,9 @@ export type ResponseInputItem = | ResponseCustomToolCallOutput | ResponseCustomToolCall | ResponseInputItem.CompactionTrigger - | ResponseInputItem.ItemReference; + | ResponseInputItem.ItemReference + | ResponseInputItem.Program + | ResponseInputItem.ProgramOutput; export namespace ResponseInputItem { /** @@ -3861,6 +4197,11 @@ export namespace ResponseInputItem { */ id?: string | null; + /** + * The execution context that produced this tool call. + */ + caller?: FunctionCallOutput.Direct | FunctionCallOutput.Program | null; + /** * The status of the item. One of `in_progress`, `completed`, or `incomplete`. * Populated when items are returned via API. @@ -3868,6 +4209,27 @@ export namespace ResponseInputItem { status?: 'in_progress' | 'completed' | 'incomplete' | null; } + export namespace FunctionCallOutput { + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } + } + export interface ToolSearchCall { /** * The arguments supplied to the tool search call. @@ -4064,6 +4426,11 @@ export namespace ResponseInputItem { */ id?: string | null; + /** + * The execution context that produced this tool call. + */ + caller?: ShellCall.Direct | ShellCall.Program | null; + /** * The environment to execute the shell commands in. */ @@ -4097,6 +4464,25 @@ export namespace ResponseInputItem { */ timeout_ms?: number | null; } + + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } } /** @@ -4125,6 +4511,11 @@ export namespace ResponseInputItem { */ id?: string | null; + /** + * The execution context that produced this tool call. + */ + caller?: ShellCallOutput.Direct | ShellCallOutput.Program | null; + /** * The maximum number of UTF-8 characters captured for this shell call's combined * output. @@ -4137,6 +4528,27 @@ export namespace ResponseInputItem { status?: 'in_progress' | 'completed' | 'incomplete' | null; } + export namespace ShellCallOutput { + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } + } + /** * A tool call representing a request to create, delete, or update files using diff * patches. @@ -4168,6 +4580,11 @@ export namespace ResponseInputItem { * via API. */ id?: string | null; + + /** + * The execution context that produced this tool call. + */ + caller?: ApplyPatchCall.Direct | ApplyPatchCall.Program | null; } export namespace ApplyPatchCall { @@ -4225,6 +4642,25 @@ export namespace ResponseInputItem { */ type: 'update_file'; } + + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } } /** @@ -4252,6 +4688,11 @@ export namespace ResponseInputItem { */ id?: string | null; + /** + * The execution context that produced this tool call. + */ + caller?: ApplyPatchCallOutput.Direct | ApplyPatchCallOutput.Program | null; + /** * Optional human-readable log text from the apply patch tool (e.g., patch results * or errors). @@ -4259,6 +4700,27 @@ export namespace ResponseInputItem { output?: string | null; } + export namespace ApplyPatchCallOutput { + export interface Direct { + /** + * The caller type. Always `direct`. + */ + type: 'direct'; + } + + export interface Program { + /** + * The call ID of the program item that produced this tool call. + */ + caller_id: string; + + /** + * The caller type. Always `program`. + */ + type: 'program'; + } + } + /** * A list of tools available on an MCP server. */ @@ -4453,6 +4915,60 @@ export namespace ResponseInputItem { */ type?: 'item_reference' | null; } + + export interface Program { + /** + * The unique ID of this program item. + */ + id: string; + + /** + * The stable call ID of the program item. + */ + call_id: string; + + /** + * The JavaScript source executed by programmatic tool calling. + */ + code: string; + + /** + * Opaque program replay fingerprint that must be round-tripped. + */ + fingerprint: string; + + /** + * The item type. Always `program`. + */ + type: 'program'; + } + + export interface ProgramOutput { + /** + * The unique ID of this program output item. + */ + id: string; + + /** + * The call ID of the program item. + */ + call_id: string; + + /** + * The result produced by the program item. + */ + result: string; + + /** + * The terminal status of the program output. + */ + status: 'completed' | 'incomplete'; + + /** + * The item type. Always `program_output`. + */ + type: 'program_output'; + } } /** @@ -4503,6 +5019,27 @@ export interface ResponseInputText { * The type of the input item. Always `input_text`. */ type: 'input_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. + */ + prompt_cache_breakpoint?: ResponseInputText.PromptCacheBreakpoint; +} + +export namespace ResponseInputText { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } } /** @@ -4518,6 +5055,27 @@ export interface ResponseInputTextContent { * The type of the input item. Always `input_text`. */ type: 'input_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. + */ + prompt_cache_breakpoint?: ResponseInputTextContent.PromptCacheBreakpoint | null; +} + +export namespace ResponseInputTextContent { + /** + * Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL + * from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a + * token block. + */ + export interface PromptCacheBreakpoint { + /** + * The breakpoint mode. Always `explicit`. + */ + mode: 'explicit'; + } } /** @@ -4536,6 +5094,8 @@ export type ResponseItem = | ResponseToolSearchOutputItem | ResponseItem.AdditionalTools | ResponseReasoningItem + | ResponseItem.Program + | ResponseItem.ProgramOutput | ResponseCompactionItem | ResponseItem.ImageGenerationCall | ResponseCodeInterpreterToolCall @@ -4575,6 +5135,60 @@ export namespace ResponseItem { type: 'additional_tools'; } + export interface Program { + /** + * The unique ID of the program item. + */ + id: string; + + /** + * The stable call ID of the program item. + */ + call_id: string; + + /** + * The JavaScript source executed by programmatic tool calling. + */ + code: string; + + /** + * Opaque program replay fingerprint that must be round-tripped. + */ + fingerprint: string; + + /** + * The type of the item. Always `program`. + */ + type: 'program'; + } + + export interface ProgramOutput { + /** + * The unique ID of the program output item. + */ + id: string; + + /** + * The call ID of the program item. + */ + call_id: string; + + /** + * The result produced by the program item. + */ + result: string; + + /** + * The terminal status of the program output item. + */ + status: 'completed' | 'incomplete'; + + /** + * The type of the item. Always `program_output`. + */ + type: 'program_output'; + } + /** * An image generation request made by the model. */ @@ -5118,6 +5732,8 @@ export type ResponseOutputItem = | ResponseComputerToolCall | ResponseComputerToolCallOutputItem | ResponseReasoningItem + | ResponseOutputItem.Program + | ResponseOutputItem.ProgramOutput | ResponseToolSearchCall | ResponseToolSearchOutputItem | ResponseOutputItem.AdditionalTools @@ -5138,6 +5754,60 @@ export type ResponseOutputItem = | ResponseCustomToolCallOutputItem; export namespace ResponseOutputItem { + export interface Program { + /** + * The unique ID of the program item. + */ + id: string; + + /** + * The stable call ID of the program item. + */ + call_id: string; + + /** + * The JavaScript source executed by programmatic tool calling. + */ + code: string; + + /** + * Opaque program replay fingerprint that must be round-tripped. + */ + fingerprint: string; + + /** + * The type of the item. Always `program`. + */ + type: 'program'; + } + + export interface ProgramOutput { + /** + * The unique ID of the program output item. + */ + id: string; + + /** + * The call ID of the program item. + */ + call_id: string; + + /** + * The result produced by the program item. + */ + result: string; + + /** + * The terminal status of the program output item. + */ + status: 'completed' | 'incomplete'; + + /** + * The type of the item. Always `program_output`. + */ + type: 'program_output'; + } + export interface AdditionalTools { /** * The unique ID of the additional tools item. @@ -5957,6 +6627,12 @@ export interface ResponseReasoningSummaryPartDoneEvent { * The type of the event. Always `response.reasoning_summary_part.done`. */ type: 'response.reasoning_summary_part.done'; + + /** + * The completion status of the summary part. Omitted when the part completed + * normally and set to `incomplete` when generation was interrupted. + */ + status?: 'incomplete'; } export namespace ResponseReasoningSummaryPartDoneEvent { @@ -6581,6 +7257,11 @@ export namespace ResponseUsage { * A detailed breakdown of the input tokens. */ export interface InputTokensDetails { + /** + * The number of input tokens that were written to the cache. + */ + cache_write_tokens: number; + /** * The number of tokens that were retrieved from the cache. * [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). @@ -6809,11 +7490,29 @@ export interface ResponsesClientEvent { prompt_cache_key?: string; /** + * 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. + */ + prompt_cache_options?: ResponsesClientEvent.PromptCacheOptions; + + /** + * @deprecated 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). - * For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + * 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: @@ -6911,6 +7610,7 @@ export interface ResponsesClientEvent { | ToolChoiceFunction | ToolChoiceMcp | ToolChoiceCustom + | ResponsesClientEvent.SpecificProgrammaticToolCallingParam | ToolChoiceApplyPatch | ToolChoiceShell; @@ -6997,6 +7697,74 @@ export namespace ResponsesClientEvent { * 'omni-moderation-latest'. */ model: string; + + /** + * The policy to apply to moderated response input and output. + */ + policy?: Moderation.Policy | null; + } + + export namespace Moderation { + /** + * The policy to apply to moderated response input and output. + */ + export interface Policy { + /** + * The moderation policy for the response input. + */ + input?: Policy.Input | null; + + /** + * The moderation policy for the response output. + */ + output?: Policy.Output | null; + } + + export namespace Policy { + /** + * The moderation policy for the response input. + */ + export interface Input { + mode: 'score' | 'block'; + } + + /** + * The moderation policy for the response output. + */ + export interface Output { + mode: 'score' | 'block'; + } + } + } + + /** + * 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. + */ + export interface PromptCacheOptions { + /** + * 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. + */ + mode?: 'implicit' | 'explicit'; + + /** + * 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. + */ + ttl?: '30m'; } /** @@ -7013,6 +7781,13 @@ export namespace ResponsesClientEvent { */ include_obfuscation?: boolean; } + + export interface SpecificProgrammaticToolCallingParam { + /** + * The tool to call. Always `programmatic_tool_calling`. + */ + type: 'programmatic_tool_calling'; + } } /** @@ -7101,6 +7876,7 @@ export type Tool = | WebSearchTool | Tool.Mcp | Tool.CodeInterpreter + | Tool.ProgrammaticToolCalling | Tool.ImageGeneration | Tool.LocalShell | FunctionShellTool @@ -7127,6 +7903,11 @@ export namespace Tool { */ type: 'mcp'; + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; + /** * List of allowed tool names or a filter object. */ @@ -7289,6 +8070,11 @@ export namespace Tool { * The type of the code interpreter tool. Always `code_interpreter`. */ type: 'code_interpreter'; + + /** + * The tool invocation context(s). + */ + allowed_callers?: Array<'direct' | 'programmatic'> | null; } export namespace CodeInterpreter { @@ -7321,6 +8107,13 @@ export namespace Tool { } } + export interface ProgrammaticToolCalling { + /** + * The type of the tool. Always `programmatic_tool_calling`. + */ + type: 'programmatic_tool_calling'; + } + /** * A tool that generates images using the GPT image models. */ @@ -7886,11 +8679,29 @@ export interface ResponseCreateParamsBase { prompt_cache_key?: string; /** + * 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. + */ + prompt_cache_options?: ResponseCreateParams.PromptCacheOptions; + + /** + * @deprecated 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). - * For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + * 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: @@ -7987,6 +8798,7 @@ export interface ResponseCreateParamsBase { | ToolChoiceFunction | ToolChoiceMcp | ToolChoiceCustom + | ResponseCreateParams.SpecificProgrammaticToolCallingParam | ToolChoiceApplyPatch | ToolChoiceShell; @@ -8073,6 +8885,74 @@ export namespace ResponseCreateParams { * 'omni-moderation-latest'. */ model: string; + + /** + * The policy to apply to moderated response input and output. + */ + policy?: Moderation.Policy | null; + } + + export namespace Moderation { + /** + * The policy to apply to moderated response input and output. + */ + export interface Policy { + /** + * The moderation policy for the response input. + */ + input?: Policy.Input | null; + + /** + * The moderation policy for the response output. + */ + output?: Policy.Output | null; + } + + export namespace Policy { + /** + * The moderation policy for the response input. + */ + export interface Input { + mode: 'score' | 'block'; + } + + /** + * The moderation policy for the response output. + */ + export interface Output { + mode: 'score' | 'block'; + } + } + } + + /** + * 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. + */ + export interface PromptCacheOptions { + /** + * 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. + */ + mode?: 'implicit' | 'explicit'; + + /** + * 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. + */ + ttl?: '30m'; } /** @@ -8090,6 +8970,13 @@ export namespace ResponseCreateParams { include_obfuscation?: boolean; } + export interface SpecificProgrammaticToolCallingParam { + /** + * The tool to call. Always `programmatic_tool_calling`. + */ + type: 'programmatic_tool_calling'; + } + export type ResponseCreateParamsNonStreaming = ResponsesAPI.ResponseCreateParamsNonStreaming; export type ResponseCreateParamsStreaming = ResponsesAPI.ResponseCreateParamsStreaming; } @@ -8191,6 +9078,9 @@ export interface ResponseCompactParams { * available models. */ model: + | 'gpt-5.6-sol' + | 'gpt-5.6-terra' + | 'gpt-5.6-luna' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' @@ -8313,7 +9203,20 @@ export interface ResponseCompactParams { prompt_cache_key?: string | null; /** - * How long to retain a prompt cache entry created by this request. + * 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. + */ + prompt_cache_options?: ResponseCompactParams.PromptCacheOptions | null; + + /** + * @deprecated How long to retain a prompt cache entry created by this request. */ prompt_cache_retention?: 'in_memory' | '24h' | null; @@ -8323,6 +9226,38 @@ export interface ResponseCompactParams { service_tier?: 'auto' | 'default' | 'flex' | 'priority' | null; } +export namespace ResponseCompactParams { + /** + * 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. + */ + export interface PromptCacheOptions { + /** + * 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. + */ + mode?: 'implicit' | 'explicit'; + + /** + * 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. + */ + ttl?: '30m'; + } +} + Responses.InputItems = InputItems; Responses.InputTokens = InputTokens; diff --git a/src/resources/shared.ts b/src/resources/shared.ts index 61f752fde7..8628b7f5a4 100644 --- a/src/resources/shared.ts +++ b/src/resources/shared.ts @@ -19,6 +19,9 @@ export type AllModels = | 'gpt-5.1-codex-max'; export type ChatModel = + | 'gpt-5.6-sol' + | 'gpt-5.6-terra' + | 'gpt-5.6-luna' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' @@ -265,19 +268,12 @@ export interface Reasoning { context?: 'auto' | 'current_turn' | 'all_turns' | null; /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ effort?: ReasoningEffort | null; @@ -290,6 +286,13 @@ export interface Reasoning { */ generate_summary?: 'auto' | 'concise' | 'detailed' | null; + /** + * Controls the reasoning execution mode for the request. + * + * When returned on a response, this is the effective execution mode. + */ + mode?: (string & {}) | 'standard' | 'pro'; + /** * 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`, @@ -302,21 +305,14 @@ export interface Reasoning { } /** - * Constrains effort on reasoning for - * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently - * supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. - * Reducing reasoning effort can result in faster responses and fewer tokens used - * on reasoning in a response. - * - * - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported - * reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool - * calls are supported for all reasoning values in gpt-5.1. - * - All models before `gpt-5.1` default to `medium` reasoning effort, and do not - * support `none`. - * - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - * - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + * 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. */ -export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | null; +export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null; /** * JSON object response format. An older method of generating JSON responses. Using diff --git a/src/resources/webhooks/api.md b/src/resources/webhooks/api.md index b203d7206b..a2ebaf197d 100644 --- a/src/resources/webhooks/api.md +++ b/src/resources/webhooks/api.md @@ -17,6 +17,7 @@ Types: - ResponseCompletedWebhookEvent - ResponseFailedWebhookEvent - ResponseIncompleteWebhookEvent +- SafetyIdentifierBlockedWebhookEvent - UnwrapWebhookEvent Methods: diff --git a/src/resources/webhooks/webhooks.ts b/src/resources/webhooks/webhooks.ts index 4d4782e24f..1ac673309b 100644 --- a/src/resources/webhooks/webhooks.ts +++ b/src/resources/webhooks/webhooks.ts @@ -791,6 +791,68 @@ export namespace ResponseIncompleteWebhookEvent { } } +/** + * Sent when a request associated with a safety identifier has been blocked. + */ +export interface SafetyIdentifierBlockedWebhookEvent { + /** + * The unique ID of the event. + */ + id: string; + + /** + * The Unix timestamp (in seconds) of when the request was blocked. + */ + created_at: number; + + /** + * Event data payload. + */ + data: SafetyIdentifierBlockedWebhookEvent.Data; + + /** + * The type of the event. Always `safety_identifier.blocked`. + */ + type: 'safety_identifier.blocked'; + + /** + * The object of the event. Always `event`. + */ + object?: 'event'; +} + +export namespace SafetyIdentifierBlockedWebhookEvent { + /** + * Event data payload. + */ + export interface Data { + /** + * The safety category that triggered the block, such as `bio` or `cyber`. + */ + safety_category: string; + + /** + * The stable safety identifier associated with the blocked request. + */ + safety_identifier: string; + + /** + * The model used for the blocked request, if available. + */ + model?: string; + + /** + * The project associated with the blocked request, if available. + */ + project_id?: string; + + /** + * The OpenAI request ID for the blocked request, if available. + */ + request_id?: string; + } +} + /** * Sent when a batch API request has been cancelled. */ @@ -809,7 +871,8 @@ export type UnwrapWebhookEvent = | ResponseCancelledWebhookEvent | ResponseCompletedWebhookEvent | ResponseFailedWebhookEvent - | ResponseIncompleteWebhookEvent; + | ResponseIncompleteWebhookEvent + | SafetyIdentifierBlockedWebhookEvent; export declare namespace Webhooks { export { @@ -828,6 +891,7 @@ export declare namespace Webhooks { type ResponseCompletedWebhookEvent as ResponseCompletedWebhookEvent, type ResponseFailedWebhookEvent as ResponseFailedWebhookEvent, type ResponseIncompleteWebhookEvent as ResponseIncompleteWebhookEvent, + type SafetyIdentifierBlockedWebhookEvent as SafetyIdentifierBlockedWebhookEvent, type UnwrapWebhookEvent as UnwrapWebhookEvent, }; } diff --git a/tests/api-resources/beta/responses/input-items.test.ts b/tests/api-resources/beta/responses/input-items.test.ts new file mode 100644 index 0000000000..07b9b1bb9e --- /dev/null +++ b/tests/api-resources/beta/responses/input-items.test.ts @@ -0,0 +1,39 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import OpenAI from 'openai'; + +const client = new OpenAI({ + apiKey: 'My API Key', + adminAPIKey: 'My Admin API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource inputItems', () => { + test('list', async () => { + const responsePromise = client.beta.responses.inputItems.list('response_id'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('list: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.beta.responses.inputItems.list( + 'response_id', + { + after: 'after', + include: ['file_search_call.results'], + limit: 0, + order: 'asc', + betas: ['responses_multi_agent=v1'], + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(OpenAI.NotFoundError); + }); +}); diff --git a/tests/api-resources/beta/responses/input-tokens.test.ts b/tests/api-resources/beta/responses/input-tokens.test.ts new file mode 100644 index 0000000000..a67846030f --- /dev/null +++ b/tests/api-resources/beta/responses/input-tokens.test.ts @@ -0,0 +1,66 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import OpenAI from 'openai'; + +const client = new OpenAI({ + apiKey: 'My API Key', + adminAPIKey: 'My Admin API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource inputTokens', () => { + test('count', async () => { + const responsePromise = client.beta.responses.inputTokens.count(); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('count: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.beta.responses.inputTokens.count( + { + conversation: 'string', + input: 'string', + instructions: 'instructions', + model: 'model', + parallel_tool_calls: true, + personality: 'friendly', + previous_response_id: 'resp_123', + reasoning: { + context: 'auto', + effort: 'none', + generate_summary: 'auto', + mode: 'standard', + summary: 'auto', + }, + text: { + format: { type: 'text' }, + verbosity: 'low', + }, + 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' }, + }, + ], + truncation: 'auto', + betas: ['responses_multi_agent=v1'], + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(OpenAI.NotFoundError); + }); +}); diff --git a/tests/api-resources/beta/responses/responses.test.ts b/tests/api-resources/beta/responses/responses.test.ts new file mode 100644 index 0000000000..6a6fc762ad --- /dev/null +++ b/tests/api-resources/beta/responses/responses.test.ts @@ -0,0 +1,119 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import OpenAI from 'openai'; + +const client = new OpenAI({ + apiKey: 'My API Key', + adminAPIKey: 'My Admin API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource responses', () => { + test('create', async () => { + const responsePromise = client.beta.responses.create({}); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('retrieve', async () => { + const responsePromise = client.beta.responses.retrieve('resp_677efb5139a88190b512bc3fef8e535d'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('retrieve: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.beta.responses.retrieve( + 'resp_677efb5139a88190b512bc3fef8e535d', + { + include: ['file_search_call.results'], + include_obfuscation: true, + starting_after: 0, + stream: false, + betas: ['responses_multi_agent=v1'], + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(OpenAI.NotFoundError); + }); + + test('delete', async () => { + const responsePromise = client.beta.responses.delete('resp_677efb5139a88190b512bc3fef8e535d'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('delete: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.beta.responses.delete( + 'resp_677efb5139a88190b512bc3fef8e535d', + { betas: ['responses_multi_agent=v1'] }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(OpenAI.NotFoundError); + }); + + test('cancel', async () => { + const responsePromise = client.beta.responses.cancel('resp_677efb5139a88190b512bc3fef8e535d'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('cancel: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.beta.responses.cancel( + 'resp_677efb5139a88190b512bc3fef8e535d', + { betas: ['responses_multi_agent=v1'] }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(OpenAI.NotFoundError); + }); + + test('compact: only required params', async () => { + const responsePromise = client.beta.responses.compact({ model: 'gpt-5.6-sol' }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + test('compact: required and optional params', async () => { + const response = await client.beta.responses.compact({ + model: 'gpt-5.6-sol', + input: 'string', + instructions: 'instructions', + previous_response_id: 'resp_123', + prompt_cache_key: 'prompt_cache_key', + prompt_cache_options: { mode: 'implicit', ttl: '30m' }, + prompt_cache_retention: 'in_memory', + service_tier: 'auto', + betas: ['responses_multi_agent=v1'], + }); + }); +}); diff --git a/tests/api-resources/beta/threads/runs/runs.test.ts b/tests/api-resources/beta/threads/runs/runs.test.ts index 8b35986eef..3abf316aaf 100644 --- a/tests/api-resources/beta/threads/runs/runs.test.ts +++ b/tests/api-resources/beta/threads/runs/runs.test.ts @@ -37,7 +37,7 @@ describe('resource runs', () => { max_completion_tokens: 256, max_prompt_tokens: 256, metadata: { foo: 'string' }, - model: 'gpt-5.4', + model: 'gpt-5.6-sol', parallel_tool_calls: true, reasoning_effort: 'none', response_format: 'auto', diff --git a/tests/api-resources/beta/threads/threads.test.ts b/tests/api-resources/beta/threads/threads.test.ts index a4742a2c93..f41b492c01 100644 --- a/tests/api-resources/beta/threads/threads.test.ts +++ b/tests/api-resources/beta/threads/threads.test.ts @@ -104,7 +104,7 @@ describe('resource threads', () => { max_completion_tokens: 256, max_prompt_tokens: 256, metadata: { foo: 'string' }, - model: 'gpt-5.4', + model: 'gpt-5.6-sol', parallel_tool_calls: true, response_format: 'auto', stream: false, diff --git a/tests/api-resources/chat/completions/completions.test.ts b/tests/api-resources/chat/completions/completions.test.ts index 38adc7ea77..2a8821d897 100644 --- a/tests/api-resources/chat/completions/completions.test.ts +++ b/tests/api-resources/chat/completions/completions.test.ts @@ -49,12 +49,19 @@ describe('resource completions', () => { max_tokens: 0, metadata: { foo: 'string' }, modalities: ['text'], - moderation: { model: 'model' }, + moderation: { + model: 'model', + policy: { + input: { mode: 'score' }, + output: { mode: 'score' }, + }, + }, n: 1, parallel_tool_calls: true, prediction: { content: 'string', type: 'content' }, presence_penalty: -2, prompt_cache_key: 'prompt-cache-key-1234', + prompt_cache_options: { mode: 'implicit', ttl: '30m' }, prompt_cache_retention: 'in_memory', reasoning_effort: 'none', response_format: { type: 'text' }, diff --git a/tests/api-resources/responses/input-tokens.test.ts b/tests/api-resources/responses/input-tokens.test.ts index 48ccfca41b..368cf46853 100644 --- a/tests/api-resources/responses/input-tokens.test.ts +++ b/tests/api-resources/responses/input-tokens.test.ts @@ -36,6 +36,7 @@ describe('resource inputTokens', () => { context: 'auto', effort: 'none', generate_summary: 'auto', + mode: 'standard', summary: 'auto', }, text: { @@ -49,8 +50,10 @@ describe('resource inputTokens', () => { parameters: { foo: 'bar' }, strict: true, type: 'function', + allowed_callers: ['direct'], defer_loading: true, description: 'description', + output_schema: { foo: 'bar' }, }, ], truncation: 'auto', diff --git a/tests/api-resources/responses/responses.test.ts b/tests/api-resources/responses/responses.test.ts index aeee41b717..79c68ea673 100644 --- a/tests/api-resources/responses/responses.test.ts +++ b/tests/api-resources/responses/responses.test.ts @@ -76,7 +76,7 @@ describe('resource responses', () => { }); test('compact: only required params', async () => { - const responsePromise = client.responses.compact({ model: 'gpt-5.4' }); + const responsePromise = client.responses.compact({ model: 'gpt-5.6-sol' }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -88,11 +88,12 @@ describe('resource responses', () => { test('compact: required and optional params', async () => { const response = await client.responses.compact({ - model: 'gpt-5.4', + model: 'gpt-5.6-sol', input: 'string', instructions: 'instructions', previous_response_id: 'resp_123', prompt_cache_key: 'prompt_cache_key', + prompt_cache_options: { mode: 'implicit', ttl: '30m' }, prompt_cache_retention: 'in_memory', service_tier: 'auto', }); diff --git a/tests/lib/ResponseInputItems.test.ts b/tests/lib/ResponseInputItems.test.ts index 0895541683..80bd0a88f7 100644 --- a/tests/lib/ResponseInputItems.test.ts +++ b/tests/lib/ResponseInputItems.test.ts @@ -73,6 +73,20 @@ describe('toResponseInputItems', () => { status: 'completed', created_by: 'assistant', }, + { + type: 'program', + id: 'program_123', + call_id: 'program_call_123', + code: 'return 42', + fingerprint: 'program_fingerprint_123', + }, + { + type: 'program_output', + id: 'program_output_123', + call_id: 'program_call_123', + result: '42', + status: 'completed', + }, ]; expect(toResponseInputItems(history)).toEqual([ @@ -138,6 +152,20 @@ describe('toResponseInputItems', () => { output: 'created notes.txt', status: 'completed', }, + { + type: 'program', + id: 'program_123', + call_id: 'program_call_123', + code: 'return 42', + fingerprint: 'program_fingerprint_123', + }, + { + type: 'program_output', + id: 'program_output_123', + call_id: 'program_call_123', + result: '42', + status: 'completed', + }, ]); }); diff --git a/tests/lib/ResponsesParser.test.ts b/tests/lib/ResponsesParser.test.ts index 740312f5c9..c3605d3aba 100644 --- a/tests/lib/ResponsesParser.test.ts +++ b/tests/lib/ResponsesParser.test.ts @@ -76,4 +76,26 @@ describe('ResponsesParser', () => { }); } }); + + it('passes programmatic tool calling items through unchanged', () => { + const raw = makeResponse('completed', '{"size":"large"}'); + raw.output.push({ + type: 'program', + id: 'program_123', + call_id: 'program_call_123', + code: 'return 42', + fingerprint: 'program_fingerprint_123', + }); + raw.output.push({ + type: 'program_output', + id: 'program_output_123', + call_id: 'program_call_123', + result: '42', + status: 'completed', + }); + + const response = parseResponse(raw, structuredTextParams); + + expect(response.output.slice(1)).toEqual(raw.output.slice(1)); + }); }); diff --git a/tests/responsesTools.test.ts b/tests/responsesTools.test.ts new file mode 100644 index 0000000000..ef214340e9 --- /dev/null +++ b/tests/responsesTools.test.ts @@ -0,0 +1,117 @@ +import type { + FunctionTool, + ResponseCreateParamsBase, + ResponseInputItem, + ResponseOutputItem, + ResponseToolSearchOutputItemParam, + ResponsesClientEvent, + Tool, +} from 'openai/resources/responses/responses'; +import type { InputTokenCountParams } from 'openai/resources/responses/input-tokens'; +import type { + BetaFunctionTool, + BetaResponseToolSearchOutputItemParam, + BetaResponseInputItem, + BetaResponseOutputItem, + BetaResponsesClientEvent, + BetaTool, + ResponseCreateParamsBase as BetaResponseCreateParamsBase, +} from 'openai/resources/beta/responses/responses'; +import type { InputTokenCountParams as BetaInputTokenCountParams } from 'openai/resources/beta/responses/input-tokens'; +import type { ChatCompletionTool } from 'openai/resources/chat/completions'; +import type { + AutoParseableResponseTool, + ParseableToolsParams, + ResponseCreateParamsWithTools, +} from 'openai/lib/ResponsesParser'; + +type Assert = Condition; +type IsAssignable = [Source] extends [Target] ? true : false; +type IsEqual = + (() => T extends Left ? 1 : 2) extends () => T extends Right ? 1 : 2 ? true : false; + +// Stable and beta request surfaces intentionally share their response Tool union +// for backwards compatibility. +type _StableInputTokenToolsStayShared = Assert< + IsEqual[number], Tool> +>; +type _StableCreateToolsStayShared = Assert< + IsEqual[number], Tool> +>; +type _StableClientEventToolsStayShared = Assert< + IsEqual[number], Tool> +>; +type _StableToolSearchOutputToolsStayShared = Assert< + IsEqual +>; +type _StableAdditionalToolsStayShared = Assert< + IsEqual +>; + +type _BetaInputTokenToolsStayShared = Assert< + IsEqual[number], BetaTool> +>; +type _BetaCreateToolsStayShared = Assert< + IsEqual[number], BetaTool> +>; +type _BetaClientEventToolsStayShared = Assert< + IsEqual[number], BetaTool> +>; +type _BetaToolSearchOutputToolsStayShared = Assert< + IsEqual +>; +type _BetaAdditionalToolsStayShared = Assert< + IsEqual +>; + +// output_schema remains public, typed, and optional-nullable on the shared tool. +type _StableFunctionToolMayOmitOutputSchema = Assert< + IsAssignable< + { + name: string; + parameters: { [key: string]: unknown } | null; + strict: boolean | null; + type: 'function'; + }, + FunctionTool + > +>; +type _StableAdditionalToolsAreReplayable = Assert< + IsAssignable< + Pick, + Pick + > +>; + +type _BetaFunctionToolMayOmitOutputSchema = Assert< + IsAssignable< + { + name: string; + parameters: { [key: string]: unknown } | null; + strict: boolean | null; + type: 'function'; + }, + BetaFunctionTool + > +>; +type _BetaAdditionalToolsAreReplayable = Assert< + IsAssignable< + Pick, + Pick + > +>; + +// Preserve the hand-written parser helper's public source compatibility. +type ParserToolOptions = { name: string; arguments: unknown }; +type _AutoParseableToolRemainsFunctionTool = Assert< + IsAssignable, FunctionTool> +>; +type _ParseableToolsStillAcceptNull = Assert>; +type _ParseableToolsStillAcceptChatTools = Assert>; +type _ResponseCreateParamsWithToolsStillAcceptSharedTools = Assert< + IsAssignable<{ tools?: Array }, Pick> +>; + +test('response tools and parser helpers stay backwards compatible', () => { + expect(true).toBe(true); +}); From 8a7ec045102ef6c127b5aeccb068d1c8b2b92ec7 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 9 Jul 2026 17:00:28 +0000 Subject: [PATCH 2/2] release: 6.46.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 22 ++++++++++++++++++++++ jsr.json | 2 +- package.json | 2 +- src/version.ts | 2 +- 5 files changed, 26 insertions(+), 4 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 80aa6f36a3..fb3bf73bc1 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "6.45.0" + ".": "6.46.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 4fad015b92..9750a34f1c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,27 @@ # Changelog +## 6.46.0 (2026-07-09) + +Full Changelog: [v6.45.0...v6.46.0](https://github.com/openai/openai-node/compare/v6.45.0...v6.46.0) + +### Features + +* **api:** gpt-5.6-sol updates ([6c397d5](https://github.com/openai/openai-node/commit/6c397d5d281d6061e88b4a0120fab335ec862a89)) + + +### Bug Fixes + +* **assistants:** place array delta entries by index instead of appending ([#1963](https://github.com/openai/openai-node/issues/1963)) ([0e18d30](https://github.com/openai/openai-node/commit/0e18d30a31595acf0fd5e03b8e6bbf8bf31d15d1)) +* **runner:** normalize missing tool call IDs ([#1958](https://github.com/openai/openai-node/issues/1958)) ([6371623](https://github.com/openai/openai-node/commit/6371623aadd26ec34a0edecba62a0a10c834b37d)) +* upgrade next to 15.5.16 in examples ([#1967](https://github.com/openai/openai-node/issues/1967)) ([95b54e5](https://github.com/openai/openai-node/commit/95b54e5894910e31d01ef418ef0de31e9d653b08)) + + +### Documentation + +* add Azure Assistants example ([#1975](https://github.com/openai/openai-node/issues/1975)) ([90a72e5](https://github.com/openai/openai-node/commit/90a72e53452fca62e0c1da42c304eba87d8e87e7)), closes [#701](https://github.com/openai/openai-node/issues/701) +* document assistant stream failures ([#1979](https://github.com/openai/openai-node/issues/1979)) ([d93fbe5](https://github.com/openai/openai-node/commit/d93fbe5bc5a7879ff4a2b81f3840614da6df594e)), closes [#959](https://github.com/openai/openai-node/issues/959) +* document file search result limits ([#1981](https://github.com/openai/openai-node/issues/1981)) ([e9dc283](https://github.com/openai/openai-node/commit/e9dc283dce5a75c569c1aa418f973da69cf7eaae)), closes [#1004](https://github.com/openai/openai-node/issues/1004) + ## 6.45.0 (2026-06-24) Full Changelog: [v6.44.0...v6.45.0](https://github.com/openai/openai-node/compare/v6.44.0...v6.45.0) diff --git a/jsr.json b/jsr.json index 7355246b05..b7add0eabb 100644 --- a/jsr.json +++ b/jsr.json @@ -1,6 +1,6 @@ { "name": "@openai/openai", - "version": "6.45.0", + "version": "6.46.0", "exports": { ".": "./index.ts", "./providers/bedrock": "./providers/bedrock.ts", diff --git a/package.json b/package.json index e251ea5bca..eed0ce28ee 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "openai", - "version": "6.45.0", + "version": "6.46.0", "description": "The official TypeScript library for the OpenAI API", "author": "OpenAI ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index e6d46dcb4c..8440453f40 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '6.45.0'; // x-release-please-version +export const VERSION = '6.46.0'; // x-release-please-version