From 3caafc6a986cb9e87e535a2e88fe178f914d6938 Mon Sep 17 00:00:00 2001 From: Dan Piet Date: Sat, 24 Oct 2026 01:55:03 +0000 Subject: [PATCH] feat(api): add delegation controls and prompt cache lifetimes Castiron-Internal-PR: https://github.com/openai/openai-node-internal/pull/370 Castiron-Source-SHA: 009299ab1845d480a1f6d5eed828d41d0f54742e Castiron-Public-Base-SHA: 8e32d2df55d99fdcd5be8862d4815007f7ad076f --- .castiron.stats.yml | 14 +- .../castiron-custom-code-comment.yml | 106 +- api.md | 37 + api_reference/openapi.transformed.yml | 17073 +++++++++------- scripts/castiron/custom_code_policy.py | 130 +- scripts/castiron/custom_code_test_support.py | 29 +- .../castiron/fixtures/github_publisher.cjs | 69 +- scripts/castiron/generated-files.json | 74 +- scripts/castiron/test_custom_code_policy.py | 47 + .../castiron/test_custom_code_publication.py | 735 +- .../test_custom_code_review_revocation.py | 619 + src/helpers/browser.ts | 32 +- src/helpers/responses-tool-runner.ts | 15 +- src/resources/audio/voices.ts | 6 +- src/resources/beta/agents/agents.ts | 92 +- src/resources/beta/agents/automations.ts | 3 + .../beta/agents/automations/automations.ts | 1198 ++ .../beta/agents/automations/index.ts | 28 + .../beta/agents/automations/invocations.ts | 422 + src/resources/beta/agents/index.ts | 18 + src/resources/beta/responses/responses.ts | 40 + src/resources/chat/completions/completions.ts | 20 + src/resources/conversations/conversations.ts | 5 + src/resources/live/api.md | 2 + src/resources/live/index.ts | 2 + src/resources/live/live.ts | 142 +- src/resources/live/sessions.ts | 19 + src/resources/live/sideband/index.ts | 2 + src/resources/live/sideband/sideband.ts | 6 + src/resources/realtime/realtime.ts | 13 +- src/resources/responses/responses.ts | 30 + .../agents/automations/automations.test.ts | 163 + .../agents/automations/invocations.test.ts | 67 + tests/api-resources/live/live.test.ts | 2 +- tests/api-resources/live/sessions.test.ts | 3 +- tests/helpers/browser-capabilities.test.ts | 16 +- tests/helpers/browser-runner.test.ts | 172 +- 37 files changed, 12913 insertions(+), 8538 deletions(-) create mode 100644 scripts/castiron/test_custom_code_review_revocation.py create mode 100644 src/resources/beta/agents/automations.ts create mode 100644 src/resources/beta/agents/automations/automations.ts create mode 100644 src/resources/beta/agents/automations/index.ts create mode 100644 src/resources/beta/agents/automations/invocations.ts create mode 100644 tests/api-resources/beta/agents/automations/automations.test.ts create mode 100644 tests/api-resources/beta/agents/automations/invocations.test.ts diff --git a/.castiron.stats.yml b/.castiron.stats.yml index bddbadb8c3..4acf3ef20b 100644 --- a/.castiron.stats.yml +++ b/.castiron.stats.yml @@ -1,8 +1,8 @@ schema_version: 1 -generation_id: 27df3794-a553-43cc-8f4b-185769024bef -openapi_spec_hash: 57a09bbc4ed186fcc90c45b35c3fcd2a -openapi_transformed_spec_hash: c75fb660cd08c6849312b7c855a5a972 -config_hash: 15b95017b61d7786c97ad38ec3b165fc -codegen_sha: 81e7b6df84e3fd0ddf1d3644e33c669a0d1d5701 -codegen_hash: 2bfc42c2dc248767860b8ab432f9234b576da369a151631ea5829cc560c63dec -public_codegen_sha: f22659f9e547eacc29686ca28d2ece06ee671a62 +generation_id: 5e74425a-cbaf-4c8b-b18a-c25a116931f4 +openapi_spec_hash: 23f0bfa58ad53fef090bea6a72a05dda +openapi_transformed_spec_hash: f137081442eeb81e7fbed2c31b205da3 +config_hash: 8b7349444923954cc826cb8f066f2fe4 +codegen_sha: 2b4ba343542f704e2ace24a0fe25c262c8955227 +codegen_hash: 798a32d2dc40415abe68f388d2ade5fbeed6da0fa86db80f9e0b0a12224b7466 +public_codegen_sha: 7339f40adf97816aec0a612869173b17d1a813cf diff --git a/.github/workflows/castiron-custom-code-comment.yml b/.github/workflows/castiron-custom-code-comment.yml index 7e2702a432..2157f6a87a 100644 --- a/.github/workflows/castiron-custom-code-comment.yml +++ b/.github/workflows/castiron-custom-code-comment.yml @@ -29,8 +29,14 @@ jobs: pull-requests: read statuses: write steps: - # Trusted main definition: no candidate checkout, artifacts, or executable inputs. - name: Re-evaluate current PR and queue after review changes + env: + GH_TOKEN: ${{ github.token }} + GIT_CONFIG_COUNT: '2' + GIT_CONFIG_KEY_0: credential.helper + GIT_CONFIG_VALUE_0: '' + GIT_CONFIG_KEY_1: credential.https://github.com.helper + GIT_CONFIG_VALUE_1: '!gh auth git-credential' uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 with: script: | @@ -56,58 +62,35 @@ jobs: if (!/^[0-9a-f]{40}$/.test(sha || '')) throw new Error('Invalid policy merge base'); return sha; } - async function readPolicy(ref) { - const {data: file} = await github.rest.repos.getContent({ - ...context.repo, path: '.castiron-ratchet.json', ref, - }); - if (file.type !== 'file' || file.encoding !== 'base64' || !Number.isSafeInteger(file.size) || - file.size > 4096 || typeof file.content !== 'string') throw new Error('Invalid policy file'); - const content = Buffer.from(file.content, 'base64'); - if (content.length !== file.size) throw new Error('Invalid policy content'); - const policy = JSON.parse(content.toString('utf8'), (key, value, source) => - key === 'max_custom_patch_lines' && typeof value === 'number' ? BigInt(source.source) : value); - if (!policy || typeof policy !== 'object' || typeof policy.max_custom_patch_lines !== 'bigint' || - policy.max_custom_patch_lines < 0n) throw new Error('Invalid policy budget'); - return policy; - } - async function supportsEffectivePinReview(ref) { - let file; + async function requiresHuman(pr, mainSha) { + if (!/^[0-9a-f]{40}$/.test(mainSha || '')) throw new Error('Invalid authenticated main'); + const path = require('node:path'); + const fs = require('node:fs'); + const root = fs.mkdtempSync(path.join(process.env.RUNNER_TEMP, 'castiron-review-')); try { - ({data: file} = await github.rest.repos.getContent({ - ...context.repo, path: 'scripts/castiron/custom_code_policy.py', ref, - })); - } catch (error) { - if (error.status === 404) return false; - throw error; + // Bind executable policy and its dependency to the authenticated + // main snapshot for this decision, including after a retry. + for (const name of ['custom_code_policy.py', 'custom_code_report.py']) { + const {data: file} = await github.rest.repos.getContent({ + ...context.repo, path: `scripts/castiron/${name}`, ref: mainSha, + }); + if (file.type !== 'file' || file.encoding !== 'base64' || + !Number.isSafeInteger(file.size) || file.size <= 0 || file.size > 1048576 || + typeof file.content !== 'string') throw new Error('Invalid trusted policy file'); + const content = Buffer.from(file.content, 'base64'); + if (content.length !== file.size) throw new Error('Invalid trusted policy content'); + fs.writeFileSync(path.join(root, name), content, {flag: 'wx'}); + } + const result = await exec.getExecOutput('python3', ['-I', + path.join(root, 'custom_code_policy.py'), 'review-required', + '--repository', repo, '--repo', path.join(root, 'objects.git'), + '--base', pr.base.sha, '--head', pr.head.sha, '--main', mainSha], {silent: true}); + const decision = JSON.parse(result.stdout); + if (typeof decision.requires_human !== 'boolean') throw new Error('Invalid review decision'); + return decision.requires_human; + } finally { + fs.rmSync(root, {recursive: true, force: true}); } - if (file.type !== 'file' || file.encoding !== 'base64' || !Number.isSafeInteger(file.size) || - file.size < 0 || typeof file.content !== 'string') throw new Error('Invalid checker contract'); - const content = Buffer.from(file.content, 'base64'); - if (content.length !== file.size) throw new Error('Invalid checker content'); - // Read data only from the effective checker, never import or execute it. - const declarations = content.toString('utf8').match(/^PIN_REVIEW_POLICY = .*$/gm) || []; - return declarations.length === 1 && declarations[0] === 'PIN_REVIEW_POLICY = "effective-policy-v1"'; - } - async function pinRequiresHuman(pr, headPolicy, mainSha) { - const targetPolicy = await readPolicy(pr.base.sha); - const pinSha = pin => pin?.repository === repo && /^[0-9a-f]{40}$/.test(pin.main_sha || '') - ? pin.main_sha : null; - const proposedChecker = pinSha(headPolicy.next_policy); - const previousChecker = targetPolicy.next_policy ? pinSha(targetPolicy.next_policy) : mainSha; - if (!proposedChecker || !/^[0-9a-f]{40}$/.test(previousChecker || '') || - !/^[0-9a-f]{40}$/.test(mainSha || '')) return true; - // Older checkers require human review for every pin edit. Retain that - // requirement until the protected checker explicitly supports the exemption. - if (!await supportsEffectivePinReview(previousChecker)) return true; - const [previous, proposed, previousBase, proposedBase] = await Promise.all([ - readPolicy(previousChecker), - readPolicy(proposedChecker), mergeBase(previousChecker, proposedChecker), - mergeBase(proposedChecker, mainSha), - ]); - return previousBase !== previousChecker || proposedBase !== proposedChecker || - proposed.max_custom_patch_lines > previous.max_custom_patch_lines || - proposed.schema_version !== previous.schema_version || - proposed.generated_files !== previous.generated_files || proposed.ratchet !== previous.ratchet; } const dirtyTargets = new Set(); // Retry discovery within this job timeout while targets are changing. @@ -146,18 +129,17 @@ jobs: const pr = matching[0]; const files = await github.paginate(github.rest.pulls.listFiles, {...context.repo, pull_number: pr.number}); if (!files.some(file => file.filename === '.castiron-ratchet.json')) return; - const baseline = await mergeBase(pr.base.sha, pr.head.sha); - const [basePolicy, headPolicy] = await Promise.all([readPolicy(baseline), readPolicy(pr.head.sha)]); - const pinChanged = !require('node:util').isDeepStrictEqual(basePolicy.next_policy ?? null, headPolicy.next_policy ?? null); - let requiresHuman = headPolicy.max_custom_patch_lines > basePolicy.max_custom_patch_lines || - (headPolicy.ratchet === 'go' && basePolicy.ratchet !== 'go'); - let mainSha = null; - if (!requiresHuman && pinChanged) { - const {data: main} = await github.rest.git.getRef({...context.repo, ref: 'heads/main'}); - mainSha = main.object.sha; - requiresHuman = await pinRequiresHuman(pr, headPolicy, mainSha); + const {data: main} = await github.rest.git.getRef({...context.repo, ref: 'heads/main'}); + const mainSha = main.object.sha; + let requiresReview; + try { + requiresReview = await requiresHuman(pr, mainSha); + } catch (error) { + const {data: currentMain} = await github.rest.git.getRef({...context.repo, ref: 'heads/main'}); + if (currentMain.object.sha !== mainSha) continue; + throw error; } - if (!requiresHuman) { + if (!requiresReview) { const [{data: current}, {data: target}, main] = await Promise.all([ github.rest.pulls.get({...context.repo, pull_number: pr.number}), github.rest.git.getRef({...context.repo, ref: 'heads/next'}), diff --git a/api.md b/api.md index 32ddbbc694..889661c8cc 100644 --- a/api.md +++ b/api.md @@ -579,6 +579,43 @@ Methods: - client.beta.agents.list({ ...params }) -> AgentsPage - client.beta.agents.delete(agentID) -> AgentDeleted +### Automations + +Types: + +- Automation +- AutomationAgentConfig +- AutomationCreatedBy +- AutomationDeleted +- AutomationEnvironment +- AutomationTarget +- AutomationTargetParam +- OneTimeAutomation +- PeriodicAutomation + +Methods: + +- client.beta.agents.automations.create({ ...params }) -> Automation +- client.beta.agents.automations.retrieve(automationID) -> Automation +- client.beta.agents.automations.update(automationID, { ...params }) -> Automation +- client.beta.agents.automations.list({ ...params }) -> AutomationsPage +- client.beta.agents.automations.delete(automationID) -> AutomationDeleted +- client.beta.agents.automations.pause(automationID) -> Automation +- client.beta.agents.automations.resume(automationID) -> Automation + +#### Invocations + +Types: + +- AutomationInvocation +- AutomationInvocationSource + +Methods: + +- client.beta.agents.automations.invocations.create(automationID) -> AutomationInvocation +- client.beta.agents.automations.invocations.retrieve(invocationID, { ...params }) -> AutomationInvocation +- client.beta.agents.automations.invocations.list(automationID, { ...params }) -> AutomationInvocationsPage + ### Environments Types: diff --git a/api_reference/openapi.transformed.yml b/api_reference/openapi.transformed.yml index 2e85c37312..4cea00f421 100644 --- a/api_reference/openapi.transformed.yml +++ b/api_reference/openapi.transformed.yml @@ -1742,6 +1742,58 @@ paths: "prompt": "A warm, calm narrator with a clear, measured delivery.", "model": "auto" }' + /audio/voices/{voice_id}: + delete: + operationId: deleteVoice + tags: + - Audio + summary: Delete voice + description: | + Deletes a voice created from a text prompt or an audio sample. + + Requires voice write permission and access to the voice's project. Access to voices created from recordings is limited to eligible customers. See the [custom voices guide](https://developers.openai.com/api/docs/guides/custom-voices). + + Deleting a voice does not delete its consent recording. Deleting an already deleted voice returns a 404 error. + parameters: + - in: path + name: voice_id + required: true + schema: + type: string + description: The ID of the voice to delete. + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/VoiceDeletedResource' + '400': + description: Invalid voice ID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The endpoint is unavailable or the voice was not found in the requested project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + x-oaiMeta: + group: audio + examples: + request: + curl: | + curl https://api.openai.com/v1/audio/voices/voice_1234 \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_API_KEY" + response: | + { + "id": "voice_1234", + "object": "audio.voice.deleted", + "deleted": true + } /batches: post: summary: Create batch @@ -3577,6 +3629,117 @@ paths: application/json: schema: $ref: '#/components/schemas/CreateCompletionResponse' + text/event-stream: + schema: + type: object + description: | + Represents a completion response from the API. Note: both the streamed and non-streamed response objects share the same shape (unlike the chat endpoint). + properties: + id: + type: string + description: A unique identifier for the completion. + choices: + type: array + description: The list of completion choices the model generated for the input prompt. + items: + type: object + required: + - finish_reason + - index + - logprobs + - text + properties: + finish_reason: + anyOf: + - type: string + enum: + - stop + - length + - content_filter + - type: 'null' + description: | + The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, + `length` if the maximum number of tokens specified in the request was reached, + or `content_filter` if content was omitted due to a flag from our content filters. The value is null while a streamed completion is unfinished. + index: + type: integer + logprobs: + anyOf: + - type: object + properties: + text_offset: + type: array + items: + type: integer + token_logprobs: + type: array + items: + type: number + tokens: + type: array + items: + type: string + top_logprobs: + type: array + items: + type: object + additionalProperties: + type: number + - type: 'null' + text: + type: string + created: + type: integer + format: unixtime + description: The Unix timestamp (in seconds) of when the completion was created. + model: + type: string + description: The model used for completion. + system_fingerprint: + type: string + description: | + This fingerprint represents the backend configuration that the model runs with. + + Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism. + object: + type: string + description: The object type, which is always "text_completion" + enum: + - text_completion + x-stainless-const: true + usage: + anyOf: + - $ref: '#/components/schemas/CompletionUsage' + - type: 'null' + required: + - id + - object + - created + - model + - choices + x-oaiMeta: + name: The completion object + legacy: true + example: | + { + "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", + "object": "text_completion", + "created": 1589478378, + "model": "gpt-3.5-turbo-instruct", + "choices": [ + { + "text": "\n\nThis is indeed a test", + "index": 0, + "logprobs": null, + "finish_reason": "length" + } + ], + "usage": { + "prompt_tokens": 5, + "completion_tokens": 7, + "total_tokens": 12 + } + } '400': description: Invalid completion request or incompatible request parameters. content: @@ -21222,6 +21385,9 @@ paths: application/json: schema: $ref: '#/components/schemas/Response' + text/event-stream: + schema: + $ref: '#/components/schemas/ResponseStreamEvent' '404': description: The response was not found. content: @@ -21715,6 +21881,9 @@ paths: application/json: schema: $ref: '#/components/schemas/RunObject' + text/event-stream: + schema: + $ref: '#/components/schemas/AssistantStreamEvent' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -22999,6 +23168,9 @@ paths: application/json: schema: $ref: '#/components/schemas/RunObject' + text/event-stream: + schema: + $ref: '#/components/schemas/AssistantStreamEvent' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -23939,6 +24111,9 @@ paths: application/json: schema: $ref: '#/components/schemas/RunObject' + text/event-stream: + schema: + $ref: '#/components/schemas/AssistantStreamEvent' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -30363,11 +30538,72 @@ paths: "total_tokens": 42 } } - /agents/environments: + /agents/automations: + post: + operationId: createAgentAutomation + summary: Create an automation + description: Saves an active automation without invoking it immediately. + tags: + - Agents + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAutomationParams' + required: true + responses: + '201': + description: The created automation. + content: + application/json: + schema: + $ref: '#/components/schemas/AutomationResource' + '400': + description: The request was invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '401': + description: Authentication or project context was missing. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '403': + description: The API key lacks the required permission. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '404': + description: The requested session or event was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current session state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '500': + description: An internal error occurred. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '503': + description: The service is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' get: - operationId: listAgentEnvironments - summary: List agent environments - description: Lists OpenAI-hosted environments owned by the authenticated principal. Requires access to the prewarming beta. + operationId: listAgentAutomations + summary: List automations + description: Lists project-owned automations, optionally filtered by target session. tags: - Agents parameters: @@ -30396,20 +30632,59 @@ paths: minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. - - name: type + - name: session_id in: query required: false schema: - $ref: '#/components/schemas/EnvironmentTypeParam' - description: The hosting type to list. Defaults to `openai_hosted`. + type: string + minLength: 0 + maxLength: 1048576 + description: Matches existing-session targets, including agent-created automations. responses: '200': - description: A page of owned environments. + description: The automations. content: application/json: schema: - $ref: '#/components/schemas/AgentEnvironmentListResource' - description: An ID-paginated list of owned environments. + type: object + properties: + object: + type: string + enum: + - list + default: list + x-stainless-const: true + description: The object type, which is always `list`. + data: + type: array + items: + $ref: '#/components/schemas/AutomationResource' + minItems: 0 + maxItems: 2000 + description: The resources returned in this page, in the requested sort order. + first_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the first resource in `data`, or `null` if the page is empty. + last_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. + has_more: + type: boolean + description: Whether there are more resources to retrieve after this page. + required: + - object + - data + - first_id + - last_id + - has_more + additionalProperties: false + description: A page of Agents API resources, with IDs for retrieving additional pages. '400': description: The request was invalid. content: @@ -30429,13 +30704,13 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested environment or referenced resource was not found. + description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current environment state. + description: The request conflicted with the current session state. content: application/json: schema: @@ -30446,40 +30721,40 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' + '501': + description: Automation listing is not implemented. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - post: - operationId: createAgentEnvironment - summary: Create an agent environment - description: Creates an OpenAI-hosted environment before creating a session. Requires access to the prewarming beta. + /agents/automations/{automation_id}: + get: + operationId: getAgentAutomation + summary: Get an automation + description: Retrieves a project-owned automation. tags: - Agents parameters: - - name: Idempotency-Key - in: header - required: false + - name: automation_id + in: path + required: true schema: type: string - minLength: 1 - maxLength: 256 - description: Deduplicates creation for 24 hours within the authenticated organization, project, and creator. Retry the same JSON parameters with the same key to retrieve the original environment in its current state. Different parameters or an incomplete hosted creation return 409. Deleted environments are not recreated. After retention expires, the key may create a new environment. Without this header, each request creates a new environment. - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateAgentEnvironmentParams' - required: true + minLength: 0 + maxLength: 1048576 responses: - '201': - description: The created OpenAI-hosted environment. + '200': + description: Successful response. content: application/json: schema: - $ref: '#/components/schemas/PublicEnvironmentResource' + $ref: '#/components/schemas/AutomationResource' '400': description: The request was invalid. content: @@ -30499,19 +30774,13 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested environment or referenced resource was not found. + description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current environment state. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse-2' - '429': - description: The request exceeded a rate or capacity limit. + description: The request conflicted with the current session state. content: application/json: schema: @@ -30528,29 +30797,33 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/environments/{environment_id}: - get: - operationId: retrieveAgentEnvironment - summary: Retrieve an agent environment - description: Retrieves an execution environment's connection status and safe installed metadata. See [environment lifecycle](https://developers.openai.com/api/docs/guides/agents-api/environments/lifecycle). + post: + operationId: updateAgentAutomation + summary: Update an automation + description: Updates supplied fields; target and metadata replace the whole field. tags: - Agents parameters: - - name: environment_id + - name: automation_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the environment. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAutomationParams' + required: true responses: '200': - description: The requested environment. + description: Successful response. content: application/json: schema: - $ref: '#/components/schemas/PublicEnvironmentResource' + $ref: '#/components/schemas/AutomationResource' '400': description: The request was invalid. content: @@ -30593,64 +30866,27 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/environments/{environment_id}/files: - get: - operationId: listAgentEnvironmentFiles - summary: List agent environment files - description: Lists live files on a connected execution environment with optional directory filtering and opaque cursor pagination. See [environment files](https://developers.openai.com/api/docs/guides/agents-api/environments/files). + delete: + operationId: deleteAgentAutomation + summary: Delete an automation + description: Deletes the automation and prevents future invocations without deleting its target session. tags: - Agents parameters: - - name: environment_id + - name: automation_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the environment. - - name: path - in: query - required: false - schema: - type: - - string - - 'null' - minLength: 0 - maxLength: 1048576 - description: Restrict the listing to this absolute workspace directory. - - name: limit - in: query - required: false - schema: - type: - - integer - - 'null' - format: int64 - minimum: 1 - maximum: 100 - description: The maximum number of files to return, between 1 and 100. - - name: order - in: query - required: false - schema: - $ref: '#/components/schemas/ListOrderParam' - description: Sort by case-sensitive path components. Defaults to descending. - - name: page - in: query - required: false - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The opaque token from the previous page. Keep the same path, order, and limit. responses: '200': - description: A page of live environment files. + description: Successful response. content: application/json: schema: - $ref: '#/components/schemas/EnvironmentFileListResource' + $ref: '#/components/schemas/DeletedAutomationResource' '400': description: The request was invalid. content: @@ -30693,37 +30929,28 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' + /agents/automations/{automation_id}/pause: post: - operationId: createAgentEnvironmentFile - summary: Write an agent environment file - description: Copies inline bytes or a Files API file into a connected execution environment, replacing an existing regular file at the same path. Upload between turns and wait for success before starting the next turn. See [environment files](https://developers.openai.com/api/docs/guides/agents-api/environments/files). + operationId: pauseAgentAutomation + summary: Pause an automation + description: Pauses future scheduled delivery without stopping an active session. tags: - Agents parameters: - - name: environment_id + - name: automation_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the environment. - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/HostedEnvironmentFileParam' - example: - type: inline - path: /workspace/example.txt - data: SGVsbG8K responses: - '201': - description: The written live environment file. + '200': + description: Successful response. content: application/json: schema: - $ref: '#/components/schemas/EnvironmentFileResource' + $ref: '#/components/schemas/AutomationResource' '400': description: The request was invalid. content: @@ -30754,12 +30981,6 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - '429': - description: The Files API rate limit for your user has been exceeded. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: @@ -30772,92 +30993,28 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/subagents: - get: - operationId: listAgentSessionSubagents - summary: List session subagents - description: Lists subagents in a session, including nested and closed subagents. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent). + /agents/automations/{automation_id}/resume: + post: + operationId: resumeAgentAutomation + summary: Resume an automation + description: Resumes scheduled delivery; one-time automations without a pending invocation require a future run_at. tags: - Agents parameters: - - name: session_id + - name: automation_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the session. - - name: limit - in: query - required: false - schema: - type: integer - format: int64 - minimum: 1 - maximum: 100 - default: 20 - description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - - name: order - in: query - required: false - schema: - $ref: '#/components/schemas/ListOrderParam' - default: desc - description: The order in which resources are returned. Defaults to `desc`. - - name: after - in: query - required: false - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: Return resources after this resource ID in the selected order. responses: '200': - description: The requested subagents. + description: Successful response. content: application/json: schema: - type: object - properties: - object: - type: string - enum: - - list - default: list - x-stainless-const: true - description: The object type, which is always `list`. - data: - type: array - items: - $ref: '#/components/schemas/SubagentResource' - minItems: 0 - maxItems: 2000 - description: The resources returned in this page, in the requested sort order. - first_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the first resource in `data`, or `null` if the page is empty. - last_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - has_more: - type: boolean - description: Whether there are more resources to retrieve after this page. - required: - - object - - data - - first_id - - last_id - - has_more - additionalProperties: false - description: A page of Agents API resources, with IDs for retrieving additional pages. + $ref: '#/components/schemas/AutomationResource' '400': description: The request was invalid. content: @@ -30900,37 +31057,28 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/subagents/{subagent_id}: - get: - operationId: retrieveAgentSessionSubagent - summary: Retrieve a session subagent - description: Retrieves a subagent belonging to this session. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent). + /agents/automations/{automation_id}/invocations: + post: + operationId: createAgentAutomationInvocation + summary: Invoke an automation + description: Queues a manual delivery without changing the saved schedule. tags: - Agents parameters: - - name: session_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the session. - - name: subagent_id + - name: automation_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the subagent in this session. responses: '200': - description: The requested subagent. + description: The queued invocation. content: application/json: schema: - $ref: '#/components/schemas/SubagentResource' + $ref: '#/components/schemas/AutomationInvocationResource' '400': description: The request was invalid. content: @@ -30973,30 +31121,20 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/subagents/{subagent_id}/items: get: - operationId: listAgentSessionSubagentItems - summary: List subagent items - description: Lists this subagent's own items across all of its turns. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent). + operationId: listAgentAutomationInvocations + summary: List automation invocations + description: Lists delivery records for a project-owned automation. tags: - Agents parameters: - - name: session_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the session. - - name: subagent_id + - name: automation_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the subagent in this session. - name: limit in: query required: false @@ -31024,11 +31162,49 @@ paths: description: Return resources after this resource ID in the selected order. responses: '200': - description: The requested subagent history. + description: The invocation history. content: application/json: schema: - $ref: '#/components/schemas/SessionItemListResource' + type: object + properties: + object: + type: string + enum: + - list + default: list + x-stainless-const: true + description: The object type, which is always `list`. + data: + type: array + items: + $ref: '#/components/schemas/AutomationInvocationResource' + minItems: 0 + maxItems: 2000 + description: The resources returned in this page, in the requested sort order. + first_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the first resource in `data`, or `null` if the page is empty. + last_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. + has_more: + type: boolean + description: Whether there are more resources to retrieve after this page. + required: + - object + - data + - first_id + - last_id + - has_more + additionalProperties: false + description: A page of Agents API resources, with IDs for retrieving additional pages. '400': description: The request was invalid. content: @@ -31065,36 +31241,97 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' + '501': + description: This operation is not implemented. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/subagents/{subagent_id}/turns: + /agents/automations/{automation_id}/invocations/{invocation_id}: get: - operationId: listAgentSessionSubagentTurns - summary: List subagent turns - description: Lists all turns of this subagent, including turns after a resume. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent). + operationId: getAgentAutomationInvocation + summary: Get an automation invocation + description: Retrieves a delivery record for a project-owned automation. tags: - Agents parameters: - - name: session_id + - name: automation_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the session. - - name: subagent_id + - name: invocation_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the subagent in this session. + responses: + '200': + description: The invocation. + content: + application/json: + schema: + $ref: '#/components/schemas/AutomationInvocationResource' + '400': + description: The request was invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '401': + description: Authentication or project context was missing. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '403': + description: The API key lacks the required permission. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '404': + description: The requested session or event was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current session state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '500': + description: An internal error occurred. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '503': + description: The service is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + /agents/environments: + get: + operationId: listAgentEnvironments + summary: List agent environments + description: Lists OpenAI-hosted environments owned by the authenticated principal. Requires access to the prewarming beta. + tags: + - Agents + parameters: - name: limit in: query required: false @@ -31120,14 +31357,20 @@ paths: minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. + - name: type + in: query + required: false + schema: + $ref: '#/components/schemas/EnvironmentTypeParam' + description: The hosting type to list. Defaults to `openai_hosted`. responses: '200': - description: The requested subagent history. + description: A page of owned environments. content: application/json: schema: - $ref: '#/components/schemas/SessionTurnListResource' - description: A page of turns from an agent session or subagent. + $ref: '#/components/schemas/AgentEnvironmentListResource' + description: An ID-paginated list of owned environments. '400': description: The request was invalid. content: @@ -31147,13 +31390,13 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested session or event was not found. + description: The requested environment or referenced resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current session state. + description: The request conflicted with the current environment state. content: application/json: schema: @@ -31170,45 +31413,34 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}: - get: - operationId: retrieveAgentSessionSubagentTurn - summary: Retrieve a subagent turn - description: Retrieves a turn belonging to this subagent. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent). + post: + operationId: createAgentEnvironment + summary: Create an agent environment + description: Creates an OpenAI-hosted environment before creating a session. Requires access to the prewarming beta. tags: - Agents parameters: - - name: session_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the session. - - name: subagent_id - in: path - required: true + - name: Idempotency-Key + in: header + required: false schema: type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the subagent in this session. - - name: turn_id - in: path + minLength: 1 + maxLength: 256 + description: Deduplicates creation for 24 hours within the authenticated organization, project, and creator. Retry the same JSON parameters with the same key to retrieve the original environment in its current state. Different parameters or an incomplete hosted creation return 409. Deleted environments are not recreated. After retention expires, the key may create a new environment. Without this header, each request creates a new environment. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAgentEnvironmentParams' required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of a turn belonging to this subagent. responses: - '200': - description: The requested subagent history. + '201': + description: The created OpenAI-hosted environment. content: application/json: schema: - $ref: '#/components/schemas/TurnResource' + $ref: '#/components/schemas/PublicEnvironmentResource' '400': description: The request was invalid. content: @@ -31228,13 +31460,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested session or event was not found. + description: The requested environment or referenced resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current session state. + description: The request conflicted with the current environment state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '429': + description: The request exceeded a rate or capacity limit. content: application/json: schema: @@ -31251,70 +31489,29 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items: + /agents/environments/{environment_id}: get: - operationId: listAgentSessionSubagentTurnItems - summary: List subagent turn items - description: Lists items belonging to one turn of this subagent. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent). + operationId: retrieveAgentEnvironment + summary: Retrieve an agent environment + description: Retrieves an execution environment's connection status and safe installed metadata. See [environment lifecycle](https://developers.openai.com/api/docs/guides/agents-api/environments/lifecycle). tags: - Agents parameters: - - name: session_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the session. - - name: subagent_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the subagent in this session. - - name: turn_id + - name: environment_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of a turn belonging to this subagent. - - name: limit - in: query - required: false - schema: - type: integer - format: int64 - minimum: 1 - maximum: 100 - default: 20 - description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - - name: order - in: query - required: false - schema: - $ref: '#/components/schemas/ListOrderParam' - default: desc - description: The order in which resources are returned. Defaults to `desc`. - - name: after - in: query - required: false - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: Return resources after this resource ID in the selected order. + description: The ID of the environment. responses: '200': - description: The requested subagent history. + description: The requested environment. content: application/json: schema: - $ref: '#/components/schemas/SessionItemListResource' + $ref: '#/components/schemas/PublicEnvironmentResource' '400': description: The request was invalid. content: @@ -31357,47 +31554,64 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents: + /agents/environments/{environment_id}/files: get: - operationId: listAgents - summary: List agents - description: Lists reusable agents in the current project. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration). + operationId: listAgentEnvironmentFiles + summary: List agent environment files + description: Lists live files on a connected execution environment with optional directory filtering and opaque cursor pagination. See [environment files](https://developers.openai.com/api/docs/guides/agents-api/environments/files). tags: - Agents parameters: + - name: environment_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the environment. + - name: path + in: query + required: false + schema: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: Restrict the listing to this absolute workspace directory. - name: limit in: query required: false schema: - type: integer + type: + - integer + - 'null' format: int64 minimum: 1 maximum: 100 - default: 20 - description: The maximum number of resources to return, between 1 and 100. Defaults to 20. + description: The maximum number of files to return, between 1 and 100. - name: order in: query required: false schema: $ref: '#/components/schemas/ListOrderParam' - default: desc - description: The order in which resources are returned. Defaults to `desc`. - - name: after + description: Sort by case-sensitive path components. Defaults to descending. + - name: page in: query required: false schema: type: string minLength: 0 maxLength: 1048576 - description: Return resources after this resource ID in the selected order. + description: The opaque token from the previous page. Keep the same path, order, and limit. responses: '200': - description: A page of agents. + description: A page of live environment files. content: application/json: schema: - $ref: '#/components/schemas/AgentListResource' - description: A page of reusable agents. + $ref: '#/components/schemas/EnvironmentFileListResource' '400': description: The request was invalid. content: @@ -31441,23 +31655,36 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' post: - operationId: createAgent - summary: Create an agent - description: Creates a reusable agent without storing credentials. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration). + operationId: createAgentEnvironmentFile + summary: Write an agent environment file + description: Copies inline bytes or a Files API file into a connected execution environment, replacing an existing regular file at the same path. Upload between turns and wait for success before starting the next turn. See [environment files](https://developers.openai.com/api/docs/guides/agents-api/environments/files). tags: - Agents + parameters: + - name: environment_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the environment. requestBody: content: application/json: schema: - $ref: '#/components/schemas/CreateAgentParams' + $ref: '#/components/schemas/HostedEnvironmentFileParam' + example: + type: inline + path: /workspace/example.txt + data: SGVsbG8K responses: '201': - description: The created agent. + description: The written live environment file. content: application/json: schema: - $ref: '#/components/schemas/AgentResource' + $ref: '#/components/schemas/EnvironmentFileResource' '400': description: The request was invalid. content: @@ -31488,6 +31715,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' + '429': + description: The Files API rate limit for your user has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: @@ -31500,36 +31733,99 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/{agent_id}: + /agents/sessions/{session_id}/subagents: get: - operationId: retrieveAgent - summary: Retrieve an agent - description: Retrieves a reusable agent by ID. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration). + operationId: listAgentSessionSubagents + summary: List session subagents + description: Lists subagents in a session, including nested and closed subagents. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent). tags: - Agents parameters: - - name: agent_id + - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the reusable agent. - responses: - '200': - description: The requested agent. - content: - application/json: - schema: - $ref: '#/components/schemas/AgentResource' - '400': - description: The request was invalid. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse-2' - '401': + description: The ID of the session. + - name: limit + in: query + required: false + schema: + type: integer + format: int64 + minimum: 1 + maximum: 100 + default: 20 + description: The maximum number of resources to return, between 1 and 100. Defaults to 20. + - name: order + in: query + required: false + schema: + $ref: '#/components/schemas/ListOrderParam' + default: desc + description: The order in which resources are returned. Defaults to `desc`. + - name: after + in: query + required: false + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: Return resources after this resource ID in the selected order. + responses: + '200': + description: The requested subagents. + content: + application/json: + schema: + type: object + properties: + object: + type: string + enum: + - list + default: list + x-stainless-const: true + description: The object type, which is always `list`. + data: + type: array + items: + $ref: '#/components/schemas/SubagentResource' + minItems: 0 + maxItems: 2000 + description: The resources returned in this page, in the requested sort order. + first_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the first resource in `data`, or `null` if the page is empty. + last_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. + has_more: + type: boolean + description: Whether there are more resources to retrieve after this page. + required: + - object + - data + - first_id + - last_id + - has_more + additionalProperties: false + description: A page of Agents API resources, with IDs for retrieving additional pages. + '400': + description: The request was invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '401': description: Authentication or project context was missing. content: application/json: @@ -31565,33 +31861,37 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - post: - operationId: updateAgent - summary: Update an agent - description: Updates a reusable agent. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration). + /agents/sessions/{session_id}/subagents/{subagent_id}: + get: + operationId: retrieveAgentSessionSubagent + summary: Retrieve a session subagent + description: Retrieves a subagent belonging to this session. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent). tags: - Agents parameters: - - name: agent_id + - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the reusable agent. - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateAgentParams' + description: The ID of the session. + - name: subagent_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the subagent in this session. responses: '200': - description: The updated agent. + description: The requested subagent. content: application/json: schema: - $ref: '#/components/schemas/AgentResource' + $ref: '#/components/schemas/SubagentResource' '400': description: The request was invalid. content: @@ -31634,173 +31934,62 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - x-oaiMeta: - examples: - request: - curl: | - # 1. Omit reasoning: keep its current settings while renaming the agent. - curl "https://api.openai.com/v1/agents/$AGENT_ID" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: agents=v1" \ - -d '{"name": "Renamed"}' - - # 2. Send null: reset reasoning to the model's defaults. - curl "https://api.openai.com/v1/agents/$AGENT_ID" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: agents=v1" \ - -d '{"reasoning": null}' - - # 3. Send an object: replace the entire reasoning configuration, without merging. - # The agent's model must support the "low" reasoning effort. - curl "https://api.openai.com/v1/agents/$AGENT_ID" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: agents=v1" \ - -d '{"reasoning": {"effort": "low"}}' - python: | - from openai import OpenAI - - client = OpenAI() - agent_id = "your-agent-id" - - # 1. Omit reasoning: keep its current settings while renaming the agent. - client.beta.agents.update(agent_id, name="Renamed") - - # 2. Python's None sends JSON null: reset reasoning to the model's defaults. - client.beta.agents.update(agent_id, reasoning=None) - - # 3. Send an object: replace the entire reasoning configuration, without merging. - # The agent's model must support the "low" reasoning effort. - client.beta.agents.update(agent_id, reasoning={"effort": "low"}) - javascript: | - import OpenAI from "openai"; - - const client = new OpenAI(); - const agentId = "your-agent-id"; - - // 1. Omit reasoning: keep its current settings while renaming the agent. - await client.beta.agents.update(agentId, { name: "Renamed" }); - - // 2. Send null: reset reasoning to the model's defaults. - await client.beta.agents.update(agentId, { reasoning: null }); - - // 3. Send an object: replace the entire reasoning configuration, without merging. - // The agent's model must support the "low" reasoning effort. - await client.beta.agents.update(agentId, { reasoning: { effort: "low" } }); - go: | - package main - - import ( - "context" - "log" - - "github.com/openai/openai-go/v3" - "github.com/openai/openai-go/v3/packages/param" - ) - - func main() { - client := openai.NewClient() - ctx := context.Background() - agentID := "your-agent-id" - - // 1. Omit reasoning: keep its current settings while renaming the agent. - _, err := client.Beta.Agents.Update(ctx, agentID, openai.BetaAgentUpdateParams{ - Name: openai.String("Renamed"), - }) - if err != nil { - log.Fatal(err) - } - - // 2. Send null: reset reasoning to the model's defaults. - _, err = client.Beta.Agents.Update(ctx, agentID, openai.BetaAgentUpdateParams{ - Reasoning: param.NullStruct[openai.AgentReasoningParam](), - }) - if err != nil { - log.Fatal(err) - } - - // 3. Send an object: replace the entire reasoning configuration, without merging. - // The agent's model must support the "low" reasoning effort. - _, err = client.Beta.Agents.Update(ctx, agentID, openai.BetaAgentUpdateParams{ - Reasoning: openai.AgentReasoningParam{Effort: openai.AgentReasoningParamEffortLow}, - }) - if err != nil { - log.Fatal(err) - } - } - java: | - import com.openai.client.OpenAIClient; - import com.openai.client.okhttp.OpenAIOkHttpClient; - import com.openai.core.JsonValue; - import com.openai.models.beta.agents.AgentReasoningParam; - import com.openai.models.beta.agents.AgentUpdateParams; - - public class AgentUpdateExample { - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - String agentId = "your-agent-id"; - - // 1. Omit reasoning: keep its current settings while renaming the agent. - client.beta().agents().update(AgentUpdateParams.builder() - .agentId(agentId) - .name("Renamed") - .build()); - - // 2. Send null: reset reasoning to the model's defaults. - client.beta().agents().update(AgentUpdateParams.builder() - .agentId(agentId) - .reasoning(JsonValue.from(null)) - .build()); - - // 3. Send an object: replace the entire reasoning configuration, without merging. - // The agent's model must support the "low" reasoning effort. - client.beta().agents().update(AgentUpdateParams.builder() - .agentId(agentId) - .reasoning(AgentReasoningParam.builder() - .effort(AgentReasoningParam.Effort.LOW) - .build()) - .build()); - } - } - ruby: | - require "openai" - - client = OpenAI::Client.new - agent_id = "your-agent-id" - - # 1. Omit reasoning: keep its current settings while renaming the agent. - client.beta.agents.update(agent_id, name: "Renamed") - - # 2. Ruby's nil sends JSON null: reset reasoning to the model's defaults. - client.beta.agents.update(agent_id, reasoning: nil) - - # 3. Send an object: replace the entire reasoning configuration, without merging. - # The agent's model must support the "low" reasoning effort. - client.beta.agents.update(agent_id, reasoning: {effort: :low}) - delete: - operationId: deleteAgent - summary: Delete an agent - description: Deletes a reusable agent. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration). + /agents/sessions/{session_id}/subagents/{subagent_id}/items: + get: + operationId: listAgentSessionSubagentItems + summary: List subagent items + description: Lists this subagent's own items across all of its turns. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent). tags: - Agents parameters: - - name: agent_id + - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the reusable agent. + description: The ID of the session. + - name: subagent_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the subagent in this session. + - name: limit + in: query + required: false + schema: + type: integer + format: int64 + minimum: 1 + maximum: 100 + default: 20 + description: The maximum number of resources to return, between 1 and 100. Defaults to 20. + - name: order + in: query + required: false + schema: + $ref: '#/components/schemas/ListOrderParam' + default: desc + description: The order in which resources are returned. Defaults to `desc`. + - name: after + in: query + required: false + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: Return resources after this resource ID in the selected order. responses: '200': - description: The deleted agent. + description: The requested subagent history. content: application/json: schema: - $ref: '#/components/schemas/DeletedAgentResource' + $ref: '#/components/schemas/SessionItemListResource' '400': description: The request was invalid. content: @@ -31843,14 +32032,30 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/environments/templates: + /agents/sessions/{session_id}/subagents/{subagent_id}/turns: get: - operationId: listAgentEnvironmentTemplates - summary: List agent environment templates - description: Lists reusable environment templates without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). + operationId: listAgentSessionSubagentTurns + summary: List subagent turns + description: Lists all turns of this subagent, including turns after a resume. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent). tags: - Agents parameters: + - name: session_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the session. + - name: subagent_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the subagent in this session. - name: limit in: query required: false @@ -31878,12 +32083,12 @@ paths: description: Return resources after this resource ID in the selected order. responses: '200': - description: A page of environment templates. + description: The requested subagent history. content: application/json: schema: - $ref: '#/components/schemas/EnvironmentTemplateListResource' - description: A page of reusable environment templates. + $ref: '#/components/schemas/SessionTurnListResource' + description: A page of turns from an agent session or subagent. '400': description: The request was invalid. content: @@ -31897,13 +32102,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required management permission. + description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested environment definition was not found. + description: The requested session or event was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current session state. content: application/json: schema: @@ -31920,24 +32131,45 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - post: - operationId: createAgentEnvironmentTemplate - summary: Create an agent environment template - description: Creates reusable environment configuration without returning confidential setup commands or environment values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). + /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}: + get: + operationId: retrieveAgentSessionSubagentTurn + summary: Retrieve a subagent turn + description: Retrieves a turn belonging to this subagent. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent). tags: - Agents - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateEnvironmentTemplateParams' + parameters: + - name: session_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the session. + - name: subagent_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the subagent in this session. + - name: turn_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of a turn belonging to this subagent. responses: - '201': - description: The created environment template. + '200': + description: The requested subagent history. content: application/json: schema: - $ref: '#/components/schemas/EnvironmentTemplateResource' + $ref: '#/components/schemas/TurnResource' '400': description: The request was invalid. content: @@ -31951,13 +32183,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required management permission. + description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested environment definition was not found. + description: The requested session or event was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current session state. content: application/json: schema: @@ -31974,29 +32212,70 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/environments/templates/{environment_template_id}: + /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items: get: - operationId: retrieveAgentEnvironmentTemplate - summary: Retrieve an agent environment template - description: Retrieves reusable environment configuration without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). + operationId: listAgentSessionSubagentTurnItems + summary: List subagent turn items + description: Lists items belonging to one turn of this subagent. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent). tags: - Agents parameters: - - name: environment_template_id + - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the reusable environment template. + description: The ID of the session. + - name: subagent_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the subagent in this session. + - name: turn_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of a turn belonging to this subagent. + - name: limit + in: query + required: false + schema: + type: integer + format: int64 + minimum: 1 + maximum: 100 + default: 20 + description: The maximum number of resources to return, between 1 and 100. Defaults to 20. + - name: order + in: query + required: false + schema: + $ref: '#/components/schemas/ListOrderParam' + default: desc + description: The order in which resources are returned. Defaults to `desc`. + - name: after + in: query + required: false + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: Return resources after this resource ID in the selected order. responses: '200': - description: The requested environment template. + description: The requested subagent history. content: application/json: schema: - $ref: '#/components/schemas/EnvironmentTemplateResource' + $ref: '#/components/schemas/SessionItemListResource' '400': description: The request was invalid. content: @@ -32010,13 +32289,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required management permission. + description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested environment definition was not found. + description: The requested session or event was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current session state. content: application/json: schema: @@ -32033,33 +32318,47 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - post: - operationId: updateAgentEnvironmentTemplate - summary: Update an agent environment template - description: Updates reusable environment configuration without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). + /agents: + get: + operationId: listAgents + summary: List agents + description: Lists reusable agents in the current project. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration). tags: - Agents parameters: - - name: environment_template_id - in: path - required: true + - name: limit + in: query + required: false + schema: + type: integer + format: int64 + minimum: 1 + maximum: 100 + default: 20 + description: The maximum number of resources to return, between 1 and 100. Defaults to 20. + - name: order + in: query + required: false + schema: + $ref: '#/components/schemas/ListOrderParam' + default: desc + description: The order in which resources are returned. Defaults to `desc`. + - name: after + in: query + required: false schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the reusable environment template. - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateEnvironmentTemplateParams' + description: Return resources after this resource ID in the selected order. responses: '200': - description: The updated environment template. + description: A page of agents. content: application/json: schema: - $ref: '#/components/schemas/EnvironmentTemplateResource' + $ref: '#/components/schemas/AgentListResource' + description: A page of reusable agents. '400': description: The request was invalid. content: @@ -32073,19 +32372,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required management permission. + description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested environment definition was not found. + description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current environment state. + description: The request conflicted with the current session state. content: application/json: schema: @@ -32102,28 +32401,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - delete: - operationId: deleteAgentEnvironmentTemplate - summary: Delete an agent environment template - description: Deletes reusable environment configuration and all confidential template inputs. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). + post: + operationId: createAgent + summary: Create an agent + description: Creates a reusable agent without storing credentials. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration). tags: - Agents - parameters: - - name: environment_template_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the reusable environment template. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAgentParams' responses: - '200': - description: The deleted environment template. + '201': + description: The created agent. content: application/json: schema: - $ref: '#/components/schemas/DeletedEnvironmentTemplateResource' + $ref: '#/components/schemas/AgentResource' '400': description: The request was invalid. content: @@ -32137,19 +32432,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required management permission. + description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested environment definition was not found. + description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current environment state. + description: The request conflicted with the current session state. content: application/json: schema: @@ -32166,55 +32461,29 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions: + /agents/{agent_id}: get: - operationId: listAgentSessions - summary: List agent sessions - description: Lists managed agent sessions using ID-based pagination and the requested sort order. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage). + operationId: retrieveAgent + summary: Retrieve an agent + description: Retrieves a reusable agent by ID. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration). tags: - Agents parameters: - - name: limit - in: query - required: false - schema: - type: integer - format: int64 - minimum: 1 - maximum: 100 - default: 20 - description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - - name: order - in: query - required: false - schema: - $ref: '#/components/schemas/ListOrderParam' - default: desc - description: The order in which resources are returned. Defaults to `desc`. - - name: after - in: query - required: false - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: Return resources after this resource ID in the selected order. - name: agent_id - in: query - required: false + in: path + required: true schema: type: string minLength: 0 maxLength: 1048576 - description: Only return sessions whose root agent has this ID. Omit to return sessions for all agents. + description: The ID of the reusable agent. responses: '200': - description: A page of sessions. + description: The requested agent. content: application/json: schema: - $ref: '#/components/schemas/SessionListResource' - description: A paginated list of sessions. + $ref: '#/components/schemas/AgentResource' '400': description: The request was invalid. content: @@ -32258,26 +32527,32 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' post: - operationId: createAgentSession - summary: Create an agent session - description: Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true. See [running sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions). + operationId: updateAgent + summary: Update an agent + description: Updates a reusable agent. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration). tags: - Agents + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the reusable agent. requestBody: content: application/json: schema: - $ref: '#/components/schemas/CreateAgentSessionParams' + $ref: '#/components/schemas/UpdateAgentParams' responses: - '201': - description: The created session or its event stream. + '200': + description: The updated agent. content: application/json: schema: - $ref: '#/components/schemas/SessionResource' - text/event-stream: - schema: - $ref: '#/components/schemas/SessionEvent' + $ref: '#/components/schemas/AgentResource' '400': description: The request was invalid. content: @@ -32308,12 +32583,6 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - '429': - description: The Files API rate limit for your user has been exceeded. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse-2' '500': description: An internal error occurred. content: @@ -32326,32 +32595,173 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - x-oai-streaming: - request_field: stream - response_status_code: 201 - /agents/sessions/{session_id}: - get: - operationId: retrieveAgentSession - summary: Retrieve an agent session - description: Retrieves the current state of a managed agent session. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage). + x-oaiMeta: + examples: + request: + curl: | + # 1. Omit reasoning: keep its current settings while renaming the agent. + curl "https://api.openai.com/v1/agents/$AGENT_ID" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: agents=v1" \ + -d '{"name": "Renamed"}' + + # 2. Send null: reset reasoning to the model's defaults. + curl "https://api.openai.com/v1/agents/$AGENT_ID" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: agents=v1" \ + -d '{"reasoning": null}' + + # 3. Send an object: replace the entire reasoning configuration, without merging. + # The agent's model must support the "low" reasoning effort. + curl "https://api.openai.com/v1/agents/$AGENT_ID" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: agents=v1" \ + -d '{"reasoning": {"effort": "low"}}' + python: | + from openai import OpenAI + + client = OpenAI() + agent_id = "your-agent-id" + + # 1. Omit reasoning: keep its current settings while renaming the agent. + client.beta.agents.update(agent_id, name="Renamed") + + # 2. Python's None sends JSON null: reset reasoning to the model's defaults. + client.beta.agents.update(agent_id, reasoning=None) + + # 3. Send an object: replace the entire reasoning configuration, without merging. + # The agent's model must support the "low" reasoning effort. + client.beta.agents.update(agent_id, reasoning={"effort": "low"}) + javascript: | + import OpenAI from "openai"; + + const client = new OpenAI(); + const agentId = "your-agent-id"; + + // 1. Omit reasoning: keep its current settings while renaming the agent. + await client.beta.agents.update(agentId, { name: "Renamed" }); + + // 2. Send null: reset reasoning to the model's defaults. + await client.beta.agents.update(agentId, { reasoning: null }); + + // 3. Send an object: replace the entire reasoning configuration, without merging. + // The agent's model must support the "low" reasoning effort. + await client.beta.agents.update(agentId, { reasoning: { effort: "low" } }); + go: | + package main + + import ( + "context" + "log" + + "github.com/openai/openai-go/v3" + "github.com/openai/openai-go/v3/packages/param" + ) + + func main() { + client := openai.NewClient() + ctx := context.Background() + agentID := "your-agent-id" + + // 1. Omit reasoning: keep its current settings while renaming the agent. + _, err := client.Beta.Agents.Update(ctx, agentID, openai.BetaAgentUpdateParams{ + Name: openai.String("Renamed"), + }) + if err != nil { + log.Fatal(err) + } + + // 2. Send null: reset reasoning to the model's defaults. + _, err = client.Beta.Agents.Update(ctx, agentID, openai.BetaAgentUpdateParams{ + Reasoning: param.NullStruct[openai.AgentReasoningParam](), + }) + if err != nil { + log.Fatal(err) + } + + // 3. Send an object: replace the entire reasoning configuration, without merging. + // The agent's model must support the "low" reasoning effort. + _, err = client.Beta.Agents.Update(ctx, agentID, openai.BetaAgentUpdateParams{ + Reasoning: openai.AgentReasoningParam{Effort: openai.AgentReasoningParamEffortLow}, + }) + if err != nil { + log.Fatal(err) + } + } + java: | + import com.openai.client.OpenAIClient; + import com.openai.client.okhttp.OpenAIOkHttpClient; + import com.openai.core.JsonValue; + import com.openai.models.beta.agents.AgentReasoningParam; + import com.openai.models.beta.agents.AgentUpdateParams; + + public class AgentUpdateExample { + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + String agentId = "your-agent-id"; + + // 1. Omit reasoning: keep its current settings while renaming the agent. + client.beta().agents().update(AgentUpdateParams.builder() + .agentId(agentId) + .name("Renamed") + .build()); + + // 2. Send null: reset reasoning to the model's defaults. + client.beta().agents().update(AgentUpdateParams.builder() + .agentId(agentId) + .reasoning(JsonValue.from(null)) + .build()); + + // 3. Send an object: replace the entire reasoning configuration, without merging. + // The agent's model must support the "low" reasoning effort. + client.beta().agents().update(AgentUpdateParams.builder() + .agentId(agentId) + .reasoning(AgentReasoningParam.builder() + .effort(AgentReasoningParam.Effort.LOW) + .build()) + .build()); + } + } + ruby: | + require "openai" + + client = OpenAI::Client.new + agent_id = "your-agent-id" + + # 1. Omit reasoning: keep its current settings while renaming the agent. + client.beta.agents.update(agent_id, name: "Renamed") + + # 2. Ruby's nil sends JSON null: reset reasoning to the model's defaults. + client.beta.agents.update(agent_id, reasoning: nil) + + # 3. Send an object: replace the entire reasoning configuration, without merging. + # The agent's model must support the "low" reasoning effort. + client.beta.agents.update(agent_id, reasoning: {effort: :low}) + delete: + operationId: deleteAgent + summary: Delete an agent + description: Deletes a reusable agent. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration). tags: - Agents parameters: - - name: session_id + - name: agent_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the session. + description: The ID of the reusable agent. responses: '200': - description: The requested session. + description: The deleted agent. content: application/json: schema: - $ref: '#/components/schemas/SessionResource' + $ref: '#/components/schemas/DeletedAgentResource' '400': description: The request was invalid. content: @@ -32394,33 +32804,47 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - post: - operationId: updateAgentSession - summary: Update an agent session - description: Updates session metadata, model, reasoning effort, or service tier. Model settings apply to subsequent turns. Omitted fields are unchanged. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage). + /agents/environments/templates: + get: + operationId: listAgentEnvironmentTemplates + summary: List agent environment templates + description: Lists reusable environment templates without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). tags: - Agents parameters: - - name: session_id - in: path - required: true + - name: limit + in: query + required: false + schema: + type: integer + format: int64 + minimum: 1 + maximum: 100 + default: 20 + description: The maximum number of resources to return, between 1 and 100. Defaults to 20. + - name: order + in: query + required: false + schema: + $ref: '#/components/schemas/ListOrderParam' + default: desc + description: The order in which resources are returned. Defaults to `desc`. + - name: after + in: query + required: false schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the session. - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateAgentSessionParams' + description: Return resources after this resource ID in the selected order. responses: '200': - description: The updated session. + description: A page of environment templates. content: application/json: schema: - $ref: '#/components/schemas/SessionResource' + $ref: '#/components/schemas/EnvironmentTemplateListResource' + description: A page of reusable environment templates. '400': description: The request was invalid. content: @@ -32434,19 +32858,13 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required permission. + description: The API key lacks the required management permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested session or event was not found. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse-2' - '409': - description: The request conflicted with the current session state. + description: The requested environment definition was not found. content: application/json: schema: @@ -32463,28 +32881,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - delete: - operationId: deleteAgentSession - summary: Delete an agent session - description: Removes a managed agent session from the public API and returns a deletion confirmation. If backend execution has ended, deletion can cancel a still-open public turn and abandon unpublished outputs. Running execution must be cancelled first. Physical cleanup may continue asynchronously. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage). + post: + operationId: createAgentEnvironmentTemplate + summary: Create an agent environment template + description: Creates reusable environment configuration without returning confidential setup commands or environment values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). tags: - Agents - parameters: - - name: session_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the session. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateEnvironmentTemplateParams' responses: - '200': - description: The deleted session. + '201': + description: The created environment template. content: application/json: schema: - $ref: '#/components/schemas/DeletedSessionResource' + $ref: '#/components/schemas/EnvironmentTemplateResource' '400': description: The request was invalid. content: @@ -32498,19 +32912,13 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required permission. + description: The API key lacks the required management permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested session or event was not found. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse-2' - '409': - description: The request conflicted with the current session state. + description: The requested environment definition was not found. content: application/json: schema: @@ -32527,65 +32935,29 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/artifacts: + /agents/environments/templates/{environment_template_id}: get: - operationId: listAgentSessionArtifacts - summary: List agent session artifacts - description: Lists immutable artifacts published by completed hosted session turns. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). + operationId: retrieveAgentEnvironmentTemplate + summary: Retrieve an agent environment template + description: Retrieves reusable environment configuration without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). tags: - Agents parameters: - - name: session_id + - name: environment_template_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the session. - - name: limit - in: query - required: false - schema: - type: integer - format: int64 - minimum: 1 - maximum: 100 - default: 20 - description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - - name: order - in: query - required: false - schema: - $ref: '#/components/schemas/ListOrderParam' - default: desc - description: The order in which resources are returned. Defaults to `desc`. - - name: after - in: query - required: false - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: Return resources after this resource ID in the selected order. - - name: environment_id - in: query - required: false - schema: - type: - - string - - 'null' - minLength: 0 - maxLength: 1048576 - description: Restrict the listing to artifacts produced by this environment. + description: The ID of the reusable environment template. responses: '200': - description: A page of durable session artifacts. + description: The requested environment template. content: application/json: schema: - $ref: '#/components/schemas/SessionArtifactListResource' - description: A page of durable artifacts published by a session. + $ref: '#/components/schemas/EnvironmentTemplateResource' '400': description: The request was invalid. content: @@ -32599,19 +32971,13 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required permission. + description: The API key lacks the required management permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested session or event was not found. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse-2' - '409': - description: The request conflicted with the current session state. + description: The requested environment definition was not found. content: application/json: schema: @@ -32628,37 +32994,33 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/artifacts/{artifact_id}: - get: - operationId: retrieveAgentSessionArtifact - summary: Retrieve an agent session artifact - description: Retrieves immutable metadata for one durable session artifact. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). + post: + operationId: updateAgentEnvironmentTemplate + summary: Update an agent environment template + description: Updates reusable environment configuration without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). tags: - Agents parameters: - - name: session_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the session that owns the artifact. - - name: artifact_id + - name: environment_template_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The immutable session artifact ID. + description: The ID of the reusable environment template. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateEnvironmentTemplateParams' responses: '200': - description: The requested session artifact. + description: The updated environment template. content: application/json: schema: - $ref: '#/components/schemas/SessionArtifactResource' + $ref: '#/components/schemas/EnvironmentTemplateResource' '400': description: The request was invalid. content: @@ -32672,19 +33034,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required permission. + description: The API key lacks the required management permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested session or event was not found. + description: The requested environment definition was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current session state. + description: The request conflicted with the current environment state. content: application/json: schema: @@ -32702,35 +33064,27 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' delete: - operationId: deleteAgentSessionArtifact - summary: Delete an agent session artifact - description: Deletes an immutable session artifact without deleting its live environment file or original Files API object. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). + operationId: deleteAgentEnvironmentTemplate + summary: Delete an agent environment template + description: Deletes reusable environment configuration and all confidential template inputs. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). tags: - Agents parameters: - - name: session_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the session that owns the artifact. - - name: artifact_id + - name: environment_template_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The immutable session artifact ID. + description: The ID of the reusable environment template. responses: '200': - description: The deleted session artifact. + description: The deleted environment template. content: application/json: schema: - $ref: '#/components/schemas/DeletedSessionArtifactResource' + $ref: '#/components/schemas/DeletedEnvironmentTemplateResource' '400': description: The request was invalid. content: @@ -32744,19 +33098,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required permission. + description: The API key lacks the required management permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested session or event was not found. + description: The requested environment definition was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current session state. + description: The request conflicted with the current environment state. content: application/json: schema: @@ -32773,38 +33127,55 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/artifacts/{artifact_id}/content: + /agents/sessions: get: - operationId: retrieveAgentSessionArtifactContent - summary: Retrieve agent session artifact content - description: Downloads immutable session artifact bytes after the execution environment expires. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). + operationId: listAgentSessions + summary: List agent sessions + description: Lists managed agent sessions using ID-based pagination and the requested sort order. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage). tags: - Agents parameters: - - name: session_id - in: path - required: true + - name: limit + in: query + required: false schema: - type: string - minLength: 0 + type: integer + format: int64 + minimum: 1 + maximum: 100 + default: 20 + description: The maximum number of resources to return, between 1 and 100. Defaults to 20. + - name: order + in: query + required: false + schema: + $ref: '#/components/schemas/ListOrderParam' + default: desc + description: The order in which resources are returned. Defaults to `desc`. + - name: after + in: query + required: false + schema: + type: string + minLength: 0 maxLength: 1048576 - description: The ID of the session that owns the artifact. - - name: artifact_id - in: path - required: true + description: Return resources after this resource ID in the selected order. + - name: agent_id + in: query + required: false schema: type: string minLength: 0 maxLength: 1048576 - description: The immutable session artifact ID. + description: Only return sessions whose root agent has this ID. Omit to return sessions for all agents. responses: '200': - description: The immutable artifact contents. + description: A page of sessions. content: - application/octet-stream: + application/json: schema: - type: string - format: binary + $ref: '#/components/schemas/SessionListResource' + description: A paginated list of sessions. '400': description: The request was invalid. content: @@ -32847,11 +33218,83 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/events: + post: + operationId: createAgentSession + summary: Create an agent session + description: Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true. See [running sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions). + tags: + - Agents + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAgentSessionParams' + responses: + '201': + description: The created session or its event stream. + content: + application/json: + schema: + $ref: '#/components/schemas/SessionResource' + text/event-stream: + schema: + $ref: '#/components/schemas/SessionEvent' + '400': + description: The request was invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '401': + description: Authentication or project context was missing. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '403': + description: The API key lacks the required permission. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '404': + description: The requested session or event was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current session state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '429': + description: The Files API rate limit for your user has been exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '500': + description: An internal error occurred. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '503': + description: The service is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + x-oai-streaming: + request_field: stream + response_status_code: 201 + /agents/sessions/{session_id}: get: - operationId: listAgentSessionEvents - summary: Stream agent session events - description: Streams live events for an agent session. See [session events](https://developers.openai.com/api/docs/guides/agents-api/sessions/events). + operationId: retrieveAgentSession + summary: Retrieve an agent session + description: Retrieves the current state of a managed agent session. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage). tags: - Agents parameters: @@ -32865,11 +33308,11 @@ paths: description: The ID of the session. responses: '200': - description: A live stream of session events. + description: The requested session. content: - text/event-stream: + application/json: schema: - $ref: '#/components/schemas/SessionEvent' + $ref: '#/components/schemas/SessionResource' '400': description: The request was invalid. content: @@ -32912,13 +33355,10 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - x-oai-streaming: - request_field: null - response_status_code: 200 post: - operationId: createAgentSessionEvents - summary: Create agent session input events - description: Submits message, cancellation, tool-result, or computer-use approval-response events to a managed agent session. Cancellation can recover a still-open turn whose backend execution has ended by marking it cancelled and abandoning unpublished outputs. Saved results, published files, and existing terminal outcomes are preserved. HTTP 202 confirms acceptance, not durable completion. See [session events](https://developers.openai.com/api/docs/guides/agents-api/sessions/events). + operationId: updateAgentSession + summary: Update an agent session + description: Updates session metadata, model, reasoning effort, or service tier. Model settings apply to subsequent turns. Omitted fields are unchanged. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage). tags: - Agents parameters: @@ -32930,22 +33370,18 @@ paths: minLength: 0 maxLength: 1048576 description: The ID of the session. - - name: Idempotency-Key - in: header - required: false - schema: - type: string - minLength: 1 - maxLength: 256 - description: An optional client-generated key that makes retries of submitted messages idempotent. requestBody: content: application/json: schema: - $ref: '#/components/schemas/CreateSessionEventsParams' + $ref: '#/components/schemas/UpdateAgentSessionParams' responses: - '202': - description: The events were accepted. + '200': + description: The updated session. + content: + application/json: + schema: + $ref: '#/components/schemas/SessionResource' '400': description: The request was invalid. content: @@ -32988,11 +33424,10 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/items: - get: - operationId: listAgentSessionItems - summary: List agent session items - description: Lists items produced by the session's root agent, including its interactions with subagents. Each subagent has its own item history. See [inspecting agent output](https://developers.openai.com/api/docs/guides/agents-api/observability). + delete: + operationId: deleteAgentSession + summary: Delete an agent session + description: Removes a managed agent session from the public API and returns a deletion confirmation. If backend execution has ended, deletion can cancel a still-open public turn and abandon unpublished outputs. Running execution must be cancelled first. Physical cleanup may continue asynchronously. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage). tags: - Agents parameters: @@ -33004,38 +33439,13 @@ paths: minLength: 0 maxLength: 1048576 description: The ID of the session. - - name: limit - in: query - required: false - schema: - type: integer - format: int64 - minimum: 1 - maximum: 100 - default: 20 - description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - - name: order - in: query - required: false - schema: - $ref: '#/components/schemas/ListOrderParam' - default: desc - description: The order in which resources are returned. Defaults to `desc`. - - name: after - in: query - required: false - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: Return resources after this resource ID in the selected order. responses: '200': - description: A page of session items. + description: The deleted session. content: application/json: schema: - $ref: '#/components/schemas/SessionItemListResource' + $ref: '#/components/schemas/DeletedSessionResource' '400': description: The request was invalid. content: @@ -33078,11 +33488,11 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/traces: + /agents/sessions/{session_id}/artifacts: get: - operationId: listAgentSessionTraces - summary: List agent session traces - description: Lists published root-turn traces as OTLP JSON, ordered by turn creation time and ID. Unpublished traces are skipped. Each page returns data available when read; it does not wait for late traces. Trace reads and the JSON response are limited to 16 MiB per request. If the limit is exceeded, request fewer traces. + operationId: listAgentSessionArtifacts + summary: List agent session artifacts + description: Lists immutable artifacts published by completed hosted session turns. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). tags: - Agents parameters: @@ -33119,14 +33529,24 @@ paths: minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. + - name: environment_id + in: query + required: false + schema: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: Restrict the listing to artifacts produced by this environment. responses: '200': - description: A page of published session traces. + description: A page of durable session artifacts. content: application/json: schema: - $ref: '#/components/schemas/SessionTraceListResource' - description: A page of published session traces. + $ref: '#/components/schemas/SessionArtifactListResource' + description: A page of durable artifacts published by a session. '400': description: The request was invalid. content: @@ -33169,11 +33589,11 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/turns: + /agents/sessions/{session_id}/artifacts/{artifact_id}: get: - operationId: listAgentSessionTurns - summary: List agent session turns - description: Lists turns by creation time and turn ID. The after cursor is exclusive in the selected order. See [session turns](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage#inspect-session-turns). + operationId: retrieveAgentSessionArtifact + summary: Retrieve an agent session artifact + description: Retrieves immutable metadata for one durable session artifact. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). tags: - Agents parameters: @@ -33184,40 +33604,22 @@ paths: type: string minLength: 0 maxLength: 1048576 - description: The ID of the session. - - name: limit - in: query - required: false - schema: - type: integer - format: int64 - minimum: 1 - maximum: 100 - default: 20 - description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - - name: order - in: query - required: false - schema: - $ref: '#/components/schemas/ListOrderParam' - default: desc - description: The order in which resources are returned. Defaults to `desc`. - - name: after - in: query - required: false + description: The ID of the session that owns the artifact. + - name: artifact_id + in: path + required: true schema: type: string minLength: 0 maxLength: 1048576 - description: Return resources after this resource ID in the selected order. + description: The immutable session artifact ID. responses: '200': - description: A page of session turns. + description: The requested session artifact. content: application/json: schema: - $ref: '#/components/schemas/SessionTurnListResource' - description: A page of turns from an agent session or subagent. + $ref: '#/components/schemas/SessionArtifactResource' '400': description: The request was invalid. content: @@ -33260,11 +33662,10 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/turns/{turn_id}: - get: - operationId: retrieveAgentSessionTurn - summary: Retrieve an agent session turn - description: Retrieves a turn's current status, timestamps, usage, and error. Returns 404 if the turn does not belong to the session. See [session turns](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage#inspect-session-turns). + delete: + operationId: deleteAgentSessionArtifact + summary: Delete an agent session artifact + description: Deletes an immutable session artifact without deleting its live environment file or original Files API object. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). tags: - Agents parameters: @@ -33275,22 +33676,22 @@ paths: type: string minLength: 0 maxLength: 1048576 - description: The ID of the session that owns the turn. - - name: turn_id + description: The ID of the session that owns the artifact. + - name: artifact_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the turn. + description: The immutable session artifact ID. responses: '200': - description: The requested turn. + description: The deleted session artifact. content: application/json: schema: - $ref: '#/components/schemas/TurnResource' + $ref: '#/components/schemas/DeletedSessionArtifactResource' '400': description: The request was invalid. content: @@ -33333,11 +33734,11 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/turns/{turn_id}/items: + /agents/sessions/{session_id}/artifacts/{artifact_id}/content: get: - operationId: listAgentSessionTurnItems - summary: List agent session turn items - description: Lists items belonging to one root-agent turn, including its interactions with subagents. See [inspecting agent output](https://developers.openai.com/api/docs/guides/agents-api/observability). + operationId: retrieveAgentSessionArtifactContent + summary: Retrieve agent session artifact content + description: Downloads immutable session artifact bytes after the execution environment expires. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). tags: - Agents parameters: @@ -33348,47 +33749,164 @@ paths: type: string minLength: 0 maxLength: 1048576 - description: The ID of the session that owns the turn. - - name: turn_id + description: The ID of the session that owns the artifact. + - name: artifact_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the turn. - - name: limit - in: query - required: false - schema: - type: integer - format: int64 - minimum: 1 - maximum: 100 - default: 20 - description: The maximum number of resources to return, between 1 and 100. Defaults to 20. - - name: order - in: query - required: false - schema: - $ref: '#/components/schemas/ListOrderParam' - default: desc - description: The order in which resources are returned. Defaults to `desc`. - - name: after - in: query - required: false + description: The immutable session artifact ID. + responses: + '200': + description: The immutable artifact contents. + content: + application/octet-stream: + schema: + type: string + format: binary + '400': + description: The request was invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '401': + description: Authentication or project context was missing. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '403': + description: The API key lacks the required permission. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '404': + description: The requested session or event was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current session state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '500': + description: An internal error occurred. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '503': + description: The service is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + /agents/sessions/{session_id}/events: + get: + operationId: listAgentSessionEvents + summary: Stream agent session events + description: Streams live events for an agent session. See [session events](https://developers.openai.com/api/docs/guides/agents-api/sessions/events). + tags: + - Agents + parameters: + - name: session_id + in: path + required: true schema: type: string minLength: 0 maxLength: 1048576 - description: Return items after this cursor in the selected order. Pass the previous response's last_id, which can differ from the last item's ID. + description: The ID of the session. responses: '200': - description: A page of session turn items. + description: A live stream of session events. + content: + text/event-stream: + schema: + $ref: '#/components/schemas/SessionEvent' + '400': + description: The request was invalid. content: application/json: schema: - $ref: '#/components/schemas/SessionItemListResource' + $ref: '#/components/schemas/ErrorResponse-2' + '401': + description: Authentication or project context was missing. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '403': + description: The API key lacks the required permission. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '404': + description: The requested session or event was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current session state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '500': + description: An internal error occurred. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '503': + description: The service is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + x-oai-streaming: + request_field: null + response_status_code: 200 + post: + operationId: createAgentSessionEvents + summary: Create agent session input events + description: Submits message, cancellation, tool-result, or computer-use approval-response events to a managed agent session. Cancellation can recover a still-open turn whose backend execution has ended by marking it cancelled and abandoning unpublished outputs. Saved results, published files, and existing terminal outcomes are preserved. HTTP 202 confirms acceptance, not durable completion. See [session events](https://developers.openai.com/api/docs/guides/agents-api/sessions/events). + tags: + - Agents + parameters: + - name: session_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the session. + - name: Idempotency-Key + in: header + required: false + schema: + type: string + minLength: 1 + maxLength: 256 + description: An optional client-generated key that makes retries of submitted messages idempotent. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateSessionEventsParams' + responses: + '202': + description: The events were accepted. '400': description: The request was invalid. content: @@ -33431,14 +33949,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /vaults: + /agents/sessions/{session_id}/items: get: - operationId: listVaults - summary: List vaults - description: Lists vaults using ID-based pagination. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + operationId: listAgentSessionItems + summary: List agent session items + description: Lists items produced by the session's root agent, including its interactions with subagents. Each subagent has its own item history. See [inspecting agent output](https://developers.openai.com/api/docs/guides/agents-api/observability). tags: - - Vaults + - Agents parameters: + - name: session_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the session. - name: limit in: query required: false @@ -33464,38 +33990,13 @@ paths: minLength: 0 maxLength: 1048576 description: Return resources after this resource ID in the selected order. - - name: metadata - in: query - required: false - schema: - type: object - additionalProperties: - type: string - minLength: 0 - maxLength: 512 - propertyNames: - type: string - minLength: 1 - maxLength: 64 - minProperties: 0 - maxProperties: 16 - description: Exact string matches supplied as `metadata[key]=value`. All supplied pairs must match. Up to 16 pairs, with keys from 1 to 64 characters and values up to 512 characters. Filtering is eventually consistent; metadata changes may take time to appear. - style: deepObject - explode: true - - name: status - in: query - required: false - schema: - $ref: '#/components/schemas/VaultStatusFilterParam' - description: Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default. responses: '200': - description: A page of vaults. + description: A page of session items. content: application/json: schema: - $ref: '#/components/schemas/VaultListResource' - description: A page of vaults. + $ref: '#/components/schemas/SessionItemListResource' '400': description: The request was invalid. content: @@ -33509,19 +34010,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required management permission. + description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested vault or credential was not found. + description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current vault state. + description: The request conflicted with the current session state. content: application/json: schema: @@ -33538,24 +34039,55 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - post: - operationId: createVault - summary: Create a vault - description: Creates a vault for the current project. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + /agents/sessions/{session_id}/traces: + get: + operationId: listAgentSessionTraces + summary: List agent session traces + description: Lists published root-turn traces as OTLP JSON, ordered by turn creation time and ID. Unpublished traces are skipped. Each page returns data available when read; it does not wait for late traces. Trace reads and the JSON response are limited to 16 MiB per request. If the limit is exceeded, request fewer traces. tags: - - Vaults - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateVaultParams' + - Agents + parameters: + - name: session_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the session. + - name: limit + in: query + required: false + schema: + type: integer + format: int64 + minimum: 1 + maximum: 100 + default: 20 + description: The maximum number of resources to return, between 1 and 100. Defaults to 20. + - name: order + in: query + required: false + schema: + $ref: '#/components/schemas/ListOrderParam' + default: desc + description: The order in which resources are returned. Defaults to `desc`. + - name: after + in: query + required: false + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: Return resources after this resource ID in the selected order. responses: - '201': - description: The created vault. + '200': + description: A page of published session traces. content: application/json: schema: - $ref: '#/components/schemas/VaultResource' + $ref: '#/components/schemas/SessionTraceListResource' + description: A page of published session traces. '400': description: The request was invalid. content: @@ -33569,19 +34101,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required management permission. + description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested vault or credential was not found. + description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current vault state. + description: The request conflicted with the current session state. content: application/json: schema: @@ -33598,29 +34130,55 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /vaults/{vault_id}: + /agents/sessions/{session_id}/turns: get: - operationId: retrieveVault - summary: Retrieve a vault - description: Retrieves a vault by its ID. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + operationId: listAgentSessionTurns + summary: List agent session turns + description: Lists turns by creation time and turn ID. The after cursor is exclusive in the selected order. See [session turns](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage#inspect-session-turns). tags: - - Vaults + - Agents parameters: - - name: vault_id + - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the vault. + description: The ID of the session. + - name: limit + in: query + required: false + schema: + type: integer + format: int64 + minimum: 1 + maximum: 100 + default: 20 + description: The maximum number of resources to return, between 1 and 100. Defaults to 20. + - name: order + in: query + required: false + schema: + $ref: '#/components/schemas/ListOrderParam' + default: desc + description: The order in which resources are returned. Defaults to `desc`. + - name: after + in: query + required: false + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: Return resources after this resource ID in the selected order. responses: '200': - description: The requested vault. + description: A page of session turns. content: application/json: schema: - $ref: '#/components/schemas/VaultResource' + $ref: '#/components/schemas/SessionTurnListResource' + description: A page of turns from an agent session or subagent. '400': description: The request was invalid. content: @@ -33634,19 +34192,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required management permission. + description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested vault or credential was not found. + description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current vault state. + description: The request conflicted with the current session state. content: application/json: schema: @@ -33663,36 +34221,37 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - post: - operationId: updateVault - summary: Update a vault - description: Updates the name or metadata of an active vault. Omitted fields remain unchanged. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + /agents/sessions/{session_id}/turns/{turn_id}: + get: + operationId: retrieveAgentSessionTurn + summary: Retrieve an agent session turn + description: Retrieves a turn's current status, timestamps, usage, and error. Returns 404 if the turn does not belong to the session. See [session turns](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage#inspect-session-turns). tags: - - Vaults + - Agents parameters: - - name: vault_id + - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the vault. - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateVaultParams' - example: - name: Research vault + description: The ID of the session that owns the turn. + - name: turn_id + in: path required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the turn. responses: '200': - description: The updated vault. + description: The requested turn. content: application/json: schema: - $ref: '#/components/schemas/VaultResource' + $ref: '#/components/schemas/TurnResource' '400': description: The request was invalid. content: @@ -33706,19 +34265,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required management permission. + description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested vault or credential was not found. + description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current vault state. + description: The request conflicted with the current session state. content: application/json: schema: @@ -33735,28 +34294,62 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - delete: - operationId: deleteVault - summary: Delete a vault - description: Deletes a vault and all its credentials. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + /agents/sessions/{session_id}/turns/{turn_id}/items: + get: + operationId: listAgentSessionTurnItems + summary: List agent session turn items + description: Lists items belonging to one root-agent turn, including its interactions with subagents. See [inspecting agent output](https://developers.openai.com/api/docs/guides/agents-api/observability). tags: - - Vaults + - Agents parameters: - - name: vault_id + - name: session_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the vault. + description: The ID of the session that owns the turn. + - name: turn_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the turn. + - name: limit + in: query + required: false + schema: + type: integer + format: int64 + minimum: 1 + maximum: 100 + default: 20 + description: The maximum number of resources to return, between 1 and 100. Defaults to 20. + - name: order + in: query + required: false + schema: + $ref: '#/components/schemas/ListOrderParam' + default: desc + description: The order in which resources are returned. Defaults to `desc`. + - name: after + in: query + required: false + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: Return items after this cursor in the selected order. Pass the previous response's last_id, which can differ from the last item's ID. responses: '200': - description: The deleted vault. + description: A page of session turn items. content: application/json: schema: - $ref: '#/components/schemas/DeletedVaultResource' + $ref: '#/components/schemas/SessionItemListResource' '400': description: The request was invalid. content: @@ -33770,19 +34363,19 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' '403': - description: The API key lacks the required management permission. + description: The API key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '404': - description: The requested vault or credential was not found. + description: The requested session or event was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' '409': - description: The request conflicted with the current vault state. + description: The request conflicted with the current session state. content: application/json: schema: @@ -33799,22 +34392,14 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /vaults/{vault_id}/credentials: + /vaults: get: - operationId: listVaultCredentials - summary: List vault credentials - description: Lists a vault's credentials using ID-based pagination without returning secret values. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + operationId: listVaults + summary: List vaults + description: Lists vaults using ID-based pagination. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). tags: - Vaults parameters: - - name: vault_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the vault. - name: limit in: query required: false @@ -33866,12 +34451,12 @@ paths: description: Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default. responses: '200': - description: A page of vault credentials. + description: A page of vaults. content: application/json: schema: - $ref: '#/components/schemas/VaultCredentialListResource' - description: A page of credentials in a vault. + $ref: '#/components/schemas/VaultListResource' + description: A page of vaults. '400': description: The request was invalid. content: @@ -33915,32 +34500,23 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' post: - operationId: createVaultCredential - summary: Create a vault credential - description: Creates a vault credential. Secret values are write-only and are never returned. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + operationId: createVault + summary: Create a vault + description: Creates a vault for the current project. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). tags: - Vaults - parameters: - - name: vault_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the vault. requestBody: content: application/json: schema: - $ref: '#/components/schemas/CreateVaultCredentialParams' + $ref: '#/components/schemas/CreateVaultParams' responses: '201': - description: The created vault credential without secret values. + description: The created vault. content: application/json: schema: - $ref: '#/components/schemas/VaultCredentialResource' + $ref: '#/components/schemas/VaultResource' '400': description: The request was invalid. content: @@ -33983,11 +34559,11 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /vaults/{vault_id}/credentials/{credential_id}: + /vaults/{vault_id}: get: - operationId: retrieveVaultCredential - summary: Retrieve a vault credential - description: Retrieves vault credential metadata without returning secret values. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + operationId: retrieveVault + summary: Retrieve a vault + description: Retrieves a vault by its ID. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). tags: - Vaults parameters: @@ -33999,21 +34575,13 @@ paths: minLength: 0 maxLength: 1048576 description: The ID of the vault. - - name: credential_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the vault credential. responses: '200': - description: The requested vault credential without secret values. + description: The requested vault. content: application/json: schema: - $ref: '#/components/schemas/VaultCredentialResource' + $ref: '#/components/schemas/VaultResource' '400': description: The request was invalid. content: @@ -34057,9 +34625,9 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse-2' post: - operationId: rotateVaultCredential - summary: Update a vault credential - description: Updates credential metadata or rotates its write-only secret. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + operationId: updateVault + summary: Update a vault + description: Updates the name or metadata of an active vault. Omitted fields remain unchanged. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). tags: - Vaults parameters: @@ -34071,9 +34639,402 @@ paths: minLength: 0 maxLength: 1048576 description: The ID of the vault. - - name: credential_id - in: path - required: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateVaultParams' + example: + name: Research vault + required: true + responses: + '200': + description: The updated vault. + content: + application/json: + schema: + $ref: '#/components/schemas/VaultResource' + '400': + description: The request was invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '401': + description: Authentication or project context was missing. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '403': + description: The API key lacks the required management permission. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '404': + description: The requested vault or credential was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current vault state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '500': + description: An internal error occurred. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '503': + description: The service is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + delete: + operationId: deleteVault + summary: Delete a vault + description: Deletes a vault and all its credentials. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + tags: + - Vaults + parameters: + - name: vault_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the vault. + responses: + '200': + description: The deleted vault. + content: + application/json: + schema: + $ref: '#/components/schemas/DeletedVaultResource' + '400': + description: The request was invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '401': + description: Authentication or project context was missing. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '403': + description: The API key lacks the required management permission. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '404': + description: The requested vault or credential was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current vault state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '500': + description: An internal error occurred. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '503': + description: The service is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + /vaults/{vault_id}/credentials: + get: + operationId: listVaultCredentials + summary: List vault credentials + description: Lists a vault's credentials using ID-based pagination without returning secret values. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + tags: + - Vaults + parameters: + - name: vault_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the vault. + - name: limit + in: query + required: false + schema: + type: integer + format: int64 + minimum: 1 + maximum: 100 + default: 20 + description: The maximum number of resources to return, between 1 and 100. Defaults to 20. + - name: order + in: query + required: false + schema: + $ref: '#/components/schemas/ListOrderParam' + default: desc + description: The order in which resources are returned. Defaults to `desc`. + - name: after + in: query + required: false + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: Return resources after this resource ID in the selected order. + - name: metadata + in: query + required: false + schema: + type: object + additionalProperties: + type: string + minLength: 0 + maxLength: 512 + propertyNames: + type: string + minLength: 1 + maxLength: 64 + minProperties: 0 + maxProperties: 16 + description: Exact string matches supplied as `metadata[key]=value`. All supplied pairs must match. Up to 16 pairs, with keys from 1 to 64 characters and values up to 512 characters. Filtering is eventually consistent; metadata changes may take time to appear. + style: deepObject + explode: true + - name: status + in: query + required: false + schema: + $ref: '#/components/schemas/VaultStatusFilterParam' + description: Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default. + responses: + '200': + description: A page of vault credentials. + content: + application/json: + schema: + $ref: '#/components/schemas/VaultCredentialListResource' + description: A page of credentials in a vault. + '400': + description: The request was invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '401': + description: Authentication or project context was missing. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '403': + description: The API key lacks the required management permission. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '404': + description: The requested vault or credential was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current vault state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '500': + description: An internal error occurred. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '503': + description: The service is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + post: + operationId: createVaultCredential + summary: Create a vault credential + description: Creates a vault credential. Secret values are write-only and are never returned. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + tags: + - Vaults + parameters: + - name: vault_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the vault. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateVaultCredentialParams' + responses: + '201': + description: The created vault credential without secret values. + content: + application/json: + schema: + $ref: '#/components/schemas/VaultCredentialResource' + '400': + description: The request was invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '401': + description: Authentication or project context was missing. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '403': + description: The API key lacks the required management permission. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '404': + description: The requested vault or credential was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current vault state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '500': + description: An internal error occurred. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '503': + description: The service is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + /vaults/{vault_id}/credentials/{credential_id}: + get: + operationId: retrieveVaultCredential + summary: Retrieve a vault credential + description: Retrieves vault credential metadata without returning secret values. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + tags: + - Vaults + parameters: + - name: vault_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the vault. + - name: credential_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the vault credential. + responses: + '200': + description: The requested vault credential without secret values. + content: + application/json: + schema: + $ref: '#/components/schemas/VaultCredentialResource' + '400': + description: The request was invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '401': + description: Authentication or project context was missing. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '403': + description: The API key lacks the required management permission. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '404': + description: The requested vault or credential was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current vault state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '500': + description: An internal error occurred. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + '503': + description: The service is temporarily unavailable. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse-2' + post: + operationId: rotateVaultCredential + summary: Update a vault credential + description: Updates credential metadata or rotates its write-only secret. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults). + tags: + - Vaults + parameters: + - name: vault_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the vault. + - name: credential_id + in: path + required: true schema: type: string minLength: 0 @@ -35821,6 +36782,9 @@ paths: application/json: schema: $ref: '#/components/schemas/BetaResponse' + text/event-stream: + schema: + $ref: '#/components/schemas/BetaResponseStreamEvent' '404': description: The response was not found. content: @@ -36521,58 +37485,6 @@ paths: "object": "response.input_tokens", "input_tokens": 11 } - /audio/voices/{voice_id}: - delete: - operationId: deleteVoice - tags: - - Audio - summary: Delete voice - description: | - Deletes a voice created from a text prompt or an audio sample. - - Requires voice write permission and access to the voice's project. Access to voices created from recordings is limited to eligible customers. See the [custom voices guide](https://developers.openai.com/api/docs/guides/custom-voices). - - Deleting a voice does not delete its consent recording. Deleting an already deleted voice returns a 404 error. - parameters: - - in: path - name: voice_id - required: true - schema: - type: string - description: The ID of the voice to delete. - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/VoiceDeletedResource' - '400': - description: Invalid voice ID. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse' - '404': - description: The endpoint is unavailable or the voice was not found in the requested project. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse' - x-oaiMeta: - group: audio - examples: - request: - curl: | - curl https://api.openai.com/v1/audio/voices/voice_1234 \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_API_KEY" - response: | - { - "id": "voice_1234", - "object": "audio.voice.deleted", - "deleted": true - } webhooks: agent_environment_expired: post: @@ -36998,96 +37910,6 @@ webhooks: description: Return any 2xx status code to acknowledge receipt. A 410 Gone response also stops retries; other non-2xx responses are retried. components: schemas: - ImageGenToolCallError: - properties: - code: - anyOf: - - type: string - description: The error code. - - type: 'null' - type: - type: string - description: The error type. - message: - type: string - description: A description of the error. - param: - anyOf: - - type: string - description: The related request parameter. - - type: 'null' - moderation_details: - $ref: '#/components/schemas/ImageGenToolCallModerationDetails' - description: Public details for a `moderation_blocked` error, when available. - type: object - required: - - code - - type - - message - - param - ImageGenToolCallModerationDetails: - properties: - moderation_stage: - type: string - enum: - - input - - output - - unknown - description: The stage where moderation blocked the image generation call. - categories: - items: - type: string - type: array - description: Public moderation categories. New category values may be added over time. - type: object - required: - - moderation_stage - - categories - BetaImageGenToolCallError: - properties: - code: - anyOf: - - type: string - description: The error code. - - type: 'null' - type: - type: string - description: The error type. - message: - type: string - description: A description of the error. - param: - anyOf: - - type: string - description: The related request parameter. - - type: 'null' - moderation_details: - $ref: '#/components/schemas/BetaImageGenToolCallModerationDetails' - description: Public details for a `moderation_blocked` error, when available. - type: object - required: - - code - - type - - message - - param - BetaImageGenToolCallModerationDetails: - properties: - moderation_stage: - type: string - enum: - - input - - output - - unknown - description: The stage where moderation blocked the image generation call. - categories: - items: - type: string - type: array - description: Public moderation categories. New category values may be added over time. - type: object - required: - - moderation_stage - - categories AddUploadPartRequest: type: object additionalProperties: false @@ -37539,6 +38361,15 @@ components: - gpt-3.5-turbo-1106 - gpt-3.5-turbo-0125 - gpt-3.5-turbo-16k-0613 + x-openai-enum-deprecations: + gpt-4.1: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-4.1-mini: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-4o: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-4o-mini: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' AssistantToolsCode: type: object title: Code interpreter tool @@ -41495,6 +42326,7 @@ components: anyOf: - $ref: '#/components/schemas/ResponseFormatText' - $ref: '#/components/schemas/ResponseFormatJsonSchema' + x-openai-ruby-json-schema-input: true - $ref: '#/components/schemas/ResponseFormatJsonObject' audio: type: @@ -41514,7 +42346,8 @@ components: `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `nova`, `onyx`, `sage`, `shimmer`, `marin`, and `cedar`. You may also provide a custom voice object with an `id`, for example `{ "id": "voice_1234" }`. - Custom voices must be created from audio samples. Voices created from text prompts are supported only in Live. + Custom voices must be created from audio samples. Voices created from text + prompts are supported only in Live. format: type: string enum: @@ -41647,6 +42480,7 @@ components: propertyName: type x-stainless-go-variant-constructor: naming: chat_completion_{variant}_tool + x-openai-ruby-json-schema-input: true tool_choice: $ref: '#/components/schemas/ChatCompletionToolChoiceOption' parallel_tool_calls: @@ -41892,6 +42726,12 @@ components: index: type: integer description: The index of the choice in the list of choices. + x-openai-go-public-shape: + field_order: + - delta + - finish_reason + - index + - logprobs created: type: integer format: unixtime @@ -43347,11 +44187,18 @@ components: The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the `webp` or `jpeg` output formats, and defaults to 100. + safety_identifier: + type: + - string + - 'null' + maxLength: 128 + example: user-1234 + description: A stable identifier for an end user in your organization, used for safety monitoring and abuse detection. Hash a username or email address to avoid sending identifying information. A non-empty value takes precedence over the deprecated `user` parameter. If omitted, null, or empty, the API uses `user` when available. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). user: type: string example: user-1234 - description: 'Deprecated: use `safety_identifier` instead. This parameter remains accepted for backward compatibility and is used when `safety_identifier` is omitted, null, or empty. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).' deprecated: true + description: 'Deprecated: use `safety_identifier` instead. This parameter remains accepted for backward compatibility and is used when `safety_identifier` is omitted, null, or empty. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).' input_fidelity: anyOf: - $ref: '#/components/schemas/InputFidelity' @@ -43386,13 +44233,6 @@ components: example: high description: | The quality of the image that will be generated for GPT image models. The GPT image models support `low`, `medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Defaults to `auto`. - safety_identifier: - type: - - string - - 'null' - maxLength: 128 - example: user-1234 - description: A stable identifier for an end user in your organization, used for safety monitoring and abuse detection. Hash a username or email address to avoid sending identifying information. A non-empty value takes precedence over the deprecated `user` parameter. If omitted, null, or empty, the API uses `user` when available. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). required: - prompt - image @@ -43574,11 +44414,6 @@ components: example: vivid deprecated: true description: Legacy style parameter for retired image models. Unsupported for GPT image models; describe the desired style in the prompt instead. - user: - type: string - example: user-1234 - description: 'Deprecated: use `safety_identifier` instead. This parameter remains accepted for backward compatibility and is used when `safety_identifier` is omitted, null, or empty. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).' - deprecated: true safety_identifier: type: - string @@ -43586,6 +44421,11 @@ components: maxLength: 128 example: user-1234 description: A stable identifier for an end user in your organization, used for safety monitoring and abuse detection. Hash a username or email address to avoid sending identifying information. A non-empty value takes precedence over the deprecated `user` parameter. If omitted, null, or empty, the API uses `user` when available. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). + user: + type: string + example: user-1234 + deprecated: true + description: 'Deprecated: use `safety_identifier` instead. This parameter remains accepted for backward compatibility and is used when `safety_identifier` is omitted, null, or empty. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).' required: - prompt CreateImageVariationRequest: @@ -45256,6 +46096,45 @@ components: - name - audio_sample - consent + CreateVoicePromptRequest: + type: object + title: Prompt + description: Creates a synthetic voice from a text description. Supports application/json or multipart/form-data. + additionalProperties: false + properties: + type: + type: string + enum: + - prompt + description: Set to `prompt` to create a voice from a text description. + name: + type: string + minLength: 1 + maxLength: 256 + description: The name of the new voice. + prompt: + type: string + minLength: 1 + maxLength: 2000 + description: A description of the desired voice. Must not contain only whitespace. + script_hint: + type: string + minLength: 1 + maxLength: 2000 + description: Optional text for the voice to speak during creation. If omitted, a script is generated from the prompt. Must not be blank after trimming whitespace; scripts that are too short are rejected. + model: + anyOf: + - type: string + - type: string + enum: + - auto + - 2026-10-08 + default: auto + description: The voice creation model to use. Defaults to `auto`. + required: + - type + - name + - prompt CreateVoiceRequest: discriminator: propertyName: type @@ -45806,11 +46685,18 @@ components: default: auto example: 1024x1024 description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, 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. + safety_identifier: + type: + - string + - 'null' + maxLength: 128 + example: user-1234 + description: A stable identifier for an end user in your organization, used for safety monitoring and abuse detection. Hash a username or email address to avoid sending identifying information. A non-empty value takes precedence over the deprecated `user` parameter. If omitted, null, or empty, the API uses `user` when available. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). user: type: string example: user-1234 - description: 'Deprecated: use `safety_identifier` instead. This parameter remains accepted for backward compatibility and is used when `safety_identifier` is omitted, null, or empty. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).' deprecated: true + description: 'Deprecated: use `safety_identifier` instead. This parameter remains accepted for backward compatibility and is used when `safety_identifier` is omitted, null, or empty. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).' output_format: anyOf: - type: string @@ -45860,13 +46746,6 @@ components: description: Stream partial image results as events. partial_images: $ref: '#/components/schemas/PartialImages' - safety_identifier: - type: - - string - - 'null' - maxLength: 128 - example: user-1234 - description: A stable identifier for an end user in your organization, used for safety monitoring and abuse detection. Hash a username or email address to avoid sending identifying information. A non-empty value takes precedence over the deprecated `user` parameter. If omitted, null, or empty, the API uses `user` when available. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). required: - images - prompt @@ -49106,6 +49985,11 @@ components: description: | Emitted when image editing has completed and the final image is available. properties: + safety_identifier: + type: + - string + - 'null' + description: The effective safety identifier used for safety monitoring and abuse detection. This is the non-empty `safety_identifier` from the request, or the deprecated `user` value when `safety_identifier` is omitted, null, or empty. type: type: string description: | @@ -49162,11 +50046,6 @@ components: - jpeg usage: $ref: '#/components/schemas/ImagesUsage' - safety_identifier: - type: - - string - - 'null' - description: The effective safety identifier used for safety monitoring and abuse detection. This is the non-empty `safety_identifier` from the request, or the deprecated `user` value when `safety_identifier` is omitted, null, or empty. required: - type - b64_json @@ -49295,6 +50174,11 @@ components: description: | Emitted when image generation has completed and the final image is available. properties: + safety_identifier: + type: + - string + - 'null' + description: The effective safety identifier used for safety monitoring and abuse detection. This is the non-empty `safety_identifier` from the request, or the deprecated `user` value when `safety_identifier` is omitted, null, or empty. type: type: string description: | @@ -49351,11 +50235,6 @@ components: - jpeg usage: $ref: '#/components/schemas/ImagesUsage' - safety_identifier: - type: - - string - - 'null' - description: The effective safety identifier used for safety monitoring and abuse detection. This is the non-empty `safety_identifier` from the request, or the deprecated `user` value when `safety_identifier` is omitted, null, or empty. required: - type - b64_json @@ -49648,6 +50527,11 @@ components: title: Image generation response description: The response from the image generation endpoint. properties: + safety_identifier: + type: + - string + - 'null' + description: The effective safety identifier used for safety monitoring and abuse detection. This is the non-empty `safety_identifier` from the request, or the deprecated `user` value when `safety_identifier` is omitted, null, or empty. created: type: integer format: unixtime @@ -49691,11 +50575,6 @@ components: - max usage: $ref: '#/components/schemas/ImageGenUsage' - safety_identifier: - type: - - string - - 'null' - description: The effective safety identifier used for safety monitoring and abuse detection. This is the non-empty `safety_identifier` from the request, or the deprecated `user` value when `safety_identifier` is omitted, null, or empty. required: - created x-oaiMeta: @@ -50119,6 +50998,9 @@ components: ItemResource: description: | Content item used to generate a response. + x-openai-go-public-shape: + dispatch: + message: '#/components/schemas/OutputMessage' discriminator: propertyName: type anyOf: @@ -50621,6 +51503,8 @@ components: description: Startup audio output configuration. SIP negotiates the media format; audio.format is only accepted for primary WebSockets. Voice cannot change after startup. delegation: $ref: '#/components/schemas/delegation' + triggers: + $ref: '#/components/schemas/triggers' store: $ref: '#/components/schemas/store' input: @@ -50632,8 +51516,6 @@ components: default: live x-stainless-const: true description: The session type. Always `live`. - triggers: - $ref: '#/components/schemas/triggers' required: - model - type @@ -50789,14 +51671,14 @@ components: description: Startup audio configuration. WebRTC and SIP negotiate their audio format on the media transport. delegation: $ref: '#/components/schemas/delegation' + triggers: + $ref: '#/components/schemas/triggers' store: $ref: '#/components/schemas/store' input: $ref: '#/components/schemas/input' client: $ref: '#/components/schemas/LiveClientConfigParam' - triggers: - $ref: '#/components/schemas/triggers' required: - model additionalProperties: false @@ -51994,9 +52876,14 @@ components: description: The tools to add this file to. type: array items: + x-openai-go-public-shape: + variant_names: + '#/components/schemas/AssistantToolsFileSearchTypeOnly': FileSearchTool anyOf: - $ref: '#/components/schemas/AssistantToolsCode' - $ref: '#/components/schemas/AssistantToolsFileSearchTypeOnly' + x-openai-go-public-shape: + type_name: MessageAttachmentToolFileSearchTool description: A list of files attached to the message, and the tools they were added to. - type: 'null' metadata: @@ -52927,6 +53814,9 @@ components: - $ref: '#/components/schemas/RefusalContent' - $ref: '#/components/schemas/ReasoningTextContent' OutputItem: + x-openai-go-public-shape: + projection_sources: + content: '#/components/schemas/OutputMessage/properties/content' discriminator: propertyName: type anyOf: @@ -58719,7 +59609,7 @@ components: logprobs: anyOf: - type: array - description: 'The log probabilities of the transcription. These can be enabled by configurating the session with `"include": ["item.input_audio_transcription.logprobs"]`. Each entry in the array corresponds a log probability of which token would be selected for this chunk of transcription. This can help to identify if it was possible there were multiple valid options for a given chunk of transcription.' + description: 'The log probabilities of the transcription. These can be enabled by configuring the session with `"include": ["item.input_audio_transcription.logprobs"]`. Each entry in the array corresponds a log probability of which token would be selected for this chunk of transcription. This can help to identify if it was possible there were multiple valid options for a given chunk of transcription.' items: $ref: '#/components/schemas/LogProbProperties' - type: 'null' @@ -58941,7 +59831,7 @@ components: description: | Returned when an error occurs, which could be a client problem or a server problem. Most errors are recoverable and the session will stay open, we - recommend to implementors to monitor and log error messages by default. + recommend to implementers to monitor and log error messages by default. properties: event_id: type: string @@ -61079,8 +61969,10 @@ components: - gpt-audio-mini-2025-10-06 - gpt-audio-mini-2025-12-15 x-stainless-nominal: false + x-openai-go-public-type: string_alias description: | The Realtime model used for this session. + x-openai-go-public-type: string_alias instructions: type: string description: | @@ -63868,6 +64760,16 @@ components: description: | An error object returned when the model fails to generate a Response. properties: + type: + anyOf: + - type: string + - type: 'null' + description: The original error type, or null if it was not recorded. + param: + anyOf: + - type: string + - type: 'null' + description: The request parameter associated with the error, or null if none was recorded. code: $ref: '#/components/schemas/ResponseErrorCode' message: @@ -63876,16 +64778,6 @@ components: A human-readable description of the error. misalignment: $ref: '#/components/schemas/MisalignmentErrorDetailsResource' - param: - anyOf: - - type: string - - type: 'null' - description: The request parameter associated with the error, or null if none was recorded. - type: - anyOf: - - type: string - - type: 'null' - description: The original error type, or null if it was not recorded. required: - code - message @@ -64189,6 +65081,7 @@ components: schema: $ref: '#/components/schemas/ResponseFormatJsonSchemaSchema' x-openai-ruby-json-schema-input: true + x-openai-go-public-type: any strict: anyOf: - type: boolean @@ -66283,6 +67176,7 @@ components: - $ref: '#/components/schemas/ResponseShellCallOutputContentDeltaStreamingEvent' x-stainless-skip: - go + x-openai-go-include-union-variant: true - $ref: '#/components/schemas/ResponseShellCallOutputContentDoneStreamingEvent' - $ref: '#/components/schemas/ResponseInProgressEvent' - $ref: '#/components/schemas/ResponseFailedEvent' @@ -69192,6 +70086,7 @@ components: anyOf: - $ref: '#/components/schemas/ResponseFormatText' - $ref: '#/components/schemas/TextResponseFormatJsonSchema' + x-openai-ruby-json-schema-input: true - $ref: '#/components/schemas/ResponseFormatJsonObject' discriminator: propertyName: type @@ -69343,6 +70238,7 @@ components: propertyName: type anyOf: - $ref: '#/components/schemas/FunctionTool' + x-openai-ruby-json-schema-input: true - $ref: '#/components/schemas/FileSearchTool' - $ref: '#/components/schemas/ComputerTool' - $ref: '#/components/schemas/ComputerUsePreviewTool' @@ -70315,6 +71211,11 @@ components: input_cache_write_tokens: type: integer description: The aggregated number of input tokens written to the cache across 30-minute and 12-hour retention periods. + input_cache_write_30m_tokens: + anyOf: + - type: integer + description: The aggregated number of input tokens written to the cache with a 30-minute retention period. May be absent or null for older responses. + - type: 'null' input_cache_write_12h_tokens: type: integer description: The aggregated number of input tokens written to the cache with a 12-hour retention period. @@ -70384,11 +71285,6 @@ components: - type: string description: When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - type: 'null' - input_cache_write_30m_tokens: - anyOf: - - type: integer - description: The aggregated number of input tokens written to the cache with a 30-minute retention period. May be absent or null for older responses. - - type: 'null' required: - object - input_tokens @@ -71738,6 +72634,35 @@ components: "language": "en-US", "created_at": 1734220800 } + VoiceDeletedResource: + type: object + additionalProperties: false + properties: + id: + type: string + description: The voice identifier. + example: voice_1234 + object: + type: string + enum: + - audio.voice.deleted + x-stainless-const: true + description: The object type, which is always `audio.voice.deleted`. + deleted: + type: boolean + description: Whether the voice was deleted. + required: + - id + - object + - deleted + x-oaiMeta: + name: The voice deletion object + example: | + { + "id": "voice_1234", + "object": "audio.voice.deleted", + "deleted": true + } VoiceIdsOrCustomVoice: title: Voice description: | @@ -71843,6 +72768,9 @@ components: - type - url - pattern + x-stainless-naming: + go: + type_name: ResponseFunctionWebSearchActionFind WebSearchActionOpenPage: type: object title: Open page action @@ -72064,6 +72992,9 @@ components: description: | 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). + x-openai-go-public-shape: + variant_names: + '#/components/schemas/WebSearchActionFind': Find discriminator: propertyName: type anyOf: @@ -73767,6 +74698,12 @@ components: description: The breakpoint mode. Always `explicit`. default: explicit x-stainless-const: true + ttl: + type: string + enum: + - 30m + - 12h + description: The minimum lifetime of this cache breakpoint. Defaults to the request TTL. type: object required: - mode @@ -73991,6 +74928,12 @@ components: description: The breakpoint mode. Always `explicit`. default: explicit x-stainless-const: true + ttl: + type: string + enum: + - 30m + - 12h + description: The minimum lifetime of this cache breakpoint. Defaults to the request TTL. type: object required: - mode @@ -74509,6 +75452,51 @@ components: - completed - failed - incomplete + ImageGenToolCallModerationDetails: + properties: + moderation_stage: + type: string + enum: + - input + - output + - unknown + description: The stage where moderation blocked the image generation call. + categories: + items: + type: string + type: array + description: Public moderation categories. New category values may be added over time. + type: object + required: + - moderation_stage + - categories + ImageGenToolCallError: + properties: + code: + anyOf: + - type: string + description: The error code. + - type: 'null' + type: + type: string + description: The error type. + message: + type: string + description: A description of the error. + param: + anyOf: + - type: string + description: The related request parameter. + - type: 'null' + moderation_details: + $ref: '#/components/schemas/ImageGenToolCallModerationDetails' + description: Public details for a `moderation_blocked` error, when available. + type: object + required: + - code + - type + - message + - param ImageGenActionEnum: type: string enum: @@ -74529,9 +75517,6 @@ components: - jpeg ImageGenToolCall: properties: - error: - $ref: '#/components/schemas/ImageGenToolCallError' - description: Details of a moderation failure, when available. type: type: string enum: @@ -74554,6 +75539,10 @@ components: - type: string description: The generated image encoded in base64. - type: 'null' + error: + $ref: '#/components/schemas/ImageGenToolCallError' + description: Details of a moderation failure, when available. + x-openai-go-skip-union-projection: true size: anyOf: - anyOf: @@ -77351,6 +78340,11 @@ components: description: Delegate tasks to your application. The Live session emits delegation events that your backend handles. type: object properties: + acknowledgement_delay_ms: + description: Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400 for Decisions sessions and 0 (request immediately) for other sessions. Omission in a session update preserves the current value. Updates apply to subsequent delegations. + type: integer + minimum: 0 + maximum: 800 type: description: The delegation owner. Always `client` for tasks handled by your application. default: client @@ -78089,6 +79083,11 @@ components: description: Delegate tasks to a Responses model managed by the Live session. type: object properties: + acknowledgement_delay_ms: + description: Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400 for Decisions sessions and 0 (request immediately) for other sessions. Omission in a session update preserves the current value. Updates apply to subsequent delegations. + type: integer + minimum: 0 + maximum: 800 type: description: The delegation owner. Always `responses` for tasks handled by the Responses API. default: responses @@ -78103,6 +79102,130 @@ components: required: - type - responses + LiveDecisionChoiceParam: + type: object + properties: + value: + anyOf: + - type: string + - type: boolean + description: + type: string + required: + - value + LiveDecisionChoiceQuestionParam: + type: object + properties: + type: + default: choice + x-stainless-const: true + type: string + enum: + - choice + name: + type: string + instructions: + type: string + choices: + type: array + items: + $ref: '#/components/schemas/LiveDecisionChoiceParam' + minItems: 2 + maxItems: 255 + required: + - type + - instructions + - choices + LiveDecisionPredicateQuestionParam: + type: object + properties: + type: + default: predicate + x-stainless-const: true + type: string + enum: + - predicate + name: + type: string + instructions: + type: string + required: + - type + - instructions + LiveDecisionScoreLevelParam: + type: object + properties: + label: + type: string + description: + type: string + required: + - label + LiveDecisionScoreQuestionParam: + type: object + properties: + type: + default: score + x-stainless-const: true + type: string + enum: + - score + name: + type: string + instructions: + type: string + levels: + type: array + items: + $ref: '#/components/schemas/LiveDecisionScoreLevelParam' + minItems: 2 + maxItems: 10 + required: + - type + - instructions + - levels + LiveDecisionQuestion: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/LiveDecisionChoiceQuestionParam' + - $ref: '#/components/schemas/LiveDecisionPredicateQuestionParam' + - $ref: '#/components/schemas/LiveDecisionScoreQuestionParam' + LiveDecisionsSettingsInputParam: + type: object + properties: + questions: + description: Native Decision API questions evaluated together, in order. + type: array + items: + $ref: '#/components/schemas/QuestionParam' + minItems: 1 + maxItems: 64 + model: + type: string + minLength: 1 + required: + - questions + - model + LiveDecisionsDelegationParam: + type: object + properties: + acknowledgement_delay_ms: + description: Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400. Updates apply to subsequent delegations. + type: integer + minimum: 0 + maximum: 800 + type: + default: decisions + x-stainless-const: true + type: string + enum: + - decisions + decisions: + $ref: '#/components/schemas/LiveDecisionsSettingsInputParam' + required: + - type + - decisions delegation: anyOf: - description: Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` or `decisions` to delegate to the corresponding API. @@ -78113,6 +79236,47 @@ components: - $ref: '#/components/schemas/LiveResponsesDelegationParam' - $ref: '#/components/schemas/LiveDecisionsDelegationParam' - type: 'null' + LiveDecisionQuestionsInputParam: + description: Questions evaluated using the current transcript and the session's shared Decision items. + type: object + properties: + questions: + description: Native Decision API questions evaluated together, in order. + type: array + items: + $ref: '#/components/schemas/QuestionParam' + minItems: 1 + maxItems: 64 + required: + - questions + LiveDecisionTriggerInputParam: + type: object + properties: + type: + default: decisions + x-stainless-const: true + type: string + enum: + - decisions + event_type: + type: string + enum: + - session.input_transcript.delta + - session.output_transcript.delta + decisions: + description: Questions evaluated using the current transcript and the session's shared Decision items. + $ref: '#/components/schemas/LiveDecisionQuestionsInputParam' + required: + - type + - event_type + - decisions + additionalProperties: false + triggers: + description: At most one Decisions trigger per transcript event type. Triggers run independently of delegation. On update, omit triggers to keep the current configuration, send a list to replace it, or send an empty list to disable triggers. + type: array + items: + $ref: '#/components/schemas/LiveDecisionTriggerInputParam' + maxItems: 2 store: description: Whether to store the session for later forking and recording download. Defaults to false for new sessions. type: boolean @@ -78439,6 +79603,11 @@ components: description: Update the Responses backend for an existing Live session without changing delegation ownership. type: object properties: + acknowledgement_delay_ms: + description: Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400 for Decisions sessions and 0 (request immediately) for other sessions. Omission in a session update preserves the current value. Updates apply to subsequent delegations. + type: integer + minimum: 0 + maximum: 800 type: description: The delegation owner. Always `responses` for tasks handled by the Responses API. default: responses @@ -78599,6 +79768,7 @@ components: maximum: 31536000 minimum: 1 description: Number of seconds from this request until the API key expires. Must comply with the organization and project expiry policies. Expired keys cannot be updated. Retrying resets the expiry relative to the new request. Omit to keep the current expiration. + x-openai-go-public-type: plain_scalar scopes: items: type: string @@ -79026,6 +80196,7 @@ components: delta: $ref: '#/components/schemas/ShellCallOutputDelta' description: The stdout/stderr delta that was emitted. + x-openai-go-skip-union-projection: true type: object required: - type @@ -79258,6 +80429,11 @@ components: - type: integer description: The aggregated number of input tokens written to the cache across 30-minute and 12-hour retention periods. - type: 'null' + input_cache_write_30m_tokens: + anyOf: + - type: integer + description: The aggregated number of input tokens written to the cache with a 30-minute retention period. + - type: 'null' input_cache_write_12h_tokens: anyOf: - type: integer @@ -79349,11 +80525,6 @@ components: - type: string description: When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - type: 'null' - input_cache_write_30m_tokens: - anyOf: - - type: integer - description: The aggregated number of input tokens written to the cache with a 30-minute retention period. - - type: 'null' type: object required: - object @@ -80014,6 +81185,16 @@ components: code: type: string description: A machine-readable error code that was returned. + type: + anyOf: + - type: string + description: The original error type, or null if it was not recorded. + - type: 'null' + param: + anyOf: + - type: string + description: The request parameter associated with the error, or null if none was recorded. + - type: 'null' message: type: string description: A human-readable description of the error that was returned. @@ -80026,16 +81207,6 @@ components: x-oaiTypeLabel: map misalignment: $ref: '#/components/schemas/MisalignmentErrorDetailsResource' - param: - anyOf: - - type: string - description: The request parameter associated with the error, or null if none was recorded. - - type: 'null' - type: - anyOf: - - type: string - description: The original error type, or null if it was not recorded. - - type: 'null' type: object required: - code @@ -81965,16 +83136,16 @@ components: - type: 'null' description: The image detail level, using the selected model's image profile. Defaults to auto. default: auto + prompt_cache_breakpoint: + anyOf: + - $ref: '#/components/schemas/DecisionPromptCacheBreakpoint' + - type: 'null' type: type: string enum: - input_image default: input_image x-stainless-const: true - prompt_cache_breakpoint: - anyOf: - - $ref: '#/components/schemas/DecisionPromptCacheBreakpoint' - - type: 'null' required: - image_url - type @@ -82706,6 +83877,7 @@ components: - explicit - null description: 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. + x-openai-go-optional-enum: true additionalProperties: false title: Prompt cache options description: 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://developers.openai.com/api/docs/guides/prompt-caching) for current details. @@ -82933,19 +84105,19 @@ components: type: object properties: model: - description: The model used. type: string minLength: 0 + description: The model used. answers: - description: 'Answers in question order. Any question can return a refusal instead of an answer; other questions can still receive answers. A refusal has `type: "refusal"` and the question''s `name`, or `null` if it was unnamed.' type: array items: $ref: '#/components/schemas/AnswerResource' minItems: 0 maxItems: 2000 + description: 'Answers in question order. Any question can return a refusal instead of an answer; other questions can still receive answers. A refusal has `type: "refusal"` and the question''s `name`, or `null` if it was unnamed.' usage: - description: Token usage for the request. $ref: '#/components/schemas/ResponseUsageResource' + description: Token usage for the request. required: - model - answers @@ -82960,406 +84132,582 @@ components: - Returns resources in ascending order. - Returns resources in descending order. description: The order in which paginated resources are returned. - EnvironmentTypeParam: - type: string - enum: - - openai_hosted - description: The hosting type of an execution environment. - EnvironmentTypeResource: + ReasoningEffortResource: type: string enum: - - openai_hosted - - self_hosted - description: The kind of execution environment. - EnvironmentStatusResource: + - none + - minimal + - low + - medium + - high + - xhigh + - max + description: The amount of reasoning effort used by an agent. + ReasoningSummaryResource: type: string enum: - - pending - - ready - - connected - - disconnected - - suspended - - expired - - failed + - concise + - detailed + - auto x-enumDescriptions: - - '' - - Provisioning succeeded and the environment is available for attachment or use. - - '' - - '' - - The sandbox is stopped and can be resumed from its private checkpoint. - - '' - - '' - description: The public lifecycle status of an execution environment. - HostedEnvironmentFileResourceFileId: + - Returns a concise reasoning summary when supported. + - Returns a detailed reasoning summary when supported. + - Automatically selects the most detailed summary supported by the model. + description: The reasoning summary format requested from an agent. + ReasoningResource: + type: object + properties: + effort: + anyOf: + - $ref: '#/components/schemas/ReasoningEffortResource' + - type: 'null' + description: The requested reasoning effort, or `null` when the model selects its own default. + summary: + anyOf: + - $ref: '#/components/schemas/ReasoningSummaryResource' + - type: 'null' + description: The requested reasoning summary format, or `null` when summaries are disabled. + required: + - effort + - summary + additionalProperties: false + description: The reasoning configuration used by an agent. + TextFormatResourceText: type: object properties: type: type: string enum: - - file_id - default: file_id + - text + default: text x-stainless-const: true - description: The type of the object. Always `file_id`. - id: - type: string - minLength: 0 - description: The session-scoped ID of the file in the execution environment. - file_id: - type: string - minLength: 0 - description: The ID of the uploaded file. - path: - type: string - minLength: 0 - description: The file's absolute path inside the environment. - size_bytes: - type: integer - format: int64 - minimum: 0 - description: The decoded file size in bytes. + description: The type of the object. Always `text`. required: - type - - id - - file_id - - path - - size_bytes additionalProperties: false - description: A file copied from the OpenAI Files API. - HostedEnvironmentFileResourceInline: + description: Generates ordinary text without a structured-output constraint. + TextFormatResourceJsonSchema: type: object properties: type: type: string enum: - - inline - default: inline + - json_schema + default: json_schema x-stainless-const: true - description: The type of the object. Always `inline`. - id: - type: string - minLength: 0 - description: The session-scoped ID of the file in the execution environment. - path: - type: string - minLength: 0 - description: The file's absolute path inside the environment. - size_bytes: - type: integer - format: int64 - minimum: 0 - description: The decoded file size in bytes. + description: The type of the object. Always `json_schema`. + schema: + type: object + additionalProperties: {} + propertyNames: + type: string + minLength: 0 + minProperties: 0 + description: The JSON Schema that generated text must match. required: - type - - id - - path - - size_bytes + - schema additionalProperties: false - description: A file supplied inline when the session was created. - HostedEnvironmentFileResource: - description: Metadata for a file materialized in an OpenAI-hosted execution environment. + description: Constrains generated text to a JSON Schema. + TextFormatResource: + description: The effective output format for generated text. discriminator: propertyName: type mapping: - file_id: '#/components/schemas/HostedEnvironmentFileResourceFileId' - inline: '#/components/schemas/HostedEnvironmentFileResourceInline' + text: '#/components/schemas/TextFormatResourceText' + json_schema: '#/components/schemas/TextFormatResourceJsonSchema' x-oai-discriminator-values: - - file_id - - inline + - text + - json_schema anyOf: - - $ref: '#/components/schemas/HostedEnvironmentFileResourceFileId' - - $ref: '#/components/schemas/HostedEnvironmentFileResourceInline' - HostedSkillResourceSkillReference: + - $ref: '#/components/schemas/TextFormatResourceText' + - $ref: '#/components/schemas/TextFormatResourceJsonSchema' + VerbosityResource: + type: string + enum: + - low + - medium + - high + description: The amount of text produced by an agent. + TextResource: + type: object + properties: + format: + $ref: '#/components/schemas/TextFormatResource' + description: The effective output format. Defaults to ordinary text. + verbosity: + $ref: '#/components/schemas/VerbosityResource' + description: The amount of text produced by the agent. Defaults to `medium`. + required: + - format + - verbosity + additionalProperties: false + description: The text configuration used by an agent. + ServiceTierResource: + type: string + enum: + - auto + - default + - flex + - priority + - fast + - ultrafast + description: The service-tier policy configured for an agent. + AgentToolResourceFunction: type: object properties: type: type: string enum: - - skill_reference - default: skill_reference + - function + default: function x-stainless-const: true - description: The type of the object. Always `skill_reference`. - skill_id: - type: string - minLength: 0 - description: The referenced skill ID. - version: - type: string - minLength: 0 - description: The concrete skill version installed for this session. + description: The type of the object. Always `function`. name: type: string minLength: 0 - description: The installed skill name. + description: The name of the function. description: type: string minLength: 0 - description: The installed skill description. + description: A description of what the function does. + parameters: + type: object + additionalProperties: {} + propertyNames: + type: string + minLength: 0 + minProperties: 0 + description: A JSON Schema object describing the function's arguments. + defer_loading: + type: boolean + description: Whether the function is deferred and discovered through tool search. required: - type - - skill_id - - version - name - description + - parameters + - defer_loading additionalProperties: false - description: A skill installed from the Skills API. - HostedSkillResourceInline: + description: A function defined by the application. + AgentToolResourceProgrammaticToolCalling: type: object properties: type: type: string enum: - - inline - default: inline + - programmatic_tool_calling + default: programmatic_tool_calling x-stainless-const: true - description: The type of the object. Always `inline`. - name: - type: string - minLength: 0 - description: The installed skill name. - description: - type: string - minLength: 0 - description: The installed skill description. + description: The type of the object. Always `programmatic_tool_calling`. + enabled: + type: boolean + description: Whether tools can be called from model-generated code. required: - type - - name - - description + - enabled additionalProperties: false - description: A skill installed from an inline ZIP archive. - HostedSkillResource: - description: A skill installed in an OpenAI-hosted environment. - discriminator: - propertyName: type - mapping: - skill_reference: '#/components/schemas/HostedSkillResourceSkillReference' - inline: '#/components/schemas/HostedSkillResourceInline' - x-oai-discriminator-values: - - skill_reference - - inline - anyOf: - - $ref: '#/components/schemas/HostedSkillResourceSkillReference' - - $ref: '#/components/schemas/HostedSkillResourceInline' - HostedPluginResourceInline: + description: Enables calling tools from model-generated code. + McpTransportResourceHttp: type: object properties: type: type: string enum: - - inline - default: inline + - http + default: http x-stainless-const: true - description: The type of the object. Always `inline`. - name: - type: string - minLength: 0 - description: The installed plugin name. - description: + description: The type of the object. Always `http`. + server_url: type: string minLength: 0 - description: The installed plugin description. + description: The URL of the MCP server. required: - type - - name - - description + - server_url additionalProperties: false - description: A plugin installed from an inline ZIP archive. - HostedPluginResource: - description: A plugin installed in an OpenAI-hosted environment. - discriminator: - propertyName: type - mapping: - inline: '#/components/schemas/HostedPluginResourceInline' - x-oai-discriminator-values: - - inline - anyOf: - - $ref: '#/components/schemas/HostedPluginResourceInline' - PublicEnvironmentResource: + description: Connects to an MCP server over HTTP. + McpTransportResourceStdio: type: object properties: type: - $ref: '#/components/schemas/EnvironmentTypeResource' - description: Whether the environment is hosted by OpenAI or by the application. - id: - type: string - minLength: 0 - description: The ID of the environment. - object: type: string enum: - - agent.environment - default: agent.environment + - stdio + default: stdio x-stainless-const: true - description: The object type. Always `agent.environment`. - status: - $ref: '#/components/schemas/EnvironmentStatusResource' - description: The current environment connection status. - files: - type: array - items: - $ref: '#/components/schemas/HostedEnvironmentFileResource' - minItems: 0 - maxItems: 2000 - description: Files installed in the environment, without their contents. - skills: + description: The type of the object. Always `stdio`. + command: + type: string + minLength: 0 + description: The command used to start the MCP server. + args: type: array items: - $ref: '#/components/schemas/HostedSkillResource' + type: string + minLength: 0 minItems: 0 maxItems: 2000 - description: Skills installed in the environment, without their archive contents. - plugins: + description: Arguments passed to the MCP server command. + cwd: + type: string + minLength: 0 + description: The working directory used to start the MCP server. + env_vars: type: array items: - $ref: '#/components/schemas/HostedPluginResource' + type: string + minLength: 0 minItems: 0 maxItems: 2000 - description: Plugins installed in the environment, without their archive contents. + description: Environment variable names inherited from the execution environment. required: - - id - - object - type - - status - - files - - skills - - plugins + - command + - args + - cwd + - env_vars additionalProperties: false - description: Safe metadata for a first-class execution environment. - AgentEnvironmentListResource: + description: Starts an MCP server as a local process. + McpTransportResource: + description: The transport used to connect to an MCP server. + discriminator: + propertyName: type + mapping: + http: '#/components/schemas/McpTransportResourceHttp' + stdio: '#/components/schemas/McpTransportResourceStdio' + x-oai-discriminator-values: + - http + - stdio + anyOf: + - $ref: '#/components/schemas/McpTransportResourceHttp' + - $ref: '#/components/schemas/McpTransportResourceStdio' + McpConnectionOriginResource: + type: string + enum: + - service + - environment + description: Where outbound MCP HTTP connections originate. + AgentToolResourceMcp: type: object properties: - object: + type: type: string enum: - - list - default: list + - mcp + default: mcp x-stainless-const: true - description: The object type, which is always `list`. - data: - type: array - items: - $ref: '#/components/schemas/PublicEnvironmentResource' - minItems: 0 - maxItems: 2000 - description: The resources returned in this page, in the requested sort order. - first_id: + description: The type of the object. Always `mcp`. + server_label: + type: string + minLength: 0 + description: A label used to identify the MCP server in tool calls. + credential_id: type: - string - 'null' minLength: 0 - description: The ID of the first resource in `data`, or `null` if the page is empty. - last_id: + description: The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. + transport: + $ref: '#/components/schemas/McpTransportResource' + description: The transport used to connect to the MCP server. + request_metadata: + type: object + additionalProperties: {} + propertyNames: + type: string + minLength: 0 + minProperties: 0 + description: Metadata included with requests to this MCP server. + allowed_tools: type: - - string + - array - 'null' - minLength: 0 - description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - has_more: + items: + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: The MCP tools the agent may call. + required: type: boolean - description: Whether there are more resources to retrieve after this page. + description: Whether this MCP server must initialize before the first turn. + connection_origin: + $ref: '#/components/schemas/McpConnectionOriginResource' + description: Where outbound MCP HTTP connections originate. required: - - object - - data - - first_id - - last_id - - has_more + - type + - server_label + - credential_id + - transport + - request_metadata + - allowed_tools + - required + - connection_origin additionalProperties: false - description: A page of Agents API resources, with IDs for retrieving additional pages. - ErrorBodyResource: + description: Tools provided by a remote MCP server. + WebSearchModeResource: + type: string + enum: + - disabled + - cached + - live + description: The source used for web search results. + WebSearchContextSizeResource: + type: string + enum: + - low + - medium + - high + description: The amount of web search context made available to the model. + WebSearchLocationResource: type: object properties: - type: - type: string - minLength: 0 - description: The error type. - code: - type: string + country: + type: + - string + - 'null' minLength: 0 - description: A machine-readable error code. - message: - type: string + description: The two-letter ISO country code, such as `US`. + region: + type: + - string + - 'null' minLength: 0 - description: A human-readable error message. - param: + description: The region or state name. + city: type: - string - 'null' minLength: 0 - description: The request parameter that caused the error, or null for a request-wide error. - required: + description: The city name. + timezone: + type: + - string + - 'null' + minLength: 0 + description: The IANA timezone, such as `America/Los_Angeles`. + required: + - country + - region + - city + - timezone + additionalProperties: false + description: Approximate user location used to localize web search results. + AgentToolResourceWebSearch: + type: object + properties: + type: + type: string + enum: + - web_search + default: web_search + x-stainless-const: true + description: The type of the object. Always `web_search`. + mode: + $ref: '#/components/schemas/WebSearchModeResource' + description: The source used for web search results. + context_size: + $ref: '#/components/schemas/WebSearchContextSizeResource' + description: The amount of search context made available to the model. Defaults to `medium`. + allowed_domains: + type: + - array + - 'null' + items: + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: Allowed search domains, or `null` when the search is unrestricted. + location: + anyOf: + - $ref: '#/components/schemas/WebSearchLocationResource' + - type: 'null' + description: Approximate location used to localize search results, if provided. + required: - type - - code - - message - - param + - mode + - context_size + - allowed_domains + - location additionalProperties: false - description: Details about an API error. - ErrorResponse-2: + description: Web search. + AgentToolResourceComputerUse: type: object properties: - error: - $ref: '#/components/schemas/ErrorBodyResource' - description: The error returned by the API. + type: + type: string + enum: + - computer_use + default: computer_use + x-stainless-const: true + description: The type of the object. Always `computer_use`. + include_screenshots: + type: boolean + description: Whether computer tool outputs include screenshots. required: - - error + - type + - include_screenshots additionalProperties: false - description: An API error response. - EnvironmentPackagesParam: + description: Browser use in an OpenAI-hosted session. + AgentToolResourceAutomations: type: object properties: - python: + type: + type: string + enum: + - automations + default: automations + x-stainless-const: true + description: The type of the object. Always `automations`. + required: + - type + additionalProperties: false + description: Lets the agent manage its own scheduled wakeups. + AgentToolResource: + description: A tool available to the agent. + discriminator: + propertyName: type + mapping: + function: '#/components/schemas/AgentToolResourceFunction' + programmatic_tool_calling: '#/components/schemas/AgentToolResourceProgrammaticToolCalling' + mcp: '#/components/schemas/AgentToolResourceMcp' + web_search: '#/components/schemas/AgentToolResourceWebSearch' + computer_use: '#/components/schemas/AgentToolResourceComputerUse' + automations: '#/components/schemas/AgentToolResourceAutomations' + x-oai-discriminator-values: + - function + - programmatic_tool_calling + - mcp + - web_search + - computer_use + - automations + anyOf: + - $ref: '#/components/schemas/AgentToolResourceFunction' + - $ref: '#/components/schemas/AgentToolResourceProgrammaticToolCalling' + - $ref: '#/components/schemas/AgentToolResourceMcp' + - $ref: '#/components/schemas/AgentToolResourceWebSearch' + - $ref: '#/components/schemas/AgentToolResourceComputerUse' + - $ref: '#/components/schemas/AgentToolResourceAutomations' + MultiAgentConfigResource: + type: object + properties: + enabled: + type: boolean + description: Whether subagent tools are enabled. Defaults to false. + max_concurrent_subagents: type: - - array + - integer + - 'null' + format: int64 + minimum: 1 + maximum: 4294967295 + description: Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. + required: + - enabled + - max_concurrent_subagents + additionalProperties: false + description: The resolved configuration for creating and coordinating subagents. + AutomationAgentConfigResource: + type: object + properties: + model: + type: string + minLength: 0 + description: The requested model name. + reasoning: + $ref: '#/components/schemas/ReasoningResource' + description: The configured reasoning policy. + text: + $ref: '#/components/schemas/TextResource' + description: The configured output format and verbosity. + service_tier: + $ref: '#/components/schemas/ServiceTierResource' + description: The configured service-tier policy. + instructions: + type: + - string - 'null' + minLength: 0 + description: Custom instructions, or null when absent. + tools: + type: array + items: + $ref: '#/components/schemas/AgentToolResource' + minItems: 0 + maxItems: 2000 + description: Configured tools, excluding confidential credentials. + multi_agent: + $ref: '#/components/schemas/MultiAgentConfigResource' + description: The configuration for creating and coordinating subagents. + required: + - model + - reasoning + - text + - service_tier + - instructions + - tools + - multi_agent + additionalProperties: false + description: Inline agent configuration without a generated session-local identity. + AutomationEnvironmentResourceNone: + type: object + properties: + type: + type: string + enum: + - none + default: none + x-stainless-const: true + description: The type of the object. Always `none`. + required: + - type + additionalProperties: false + ContainerSizeResource: + type: string + enum: + - small + - medium + - large + description: The effective CPU and memory tier of an OpenAI-hosted environment. + EnvironmentPackagesResource: + type: object + properties: + python: + type: array items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 - description: Python packages to install. Defaults to an empty list. + description: Python packages installed in the environment. system: - type: - - array - - 'null' + type: array items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 - description: System packages to install. Defaults to an empty list. + description: System packages installed in the environment. npm: - type: - - array - - 'null' + type: array items: type: string minLength: 0 maxLength: 1048576 minItems: 0 maxItems: 16384 - description: npm packages to install globally. Defaults to an empty list. - additionalProperties: false - description: Packages to install in an OpenAI-hosted environment. - SetupCommandParam: - type: object - properties: - command: - type: string - minLength: 0 - maxLength: 65536 - description: The shell command to execute. - cwd: - type: - - string - - 'null' - minLength: 0 - maxLength: 4096 - description: The absolute working directory. Defaults to `/workspace`. + description: npm packages installed globally in the environment. required: - - command + - python + - system + - npm additionalProperties: false - description: A confidential setup command executed before the hosted agent starts. - NetworkAccessParam: + description: Packages installed in an OpenAI-hosted environment. + NetworkAccessResource: type: string enum: - enabled @@ -83370,54 +84718,36 @@ components: - Disables network access. - Applies the configured domain restrictions. description: The network access mode for an OpenAI-hosted environment. - NetworkPolicyParam: + NetworkPolicyResource: type: object properties: access: - $ref: '#/components/schemas/NetworkAccessParam' + $ref: '#/components/schemas/NetworkAccessResource' description: The environment's network access mode. allowed_domains: - type: - - array - - 'null' + type: array items: type: string minLength: 0 - maxLength: 1048576 minItems: 0 - maxItems: 16384 + maxItems: 2000 description: Domains the environment may access when network access is restricted. - blocked_domains: - type: - - array - - 'null' - items: - type: string - minLength: 0 - maxLength: 1048576 - minItems: 0 - maxItems: 100 - description: 'Domains blocked for both executor and browser when access is restricted. A nonempty list requires `access: restricted` and cannot be combined with nonempty `allowed_domains`. Wildcard domains are not supported.' required: - access + - allowed_domains additionalProperties: false description: Network access for an OpenAI-hosted environment. - example: - access: restricted - allowed_domains: - - example.com - blocked_domains: [] - DesktopParam: + DesktopResource: type: object properties: enabled: type: boolean - description: Whether to provision the desktop and its browser proxy. + description: Whether the environment provisions a desktop and browser proxy. required: - enabled additionalProperties: false - description: Desktop configuration for an OpenAI-hosted environment. - HostedSkillParamSkillReference: + description: The effective desktop configuration for an OpenAI-hosted environment. + HostedTemplateSkillResourceSkillReference: type: object properties: type: @@ -83429,62 +84759,21 @@ components: description: The type of the object. Always `skill_reference`. skill_id: type: string - minLength: 1 - maxLength: 64 - description: The ID of the skill created through `/v1/skills`. + minLength: 0 + description: The referenced skill ID. version: type: - string - 'null' minLength: 0 - maxLength: 1048576 - description: The skill version, a positive integer or `latest`; omission selects the default. + description: The requested version selector, including `latest`. required: - type - skill_id + - version additionalProperties: false - description: References a skill uploaded through the Skills API. - InlineCapabilitySourceParamBase64: - type: object - properties: - type: - type: string - enum: - - base64 - default: base64 - x-stainless-const: true - description: The type of the object. Always `base64`. - media_type: - type: string - enum: - - application/zip - default: application/zip - x-stainless-const: true - x-enumDescriptions: - - A ZIP archive. - description: The archive media type, always `application/zip`. - data: - type: string - minLength: 1 - maxLength: 70254592 - description: Standard-base64 encoded ZIP archive bytes. - required: - - type - - media_type - - data - additionalProperties: false - description: Provides ZIP bytes encoded with standard base64. - InlineCapabilitySourceParam: - description: The encoded ZIP archive for an inline skill or plugin. - discriminator: - propertyName: type - mapping: - base64: '#/components/schemas/InlineCapabilitySourceParamBase64' - x-oai-discriminator-values: - - base64 - anyOf: - - $ref: '#/components/schemas/InlineCapabilitySourceParamBase64' - HostedSkillParamInline: + description: A skill resolved afresh from the Skills API whenever a session starts. + HostedTemplateSkillResourceInline: type: object properties: type: @@ -83496,39 +84785,32 @@ components: description: The type of the object. Always `inline`. name: type: string - minLength: 1 - maxLength: 64 + minLength: 0 description: The skill name declared in `SKILL.md`. description: type: string minLength: 0 - maxLength: 1048576 description: The skill description declared in `SKILL.md`. - source: - $ref: '#/components/schemas/InlineCapabilitySourceParam' - description: The inline ZIP archive. - x-stainless-go-json: omitzero required: - type - name - description - - source additionalProperties: false - description: Supplies a skill ZIP directly in the session request. - HostedSkillParam: - description: A skill installed in an OpenAI-hosted environment. + description: Safe metadata for an inline skill archive. + HostedTemplateSkillResource: + description: Safe metadata for a skill configured by an environment template. discriminator: propertyName: type mapping: - skill_reference: '#/components/schemas/HostedSkillParamSkillReference' - inline: '#/components/schemas/HostedSkillParamInline' + skill_reference: '#/components/schemas/HostedTemplateSkillResourceSkillReference' + inline: '#/components/schemas/HostedTemplateSkillResourceInline' x-oai-discriminator-values: - skill_reference - inline anyOf: - - $ref: '#/components/schemas/HostedSkillParamSkillReference' - - $ref: '#/components/schemas/HostedSkillParamInline' - HostedPluginParamInline: + - $ref: '#/components/schemas/HostedTemplateSkillResourceSkillReference' + - $ref: '#/components/schemas/HostedTemplateSkillResourceInline' + HostedPluginResourceInline: type: object properties: type: @@ -83540,36 +84822,29 @@ components: description: The type of the object. Always `inline`. name: type: string - minLength: 1 - maxLength: 64 - description: The plugin name declared in `.codex-plugin/plugin.json`. + minLength: 0 + description: The installed plugin name. description: type: string minLength: 0 - maxLength: 1048576 - description: The plugin description declared in `.codex-plugin/plugin.json`. - source: - $ref: '#/components/schemas/InlineCapabilitySourceParam' - description: The inline ZIP archive. - x-stainless-go-json: omitzero + description: The installed plugin description. required: - type - name - description - - source additionalProperties: false - description: Supplies a plugin ZIP directly in the session request. - HostedPluginParam: + description: A plugin installed from an inline ZIP archive. + HostedPluginResource: description: A plugin installed in an OpenAI-hosted environment. discriminator: propertyName: type mapping: - inline: '#/components/schemas/HostedPluginParamInline' + inline: '#/components/schemas/HostedPluginResourceInline' x-oai-discriminator-values: - inline anyOf: - - $ref: '#/components/schemas/HostedPluginParamInline' - HostedEnvironmentFileParamFileId: + - $ref: '#/components/schemas/HostedPluginResourceInline' + HostedTemplateFileResourceFileId: type: object properties: type: @@ -83581,21 +84856,19 @@ components: description: The type of the object. Always `file_id`. file_id: type: string - minLength: 1 - maxLength: 256 + minLength: 0 description: The ID of the uploaded file. path: type: string - minLength: 1 - maxLength: 4096 - description: The absolute destination path inside `/workspace`. + minLength: 0 + description: The file's absolute path inside the environment. required: - type - file_id - path additionalProperties: false - description: A file previously uploaded through the OpenAI Files API. - HostedEnvironmentFileParamInline: + description: A project-scoped Files API reference resolved separately for each session. + HostedTemplateFileResourceInline: type: object properties: type: @@ -83605,36 +84878,35 @@ components: default: inline x-stainless-const: true description: The type of the object. Always `inline`. - data: - type: string - minLength: 0 - maxLength: 6990508 - description: The standard-base64-encoded file contents. path: type: string - minLength: 1 - maxLength: 4096 - description: The absolute destination path inside `/workspace`. + minLength: 0 + description: The file's absolute path inside the environment. + size_bytes: + type: integer + format: int64 + minimum: 0 + description: The decoded size of the inline file in bytes. required: - type - - data - path + - size_bytes additionalProperties: false - description: A file supplied directly as standard-base64 data. - HostedEnvironmentFileParam: - description: A file materialized in an OpenAI-hosted execution environment. + description: Metadata for confidential inline file contents. + HostedTemplateFileResource: + description: Safe metadata for a file configured by an environment template. discriminator: propertyName: type mapping: - file_id: '#/components/schemas/HostedEnvironmentFileParamFileId' - inline: '#/components/schemas/HostedEnvironmentFileParamInline' + file_id: '#/components/schemas/HostedTemplateFileResourceFileId' + inline: '#/components/schemas/HostedTemplateFileResourceInline' x-oai-discriminator-values: - file_id - inline anyOf: - - $ref: '#/components/schemas/HostedEnvironmentFileParamFileId' - - $ref: '#/components/schemas/HostedEnvironmentFileParamInline' - CreateEnvironmentParamOpenaiHosted: + - $ref: '#/components/schemas/HostedTemplateFileResourceFileId' + - $ref: '#/components/schemas/HostedTemplateFileResourceInline' + AutomationEnvironmentResourceOpenaiHosted: type: object properties: type: @@ -83644,45 +84916,38 @@ components: default: openai_hosted x-stainless-const: true description: The type of the object. Always `openai_hosted`. + environment_id: + type: + - string + - 'null' + minLength: 0 + description: An existing environment reference, or null when provisioning a new environment. + environment_template_id: + type: + - string + - 'null' + minLength: 0 + description: A template reference, or null when no template is selected. + container_size: + anyOf: + - $ref: '#/components/schemas/ContainerSizeResource' + - type: 'null' + description: The configured container size, or null to use the creation default. packages: anyOf: - - $ref: '#/components/schemas/EnvironmentPackagesParam' + - $ref: '#/components/schemas/EnvironmentPackagesResource' - type: 'null' - description: Packages to install in the environment. Defaults to empty package lists. - setup_commands: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/SetupCommandParam' - minItems: 0 - maxItems: 16 - description: Ordered, confidential setup commands. Command bodies are never returned. + description: Package overrides, or null to inherit the template or creation default. network: anyOf: - - $ref: '#/components/schemas/NetworkPolicyParam' + - $ref: '#/components/schemas/NetworkPolicyResource' - type: 'null' - description: Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled. + description: Network overrides, or null to inherit the template or creation default. desktop: anyOf: - - $ref: '#/components/schemas/DesktopParam' + - $ref: '#/components/schemas/DesktopResource' - type: 'null' - description: Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled. - env: - type: - - object - - 'null' - additionalProperties: - type: string - minLength: 0 - maxLength: 1048576 - propertyNames: - type: string - minLength: 1 - maxLength: 256 - minProperties: 0 - maxProperties: 1024 - description: Environment variables made available to the agent. + description: Desktop overrides, or null to inherit the template or creation default. capability_directories: type: - array @@ -83690,4418 +84955,4181 @@ components: items: type: string minLength: 0 - maxLength: 1048576 minItems: 0 - maxItems: 16384 - description: Directories that contain capabilities exposed to the agent. Defaults to an empty list. + maxItems: 2000 + description: Directory overrides, or null to inherit the template or creation default. skills: type: - array - 'null' items: - $ref: '#/components/schemas/HostedSkillParam' + $ref: '#/components/schemas/HostedTemplateSkillResource' minItems: 0 - maxItems: 200 - description: Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. + maxItems: 2000 + description: Skill overrides, excluding archive contents, or null to inherit. plugins: type: - array - 'null' items: - $ref: '#/components/schemas/HostedPluginParam' + $ref: '#/components/schemas/HostedPluginResource' minItems: 0 - maxItems: 32 - description: Plugins provided as inline ZIP archives. Defaults to an empty list. + maxItems: 2000 + description: Plugin overrides, excluding archive contents, or null to inherit. files: type: - array - 'null' items: - $ref: '#/components/schemas/HostedEnvironmentFileParam' + $ref: '#/components/schemas/HostedTemplateFileResource' minItems: 0 - maxItems: 50 - description: Files available before the agent starts. Defaults to an empty list. - environment_template_id: + maxItems: 2000 + description: File overrides, excluding contents, or null to inherit. + required: + - type + - environment_id + - environment_template_id + - container_size + - packages + - network + - desktop + - capability_directories + - skills + - plugins + - files + additionalProperties: false + description: Hosted environment selection with confidential setup commands and variables omitted. + AutomationEnvironmentResourceSelfHosted: + type: object + properties: + type: + type: string + enum: + - self_hosted + default: self_hosted + x-stainless-const: true + description: The type of the object. Always `self_hosted`. + environment_id: + type: + - string + - 'null' + minLength: 0 + description: An existing registration, or null to create a session-owned environment. + workspace_directory: type: string minLength: 0 - maxLength: 64 - description: A reusable hosted template applied before inline configuration. Omitted fields inherit the template; network overrides cannot broaden its policy. + description: The absolute project directory in the environment. + capability_directories: + type: array + items: + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: Directories that expose capabilities to the agent. required: - type + - environment_id + - workspace_directory + - capability_directories additionalProperties: false - description: Provision an OpenAI-hosted environment from inline configuration or a template. - CreateEnvironmentParam: - description: Configuration for a new prewarmed OpenAI-hosted environment. + AutomationEnvironmentResource: + description: Environment selection saved before an invocation creates its session. discriminator: propertyName: type mapping: - openai_hosted: '#/components/schemas/CreateEnvironmentParamOpenaiHosted' + none: '#/components/schemas/AutomationEnvironmentResourceNone' + openai_hosted: '#/components/schemas/AutomationEnvironmentResourceOpenaiHosted' + self_hosted: '#/components/schemas/AutomationEnvironmentResourceSelfHosted' x-oai-discriminator-values: + - none - openai_hosted + - self_hosted anyOf: - - $ref: '#/components/schemas/CreateEnvironmentParamOpenaiHosted' - CreateAgentEnvironmentParams: - type: object - properties: - environment: - $ref: '#/components/schemas/CreateEnvironmentParam' - description: The required hosting type and its configuration. - vault_ids: - type: - - array - - 'null' - items: - type: string - minLength: 0 - maxLength: 1048576 - minItems: 0 - maxItems: 10 - description: The IDs of up to 10 vaults made available to an OpenAI-hosted environment. - required: - - environment - additionalProperties: false - description: Parameters for creating an execution environment before its sessions. - EnvironmentFilePageObjectResource: - type: string - enum: - - page - default: page - x-stainless-const: true - description: The object type for a page of files in an execution environment. - EnvironmentFileResource: - type: object - properties: - object: - type: string - enum: - - agent.environment.file - default: agent.environment.file - x-stainless-const: true - description: The object type. Always `agent.environment.file`. - environment_id: - type: string - minLength: 0 - description: The ID of the environment containing this file. - path: - type: string - minLength: 0 - description: The absolute file path inside the environment's workspace. - size_bytes: - type: integer - format: int64 - minimum: 0 - description: The file size in bytes. - required: - - object - - environment_id - - path - - size_bytes - additionalProperties: false - description: A live file in an execution environment. - EnvironmentFileListResource: - type: object - properties: - object: - $ref: '#/components/schemas/EnvironmentFilePageObjectResource' - description: The object type. Always `page`. - data: - type: array - items: - $ref: '#/components/schemas/EnvironmentFileResource' - minItems: 0 - maxItems: 2000 - description: Files available on the current page. - next: - type: - - string - - 'null' - minLength: 0 - description: The opaque cursor to use when requesting the next page, if any. - has_more: - type: boolean - description: Whether more files follow this page. - required: - - object - - data - - next - - has_more - additionalProperties: false - description: A paginated list of live execution environment files. - SubagentObjectResource: - type: string - enum: - - agent.session.subagent - default: agent.session.subagent - x-stainless-const: true - description: The object type for a subagent. - OutputTextResource: + - $ref: '#/components/schemas/AutomationEnvironmentResourceNone' + - $ref: '#/components/schemas/AutomationEnvironmentResourceOpenaiHosted' + - $ref: '#/components/schemas/AutomationEnvironmentResourceSelfHosted' + InputContentResourceInputText: type: object properties: type: type: string enum: - - output_text - default: output_text + - input_text + default: input_text x-stainless-const: true - description: The content type. Always `output_text`. + description: The type of the object. Always `input_text`. text: type: string minLength: 0 - description: The text produced by the agent. + description: The text supplied to the agent. required: - type - text additionalProperties: false - description: A text content part produced by the agent. - EncryptedContentResource: + description: Text input recorded in a session item. + InputContentResourceInputImage: type: object properties: type: type: string enum: - - encrypted_content - default: encrypted_content + - input_image + default: input_image x-stainless-const: true - description: The content type. Always `encrypted_content`. - encrypted_content: + description: The type of the object. Always `input_image`. + image_url: type: string minLength: 0 - description: The encrypted content payload. + description: The URL of the image supplied to the agent, which may be a base64-encoded data URL. required: - type - - encrypted_content + - image_url additionalProperties: false - description: Encrypted content exchanged between agents. - AgentContentResource: - description: A plaintext or encrypted content part exchanged between agents. + description: Image input recorded in a session item. + InputContentResource: + description: User-provided content recorded in a session item. discriminator: propertyName: type mapping: - output_text: '#/components/schemas/OutputTextResource' - encrypted_content: '#/components/schemas/EncryptedContentResource' + input_text: '#/components/schemas/InputContentResourceInputText' + input_image: '#/components/schemas/InputContentResourceInputImage' x-oai-discriminator-values: - - output_text - - encrypted_content + - input_text + - input_image anyOf: - - $ref: '#/components/schemas/OutputTextResource' - - $ref: '#/components/schemas/EncryptedContentResource' - SubagentStatusResource: - type: string - enum: - - active - - closed - x-enumDescriptions: - - The subagent remains available, including while idle between turns. - - The subagent is closed. - description: The current status of a subagent. - SubagentResource: + - $ref: '#/components/schemas/InputContentResourceInputText' + - $ref: '#/components/schemas/InputContentResourceInputImage' + InputMessageResource-2: type: object properties: - id: + type: type: string - minLength: 0 - description: The ID of the subagent. - object: - $ref: '#/components/schemas/SubagentObjectResource' - description: The object type. Always `agent.session.subagent`. - session_id: + enum: + - message + default: message + x-stainless-const: true + description: The type of the input item. Always `message`. + role: type: string - minLength: 0 - description: The ID of the session that owns the subagent. - name: + enum: + - user + default: user + x-stainless-const: true + description: The role of the message author. Always `user`. + content: + type: array + items: + $ref: '#/components/schemas/InputContentResource' + minItems: 0 + maxItems: 2000 + description: The content of the message. + required: + - type + - role + - content + additionalProperties: false + description: A user message recorded in a session. + AutomationTargetResourceNewSession: + type: object + properties: + type: + type: string + enum: + - new_session + default: new_session + x-stainless-const: true + description: The type of the object. Always `new_session`. + agent_id: type: - string - 'null' minLength: 0 - description: The runner-assigned nickname, or null when unavailable. - instructions: - type: - - array - - 'null' + description: The saved agent reference, or null when an inline agent is configured. + agent: + anyOf: + - $ref: '#/components/schemas/AutomationAgentConfigResource' + - type: 'null' + description: The inline agent configuration, or null when agent_id is configured. + environment: + $ref: '#/components/schemas/AutomationEnvironmentResource' + description: Configuration or references used to select the execution environment. + input: + type: array items: - $ref: '#/components/schemas/AgentContentResource' + $ref: '#/components/schemas/InputMessageResource-2' minItems: 0 maxItems: 2000 - description: Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available. - parent_agent_id: - type: string - minLength: 0 - description: The ID of the agent that created this subagent. - status: - $ref: '#/components/schemas/SubagentStatusResource' - description: The current status of the subagent. - opened_at: - type: integer - format: int64 - description: The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - closed_at: - type: - - integer - - 'null' - format: int64 - description: The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. + description: Initial input delivered to each new session. + vault_ids: + type: array + items: + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: Vaults made available to each new session. + metadata: + type: object + additionalProperties: + type: string + minLength: 0 + propertyNames: + type: string + minLength: 0 + minProperties: 0 + description: Metadata attached to each new session. required: - - id - - object - - session_id - - name - - instructions - - parent_agent_id - - status - - opened_at - - closed_at + - type + - agent_id + - agent + - environment + - input + - vault_ids + - metadata additionalProperties: false - description: A subagent created within a session. - SessionMessageRoleResource: - type: string - enum: - - user - - assistant - description: The author of a session message. - MessageContentResourceInputText: + AutomationTargetResourceExistingSession: type: object properties: type: type: string enum: - - input_text - default: input_text + - existing_session + default: existing_session x-stainless-const: true - description: The type of the object. Always `input_text`. - text: + description: The type of the object. Always `existing_session`. + session_id: type: string minLength: 0 - description: The text supplied by the user. + description: The session receiving each invocation. + instructions: + type: string + minLength: 0 + description: Saved instructions delivered as an automation notification. required: - type - - text + - session_id + - instructions additionalProperties: false - description: Text supplied by the user. - MessageContentResourceInputImage: + AutomationTargetResource: + description: Saved target configuration, excluding confidential request-only values. + discriminator: + propertyName: type + mapping: + new_session: '#/components/schemas/AutomationTargetResourceNewSession' + existing_session: '#/components/schemas/AutomationTargetResourceExistingSession' + x-oai-discriminator-values: + - new_session + - existing_session + anyOf: + - $ref: '#/components/schemas/AutomationTargetResourceNewSession' + - $ref: '#/components/schemas/AutomationTargetResourceExistingSession' + AutomationCreatedByResourceDeveloper: type: object properties: type: type: string enum: - - input_image - default: input_image + - developer + default: developer x-stainless-const: true - description: The type of the object. Always `input_image`. - image_url: - type: string - minLength: 0 - description: The URL of the image supplied by the user, which may be a base64-encoded data URL. + description: The type of the object. Always `developer`. required: - type - - image_url additionalProperties: false - description: An image supplied by the user. - MessageContentResourceOutputText: + AutomationCreatedByResourceAgent: type: object properties: type: type: string enum: - - output_text - default: output_text + - agent + default: agent x-stainless-const: true - description: The type of the object. Always `output_text`. - text: + description: The type of the object. Always `agent`. + session_id: type: string minLength: 0 - description: The text produced by the assistant. + description: The creator session, which is also the automation's target. + tool_call_id: + type: string + minLength: 0 + description: The tool call that created the automation. required: - type - - text + - session_id + - tool_call_id additionalProperties: false - description: Text produced by the assistant. - MessageContentResource: - description: A content part in a session message. + AutomationCreatedByResource: + description: How the automation was created, independently of how an invocation started. discriminator: propertyName: type mapping: - input_text: '#/components/schemas/MessageContentResourceInputText' - input_image: '#/components/schemas/MessageContentResourceInputImage' - output_text: '#/components/schemas/MessageContentResourceOutputText' + developer: '#/components/schemas/AutomationCreatedByResourceDeveloper' + agent: '#/components/schemas/AutomationCreatedByResourceAgent' x-oai-discriminator-values: - - input_text - - input_image - - output_text + - developer + - agent anyOf: - - $ref: '#/components/schemas/MessageContentResourceInputText' - - $ref: '#/components/schemas/MessageContentResourceInputImage' - - $ref: '#/components/schemas/MessageContentResourceOutputText' - OutputItemStatusResource: - type: string - enum: - - in_progress - - completed - - incomplete - x-enumDescriptions: - - The item is in progress. - - The item is complete. - - The item stopped before completing. - description: The status of an agent output item. - MessagePhaseResource: + - $ref: '#/components/schemas/AutomationCreatedByResourceDeveloper' + - $ref: '#/components/schemas/AutomationCreatedByResourceAgent' + PeriodicAutomationStatusResource: type: string enum: - - commentary - - final_answer - x-enumDescriptions: - - Commentary produced while the agent works. - - The agent's final answer. - description: The phase of an assistant message. - MessageItemResource: + - active + - paused + AutomationResourcePeriodic: type: object properties: type: type: string enum: - - message - default: message + - periodic + default: periodic x-stainless-const: true - description: The item type. Always `message`. + description: The type of the object. Always `periodic`. id: - type: - - string - - 'null' - minLength: 0 - description: The ID of this item, or null for legacy user messages whose ID was not recorded. - turn_id: type: string minLength: 0 - description: The ID of the turn that contains this item. - role: - $ref: '#/components/schemas/SessionMessageRoleResource' - description: The role of the message author. - content: - type: array - items: - $ref: '#/components/schemas/MessageContentResource' - minItems: 0 - maxItems: 2000 - description: The content of the message. User messages contain input text or images; assistant messages contain output text. - status: - $ref: '#/components/schemas/OutputItemStatusResource' - description: The status of the message. User messages are always `completed`. - phase: - anyOf: - - $ref: '#/components/schemas/MessagePhaseResource' - - type: 'null' - description: The phase of an assistant message. Null for user messages. - required: - - type - - id - - turn_id - - role - - content - - status - - phase - additionalProperties: false - description: A user or assistant message recorded in a session. - SummaryTextResource: - type: object - properties: - type: + description: The automation ID. + object: type: string enum: - - summary_text - default: summary_text + - agent.automation + default: agent.automation x-stainless-const: true - description: The content type. Always `summary_text`. - text: + description: Always `agent.automation`. + created_at: + type: integer + format: int64 + description: The creation time as a Unix timestamp in seconds. + name: type: string minLength: 0 - description: The reasoning summary text. - required: - - type - - text - additionalProperties: false - description: A reasoning summary content part. - ReasoningItemResource: - type: object - properties: - type: - type: string - enum: - - reasoning - default: reasoning - x-stainless-const: true - description: The item type. Always `reasoning`. - id: + description: The automation's display name. + target: + $ref: '#/components/schemas/AutomationTargetResource' + description: The session configuration or existing session receiving invocations. + metadata: + type: object + additionalProperties: + type: string + minLength: 0 + propertyNames: + type: string + minLength: 0 + minProperties: 0 + description: Custom string key-value pairs attached to the automation. + created_by: + $ref: '#/components/schemas/AutomationCreatedByResource' + description: Service-recorded provenance; callers cannot supply this field. + expression: type: string minLength: 0 - description: The ID of the reasoning item. - turn_id: + description: The cron expression determining scheduled occurrences. + timezone: type: string minLength: 0 - description: The ID of the turn that contains this item. - summary: - type: array - items: - $ref: '#/components/schemas/SummaryTextResource' - minItems: 0 - maxItems: 2000 - description: The reasoning summaries produced by the agent. + description: The timezone used to interpret the expression. status: - anyOf: - - $ref: '#/components/schemas/OutputItemStatusResource' - - type: 'null' - description: The status of the reasoning item. + $ref: '#/components/schemas/PeriodicAutomationStatusResource' + description: Whether scheduled delivery is active or paused. required: - type - id - - turn_id - - summary + - object + - created_at + - name + - target + - metadata + - created_by + - expression + - timezone - status additionalProperties: false - description: A reasoning item produced by the agent. - FunctionCallStatusResource: + description: Fields shared by periodic and one-time automations. + OnceAutomationStatusResource: type: string enum: - - in_progress + - active + - paused - completed - - failed - - incomplete - x-enumDescriptions: - - The call is in progress. - - The call completed successfully. - - The call failed. - - The call stopped before completing. - description: The status of a tool call. - FunctionCallItemResource: + AutomationResourceOnce: type: object properties: type: type: string enum: - - function_call - default: function_call + - once + default: once x-stainless-const: true - description: The item type. Always `function_call`. + description: The type of the object. Always `once`. id: type: string minLength: 0 - description: The ID of the function call item. - turn_id: - type: string - minLength: 0 - description: The ID of the turn that contains this item. - call_id: + description: The automation ID. + object: type: string - minLength: 0 - description: The ID used to submit the function result. + enum: + - agent.automation + default: agent.automation + x-stainless-const: true + description: Always `agent.automation`. + created_at: + type: integer + format: int64 + description: The creation time as a Unix timestamp in seconds. name: type: string minLength: 0 - description: The name of the function to call. - arguments: - description: The arguments to pass to the function. + description: The automation's display name. + target: + $ref: '#/components/schemas/AutomationTargetResource' + description: The session configuration or existing session receiving invocations. + metadata: + type: object + additionalProperties: + type: string + minLength: 0 + propertyNames: + type: string + minLength: 0 + minProperties: 0 + description: Custom string key-value pairs attached to the automation. + created_by: + $ref: '#/components/schemas/AutomationCreatedByResource' + description: Service-recorded provenance; callers cannot supply this field. + run_at: + type: integer + format: int64 + description: The Unix timestamp, in seconds, of the scheduled occurrence. status: - $ref: '#/components/schemas/FunctionCallStatusResource' - description: The status of the function call. + $ref: '#/components/schemas/OnceAutomationStatusResource' + description: Completion means the schedule has finished, not the agent's work. required: - type - id - - turn_id - - call_id + - object + - created_at - name - - arguments + - target + - metadata + - created_by + - run_at - status additionalProperties: false - description: A function call produced by the agent. - InputContentResourceInputText: + description: Fields shared by periodic and one-time automations. + AutomationResource: + description: A saved automation and its schedule. + discriminator: + propertyName: type + mapping: + periodic: '#/components/schemas/AutomationResourcePeriodic' + once: '#/components/schemas/AutomationResourceOnce' + x-oai-discriminator-values: + - periodic + - once + anyOf: + - $ref: '#/components/schemas/AutomationResourcePeriodic' + - $ref: '#/components/schemas/AutomationResourceOnce' + ErrorBodyResource: type: object properties: type: type: string - enum: - - input_text - default: input_text - x-stainless-const: true - description: The type of the object. Always `input_text`. - text: + minLength: 0 + description: The error type. + code: type: string minLength: 0 - description: The text supplied to the agent. + description: A machine-readable error code. + message: + type: string + minLength: 0 + description: A human-readable error message. + param: + type: + - string + - 'null' + minLength: 0 + description: The request parameter that caused the error, or null for a request-wide error. required: - type - - text + - code + - message + - param additionalProperties: false - description: Text input recorded in a session item. - InputContentResourceInputImage: + description: Details about an API error. + ErrorResponse-2: + type: object + properties: + error: + $ref: '#/components/schemas/ErrorBodyResource' + description: The error returned by the API. + required: + - error + additionalProperties: false + description: An API error response. + ReasoningEffortParam: + type: string + enum: + - none + - minimal + - low + - medium + - high + - xhigh + - max + description: The amount of reasoning effort the model should use. + ReasoningSummaryParam: + type: string + enum: + - concise + - detailed + - auto + x-enumDescriptions: + - Returns a concise reasoning summary when supported. + - Returns a detailed reasoning summary when supported. + - Automatically selects the most detailed summary supported by the model. + description: The reasoning summary format requested from the model. + ReasoningParam: + type: object + properties: + effort: + anyOf: + - $ref: '#/components/schemas/ReasoningEffortParam' + - type: 'null' + description: The amount of reasoning effort the model should use. Omission lets the model select it. + summary: + anyOf: + - $ref: '#/components/schemas/ReasoningSummaryParam' + - type: 'null' + description: Controls whether the response includes a reasoning summary. + additionalProperties: false + description: Reasoning configuration for the agent. + TextFormatParamText: type: object properties: type: type: string enum: - - input_image - default: input_image + - text + default: text x-stainless-const: true - description: The type of the object. Always `input_image`. - image_url: + description: The type of the object. Always `text`. + required: + - type + additionalProperties: false + description: Generates ordinary text without a structured-output constraint. + TextFormatParamJsonSchema: + type: object + properties: + type: type: string - minLength: 0 - description: The URL of the image supplied to the agent, which may be a base64-encoded data URL. + enum: + - json_schema + default: json_schema + x-stainless-const: true + description: The type of the object. Always `json_schema`. + schema: + type: object + additionalProperties: {} + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: The JSON Schema that generated text must match. required: - type - - image_url + - schema additionalProperties: false - description: Image input recorded in a session item. - InputContentResource: - description: User-provided content recorded in a session item. + description: Constrains generated text to a JSON Schema. + TextFormatParam: + description: The output format for generated text. discriminator: propertyName: type mapping: - input_text: '#/components/schemas/InputContentResourceInputText' - input_image: '#/components/schemas/InputContentResourceInputImage' + text: '#/components/schemas/TextFormatParamText' + json_schema: '#/components/schemas/TextFormatParamJsonSchema' x-oai-discriminator-values: - - input_text - - input_image - anyOf: - - $ref: '#/components/schemas/InputContentResourceInputText' - - $ref: '#/components/schemas/InputContentResourceInputImage' - FunctionCallOutputResource: - description: The text or model-input content supplied as a function result. + - text + - json_schema anyOf: - - type: string - minLength: 0 - - type: array - items: - $ref: '#/components/schemas/InputContentResource' - minItems: 0 - maxItems: 2000 - FunctionCallOutputItemResource: + - $ref: '#/components/schemas/TextFormatParamText' + - $ref: '#/components/schemas/TextFormatParamJsonSchema' + VerbosityParam: + type: string + enum: + - low + - medium + - high + x-enumDescriptions: + - Produces less text. + - Uses the default amount of text. + - Produces more text. + description: The amount of text the model should produce. + TextParam: type: object properties: - id: - type: string - minLength: 0 - description: The ID of the function call output item. - turn_id: - type: string - minLength: 0 - description: The ID of the turn that contains this item. - type: - type: string - enum: - - function_call_output - default: function_call_output - x-stainless-const: true - description: The item type. Always `function_call_output`. - call_id: - type: string - minLength: 0 - description: The ID of the function call that produced this output. - status: - $ref: '#/components/schemas/FunctionCallStatusResource' - description: The status of the function call. - output: + format: anyOf: - - $ref: '#/components/schemas/FunctionCallOutputResource' + - $ref: '#/components/schemas/TextFormatParam' - type: 'null' - description: The function result, if the call succeeded. - error: - type: - - string - - 'null' - minLength: 0 - description: The error message, if the call failed. + description: 'The output format. Omission uses ordinary text (`{"type": "text"}`).' + verbosity: + anyOf: + - $ref: '#/components/schemas/VerbosityParam' + - type: 'null' + description: The amount of text the model should produce. Defaults to `medium`, matching Responses. + additionalProperties: false + description: Configuration for text generated by the agent. + ServiceTierParam: + type: string + enum: + - auto + - default + - flex + - priority + - fast + - ultrafast + x-enumDescriptions: + - Selects the service tier automatically. + - Uses the default service tier. + - Uses the flex service tier. + - Uses the priority service tier. + - Uses the fast service tier. + - Uses the ultrafast service tier. + description: The service tier used for model requests. + MultiAgentConfigCurrentParam: + type: object + properties: + enabled: + type: boolean + description: Whether subagent tools are enabled. + max_concurrent_subagents: + type: integer + format: int64 + minimum: 1 + maximum: 4294967295 + description: Maximum number of subagents that may run concurrently. Defaults to 6. required: - - id - - turn_id - - type - - call_id - - status - - output - - error + - enabled additionalProperties: false - description: The result supplied for a function call. - AgentMessageItemResource: + description: Explicit configuration for creating and coordinating subagents. + x-openai-go-legacy-bool-fields: + - enabled + AgentToolConfigParamFunction: type: object properties: - id: - type: string - minLength: 0 - description: The ID of the message. - turn_id: - type: string - minLength: 0 - description: The ID of the turn that contains this item. type: type: string enum: - - agent_message - default: agent_message + - function + default: function x-stainless-const: true - description: The item type. Always `agent_message`. - sender_agent_id: + description: The type of the object. Always `function`. + name: type: string minLength: 0 - description: The ID or name of the sending agent. - recipient_agent_id: + maxLength: 1048576 + description: The name of the function. + description: type: string minLength: 0 - description: The ID or name of the receiving agent. - content: - type: array - items: - $ref: '#/components/schemas/AgentContentResource' - minItems: 0 - maxItems: 2000 - description: The content exchanged between the agents. + maxLength: 1048576 + description: A description of what the function does. + parameters: + type: object + additionalProperties: {} + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: A JSON Schema object describing the function's arguments. + defer_loading: + type: boolean + default: false + description: Whether this function is deferred and discovered through tool search. Defaults to `false`. required: - - id - - turn_id - type - - sender_agent_id - - recipient_agent_id - - content + - name + - description + - parameters additionalProperties: false - description: A message exchanged between agent threads. - McpCallItemResource: + description: A function defined by the application. + AgentToolConfigParamToolSearch: type: object properties: type: type: string enum: - - mcp_call - default: mcp_call + - tool_search + default: tool_search x-stainless-const: true - description: The item type. Always `mcp_call`. - id: - type: string - minLength: 0 - description: The ID of the MCP call item. - turn_id: - type: string - minLength: 0 - description: The ID of the turn that contains this item. - server_label: - type: string - minLength: 0 - description: The label of the MCP server. - name: - type: string - minLength: 0 - description: The name of the MCP tool. - arguments: - description: The arguments passed to the MCP tool. - status: - $ref: '#/components/schemas/FunctionCallStatusResource' - description: The status of the MCP tool call. - output: - anyOf: - - {} - - type: 'null' - description: The output returned by the MCP tool, if any. - error: - anyOf: - - {} - - type: 'null' - description: The error returned by the MCP tool, if any. + description: The type of the object. Always `tool_search`. required: - type - - id - - turn_id - - server_label - - name - - arguments - - status - - output - - error additionalProperties: false - description: A call to a tool on an MCP server. - ComputerScreenshotResource: + description: Discovers deferred function tools and loads them into the model context. + AgentToolConfigParamProgrammaticToolCalling: type: object properties: type: type: string enum: - - computer_screenshot - default: computer_screenshot + - programmatic_tool_calling + default: programmatic_tool_calling x-stainless-const: true - description: The content type. Always `computer_screenshot`. - image_url: - type: string - minLength: 0 - description: The complete JPEG image as a base64 data URL. + description: The type of the object. Always `programmatic_tool_calling`. + enabled: + type: boolean + default: true + description: Whether tools can be called from model-generated code. Defaults to `true`. required: - type - - image_url additionalProperties: false - description: A browser screenshot emitted by the model during computer use. - ComputerUseCallItemResource: + description: Enables calling tools from model-generated code. + McpTransportConfigParamHttp: type: object properties: type: type: string enum: - - computer_use_call - default: computer_use_call + - http + default: http x-stainless-const: true - description: The item type. Always `computer_use_call`. - id: - type: string - minLength: 0 - description: The ID of the activity item. - turn_id: + description: The type of the object. Always `http`. + server_url: type: string minLength: 0 - description: The ID of the turn that contains this item. - title: + maxLength: 1048576 + description: The URL of the MCP server. + authorization: type: - string - 'null' minLength: 0 - description: A model-generated description of the activity, when available. - status: - $ref: '#/components/schemas/FunctionCallStatusResource' - description: The execution status of the activity. - output: - anyOf: - - $ref: '#/components/schemas/ComputerScreenshotResource' - - type: 'null' - description: The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. + maxLength: 1048576 + description: The authorization value sent to the MCP server, if any. + headers: + type: + - object + - 'null' + additionalProperties: + type: string + minLength: 0 + maxLength: 1048576 + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: Additional HTTP headers sent to the MCP server. required: - type - - id - - turn_id - - title - - status - - output + - server_url additionalProperties: false - description: One execution of the platform-provided computer-use capability. - BrowserAuthenticationFieldResource: + description: Connects to an MCP server over HTTP. + McpTransportConfigParamStdio: type: object properties: - id: - type: string - minLength: 0 - description: The field ID to submit as field_id in a fields entry. - label: - type: string - minLength: 0 - description: The label to display beside the control. type: type: string - minLength: 0 - description: The rendering type, such as email, password, or text. - required: - type: boolean - description: Whether this control requires a nonempty value. - required: - - id - - label - - type - - required - additionalProperties: false - description: A control in a registered browser-login form. - BrowserAuthenticationOptionResource: - type: object - properties: - id: - type: string - minLength: 0 - description: The option ID to submit as selected_option. - label: + enum: + - stdio + default: stdio + x-stainless-const: true + description: The type of the object. Always `stdio`. + command: type: string minLength: 0 - description: The method label to display. - field_ids: - type: array + maxLength: 1048576 + description: The command used to start the MCP server. + args: + type: + - array + - 'null' items: type: string minLength: 0 + maxLength: 1048576 minItems: 0 - maxItems: 2000 - description: IDs from the registered fields that this method accepts. - required: - - id - - label - - field_ids - additionalProperties: false - description: A sign-in method and the fields that belong to it. - BrowserAuthenticationHistoryRequestKindResourceBrowserAuthentication: - type: object - properties: - type: + maxItems: 16384 + description: Arguments passed to the MCP server command. + cwd: type: string - enum: - - browser_authentication - default: browser_authentication - x-stainless-const: true - description: The type of the object. Always `browser_authentication`. - reason: + minLength: 0 + maxLength: 1048576 + description: The working directory used to start the MCP server. + env: type: - - string + - object - 'null' - minLength: 0 - description: Why the agent needs the user to sign in. - credential_origin: + additionalProperties: + type: string + minLength: 0 + maxLength: 1048576 + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: Environment variables set for the MCP server process. + env_vars: type: - - string + - array - 'null' - minLength: 0 - description: The registered form or frame origin where values will be entered. - fields: - type: array - items: - $ref: '#/components/schemas/BrowserAuthenticationFieldResource' - minItems: 0 - maxItems: 2000 - description: Controls to render. All submitted values are sensitive. - options: - type: array items: - $ref: '#/components/schemas/BrowserAuthenticationOptionResource' + type: string + minLength: 0 + maxLength: 1048576 minItems: 0 - maxItems: 2000 - description: Sign-in methods. Empty for a plain form. + maxItems: 16384 + description: Environment variable names to inherit from the selected execution environment. required: - type - - reason - - credential_origin - - fields - - options + - command + - cwd additionalProperties: false - description: A registered form awaiting the application's response. - BrowserAuthenticationHistoryRequestKindResource: - x-oai-discriminator-values: - - browser_authentication + description: Starts an MCP server as a local process. + McpTransportConfigParam: + description: The transport used to connect to an MCP server. discriminator: propertyName: type mapping: - browser_authentication: '#/components/schemas/BrowserAuthenticationHistoryRequestKindResourceBrowserAuthentication' + http: '#/components/schemas/McpTransportConfigParamHttp' + stdio: '#/components/schemas/McpTransportConfigParamStdio' + x-oai-discriminator-values: + - http + - stdio anyOf: - - $ref: '#/components/schemas/BrowserAuthenticationHistoryRequestKindResourceBrowserAuthentication' - BrowserAuthenticationRequestItemResource: + - $ref: '#/components/schemas/McpTransportConfigParamHttp' + - $ref: '#/components/schemas/McpTransportConfigParamStdio' + McpConnectionOriginParam: + type: string + enum: + - service + - environment + x-enumDescriptions: + - Uses the Managed Agents service network. + - Uses the session's execution environment. + description: Where outbound MCP HTTP connections originate. + AgentToolConfigParamMcp: type: object properties: - turn_id: - type: string - minLength: 0 - request_id: - type: string - minLength: 0 - request: - $ref: '#/components/schemas/BrowserAuthenticationHistoryRequestKindResource' - id: - type: string - minLength: 0 - description: The stable history item ID. type: type: string enum: - - computer_use_approval_request - default: computer_use_approval_request + - mcp + default: mcp x-stainless-const: true - description: The item type. Always computer_use_approval_request. + description: The type of the object. Always `mcp`. + server_label: + type: string + minLength: 0 + maxLength: 1048576 + description: A label used to identify the MCP server in tool calls. + credential_id: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL. + transport: + $ref: '#/components/schemas/McpTransportConfigParam' + description: The transport used to connect to the MCP server. + request_metadata: + type: + - object + - 'null' + additionalProperties: {} + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: Metadata included with requests to this MCP server. + allowed_tools: + type: + - array + - 'null' + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: The MCP tools the agent may call. All server tools are allowed when omitted. + required: + type: boolean + default: false + description: Whether this MCP server must initialize before the first turn. Defaults to `false`. + connection_origin: + anyOf: + - $ref: '#/components/schemas/McpConnectionOriginParam' + - type: 'null' + description: Selects where outbound MCP HTTP connections originate. Omitted or `service` uses the Managed Agents service network; `environment` uses the session's selected environment. required: - - turn_id - - request_id - - request - - id - type + - server_label + - transport additionalProperties: false - description: A credential-free history record of the emitted login request. - ComputerUseApprovalResponseKindResourceBrowserAuthenticationSubmitResource: + description: Tools provided by a remote MCP server. + WebSearchModeParam: + type: string + enum: + - disabled + - cached + - live + x-enumDescriptions: + - Disables web search. + - Uses cached search results. + - Searches the live web. + description: The source used for web search results. + WebSearchContextSizeParam: + type: string + enum: + - low + - medium + - high + description: The amount of web search context made available to the model. + WebSearchLocationParam: + type: object + properties: + country: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The two-letter ISO country code, such as `US`. + region: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The region or state name. + city: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The city name. + timezone: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The IANA timezone, such as `America/Los_Angeles`. + additionalProperties: false + description: Approximate user location used to localize web search results. + AgentToolConfigParamWebSearch: type: object properties: type: type: string enum: - - browser_authentication - default: browser_authentication - x-stainless-const: true - action: - type: string - enum: - - submit - default: submit + - web_search + default: web_search x-stainless-const: true - selected_option: + description: The type of the object. Always `web_search`. + mode: + anyOf: + - $ref: '#/components/schemas/WebSearchModeParam' + - type: 'null' + description: The source used for web search results. Defaults to `live`. + context_size: + anyOf: + - $ref: '#/components/schemas/WebSearchContextSizeParam' + - type: 'null' + description: The amount of search context made available to the model. Defaults to `medium`. + allowed_domains: type: - - string + - array - 'null' - minLength: 0 - description: The chosen sign-in method, or null when no options were offered. + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: Domains the search may include. + location: + anyOf: + - $ref: '#/components/schemas/WebSearchLocationParam' + - type: 'null' + description: Approximate location used to localize search results. required: - type - - action - - selected_option additionalProperties: false - ComputerUseApprovalResponseKindResourceBrowserAuthenticationCancelResource: + description: Web search. + AgentToolConfigParamComputerUse: type: object properties: type: type: string enum: - - browser_authentication - default: browser_authentication + - computer_use + default: computer_use x-stainless-const: true - action: + description: The type of the object. Always `computer_use`. + include_screenshots: + type: boolean + default: false + description: Whether computer tool outputs include screenshots. Defaults to `false`. + required: + - type + additionalProperties: false + description: Browser use in an OpenAI-hosted session. + AgentToolConfigParamAutomations: + type: object + properties: + type: type: string enum: - - cancel - default: cancel + - automations + default: automations x-stainless-const: true + description: The type of the object. Always `automations`. required: - type - - action additionalProperties: false - ComputerUseApprovalResponseKindResource: - x-oai-discriminator-values: - - submit - - cancel + description: Lets the agent manage its own scheduled wakeups. + AgentToolConfigParam: + description: A tool available to the agent. discriminator: - propertyName: action + propertyName: type mapping: - submit: '#/components/schemas/ComputerUseApprovalResponseKindResourceBrowserAuthenticationSubmitResource' - cancel: '#/components/schemas/ComputerUseApprovalResponseKindResourceBrowserAuthenticationCancelResource' + function: '#/components/schemas/AgentToolConfigParamFunction' + tool_search: '#/components/schemas/AgentToolConfigParamToolSearch' + programmatic_tool_calling: '#/components/schemas/AgentToolConfigParamProgrammaticToolCalling' + mcp: '#/components/schemas/AgentToolConfigParamMcp' + web_search: '#/components/schemas/AgentToolConfigParamWebSearch' + computer_use: '#/components/schemas/AgentToolConfigParamComputerUse' + automations: '#/components/schemas/AgentToolConfigParamAutomations' + x-oai-discriminator-values: + - function + - tool_search + - programmatic_tool_calling + - mcp + - web_search + - computer_use + - automations anyOf: - - $ref: '#/components/schemas/ComputerUseApprovalResponseKindResourceBrowserAuthenticationSubmitResource' - - $ref: '#/components/schemas/ComputerUseApprovalResponseKindResourceBrowserAuthenticationCancelResource' - ComputerUseApprovalRequestResultItemResource: + - $ref: '#/components/schemas/AgentToolConfigParamFunction' + - $ref: '#/components/schemas/AgentToolConfigParamToolSearch' + - $ref: '#/components/schemas/AgentToolConfigParamProgrammaticToolCalling' + - $ref: '#/components/schemas/AgentToolConfigParamMcp' + - $ref: '#/components/schemas/AgentToolConfigParamWebSearch' + - $ref: '#/components/schemas/AgentToolConfigParamComputerUse' + - $ref: '#/components/schemas/AgentToolConfigParamAutomations' + SessionAgentConfigParam: type: object properties: - id: + model: type: string minLength: 0 - description: The stable history item ID. + maxLength: 1048576 + description: The model to use for the agent. The requested model name is preserved. + reasoning: + anyOf: + - $ref: '#/components/schemas/ReasoningParam' + - type: 'null' + description: Configuration for model reasoning. Omit to keep the current settings; pass `null` to reset to the model's default effort. + text: + anyOf: + - $ref: '#/components/schemas/TextParam' + - type: 'null' + description: Configuration for text generated by the agent. + service_tier: + anyOf: + - $ref: '#/components/schemas/ServiceTierParam' + - type: 'null' + description: The service tier used for model requests. + instructions: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. + multi_agent: + anyOf: + - $ref: '#/components/schemas/MultiAgentConfigCurrentParam' + - type: 'null' + description: Configuration for creating and coordinating subagents. + tools: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/AgentToolConfigParam' + minItems: 0 + maxItems: 16384 + description: Tools available to the agent. Omit to inherit, or pass null to clear them. The resolved tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON. + additionalProperties: false + description: Agent configuration for a session. Omitted fields inherit from `agent_id` when supplied. Supplied objects and arrays replace the whole field; null resets nullable fields. + EnvironmentParamNone: + type: object + properties: type: type: string enum: - - computer_use_approval_request_result - default: computer_use_approval_request_result + - none + default: none x-stainless-const: true - turn_id: - type: string - minLength: 0 - description: The ID of the turn that contains this item. - request_id: - type: string - minLength: 0 - description: The registered request answered by this item. - response: - $ref: '#/components/schemas/ComputerUseApprovalResponseKindResource' - description: The admitted response, without submitted credential values. + description: The type of the object. Always `none`. required: - - id - type - - turn_id - - request_id - - response additionalProperties: false - description: A credential-free record of an admitted response, not proof of completion. - WebSearchActionResourceSearch: + description: Runs the agent without an execution environment. + EnvironmentPackagesParam: type: object properties: - type: - type: string - enum: - - search - default: search - x-stainless-const: true - description: The type of the object. Always `search`. - query: + python: type: - - string + - array - 'null' - minLength: 0 - description: The search query, when a single query was used. - queries: + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: Python packages to install. Defaults to an empty list. + system: type: - array - 'null' items: type: string minLength: 0 + maxLength: 1048576 minItems: 0 - maxItems: 2000 - description: The search queries, when multiple queries were used. - required: - - type - - query - - queries + maxItems: 16384 + description: System packages to install. Defaults to an empty list. + npm: + type: + - array + - 'null' + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: npm packages to install globally. Defaults to an empty list. additionalProperties: false - description: A search query or group of search queries. - WebSearchActionResourceOpenPage: + description: Packages to install in an OpenAI-hosted environment. + SetupCommandParam: type: object properties: - type: + command: type: string - enum: - - open_page - default: open_page - x-stainless-const: true - description: The type of the object. Always `open_page`. - url: + minLength: 0 + maxLength: 65536 + description: The shell command to execute. + cwd: type: - string - 'null' minLength: 0 - description: The URL of the page that was opened. + maxLength: 4096 + description: The absolute working directory. Defaults to `/workspace`. required: - - type - - url + - command additionalProperties: false - description: Opens a web page. - WebSearchActionResourceFindInPage: + description: A confidential setup command executed before the hosted agent starts. + NetworkAccessParam: + type: string + enum: + - enabled + - disabled + - restricted + x-enumDescriptions: + - Allows unrestricted network access. + - Disables network access. + - Applies the configured domain restrictions. + description: The network access mode for an OpenAI-hosted environment. + NetworkPolicyParam: + type: object + properties: + access: + $ref: '#/components/schemas/NetworkAccessParam' + description: The environment's network access mode. + allowed_domains: + type: + - array + - 'null' + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: Domains the environment may access when network access is restricted. + blocked_domains: + type: + - array + - 'null' + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 100 + description: 'Domains blocked for both executor and browser when access is restricted. A nonempty list requires `access: restricted` and cannot be combined with nonempty `allowed_domains`. Wildcard domains are not supported.' + required: + - access + additionalProperties: false + description: Network access for an OpenAI-hosted environment. + example: + access: restricted + allowed_domains: + - example.com + blocked_domains: [] + DesktopParam: + type: object + properties: + enabled: + type: boolean + description: Whether to provision the desktop and its browser proxy. + required: + - enabled + additionalProperties: false + description: Desktop configuration for an OpenAI-hosted environment. + HostedSkillParamSkillReference: type: object properties: type: type: string enum: - - find_in_page - default: find_in_page + - skill_reference + default: skill_reference x-stainless-const: true - description: The type of the object. Always `find_in_page`. - url: - type: - - string - - 'null' - minLength: 0 - description: The URL of the page that was searched. - pattern: + description: The type of the object. Always `skill_reference`. + skill_id: + type: string + minLength: 1 + maxLength: 64 + description: The ID of the skill created through `/v1/skills`. + version: type: - string - 'null' minLength: 0 - description: The text pattern that was searched for. + maxLength: 1048576 + description: The skill version, a positive integer or `latest`; omission selects the default. required: - type - - url - - pattern + - skill_id additionalProperties: false - description: Finds text within a web page. - WebSearchActionResourceOther: + description: References a skill uploaded through the Skills API. + InlineCapabilitySourceParamBase64: type: object properties: type: type: string enum: - - other - default: other + - base64 + default: base64 x-stainless-const: true - description: The type of the object. Always `other`. + description: The type of the object. Always `base64`. + media_type: + type: string + enum: + - application/zip + default: application/zip + x-stainless-const: true + x-enumDescriptions: + - A ZIP archive. + description: The archive media type, always `application/zip`. + data: + type: string + minLength: 1 + maxLength: 70254592 + description: Standard-base64 encoded ZIP archive bytes. required: - type + - media_type + - data additionalProperties: false - description: Another web search action. - WebSearchActionResource: - description: An action performed by the web search tool. + description: Provides ZIP bytes encoded with standard base64. + InlineCapabilitySourceParam: + description: The encoded ZIP archive for an inline skill or plugin. discriminator: propertyName: type mapping: - search: '#/components/schemas/WebSearchActionResourceSearch' - open_page: '#/components/schemas/WebSearchActionResourceOpenPage' - find_in_page: '#/components/schemas/WebSearchActionResourceFindInPage' - other: '#/components/schemas/WebSearchActionResourceOther' + base64: '#/components/schemas/InlineCapabilitySourceParamBase64' x-oai-discriminator-values: - - search - - open_page - - find_in_page - - other + - base64 anyOf: - - $ref: '#/components/schemas/WebSearchActionResourceSearch' - - $ref: '#/components/schemas/WebSearchActionResourceOpenPage' - - $ref: '#/components/schemas/WebSearchActionResourceFindInPage' - - $ref: '#/components/schemas/WebSearchActionResourceOther' - WebSearchCallItemResource: + - $ref: '#/components/schemas/InlineCapabilitySourceParamBase64' + HostedSkillParamInline: type: object properties: type: type: string enum: - - web_search_call - default: web_search_call + - inline + default: inline x-stainless-const: true - description: The item type. Always `web_search_call`. - id: + description: The type of the object. Always `inline`. + name: type: string - minLength: 0 - description: The ID of the web search call. - turn_id: + minLength: 1 + maxLength: 64 + description: The skill name declared in `SKILL.md`. + description: type: string minLength: 0 - description: The ID of the turn that contains this item. - status: - $ref: '#/components/schemas/OutputItemStatusResource' - description: The status of the web search call. - action: - anyOf: - - $ref: '#/components/schemas/WebSearchActionResource' - - type: 'null' - description: The action performed by the web search tool. + maxLength: 1048576 + description: The skill description declared in `SKILL.md`. + source: + $ref: '#/components/schemas/InlineCapabilitySourceParam' + description: The inline ZIP archive. + x-stainless-go-json: omitzero required: - type - - id - - turn_id - - status - - action + - name + - description + - source additionalProperties: false - description: A web search call produced by the agent. - CommandExecutionItemResource: + description: Supplies a skill ZIP directly in the session request. + HostedSkillParam: + description: A skill installed in an OpenAI-hosted environment. + discriminator: + propertyName: type + mapping: + skill_reference: '#/components/schemas/HostedSkillParamSkillReference' + inline: '#/components/schemas/HostedSkillParamInline' + x-oai-discriminator-values: + - skill_reference + - inline + anyOf: + - $ref: '#/components/schemas/HostedSkillParamSkillReference' + - $ref: '#/components/schemas/HostedSkillParamInline' + HostedPluginParamInline: type: object properties: type: type: string enum: - - command_execution - default: command_execution + - inline + default: inline x-stainless-const: true - description: The item type. Always `command_execution`. - id: - type: string - minLength: 0 - description: The ID of the command execution item. - turn_id: + description: The type of the object. Always `inline`. + name: type: string - minLength: 0 - description: The ID of the turn that contains this item. - command: + minLength: 1 + maxLength: 64 + description: The plugin name declared in `.codex-plugin/plugin.json`. + description: type: string minLength: 0 - description: The command that was executed. - cwd: - type: - - string - - 'null' - minLength: 0 - description: The working directory used to execute the command. - status: - $ref: '#/components/schemas/FunctionCallStatusResource' - description: The status of the command execution. - output: - type: - - string - - 'null' - minLength: 0 - description: The command output, if available. - exit_code: - type: - - integer - - 'null' - format: int64 - description: The process exit code, if the command completed. - duration_ms: - type: - - integer - - 'null' - format: int64 - description: The command duration in milliseconds. + maxLength: 1048576 + description: The plugin description declared in `.codex-plugin/plugin.json`. + source: + $ref: '#/components/schemas/InlineCapabilitySourceParam' + description: The inline ZIP archive. + x-stainless-go-json: omitzero required: - type - - id - - turn_id - - command - - cwd - - status - - output - - exit_code - - duration_ms + - name + - description + - source additionalProperties: false - description: A command execution produced by the agent. - InterruptSubagentCallItemResource: + description: Supplies a plugin ZIP directly in the session request. + HostedPluginParam: + description: A plugin installed in an OpenAI-hosted environment. + discriminator: + propertyName: type + mapping: + inline: '#/components/schemas/HostedPluginParamInline' + x-oai-discriminator-values: + - inline + anyOf: + - $ref: '#/components/schemas/HostedPluginParamInline' + HostedEnvironmentFileParamFileId: type: object properties: type: type: string enum: - - interrupt_subagent_call - default: interrupt_subagent_call + - file_id + default: file_id x-stainless-const: true - x-enumDescriptions: - - The current public item type. - description: The item type. Always `interrupt_subagent_call`. - id: - type: string - minLength: 0 - description: The ID of the tool call item. - turn_id: - type: string - minLength: 0 - description: The ID of the turn that contains this item. - status: - $ref: '#/components/schemas/FunctionCallStatusResource' - description: The status of the tool call. - sender_agent_id: + description: The type of the object. Always `file_id`. + file_id: type: string - minLength: 0 - description: The ID of the agent requesting the interrupt. - recipient_agent_id: + minLength: 1 + maxLength: 256 + description: The ID of the uploaded file. + path: type: string - minLength: 0 - description: The ID of the agent to interrupt. + minLength: 1 + maxLength: 4096 + description: The absolute destination path inside `/workspace`. required: - type - - id - - turn_id - - status - - sender_agent_id - - recipient_agent_id + - file_id + - path additionalProperties: false - description: A request to interrupt a subagent's current turn. The subagent remains available. - CreateSubagentCallItemResource: + description: A file previously uploaded through the OpenAI Files API. + HostedEnvironmentFileParamInline: type: object properties: type: type: string enum: - - create_subagent_call - default: create_subagent_call + - inline + default: inline x-stainless-const: true - x-enumDescriptions: - - The current public item type. - description: The item type. Always `create_subagent_call`. - id: + description: The type of the object. Always `inline`. + data: type: string minLength: 0 - description: The ID of the tool call item. - turn_id: + maxLength: 6990508 + description: The standard-base64-encoded file contents. + path: type: string - minLength: 0 - description: The ID of the turn that contains this item. - status: - $ref: '#/components/schemas/FunctionCallStatusResource' - description: The status of the tool call. - agent_id: + minLength: 1 + maxLength: 4096 + description: The absolute destination path inside `/workspace`. + required: + - type + - data + - path + additionalProperties: false + description: A file supplied directly as standard-base64 data. + HostedEnvironmentFileParam: + description: A file materialized in an OpenAI-hosted execution environment. + discriminator: + propertyName: type + mapping: + file_id: '#/components/schemas/HostedEnvironmentFileParamFileId' + inline: '#/components/schemas/HostedEnvironmentFileParamInline' + x-oai-discriminator-values: + - file_id + - inline + anyOf: + - $ref: '#/components/schemas/HostedEnvironmentFileParamFileId' + - $ref: '#/components/schemas/HostedEnvironmentFileParamInline' + ContainerSizeParam: + type: string + enum: + - small + - medium + - large + description: The CPU and memory tier for a new OpenAI-hosted session environment. + EnvironmentParamOpenaiHosted: + type: object + properties: + type: type: string - minLength: 0 - description: The ID of the agent that requested the subagent. - content: - type: array + enum: + - openai_hosted + default: openai_hosted + x-stainless-const: true + description: The type of the object. Always `openai_hosted`. + packages: + anyOf: + - $ref: '#/components/schemas/EnvironmentPackagesParam' + - type: 'null' + description: Packages to install in the environment. Defaults to empty package lists. + setup_commands: + type: + - array + - 'null' items: - $ref: '#/components/schemas/AgentContentResource' + $ref: '#/components/schemas/SetupCommandParam' minItems: 0 - maxItems: 2000 - description: The task given to the spawned agent. - model: + maxItems: 16 + description: Ordered, confidential setup commands. Command bodies are never returned. + network: + anyOf: + - $ref: '#/components/schemas/NetworkPolicyParam' + - type: 'null' + description: Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled. + desktop: + anyOf: + - $ref: '#/components/schemas/DesktopParam' + - type: 'null' + description: Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled. + x-openai-go-legacy-bool-fields: + - enabled + env: type: - - string + - object - 'null' - minLength: 0 - description: The model requested for the spawned agent. - reasoning_effort: + additionalProperties: + type: string + minLength: 0 + maxLength: 1048576 + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: Environment variables made available to the agent. + capability_directories: type: - - string + - array + - 'null' + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: Directories that contain capabilities exposed to the agent. Defaults to an empty list. + skills: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/HostedSkillParam' + minItems: 0 + maxItems: 200 + description: Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. + plugins: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/HostedPluginParam' + minItems: 0 + maxItems: 32 + description: Plugins provided as inline ZIP archives. Defaults to an empty list. + files: + type: + - array - 'null' + items: + $ref: '#/components/schemas/HostedEnvironmentFileParam' + minItems: 0 + maxItems: 50 + description: Files available before the agent starts. Defaults to an empty list. + environment_id: + type: string + minLength: 9 + maxLength: 256 + description: An existing prewarmed environment. Cannot be combined with a template or inline configuration. + environment_template_id: + type: string minLength: 0 - description: The reasoning effort requested for the spawned agent. + maxLength: 64 + description: A reusable hosted template applied before inline session configuration. Omitted fields inherit the template; network overrides cannot broaden its policy. + container_size: + $ref: '#/components/schemas/ContainerSizeParam' + description: The hosted container size. Omission selects the medium tier. + x-stainless-skip: + - cli required: - type - - id - - turn_id - - status - - agent_id - - content - - model - - reasoning_effort additionalProperties: false - description: A request to spawn a subagent. - SendSubagentInputCallItemResource: + description: An existing OpenAI-hosted environment or new inline/template-based hosted configuration. + not: + required: + - environment_id + anyOf: + - required: + - packages + - required: + - setup_commands + - required: + - network + - required: + - desktop + - required: + - env + - required: + - capability_directories + - required: + - skills + - required: + - plugins + - required: + - files + - required: + - environment_template_id + - required: + - container_size + EnvironmentParamSelfHosted: type: object properties: type: type: string enum: - - send_subagent_input_call - default: send_subagent_input_call + - self_hosted + default: self_hosted x-stainless-const: true - x-enumDescriptions: - - The current public item type. - description: The item type. Always `send_subagent_input_call`. - id: - type: string - minLength: 0 - description: The ID of the tool call item. - turn_id: - type: string - minLength: 0 - description: The ID of the turn that contains this item. - status: - $ref: '#/components/schemas/FunctionCallStatusResource' - description: The status of the tool call. - sender_agent_id: - type: string - minLength: 0 - description: The ID of the agent sending the input. - recipient_agent_id: - type: string - minLength: 0 - description: The ID of the agent receiving the input. - content: - type: array + description: The type of the object. Always `self_hosted`. + capability_directories: + type: + - array + - 'null' items: - $ref: '#/components/schemas/AgentContentResource' + type: string + minLength: 0 + maxLength: 1048576 minItems: 0 - maxItems: 2000 - description: The input sent to the receiving agent. + maxItems: 16384 + description: Directories that contain capabilities exposed to the agent. Defaults to an empty list. + workspace_directory: + type: string + minLength: 0 + maxLength: 1048576 + description: Absolute project directory inside the self-hosted environment. required: - type - - id - - turn_id - - status - - sender_agent_id - - recipient_agent_id - - content + - workspace_directory additionalProperties: false - description: A request to send input to another agent. - ResumeSubagentCallItemResource: + description: An application-hosted environment configured inline. + EnvironmentParam: + description: The execution environment and optional reusable template for a session. + discriminator: + propertyName: type + mapping: + none: '#/components/schemas/EnvironmentParamNone' + openai_hosted: '#/components/schemas/EnvironmentParamOpenaiHosted' + self_hosted: '#/components/schemas/EnvironmentParamSelfHosted' + x-oai-discriminator-values: + - none + - openai_hosted + - self_hosted + anyOf: + - $ref: '#/components/schemas/EnvironmentParamNone' + - $ref: '#/components/schemas/EnvironmentParamOpenaiHosted' + - $ref: '#/components/schemas/EnvironmentParamSelfHosted' + InputContentParamInputText: type: object properties: type: type: string enum: - - resume_subagent_call - default: resume_subagent_call + - input_text + default: input_text x-stainless-const: true - x-enumDescriptions: - - The current public item type. - description: The item type. Always `resume_subagent_call`. - id: - type: string - minLength: 0 - description: The ID of the tool call item. - turn_id: - type: string - minLength: 0 - description: The ID of the turn that contains this item. - status: - $ref: '#/components/schemas/FunctionCallStatusResource' - description: The status of the tool call. - sender_agent_id: - type: string - minLength: 0 - description: The ID of the agent requesting the resume. - recipient_agent_id: + description: The type of the object. Always `input_text`. + text: type: string minLength: 0 - description: The ID of the agent to resume. + maxLength: 1048576 + description: The text sent to the model. required: - type - - id - - turn_id - - status - - sender_agent_id - - recipient_agent_id + - text additionalProperties: false - description: A request to resume a subagent. - WaitForSubagentsCallItemResource: + description: Text input to the model. + InputContentParamInputImage: type: object properties: type: type: string enum: - - wait_for_subagents_call - default: wait_for_subagents_call + - input_image + default: input_image x-stainless-const: true - x-enumDescriptions: - - The current public item type. - description: The item type. Always `wait_for_subagents_call`. - id: - type: string - minLength: 0 - description: The ID of the tool call item. - turn_id: + description: The type of the object. Always `input_image`. + image_url: type: string minLength: 0 - description: The ID of the turn that contains this item. - status: - $ref: '#/components/schemas/FunctionCallStatusResource' - description: The status of the tool call. - sender_agent_id: + maxLength: 1048576 + description: The URL of the image sent to the model. + required: + - type + - image_url + additionalProperties: false + description: Image input to the model. + InputContentParam: + description: Content included in an input message. + discriminator: + propertyName: type + mapping: + input_text: '#/components/schemas/InputContentParamInputText' + input_image: '#/components/schemas/InputContentParamInputImage' + x-oai-discriminator-values: + - input_text + - input_image + anyOf: + - $ref: '#/components/schemas/InputContentParamInputText' + - $ref: '#/components/schemas/InputContentParamInputImage' + InputMessageParam: + type: object + properties: + type: + type: string + enum: + - message + default: message + x-stainless-const: true + description: The type of the input item. Always `message`. + role: + type: string + enum: + - user + default: user + x-stainless-const: true + description: The role of the message author. Always `user`. + content: + type: array + items: + $ref: '#/components/schemas/InputContentParam' + minItems: 0 + maxItems: 16384 + description: The content of the message. + required: + - role + - content + additionalProperties: false + description: A user message submitted to a session. + AutomationTargetParamNewSession: + type: object + properties: + type: + type: string + enum: + - new_session + default: new_session + x-stainless-const: true + description: The type of the object. Always `new_session`. + agent: + $ref: '#/components/schemas/SessionAgentConfigParam' + description: Inline agent configuration. Provide exactly one of agent and agent_id. + agent_id: type: string minLength: 0 - description: The ID of the agent waiting for results. - recipient_agent_ids: + maxLength: 64 + description: A saved agent ID. Provide exactly one of agent and agent_id. + environment: + $ref: '#/components/schemas/EnvironmentParam' + description: The execution environment for each new session. + input: type: array + items: + $ref: '#/components/schemas/InputMessageParam' + minItems: 0 + maxItems: 16384 + description: Initial user messages submitted with each new session. + vault_ids: + type: + - array + - 'null' items: type: string minLength: 0 + maxLength: 1048576 minItems: 0 - maxItems: 2000 - description: The IDs of the agents to wait for. + maxItems: 16384 + description: The IDs of vaults made available to each new session. + metadata: + type: + - object + - 'null' + additionalProperties: + type: string + minLength: 0 + maxLength: 512 + propertyNames: + type: string + minLength: 1 + maxLength: 64 + minProperties: 0 + maxProperties: 16 + description: Metadata attached to each new session. required: - type - - id - - turn_id - - status - - sender_agent_id - - recipient_agent_ids + - environment + - input additionalProperties: false - description: A request to wait for one or more subagents. - CloseSubagentCallItemResource: + description: Create a session for each invocation. + AutomationTargetParamExistingSession: type: object properties: type: type: string enum: - - close_subagent_call - default: close_subagent_call + - existing_session + default: existing_session x-stainless-const: true - x-enumDescriptions: - - The current public item type. - description: The item type. Always `close_subagent_call`. - id: + description: The type of the object. Always `existing_session`. + session_id: type: string minLength: 0 - description: The ID of the tool call item. - turn_id: + maxLength: 1048576 + description: The session receiving each invocation. + instructions: type: string minLength: 0 - description: The ID of the turn that contains this item. - status: - $ref: '#/components/schemas/FunctionCallStatusResource' - description: The status of the tool call. - sender_agent_id: + maxLength: 1048576 + description: Instructions delivered as an automation notification. + required: + - type + - session_id + - instructions + additionalProperties: false + description: Deliver instructions to an existing session. + AutomationTargetParam: + description: The session an automation invocation targets. + discriminator: + propertyName: type + mapping: + new_session: '#/components/schemas/AutomationTargetParamNewSession' + existing_session: '#/components/schemas/AutomationTargetParamExistingSession' + x-oai-discriminator-values: + - new_session + - existing_session + anyOf: + - $ref: '#/components/schemas/AutomationTargetParamNewSession' + - $ref: '#/components/schemas/AutomationTargetParamExistingSession' + CreateAutomationParamsPeriodic: + type: object + properties: + type: type: string - minLength: 0 - description: The ID of the agent requesting the close. - recipient_agent_id: + enum: + - periodic + default: periodic + x-stainless-const: true + description: The type of the object. Always `periodic`. + name: type: string - minLength: 0 - description: The ID of the agent to close. + minLength: 1 + maxLength: 256 + description: A human-readable name for the automation. + target: + $ref: '#/components/schemas/AutomationTargetParam' + metadata: + $ref: '#/components/schemas/AutomationMetadataParam' + expression: + type: string + minLength: 1 + maxLength: 256 + description: A standard five-field cron expression defining scheduled occurrences. + timezone: + type: string + minLength: 1 + maxLength: 128 + description: The IANA timezone used to interpret the cron expression. required: - type - - id - - turn_id - - status - - sender_agent_id - - recipient_agent_id + - name + - target + - expression + - timezone additionalProperties: false - description: A request to close a subagent. - SessionTurnItemResource: - description: An item associated with a session turn. + CreateAutomationParamsOnce: + type: object + properties: + type: + type: string + enum: + - once + default: once + x-stainless-const: true + description: The type of the object. Always `once`. + name: + type: string + minLength: 1 + maxLength: 256 + description: A human-readable name for the automation. + target: + $ref: '#/components/schemas/AutomationTargetParam' + metadata: + $ref: '#/components/schemas/AutomationMetadataParam' + run_at: + type: integer + format: int64 + description: A future Unix timestamp in seconds. + required: + - type + - name + - target + - run_at + additionalProperties: false + CreateAutomationParams: + description: Creates an automation without invoking it immediately. discriminator: propertyName: type mapping: - message: '#/components/schemas/MessageItemResource' - reasoning: '#/components/schemas/ReasoningItemResource' - function_call: '#/components/schemas/FunctionCallItemResource' - function_call_output: '#/components/schemas/FunctionCallOutputItemResource' - agent_message: '#/components/schemas/AgentMessageItemResource' - mcp_call: '#/components/schemas/McpCallItemResource' - computer_use_call: '#/components/schemas/ComputerUseCallItemResource' - computer_use_approval_request: '#/components/schemas/BrowserAuthenticationRequestItemResource' - computer_use_approval_request_result: '#/components/schemas/ComputerUseApprovalRequestResultItemResource' - web_search_call: '#/components/schemas/WebSearchCallItemResource' - command_execution: '#/components/schemas/CommandExecutionItemResource' - interrupt_subagent_call: '#/components/schemas/InterruptSubagentCallItemResource' - create_subagent_call: '#/components/schemas/CreateSubagentCallItemResource' - send_subagent_input_call: '#/components/schemas/SendSubagentInputCallItemResource' - resume_subagent_call: '#/components/schemas/ResumeSubagentCallItemResource' - wait_for_subagents_call: '#/components/schemas/WaitForSubagentsCallItemResource' - close_subagent_call: '#/components/schemas/CloseSubagentCallItemResource' + periodic: '#/components/schemas/CreateAutomationParamsPeriodic' + once: '#/components/schemas/CreateAutomationParamsOnce' x-oai-discriminator-values: - - message - - reasoning - - function_call - - function_call_output - - agent_message - - mcp_call - - computer_use_call - - computer_use_approval_request - - computer_use_approval_request_result - - web_search_call - - command_execution - - create_subagent_call - - send_subagent_input_call - - resume_subagent_call - - wait_for_subagents_call - - interrupt_subagent_call - - close_subagent_call + - periodic + - once anyOf: - - $ref: '#/components/schemas/MessageItemResource' - - $ref: '#/components/schemas/ReasoningItemResource' - - $ref: '#/components/schemas/FunctionCallItemResource' - - $ref: '#/components/schemas/FunctionCallOutputItemResource' - - $ref: '#/components/schemas/AgentMessageItemResource' - - $ref: '#/components/schemas/McpCallItemResource' - - $ref: '#/components/schemas/ComputerUseCallItemResource' - - $ref: '#/components/schemas/BrowserAuthenticationRequestItemResource' - - $ref: '#/components/schemas/ComputerUseApprovalRequestResultItemResource' - - $ref: '#/components/schemas/WebSearchCallItemResource' - - $ref: '#/components/schemas/CommandExecutionItemResource' - - $ref: '#/components/schemas/CreateSubagentCallItemResource' - - $ref: '#/components/schemas/SendSubagentInputCallItemResource' - - $ref: '#/components/schemas/ResumeSubagentCallItemResource' - - $ref: '#/components/schemas/WaitForSubagentsCallItemResource' - - $ref: '#/components/schemas/InterruptSubagentCallItemResource' - - $ref: '#/components/schemas/CloseSubagentCallItemResource' - SessionItemListResource: + - $ref: '#/components/schemas/CreateAutomationParamsPeriodic' + - $ref: '#/components/schemas/CreateAutomationParamsOnce' + UpdateAutomationParams: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 256 + target: + $ref: '#/components/schemas/AutomationTargetParam' + description: Replaces the complete target, retaining its type and any creator session. + metadata: + type: object + additionalProperties: + type: string + minLength: 0 + maxLength: 512 + propertyNames: + type: string + minLength: 1 + maxLength: 64 + minProperties: 0 + maxProperties: 16 + description: Replaces all metadata; omit to leave unchanged. + expression: + type: string + minLength: 1 + maxLength: 256 + description: Only accepted for periodic automations. + timezone: + type: string + minLength: 1 + maxLength: 128 + description: Only accepted for periodic automations. + run_at: + type: integer + format: int64 + description: A future Unix timestamp in seconds; accepted only before a one-time scheduled invocation exists. + additionalProperties: false + description: Updates configuration; timing fields must match the stored automation type. + DeletedAutomationResource: type: object properties: + id: + type: string + minLength: 0 + description: The deleted automation ID. object: type: string enum: - - list - default: list + - agent.automation.deleted + default: agent.automation.deleted x-stainless-const: true - description: The object type, which is always `list`. - data: - type: array - items: - $ref: '#/components/schemas/SessionTurnItemResource' - minItems: 0 - maxItems: 2000 - description: The resources returned in this page, in the requested sort order. - first_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the first resource in `data`, or `null` if the page is empty. - last_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - has_more: + description: Always `agent.automation.deleted`. + deleted: type: boolean - description: Whether there are more resources to retrieve after this page. + description: Always true. required: + - id - object - - data - - first_id - - last_id - - has_more + - deleted additionalProperties: false - description: A page of messages, reasoning, and tool calls from a session's item history. - TurnObjectResource: - type: string - enum: - - agent.session.turn - default: agent.session.turn - x-stainless-const: true - description: The object type for a turn. - TurnStatusResource: + AutomationInvocationSourceResourceManual: + type: object + properties: + type: + type: string + enum: + - manual + default: manual + x-stainless-const: true + description: The type of the object. Always `manual`. + required: + - type + additionalProperties: false + AutomationInvocationSourceResourceAutomation: + type: object + properties: + type: + type: string + enum: + - automation + default: automation + x-stainless-const: true + description: The type of the object. Always `automation`. + automation: + $ref: '#/components/schemas/AutomationResource' + description: The automation snapshot for this occurrence, excluding confidential values. + required: + - type + - automation + additionalProperties: false + AutomationInvocationSourceResource: + x-oai-discriminator-values: + - manual + - automation + discriminator: + propertyName: type + mapping: + manual: '#/components/schemas/AutomationInvocationSourceResourceManual' + automation: '#/components/schemas/AutomationInvocationSourceResourceAutomation' + anyOf: + - $ref: '#/components/schemas/AutomationInvocationSourceResourceManual' + - $ref: '#/components/schemas/AutomationInvocationSourceResourceAutomation' + AutomationInvocationStatusResource: type: string enum: - queued - - in_progress - - waiting - completed - failed - - cancelled - x-enumDescriptions: - - The turn is waiting to start. - - The turn is in progress. - - The turn is waiting for external input. - - The turn completed successfully. - - The turn failed. - - The turn was cancelled. - description: The current status of a turn. - SessionTurnErrorCodeResource: - type: string - enum: - - context_length_exceeded - - session_budget_exceeded - - usage_limit_exceeded - - project_spend_limit_exceeded - - organization_spend_limit_exceeded - - organization_usage_limit_exceeded - - billing_not_active - - credit_balance_exhausted - - rate_limit_exceeded - - flex_unavailable - - server_overloaded - - cyber_policy - - misalignment_policy_violation - - connection_failed - - server_error - - authentication_error - - invalid_request - - resource_not_found - - sandbox_error - - executor_version_incompatible - - active_turn_not_steerable - - request_timeout - - internal_error - x-enumDescriptions: - - The request exceeds the model's context window. - - The session has reached its usage budget. - - The organization has reached a usage, plan, or billing limit. - - The project has reached its enforced spend limit. - - The organization has reached its enforced spend limit. - - The organization has reached its OpenAI-assigned usage limit. - - Billing is not active for the account. - - The organization has no API credits remaining. - - The request exceeds the available rate limit. - - Flex processing is temporarily unavailable. - - The model service is temporarily overloaded. - - The request was rejected by a safety policy. - - The request was blocked by the safety systems. - - The request could not connect to the model service. - - The model service encountered an unexpected error. - - The API credentials are invalid or lack the required access. - - The request contains invalid input or configuration. - - The requested model or resource is unavailable. - - The request could not complete in its execution environment. - - The executor must be upgraded before it can run this turn. - - The session cannot accept additional input while a request is running. - - The request timed out before the model service responded. - - An unexpected internal error prevented the session request from completing. - description: Stable public categories for session request failures. - SessionTurnErrorResource: + - skipped + AutomationInvocationErrorResource: type: object properties: code: - $ref: '#/components/schemas/SessionTurnErrorCodeResource' - description: A stable, machine-readable failure category. + type: string + minLength: 0 + description: A machine-readable error code. message: type: string minLength: 0 - description: A customer-safe explanation of the failure. + description: A public explanation of the delivery failure. required: - code - message additionalProperties: false - description: A customer-safe error describing why a session request failed. - InputTokensDetailsResource-2: - type: object - properties: - cached_tokens: - type: integer - format: int64 - description: The number of input tokens retrieved from the prompt cache. - required: - - cached_tokens - additionalProperties: false - description: A breakdown of input token usage for a session or turn. - OutputTokensDetailsResource-2: - type: object - properties: - reasoning_tokens: - type: integer - format: int64 - description: The number of output tokens used for reasoning. - required: - - reasoning_tokens - additionalProperties: false - description: A breakdown of output token usage for a session or turn. - TokenUsageResource: - type: object - properties: - input_tokens: - type: integer - format: int64 - description: The number of input tokens used by the agent. - input_tokens_details: - $ref: '#/components/schemas/InputTokensDetailsResource-2' - description: A breakdown of the agent's input token usage. - output_tokens: - type: integer - format: int64 - description: The number of output tokens generated by the agent. - output_tokens_details: - $ref: '#/components/schemas/OutputTokensDetailsResource-2' - description: A breakdown of the agent's output token usage. - total_tokens: - type: integer - format: int64 - description: The total number of input and output tokens used by the agent. - required: - - input_tokens - - input_tokens_details - - output_tokens - - output_tokens_details - - total_tokens - additionalProperties: false - description: Recorded token usage for a session or turn. Usage is best effort and may change. - TurnResource: + AutomationInvocationResource: type: object properties: id: type: string minLength: 0 - description: The ID of the turn. + description: The invocation ID. object: - $ref: '#/components/schemas/TurnObjectResource' - description: The object type. Always `agent.session.turn`. - session_id: type: string - minLength: 0 - description: The ID of the session that owns the turn. - agent_id: + enum: + - agent.automation.invocation + default: agent.automation.invocation + x-stainless-const: true + description: Always `agent.automation.invocation`. + automation_id: type: string minLength: 0 - description: The ID of the agent that ran the turn. - subagent_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the subagent that ran the turn, if applicable. - status: - $ref: '#/components/schemas/TurnStatusResource' - description: The current status of the turn. + description: The automation that owns the invocation. created_at: type: integer format: int64 - description: The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - started_at: + description: The creation time as a Unix timestamp in seconds. + source: + $ref: '#/components/schemas/AutomationInvocationSourceResource' + description: Whether the invocation was manual or scheduled. + scheduled_at: type: - integer - 'null' format: int64 - description: The Unix timestamp, in seconds, when the turn started. - completed_at: + description: The intended occurrence as a Unix timestamp in seconds, or null for manual runs. + session_id: type: - - integer + - string - 'null' - format: int64 - description: The Unix timestamp, in seconds, when the turn reached a terminal state. + minLength: 0 + description: The target or newly created session ID, or null before one is available. + status: + $ref: '#/components/schemas/AutomationInvocationStatusResource' + description: Delivery status; completed does not mean the agent's work has finished. + skip_reason: + type: + - string + - 'null' + enum: + - pending_delivery + - null + default: pending_delivery + x-stainless-const: true + description: Why an occurrence was skipped, or null when it was not skipped. error: anyOf: - - $ref: '#/components/schemas/SessionTurnErrorResource' - - type: 'null' - description: A customer-safe error. Non-null only for a failed turn. - usage: - anyOf: - - $ref: '#/components/schemas/TokenUsageResource' + - $ref: '#/components/schemas/AutomationInvocationErrorResource' - type: 'null' - description: Best-effort token usage for the turn, or null if unknown. Recorded usage may change. + description: The permanent delivery failure, or null when no failure occurred. required: - id - object + - automation_id + - created_at + - source + - scheduled_at - session_id - - agent_id - - subagent_id - status - - created_at - - started_at - - completed_at + - skip_reason - error - - usage additionalProperties: false - description: The canonical public representation of a session turn. - SessionTurnListResource: - type: object - properties: - object: - type: string - enum: - - list - default: list - x-stainless-const: true - description: The object type, which is always `list`. - data: - type: array - items: - $ref: '#/components/schemas/TurnResource' - minItems: 0 - maxItems: 2000 - description: The resources returned in this page, in the requested sort order. - first_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the first resource in `data`, or `null` if the page is empty. - last_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - has_more: - type: boolean - description: Whether there are more resources to retrieve after this page. - required: - - object - - data - - first_id - - last_id - - has_more - additionalProperties: false - description: A page of Agents API resources, with IDs for retrieving additional pages. - ReasoningEffortResource: + description: One attempted delivery by an automation. + EnvironmentTypeParam: type: string enum: - - none - - minimal - - low - - medium - - high - - xhigh - - max - description: The amount of reasoning effort used by an agent. - ReasoningSummaryResource: + - openai_hosted + description: The hosting type of an execution environment. + EnvironmentTypeResource: type: string enum: - - concise - - detailed - - auto + - openai_hosted + - self_hosted + description: The kind of execution environment. + EnvironmentStatusResource: + type: string + enum: + - pending + - ready + - connected + - disconnected + - suspended + - expired + - failed x-enumDescriptions: - - Returns a concise reasoning summary when supported. - - Returns a detailed reasoning summary when supported. - - Automatically selects the most detailed summary supported by the model. - description: The reasoning summary format requested from an agent. - ReasoningResource: - type: object - properties: - effort: - anyOf: - - $ref: '#/components/schemas/ReasoningEffortResource' - - type: 'null' - description: The requested reasoning effort, or `null` when the model selects its own default. - summary: - anyOf: - - $ref: '#/components/schemas/ReasoningSummaryResource' - - type: 'null' - description: The requested reasoning summary format, or `null` when summaries are disabled. - required: - - effort - - summary - additionalProperties: false - description: The reasoning configuration used by an agent. - TextFormatResourceText: + - '' + - Provisioning succeeded and the environment is available for attachment or use. + - '' + - '' + - The sandbox is stopped and can be resumed from its private checkpoint. + - '' + - '' + description: The public lifecycle status of an execution environment. + HostedEnvironmentFileResourceFileId: type: object properties: type: type: string enum: - - text - default: text + - file_id + default: file_id x-stainless-const: true - description: The type of the object. Always `text`. + description: The type of the object. Always `file_id`. + id: + type: string + minLength: 0 + description: The session-scoped ID of the file in the execution environment. + file_id: + type: string + minLength: 0 + description: The ID of the uploaded file. + path: + type: string + minLength: 0 + description: The file's absolute path inside the environment. + size_bytes: + type: integer + format: int64 + minimum: 0 + description: The decoded file size in bytes. required: - type + - id + - file_id + - path + - size_bytes additionalProperties: false - description: Generates ordinary text without a structured-output constraint. - TextFormatResourceJsonSchema: + description: A file copied from the OpenAI Files API. + HostedEnvironmentFileResourceInline: type: object properties: type: type: string enum: - - json_schema - default: json_schema + - inline + default: inline x-stainless-const: true - description: The type of the object. Always `json_schema`. - schema: - type: object - additionalProperties: {} - propertyNames: - type: string - minLength: 0 - minProperties: 0 - description: The JSON Schema that generated text must match. + description: The type of the object. Always `inline`. + id: + type: string + minLength: 0 + description: The session-scoped ID of the file in the execution environment. + path: + type: string + minLength: 0 + description: The file's absolute path inside the environment. + size_bytes: + type: integer + format: int64 + minimum: 0 + description: The decoded file size in bytes. required: - type - - schema + - id + - path + - size_bytes additionalProperties: false - description: Constrains generated text to a JSON Schema. - TextFormatResource: - description: The effective output format for generated text. + description: A file supplied inline when the session was created. + HostedEnvironmentFileResource: + description: Metadata for a file materialized in an OpenAI-hosted execution environment. discriminator: propertyName: type mapping: - text: '#/components/schemas/TextFormatResourceText' - json_schema: '#/components/schemas/TextFormatResourceJsonSchema' + file_id: '#/components/schemas/HostedEnvironmentFileResourceFileId' + inline: '#/components/schemas/HostedEnvironmentFileResourceInline' x-oai-discriminator-values: - - text - - json_schema + - file_id + - inline anyOf: - - $ref: '#/components/schemas/TextFormatResourceText' - - $ref: '#/components/schemas/TextFormatResourceJsonSchema' - VerbosityResource: - type: string - enum: - - low - - medium - - high - description: The amount of text produced by an agent. - TextResource: - type: object - properties: - format: - $ref: '#/components/schemas/TextFormatResource' - description: The effective output format. Defaults to ordinary text. - verbosity: - $ref: '#/components/schemas/VerbosityResource' - description: The amount of text produced by the agent. Defaults to `medium`. - required: - - format - - verbosity - additionalProperties: false - description: The text configuration used by an agent. - ServiceTierResource: - type: string - enum: - - auto - - default - - flex - - priority - - fast - - ultrafast - description: The service-tier policy configured for an agent. - PersistedAgentToolResourceFunction: + - $ref: '#/components/schemas/HostedEnvironmentFileResourceFileId' + - $ref: '#/components/schemas/HostedEnvironmentFileResourceInline' + HostedSkillResourceSkillReference: type: object properties: type: type: string enum: - - function - default: function + - skill_reference + default: skill_reference x-stainless-const: true - description: The type of the object. Always `function`. + description: The type of the object. Always `skill_reference`. + skill_id: + type: string + minLength: 0 + description: The referenced skill ID. + version: + type: string + minLength: 0 + description: The concrete skill version installed for this session. name: type: string minLength: 0 - description: The name of the function. + description: The installed skill name. description: type: string minLength: 0 - description: A description of what the function does. - parameters: - type: object - additionalProperties: {} - propertyNames: - type: string - minLength: 0 - minProperties: 0 - description: A JSON Schema object describing the function's arguments. - defer_loading: - type: boolean - description: Whether the function is deferred and discovered through tool search. + description: The installed skill description. required: - type + - skill_id + - version - name - description - - parameters - - defer_loading - additionalProperties: false - description: A function defined by the application. - PersistedAgentToolResourceToolSearch: - type: object - properties: - type: - type: string - enum: - - tool_search - default: tool_search - x-stainless-const: true - description: The type of the object. Always `tool_search`. - required: - - type additionalProperties: false - description: Discovers deferred function tools and loads them into the model context. - PersistedAgentToolResourceProgrammaticToolCalling: + description: A skill installed from the Skills API. + HostedSkillResourceInline: type: object properties: type: type: string enum: - - programmatic_tool_calling - default: programmatic_tool_calling + - inline + default: inline x-stainless-const: true - description: The type of the object. Always `programmatic_tool_calling`. - enabled: - type: boolean - description: Whether tools can be called from model-generated code. - required: - - type - - enabled - additionalProperties: false - description: Enables calling tools from model-generated code. - PersistedMcpTransportResourceHttp: - type: object - properties: - type: + description: The type of the object. Always `inline`. + name: type: string - enum: - - http - default: http - x-stainless-const: true - description: The type of the object. Always `http`. - server_url: + minLength: 0 + description: The installed skill name. + description: type: string minLength: 0 - description: The URL of the MCP server. - headers: - type: object - additionalProperties: - type: string - minLength: 0 - propertyNames: - type: string - minLength: 0 - minProperties: 0 - description: Non-secret HTTP headers sent to the MCP server. + description: The installed skill description. required: - type - - server_url - - headers + - name + - description additionalProperties: false - description: Connects to an MCP server over HTTP. - PersistedMcpTransportResourceStdio: + description: A skill installed from an inline ZIP archive. + HostedSkillResource: + description: A skill installed in an OpenAI-hosted environment. + discriminator: + propertyName: type + mapping: + skill_reference: '#/components/schemas/HostedSkillResourceSkillReference' + inline: '#/components/schemas/HostedSkillResourceInline' + x-oai-discriminator-values: + - skill_reference + - inline + anyOf: + - $ref: '#/components/schemas/HostedSkillResourceSkillReference' + - $ref: '#/components/schemas/HostedSkillResourceInline' + PublicEnvironmentResource: type: object properties: type: + $ref: '#/components/schemas/EnvironmentTypeResource' + description: Whether the environment is hosted by OpenAI or by the application. + id: + type: string + minLength: 0 + description: The ID of the environment. + object: type: string enum: - - stdio - default: stdio + - agent.environment + default: agent.environment x-stainless-const: true - description: The type of the object. Always `stdio`. - command: - type: string - minLength: 0 - description: The command used to start the MCP server. - args: + description: The object type. Always `agent.environment`. + status: + $ref: '#/components/schemas/EnvironmentStatusResource' + description: The current environment connection status. + files: type: array items: - type: string - minLength: 0 + $ref: '#/components/schemas/HostedEnvironmentFileResource' minItems: 0 maxItems: 2000 - description: Arguments passed to the MCP server command. - cwd: - type: string - minLength: 0 - description: The working directory used to start the MCP server. - env_vars: + description: Files installed in the environment, without their contents. + skills: type: array items: - type: string - minLength: 0 + $ref: '#/components/schemas/HostedSkillResource' minItems: 0 maxItems: 2000 - description: Environment variable names inherited from the execution environment. + description: Skills installed in the environment, without their archive contents. + plugins: + type: array + items: + $ref: '#/components/schemas/HostedPluginResource' + minItems: 0 + maxItems: 2000 + description: Plugins installed in the environment, without their archive contents. required: + - id + - object - type - - command - - args - - cwd - - env_vars + - status + - files + - skills + - plugins additionalProperties: false - description: Starts an MCP server as a local process. - PersistedMcpTransportResource: - description: A credential-free transport used to connect to an MCP server. - discriminator: - propertyName: type - mapping: - http: '#/components/schemas/PersistedMcpTransportResourceHttp' - stdio: '#/components/schemas/PersistedMcpTransportResourceStdio' - x-oai-discriminator-values: - - http - - stdio - anyOf: - - $ref: '#/components/schemas/PersistedMcpTransportResourceHttp' - - $ref: '#/components/schemas/PersistedMcpTransportResourceStdio' - McpConnectionOriginResource: - type: string - enum: - - service - - environment - description: Where outbound MCP HTTP connections originate. - PersistedAgentToolResourceMcp: + description: Safe metadata for a first-class execution environment. + AgentEnvironmentListResource: type: object properties: - type: + object: type: string enum: - - mcp - default: mcp + - list + default: list x-stainless-const: true - description: The type of the object. Always `mcp`. - server_label: - type: string - minLength: 0 - description: A label used to identify the MCP server in tool calls. - credential_id: - type: - - string - - 'null' - minLength: 0 - description: The vault credential selected for this MCP server, if any. - transport: - $ref: '#/components/schemas/PersistedMcpTransportResource' - description: The credential-free transport used to connect to the MCP server. - request_metadata: - type: object - additionalProperties: {} - propertyNames: - type: string - minLength: 0 - minProperties: 0 - description: Metadata included with requests to this MCP server. - allowed_tools: - type: - - array - - 'null' + description: The object type, which is always `list`. + data: + type: array items: - type: string - minLength: 0 + $ref: '#/components/schemas/PublicEnvironmentResource' minItems: 0 maxItems: 2000 - description: The MCP tools the agent may call, or null when all server tools are allowed. - required: - type: boolean - description: Whether this MCP server must initialize before the first turn. - connection_origin: - $ref: '#/components/schemas/McpConnectionOriginResource' - description: Where outbound MCP HTTP connections originate. - required: - - type - - server_label - - credential_id - - transport - - request_metadata - - allowed_tools - - required - - connection_origin - additionalProperties: false - description: Tools provided by a remote MCP server without stored credentials. - WebSearchModeResource: - type: string - enum: - - disabled - - cached - - live - description: The source used for web search results. - WebSearchContextSizeResource: - type: string - enum: - - low - - medium - - high - description: The amount of web search context made available to the model. - WebSearchLocationResource: - type: object - properties: - country: - type: - - string - - 'null' - minLength: 0 - description: The two-letter ISO country code, such as `US`. - region: - type: - - string - - 'null' - minLength: 0 - description: The region or state name. - city: + description: The resources returned in this page, in the requested sort order. + first_id: type: - string - 'null' minLength: 0 - description: The city name. - timezone: + description: The ID of the first resource in `data`, or `null` if the page is empty. + last_id: type: - string - 'null' minLength: 0 - description: The IANA timezone, such as `America/Los_Angeles`. + description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. + has_more: + type: boolean + description: Whether there are more resources to retrieve after this page. required: - - country - - region - - city - - timezone + - object + - data + - first_id + - last_id + - has_more additionalProperties: false - description: Approximate user location used to localize web search results. - PersistedAgentToolResourceWebSearch: + description: A page of Agents API resources, with IDs for retrieving additional pages. + CreateEnvironmentParamOpenaiHosted: type: object properties: type: type: string enum: - - web_search - default: web_search + - openai_hosted + default: openai_hosted x-stainless-const: true - description: The type of the object. Always `web_search`. - mode: - $ref: '#/components/schemas/WebSearchModeResource' - description: The source used for web search results. - context_size: - $ref: '#/components/schemas/WebSearchContextSizeResource' - description: The amount of search context made available to the model. Defaults to `medium`. - allowed_domains: + description: The type of the object. Always `openai_hosted`. + packages: + anyOf: + - $ref: '#/components/schemas/EnvironmentPackagesParam' + - type: 'null' + description: Packages to install in the environment. Defaults to empty package lists. + setup_commands: type: - array - 'null' items: - type: string - minLength: 0 + $ref: '#/components/schemas/SetupCommandParam' minItems: 0 - maxItems: 2000 - description: Allowed search domains, or `null` when the search is unrestricted. - location: + maxItems: 16 + description: Ordered, confidential setup commands. Command bodies are never returned. + network: anyOf: - - $ref: '#/components/schemas/WebSearchLocationResource' + - $ref: '#/components/schemas/NetworkPolicyParam' - type: 'null' - description: Approximate location used to localize search results, if provided. - required: - - type - - mode - - context_size - - allowed_domains - - location - additionalProperties: false - description: Web search. - PersistedAgentToolResourceComputerUse: - type: object - properties: - type: + description: Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled. + desktop: + anyOf: + - $ref: '#/components/schemas/DesktopParam' + - type: 'null' + description: Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled. + env: + type: + - object + - 'null' + additionalProperties: + type: string + minLength: 0 + maxLength: 1048576 + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: Environment variables made available to the agent. + capability_directories: + type: + - array + - 'null' + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: Directories that contain capabilities exposed to the agent. Defaults to an empty list. + skills: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/HostedSkillParam' + minItems: 0 + maxItems: 200 + description: Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. + plugins: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/HostedPluginParam' + minItems: 0 + maxItems: 32 + description: Plugins provided as inline ZIP archives. Defaults to an empty list. + files: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/HostedEnvironmentFileParam' + minItems: 0 + maxItems: 50 + description: Files available before the agent starts. Defaults to an empty list. + environment_template_id: type: string - enum: - - computer_use - default: computer_use - x-stainless-const: true - description: The type of the object. Always `computer_use`. - include_screenshots: - type: boolean - description: Whether computer tool outputs include screenshots. + minLength: 0 + maxLength: 64 + description: A reusable hosted template applied before inline configuration. Omitted fields inherit the template; network overrides cannot broaden its policy. required: - type - - include_screenshots additionalProperties: false - description: Browser use in an OpenAI-hosted session. - PersistedAgentToolResource: - description: A credential-free tool available to a reusable agent. + description: Provision an OpenAI-hosted environment from inline configuration or a template. + CreateEnvironmentParam: + description: Configuration for a new prewarmed OpenAI-hosted environment. discriminator: propertyName: type mapping: - function: '#/components/schemas/PersistedAgentToolResourceFunction' - tool_search: '#/components/schemas/PersistedAgentToolResourceToolSearch' - programmatic_tool_calling: '#/components/schemas/PersistedAgentToolResourceProgrammaticToolCalling' - mcp: '#/components/schemas/PersistedAgentToolResourceMcp' - web_search: '#/components/schemas/PersistedAgentToolResourceWebSearch' - computer_use: '#/components/schemas/PersistedAgentToolResourceComputerUse' + openai_hosted: '#/components/schemas/CreateEnvironmentParamOpenaiHosted' x-oai-discriminator-values: - - function - - tool_search - - programmatic_tool_calling - - mcp - - web_search - - computer_use + - openai_hosted anyOf: - - $ref: '#/components/schemas/PersistedAgentToolResourceFunction' - - $ref: '#/components/schemas/PersistedAgentToolResourceToolSearch' - - $ref: '#/components/schemas/PersistedAgentToolResourceProgrammaticToolCalling' - - $ref: '#/components/schemas/PersistedAgentToolResourceMcp' - - $ref: '#/components/schemas/PersistedAgentToolResourceWebSearch' - - $ref: '#/components/schemas/PersistedAgentToolResourceComputerUse' - MultiAgentConfigResource: + - $ref: '#/components/schemas/CreateEnvironmentParamOpenaiHosted' + CreateAgentEnvironmentParams: type: object properties: - enabled: - type: boolean - description: Whether subagent tools are enabled. Defaults to false. - max_concurrent_subagents: + environment: + $ref: '#/components/schemas/CreateEnvironmentParam' + description: The required hosting type and its configuration. + vault_ids: type: - - integer + - array - 'null' - format: int64 - minimum: 1 - maximum: 4294967295 - description: Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 10 + description: The IDs of up to 10 vaults made available to an OpenAI-hosted environment. required: - - enabled - - max_concurrent_subagents + - environment additionalProperties: false - description: The resolved configuration for creating and coordinating subagents. - AgentResource: + description: Parameters for creating an execution environment before its sessions. + EnvironmentFilePageObjectResource: + type: string + enum: + - page + default: page + x-stainless-const: true + description: The object type for a page of files in an execution environment. + EnvironmentFileResource: type: object properties: - id: - type: string - minLength: 0 - description: The ID of the reusable agent. object: type: string enum: - - agent - default: agent + - agent.environment.file + default: agent.environment.file x-stainless-const: true - description: The object type. Always `agent`. - created_at: - type: integer - format: int64 - description: The Unix timestamp, in seconds, when the agent was created. - updated_at: - type: integer - format: int64 - description: The Unix timestamp, in seconds, when the agent was last updated. - name: - type: - - string - - 'null' - minLength: 0 - description: A human-readable name for the agent, or null if it is unnamed. - metadata: - type: object - additionalProperties: - type: string - minLength: 0 - propertyNames: - type: string - minLength: 0 - minProperties: 0 - description: Custom string key-value pairs attached to the agent. - model: + description: The object type. Always `agent.environment.file`. + environment_id: type: string minLength: 0 - description: The requested model name used for inference. - reasoning: - $ref: '#/components/schemas/ReasoningResource' - description: The resolved reasoning configuration, including the model default for an omitted effort. - text: - $ref: '#/components/schemas/TextResource' - description: The resolved configuration for text generated by the agent. - service_tier: - $ref: '#/components/schemas/ServiceTierResource' - description: The resolved service-tier policy used for model requests. - instructions: - type: - - string - - 'null' + description: The ID of the environment containing this file. + path: + type: string minLength: 0 - description: Custom instructions appended to the agent's default base instructions. - tools: - type: array - items: - $ref: '#/components/schemas/PersistedAgentToolResource' - minItems: 0 - maxItems: 2000 - description: Tools available to the agent. - multi_agent: - $ref: '#/components/schemas/MultiAgentConfigResource' - description: The resolved configuration for creating and coordinating subagents. + description: The absolute file path inside the environment's workspace. + size_bytes: + type: integer + format: int64 + minimum: 0 + description: The file size in bytes. required: - - id - object - - created_at - - updated_at - - name - - metadata - - model - - reasoning - - text - - service_tier - - instructions - - tools - - multi_agent + - environment_id + - path + - size_bytes additionalProperties: false - description: A reusable agent scoped to the caller's project. - AgentListResource: + description: A live file in an execution environment. + EnvironmentFileListResource: type: object properties: object: - type: string - enum: - - list - default: list - x-stainless-const: true - description: The object type, which is always `list`. + $ref: '#/components/schemas/EnvironmentFilePageObjectResource' + description: The object type. Always `page`. data: type: array items: - $ref: '#/components/schemas/AgentResource' + $ref: '#/components/schemas/EnvironmentFileResource' minItems: 0 maxItems: 2000 - description: The resources returned in this page, in the requested sort order. - first_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the first resource in `data`, or `null` if the page is empty. - last_id: + description: Files available on the current page. + next: type: - string - 'null' minLength: 0 - description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. + description: The opaque cursor to use when requesting the next page, if any. has_more: type: boolean - description: Whether there are more resources to retrieve after this page. + description: Whether more files follow this page. required: - object - data - - first_id - - last_id + - next - has_more additionalProperties: false - description: A page of Agents API resources, with IDs for retrieving additional pages. - ReasoningEffortParam: - type: string - enum: - - none - - minimal - - low - - medium - - high - - xhigh - - max - description: The amount of reasoning effort the model should use. - ReasoningSummaryParam: + description: A paginated list of live execution environment files. + SubagentObjectResource: type: string enum: - - concise - - detailed - - auto - x-enumDescriptions: - - Returns a concise reasoning summary when supported. - - Returns a detailed reasoning summary when supported. - - Automatically selects the most detailed summary supported by the model. - description: The reasoning summary format requested from the model. - ReasoningParam: - type: object - properties: - effort: - anyOf: - - $ref: '#/components/schemas/ReasoningEffortParam' - - type: 'null' - description: The amount of reasoning effort the model should use. Omission lets the model select it. - summary: - anyOf: - - $ref: '#/components/schemas/ReasoningSummaryParam' - - type: 'null' - description: Controls whether the response includes a reasoning summary. - additionalProperties: false - description: Reasoning configuration for the agent. - TextFormatParamText: + - agent.session.subagent + default: agent.session.subagent + x-stainless-const: true + description: The object type for a subagent. + OutputTextResource: type: object properties: type: type: string enum: - - text - default: text + - output_text + default: output_text x-stainless-const: true - description: The type of the object. Always `text`. + description: The content type. Always `output_text`. + text: + type: string + minLength: 0 + description: The text produced by the agent. required: - type + - text additionalProperties: false - description: Generates ordinary text without a structured-output constraint. - TextFormatParamJsonSchema: + description: A text content part produced by the agent. + EncryptedContentResource: type: object properties: type: type: string enum: - - json_schema - default: json_schema + - encrypted_content + default: encrypted_content x-stainless-const: true - description: The type of the object. Always `json_schema`. - schema: - type: object - additionalProperties: {} - propertyNames: - type: string - minLength: 1 - maxLength: 256 - minProperties: 0 - maxProperties: 1024 - description: The JSON Schema that generated text must match. + description: The content type. Always `encrypted_content`. + encrypted_content: + type: string + minLength: 0 + description: The encrypted content payload. required: - type - - schema + - encrypted_content additionalProperties: false - description: Constrains generated text to a JSON Schema. - TextFormatParam: - description: The output format for generated text. + description: Encrypted content exchanged between agents. + AgentContentResource: + description: A plaintext or encrypted content part exchanged between agents. discriminator: propertyName: type mapping: - text: '#/components/schemas/TextFormatParamText' - json_schema: '#/components/schemas/TextFormatParamJsonSchema' + output_text: '#/components/schemas/OutputTextResource' + encrypted_content: '#/components/schemas/EncryptedContentResource' x-oai-discriminator-values: - - text - - json_schema + - output_text + - encrypted_content anyOf: - - $ref: '#/components/schemas/TextFormatParamText' - - $ref: '#/components/schemas/TextFormatParamJsonSchema' - VerbosityParam: + - $ref: '#/components/schemas/OutputTextResource' + - $ref: '#/components/schemas/EncryptedContentResource' + SubagentStatusResource: type: string enum: - - low - - medium - - high + - active + - closed x-enumDescriptions: - - Produces less text. - - Uses the default amount of text. - - Produces more text. - description: The amount of text the model should produce. - TextParam: + - The subagent remains available, including while idle between turns. + - The subagent is closed. + description: The current status of a subagent. + SubagentResource: type: object properties: - format: - anyOf: - - $ref: '#/components/schemas/TextFormatParam' - - type: 'null' - description: 'The output format. Omission uses ordinary text (`{"type": "text"}`).' - verbosity: - anyOf: - - $ref: '#/components/schemas/VerbosityParam' - - type: 'null' - description: The amount of text the model should produce. Defaults to `medium`, matching Responses. + id: + type: string + minLength: 0 + description: The ID of the subagent. + object: + $ref: '#/components/schemas/SubagentObjectResource' + description: The object type. Always `agent.session.subagent`. + session_id: + type: string + minLength: 0 + description: The ID of the session that owns the subagent. + name: + type: + - string + - 'null' + minLength: 0 + description: The runner-assigned nickname, or null when unavailable. + instructions: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/AgentContentResource' + minItems: 0 + maxItems: 2000 + description: Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available. + parent_agent_id: + type: string + minLength: 0 + description: The ID of the agent that created this subagent. + status: + $ref: '#/components/schemas/SubagentStatusResource' + description: The current status of the subagent. + opened_at: + type: integer + format: int64 + description: The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. + closed_at: + type: + - integer + - 'null' + format: int64 + description: The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. + required: + - id + - object + - session_id + - name + - instructions + - parent_agent_id + - status + - opened_at + - closed_at additionalProperties: false - description: Configuration for text generated by the agent. - ServiceTierParam: + description: A subagent created within a session. + SessionMessageRoleResource: type: string enum: - - auto - - default - - flex - - priority - - fast - - ultrafast - x-enumDescriptions: - - Selects the service tier automatically. - - Uses the default service tier. - - Uses the flex service tier. - - Uses the priority service tier. - - Uses the fast service tier. - - Uses the ultrafast service tier. - description: The service tier used for model requests. - PersistedAgentToolConfigParamFunction: + - user + - assistant + description: The author of a session message. + MessageContentResourceInputText: type: object properties: type: type: string enum: - - function - default: function + - input_text + default: input_text x-stainless-const: true - description: The type of the object. Always `function`. - name: + description: The type of the object. Always `input_text`. + text: type: string minLength: 0 - maxLength: 1048576 - description: The name of the function. - description: + description: The text supplied by the user. + required: + - type + - text + additionalProperties: false + description: Text supplied by the user. + MessageContentResourceInputImage: + type: object + properties: + type: type: string - minLength: 0 - maxLength: 1048576 - description: A description of what the function does. - parameters: - type: object - additionalProperties: {} - propertyNames: - type: string - minLength: 1 - maxLength: 256 - minProperties: 0 - maxProperties: 1024 - description: A JSON Schema object describing the function's arguments. - defer_loading: - type: boolean - default: false - description: Whether this function is deferred and discovered through tool search. Defaults to `false`. + enum: + - input_image + default: input_image + x-stainless-const: true + description: The type of the object. Always `input_image`. + image_url: + type: string + minLength: 0 + description: The URL of the image supplied by the user, which may be a base64-encoded data URL. required: - type - - name - - description - - parameters + - image_url additionalProperties: false - description: A function defined by the application. - PersistedAgentToolConfigParamToolSearch: + description: An image supplied by the user. + MessageContentResourceOutputText: type: object properties: type: type: string enum: - - tool_search - default: tool_search + - output_text + default: output_text x-stainless-const: true - description: The type of the object. Always `tool_search`. + description: The type of the object. Always `output_text`. + text: + type: string + minLength: 0 + description: The text produced by the assistant. required: - type + - text additionalProperties: false - description: Discovers deferred function tools and loads them into the model context. - PersistedAgentToolConfigParamProgrammaticToolCalling: + description: Text produced by the assistant. + MessageContentResource: + description: A content part in a session message. + discriminator: + propertyName: type + mapping: + input_text: '#/components/schemas/MessageContentResourceInputText' + input_image: '#/components/schemas/MessageContentResourceInputImage' + output_text: '#/components/schemas/MessageContentResourceOutputText' + x-oai-discriminator-values: + - input_text + - input_image + - output_text + anyOf: + - $ref: '#/components/schemas/MessageContentResourceInputText' + - $ref: '#/components/schemas/MessageContentResourceInputImage' + - $ref: '#/components/schemas/MessageContentResourceOutputText' + OutputItemStatusResource: + type: string + enum: + - in_progress + - completed + - incomplete + x-enumDescriptions: + - The item is in progress. + - The item is complete. + - The item stopped before completing. + description: The status of an agent output item. + MessagePhaseResource: + type: string + enum: + - commentary + - final_answer + x-enumDescriptions: + - Commentary produced while the agent works. + - The agent's final answer. + description: The phase of an assistant message. + MessageItemResource: type: object properties: type: type: string enum: - - programmatic_tool_calling - default: programmatic_tool_calling + - message + default: message x-stainless-const: true - description: The type of the object. Always `programmatic_tool_calling`. - enabled: - type: boolean - default: true - description: Whether tools can be called from model-generated code. Defaults to `true`. + description: The item type. Always `message`. + id: + type: + - string + - 'null' + minLength: 0 + description: The ID of this item, or null for legacy user messages whose ID was not recorded. + turn_id: + type: string + minLength: 0 + description: The ID of the turn that contains this item. + role: + $ref: '#/components/schemas/SessionMessageRoleResource' + description: The role of the message author. + content: + type: array + items: + $ref: '#/components/schemas/MessageContentResource' + minItems: 0 + maxItems: 2000 + description: The content of the message. User messages contain input text or images; assistant messages contain output text. + status: + $ref: '#/components/schemas/OutputItemStatusResource' + description: The status of the message. User messages are always `completed`. + phase: + anyOf: + - $ref: '#/components/schemas/MessagePhaseResource' + - type: 'null' + description: The phase of an assistant message. Null for user messages. required: - type + - id + - turn_id + - role + - content + - status + - phase additionalProperties: false - description: Enables calling tools from model-generated code. - PersistedMcpTransportConfigParamHttp: + description: A user or assistant message recorded in a session. + SummaryTextResource: type: object properties: type: type: string enum: - - http - default: http + - summary_text + default: summary_text x-stainless-const: true - description: The type of the object. Always `http`. - server_url: + description: The content type. Always `summary_text`. + text: type: string minLength: 0 - maxLength: 1048576 - description: The URL of the MCP server. - headers: - type: - - object - - 'null' - additionalProperties: - type: string - minLength: 0 - maxLength: 1048576 - propertyNames: - type: string - minLength: 1 - maxLength: 256 - minProperties: 0 - maxProperties: 1024 - description: Non-secret HTTP headers sent to the MCP server. + description: The reasoning summary text. required: - type - - server_url + - text additionalProperties: false - description: Connects to an MCP server over HTTP. - PersistedMcpTransportConfigParamStdio: + description: A reasoning summary content part. + ReasoningItemResource: type: object properties: type: type: string enum: - - stdio - default: stdio + - reasoning + default: reasoning x-stainless-const: true - description: The type of the object. Always `stdio`. - command: + description: The item type. Always `reasoning`. + id: type: string minLength: 0 - maxLength: 1048576 - description: The command used to start the MCP server. - args: - type: - - array - - 'null' - items: - type: string - minLength: 0 - maxLength: 1048576 - minItems: 0 - maxItems: 16384 - description: Arguments passed to the MCP server command. - cwd: + description: The ID of the reasoning item. + turn_id: type: string minLength: 0 - maxLength: 1048576 - description: The working directory used to start the MCP server. - env_vars: - type: - - array - - 'null' + description: The ID of the turn that contains this item. + summary: + type: array items: - type: string - minLength: 0 - maxLength: 1048576 + $ref: '#/components/schemas/SummaryTextResource' minItems: 0 - maxItems: 16384 - description: Environment variable names to inherit from the selected execution environment. + maxItems: 2000 + description: The reasoning summaries produced by the agent. + status: + anyOf: + - $ref: '#/components/schemas/OutputItemStatusResource' + - type: 'null' + description: The status of the reasoning item. required: - type - - command - - cwd + - id + - turn_id + - summary + - status additionalProperties: false - description: Starts an MCP server as a local process. - PersistedMcpTransportConfigParam: - description: A credential-free transport used to connect to an MCP server. - discriminator: - propertyName: type - mapping: - http: '#/components/schemas/PersistedMcpTransportConfigParamHttp' - stdio: '#/components/schemas/PersistedMcpTransportConfigParamStdio' - x-oai-discriminator-values: - - http - - stdio - anyOf: - - $ref: '#/components/schemas/PersistedMcpTransportConfigParamHttp' - - $ref: '#/components/schemas/PersistedMcpTransportConfigParamStdio' - McpConnectionOriginParam: + description: A reasoning item produced by the agent. + FunctionCallStatusResource: type: string enum: - - service - - environment + - in_progress + - completed + - failed + - incomplete x-enumDescriptions: - - Uses the Managed Agents service network. - - Uses the session's execution environment. - description: Where outbound MCP HTTP connections originate. - PersistedAgentToolConfigParamMcp: + - The call is in progress. + - The call completed successfully. + - The call failed. + - The call stopped before completing. + description: The status of a tool call. + FunctionCallItemResource: type: object properties: type: type: string enum: - - mcp - default: mcp + - function_call + default: function_call x-stainless-const: true - description: The type of the object. Always `mcp`. - server_label: + description: The item type. Always `function_call`. + id: type: string minLength: 0 - maxLength: 1048576 - description: A label used to identify the MCP server in tool calls. - credential_id: - type: - - string - - 'null' + description: The ID of the function call item. + turn_id: + type: string minLength: 0 - maxLength: 1048576 - description: The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL. - transport: - $ref: '#/components/schemas/PersistedMcpTransportConfigParam' - description: The credential-free transport used to connect to the MCP server. - request_metadata: - type: - - object - - 'null' - additionalProperties: {} - propertyNames: - type: string - minLength: 1 - maxLength: 256 - minProperties: 0 - maxProperties: 1024 - description: Metadata included with requests to this MCP server. - allowed_tools: - type: - - array - - 'null' - items: - type: string - minLength: 0 - maxLength: 1048576 - minItems: 0 - maxItems: 16384 - description: The MCP tools the agent may call. All server tools are allowed when omitted. - required: - type: boolean - default: false - description: Whether this MCP server must initialize before the first turn. Defaults to `false`. - connection_origin: - anyOf: - - $ref: '#/components/schemas/McpConnectionOriginParam' - - type: 'null' - description: Selects where outbound MCP HTTP connections originate. + description: The ID of the turn that contains this item. + call_id: + type: string + minLength: 0 + description: The ID used to submit the function result. + name: + type: string + minLength: 0 + description: The name of the function to call. + arguments: + description: The arguments to pass to the function. + status: + $ref: '#/components/schemas/FunctionCallStatusResource' + description: The status of the function call. required: - type - - server_label - - transport + - id + - turn_id + - call_id + - name + - arguments + - status additionalProperties: false - description: Tools provided by a remote MCP server without stored credentials. - WebSearchModeParam: - type: string - enum: - - disabled - - cached - - live - x-enumDescriptions: - - Disables web search. - - Uses cached search results. - - Searches the live web. - description: The source used for web search results. - WebSearchContextSizeParam: - type: string - enum: - - low - - medium - - high - description: The amount of web search context made available to the model. - WebSearchLocationParam: + description: A function call produced by the agent. + FunctionCallOutputResource: + description: The text or model-input content supplied as a function result. + anyOf: + - type: string + minLength: 0 + - type: array + items: + $ref: '#/components/schemas/InputContentResource' + minItems: 0 + maxItems: 2000 + FunctionCallOutputItemResource: type: object properties: - country: - type: - - string - - 'null' + id: + type: string minLength: 0 - maxLength: 1048576 - description: The two-letter ISO country code, such as `US`. - region: - type: - - string - - 'null' + description: The ID of the function call output item. + turn_id: + type: string minLength: 0 - maxLength: 1048576 - description: The region or state name. - city: - type: - - string - - 'null' + description: The ID of the turn that contains this item. + type: + type: string + enum: + - function_call_output + default: function_call_output + x-stainless-const: true + description: The item type. Always `function_call_output`. + call_id: + type: string minLength: 0 - maxLength: 1048576 - description: The city name. - timezone: + description: The ID of the function call that produced this output. + status: + $ref: '#/components/schemas/FunctionCallStatusResource' + description: The status of the function call. + output: + anyOf: + - $ref: '#/components/schemas/FunctionCallOutputResource' + - type: 'null' + description: The function result, if the call succeeded. + error: type: - string - 'null' minLength: 0 - maxLength: 1048576 - description: The IANA timezone, such as `America/Los_Angeles`. + description: The error message, if the call failed. + required: + - id + - turn_id + - type + - call_id + - status + - output + - error additionalProperties: false - description: Approximate user location used to localize web search results. - PersistedAgentToolConfigParamWebSearch: + description: The result supplied for a function call. + AgentMessageItemResource: type: object properties: + id: + type: string + minLength: 0 + description: The ID of the message. + turn_id: + type: string + minLength: 0 + description: The ID of the turn that contains this item. type: type: string enum: - - web_search - default: web_search + - agent_message + default: agent_message x-stainless-const: true - description: The type of the object. Always `web_search`. - mode: - anyOf: - - $ref: '#/components/schemas/WebSearchModeParam' - - type: 'null' - description: The source used for web search results. Defaults to `live`. - context_size: - anyOf: - - $ref: '#/components/schemas/WebSearchContextSizeParam' - - type: 'null' - description: The amount of search context made available to the model. Defaults to `medium`. - allowed_domains: - type: - - array - - 'null' + description: The item type. Always `agent_message`. + sender_agent_id: + type: string + minLength: 0 + description: The ID or name of the sending agent. + recipient_agent_id: + type: string + minLength: 0 + description: The ID or name of the receiving agent. + content: + type: array items: - type: string - minLength: 0 - maxLength: 1048576 + $ref: '#/components/schemas/AgentContentResource' minItems: 0 - maxItems: 16384 - description: Domains the search may include. - location: - anyOf: - - $ref: '#/components/schemas/WebSearchLocationParam' - - type: 'null' - description: Approximate location used to localize search results. + maxItems: 2000 + description: The content exchanged between the agents. required: + - id + - turn_id - type + - sender_agent_id + - recipient_agent_id + - content additionalProperties: false - description: Web search. - PersistedAgentToolConfigParamComputerUse: + description: A message exchanged between agent threads. + McpCallItemResource: type: object properties: type: type: string enum: - - computer_use - default: computer_use + - mcp_call + default: mcp_call x-stainless-const: true - description: The type of the object. Always `computer_use`. - include_screenshots: - type: boolean - default: false - description: Whether computer tool outputs include screenshots. Defaults to `false`. - required: - - type - additionalProperties: false - description: Browser use in an OpenAI-hosted session. - PersistedAgentToolConfigParam: - description: A tool that can be stored on a reusable agent without session credentials. - discriminator: - propertyName: type - mapping: - function: '#/components/schemas/PersistedAgentToolConfigParamFunction' - tool_search: '#/components/schemas/PersistedAgentToolConfigParamToolSearch' - programmatic_tool_calling: '#/components/schemas/PersistedAgentToolConfigParamProgrammaticToolCalling' - mcp: '#/components/schemas/PersistedAgentToolConfigParamMcp' - web_search: '#/components/schemas/PersistedAgentToolConfigParamWebSearch' - computer_use: '#/components/schemas/PersistedAgentToolConfigParamComputerUse' - x-oai-discriminator-values: - - function - - tool_search - - programmatic_tool_calling - - mcp - - web_search - - computer_use - anyOf: - - $ref: '#/components/schemas/PersistedAgentToolConfigParamFunction' - - $ref: '#/components/schemas/PersistedAgentToolConfigParamToolSearch' - - $ref: '#/components/schemas/PersistedAgentToolConfigParamProgrammaticToolCalling' - - $ref: '#/components/schemas/PersistedAgentToolConfigParamMcp' - - $ref: '#/components/schemas/PersistedAgentToolConfigParamWebSearch' - - $ref: '#/components/schemas/PersistedAgentToolConfigParamComputerUse' - MultiAgentConfigCurrentParam: - type: object - properties: - enabled: - type: boolean - description: Whether subagent tools are enabled. - max_concurrent_subagents: - type: integer - format: int64 - minimum: 1 - maximum: 4294967295 - description: Maximum number of subagents that may run concurrently. Defaults to 6. - required: - - enabled - additionalProperties: false - description: Explicit configuration for creating and coordinating subagents. - x-openai-go-legacy-bool-fields: - - enabled - CreateAgentParams: - type: object - properties: - metadata: - type: - - object - - 'null' - additionalProperties: - type: string - minLength: 0 - maxLength: 512 - propertyNames: - type: string - minLength: 1 - maxLength: 64 - minProperties: 0 - maxProperties: 16 - description: Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map. - name: - type: - - string - - 'null' + description: The item type. Always `mcp_call`. + id: + type: string minLength: 0 - maxLength: 128 - description: A human-readable name for the agent. Omission or null leaves the agent unnamed. - model: + description: The ID of the MCP call item. + turn_id: type: string minLength: 0 - maxLength: 1048576 - description: The model to use for the agent. The requested model name is preserved. - reasoning: - anyOf: - - $ref: '#/components/schemas/ReasoningParam' - - type: 'null' - description: Configuration for model reasoning. Omission uses the model's default effort. - text: + description: The ID of the turn that contains this item. + server_label: + type: string + minLength: 0 + description: The label of the MCP server. + name: + type: string + minLength: 0 + description: The name of the MCP tool. + arguments: + description: The arguments passed to the MCP tool. + status: + $ref: '#/components/schemas/FunctionCallStatusResource' + description: The status of the MCP tool call. + output: anyOf: - - $ref: '#/components/schemas/TextParam' + - {} - type: 'null' - description: Configuration for generated text. Defaults to the `text` format and medium verbosity. - service_tier: + description: The output returned by the MCP tool, if any. + error: anyOf: - - $ref: '#/components/schemas/ServiceTierParam' + - {} - type: 'null' - description: The service tier used for model requests. Defaults to `auto`. - instructions: - type: - - string - - 'null' + description: The error returned by the MCP tool, if any. + required: + - type + - id + - turn_id + - server_label + - name + - arguments + - status + - output + - error + additionalProperties: false + description: A call to a tool on an MCP server. + ComputerScreenshotResource: + type: object + properties: + type: + type: string + enum: + - computer_screenshot + default: computer_screenshot + x-stainless-const: true + description: The content type. Always `computer_screenshot`. + image_url: + type: string minLength: 0 - maxLength: 1048576 - description: Additional instructions appended to the agent's default base instructions. Omit or set to null to add no custom instructions. - tools: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/PersistedAgentToolConfigParam' - minItems: 0 - maxItems: 2000 - description: Tools available to the agent. Defaults to an empty list. The tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON. - multi_agent: - anyOf: - - $ref: '#/components/schemas/MultiAgentConfigCurrentParam' - - type: 'null' - description: Configuration for creating and coordinating subagents. Subagent tools are disabled by default. + description: The complete JPEG image as a base64 data URL. required: - - model + - type + - image_url additionalProperties: false - description: Parameters for creating a reusable agent. - UpdateAgentParams: + description: A browser screenshot emitted by the model during computer use. + ComputerUseCallItemResource: type: object properties: - model: + type: + type: string + enum: + - computer_use_call + default: computer_use_call + x-stainless-const: true + description: The item type. Always `computer_use_call`. + id: type: string minLength: 0 - maxLength: 1048576 - description: The model to use for the agent. The requested model name is preserved. - reasoning: - anyOf: - - $ref: '#/components/schemas/ReasoningParam' - - type: 'null' - description: Configuration for model reasoning. Omit to keep the current settings; pass `null` to reset to the model's default effort. - text: - anyOf: - - $ref: '#/components/schemas/TextParam' - - type: 'null' - description: Configuration for text generated by the agent. - service_tier: - anyOf: - - $ref: '#/components/schemas/ServiceTierParam' - - type: 'null' - description: The service tier used for model requests. - instructions: + description: The ID of the activity item. + turn_id: + type: string + minLength: 0 + description: The ID of the turn that contains this item. + title: type: - string - 'null' minLength: 0 - maxLength: 1048576 - description: Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. - multi_agent: + description: A model-generated description of the activity, when available. + status: + $ref: '#/components/schemas/FunctionCallStatusResource' + description: The execution status of the activity. + output: anyOf: - - $ref: '#/components/schemas/MultiAgentConfigCurrentParam' + - $ref: '#/components/schemas/ComputerScreenshotResource' - type: 'null' - description: Configuration for creating and coordinating subagents. - metadata: - type: - - object - - 'null' - additionalProperties: - type: string - minLength: 0 - maxLength: 512 - propertyNames: - type: string - minLength: 1 - maxLength: 64 - minProperties: 0 - maxProperties: 16 - description: Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. - name: - type: - - string - - 'null' - minLength: 0 - maxLength: 128 - description: A replacement name. Omit to leave unchanged, or pass null to clear it. - tools: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/PersistedAgentToolConfigParam' - minItems: 0 - maxItems: 2000 - description: Replaces the tool list. Omit to leave it unchanged, or pass null to clear it. The replacement must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON. + description: The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. + required: + - type + - id + - turn_id + - title + - status + - output additionalProperties: false - description: Fields to replace on an existing reusable agent. - DeletedAgentResource: + description: One execution of the platform-provided computer-use capability. + BrowserAuthenticationFieldResource: type: object properties: id: type: string minLength: 0 - description: The ID of the deleted agent. - object: + description: The field ID to submit as field_id in a fields entry. + label: type: string - enum: - - agent.deleted - default: agent.deleted - x-stainless-const: true - description: The object type. Always `agent.deleted`. - deleted: + minLength: 0 + description: The label to display beside the control. + type: + type: string + minLength: 0 + description: The rendering type, such as email, password, or text. + required: type: boolean - description: Whether the agent was deleted. Always `true`. + description: Whether this control requires a nonempty value. required: - id - - object - - deleted + - label + - type + - required additionalProperties: false - description: A deleted reusable agent. - EnvironmentPackagesResource: + description: A control in a registered browser-login form. + BrowserAuthenticationOptionResource: type: object properties: - python: - type: array - items: - type: string - minLength: 0 - maxLength: 1048576 - minItems: 0 - maxItems: 16384 - description: Python packages installed in the environment. - system: - type: array - items: - type: string - minLength: 0 - maxLength: 1048576 - minItems: 0 - maxItems: 16384 - description: System packages installed in the environment. - npm: + id: + type: string + minLength: 0 + description: The option ID to submit as selected_option. + label: + type: string + minLength: 0 + description: The method label to display. + field_ids: type: array items: type: string minLength: 0 - maxLength: 1048576 minItems: 0 - maxItems: 16384 - description: npm packages installed globally in the environment. + maxItems: 2000 + description: IDs from the registered fields that this method accepts. required: - - python - - system - - npm + - id + - label + - field_ids additionalProperties: false - description: Packages installed in an OpenAI-hosted environment. - NetworkAccessResource: - type: string - enum: - - enabled - - disabled - - restricted - x-enumDescriptions: - - Allows unrestricted network access. - - Disables network access. - - Applies the configured domain restrictions. - description: The network access mode for an OpenAI-hosted environment. - NetworkPolicyResource: + description: A sign-in method and the fields that belong to it. + BrowserAuthenticationHistoryRequestKindResourceBrowserAuthentication: type: object properties: - access: - $ref: '#/components/schemas/NetworkAccessResource' - description: The environment's network access mode. - allowed_domains: + type: + type: string + enum: + - browser_authentication + default: browser_authentication + x-stainless-const: true + description: The type of the object. Always `browser_authentication`. + reason: + type: + - string + - 'null' + minLength: 0 + description: Why the agent needs the user to sign in. + credential_origin: + type: + - string + - 'null' + minLength: 0 + description: The registered form or frame origin where values will be entered. + fields: type: array items: - type: string - minLength: 0 + $ref: '#/components/schemas/BrowserAuthenticationFieldResource' minItems: 0 maxItems: 2000 - description: Domains the environment may access when network access is restricted. + description: Controls to render. All submitted values are sensitive. + options: + type: array + items: + $ref: '#/components/schemas/BrowserAuthenticationOptionResource' + minItems: 0 + maxItems: 2000 + description: Sign-in methods. Empty for a plain form. required: - - access - - allowed_domains + - type + - reason + - credential_origin + - fields + - options additionalProperties: false - description: Network access for an OpenAI-hosted environment. - DesktopResource: + description: A registered form awaiting the application's response. + BrowserAuthenticationHistoryRequestKindResource: + x-oai-discriminator-values: + - browser_authentication + discriminator: + propertyName: type + mapping: + browser_authentication: '#/components/schemas/BrowserAuthenticationHistoryRequestKindResourceBrowserAuthentication' + anyOf: + - $ref: '#/components/schemas/BrowserAuthenticationHistoryRequestKindResourceBrowserAuthentication' + BrowserAuthenticationRequestItemResource: type: object properties: - enabled: - type: boolean - description: Whether the environment provisions a desktop and browser proxy. + turn_id: + type: string + minLength: 0 + request_id: + type: string + minLength: 0 + request: + $ref: '#/components/schemas/BrowserAuthenticationHistoryRequestKindResource' + id: + type: string + minLength: 0 + description: The stable history item ID. + type: + type: string + enum: + - computer_use_approval_request + default: computer_use_approval_request + x-stainless-const: true + description: The item type. Always computer_use_approval_request. required: - - enabled + - turn_id + - request_id + - request + - id + - type additionalProperties: false - description: The effective desktop configuration for an OpenAI-hosted environment. - HostedTemplateSkillResourceSkillReference: + description: A credential-free history record of the emitted login request. + ComputerUseApprovalResponseKindResourceBrowserAuthenticationSubmitResource: type: object properties: type: type: string enum: - - skill_reference - default: skill_reference + - browser_authentication + default: browser_authentication x-stainless-const: true - description: The type of the object. Always `skill_reference`. - skill_id: + action: type: string - minLength: 0 - description: The referenced skill ID. - version: + enum: + - submit + default: submit + x-stainless-const: true + selected_option: type: - string - 'null' minLength: 0 - description: The requested version selector, including `latest`. + description: The chosen sign-in method, or null when no options were offered. required: - type - - skill_id - - version + - action + - selected_option additionalProperties: false - description: A skill resolved afresh from the Skills API whenever a session starts. - HostedTemplateSkillResourceInline: + ComputerUseApprovalResponseKindResourceBrowserAuthenticationCancelResource: type: object properties: type: type: string enum: - - inline - default: inline + - browser_authentication + default: browser_authentication x-stainless-const: true - description: The type of the object. Always `inline`. - name: - type: string - minLength: 0 - description: The skill name declared in `SKILL.md`. - description: + action: type: string - minLength: 0 - description: The skill description declared in `SKILL.md`. + enum: + - cancel + default: cancel + x-stainless-const: true required: - type - - name - - description + - action additionalProperties: false - description: Safe metadata for an inline skill archive. - HostedTemplateSkillResource: - description: Safe metadata for a skill configured by an environment template. + ComputerUseApprovalResponseKindResource: + x-oai-discriminator-values: + - submit + - cancel discriminator: - propertyName: type + propertyName: action mapping: - skill_reference: '#/components/schemas/HostedTemplateSkillResourceSkillReference' - inline: '#/components/schemas/HostedTemplateSkillResourceInline' - x-oai-discriminator-values: - - skill_reference - - inline + submit: '#/components/schemas/ComputerUseApprovalResponseKindResourceBrowserAuthenticationSubmitResource' + cancel: '#/components/schemas/ComputerUseApprovalResponseKindResourceBrowserAuthenticationCancelResource' anyOf: - - $ref: '#/components/schemas/HostedTemplateSkillResourceSkillReference' - - $ref: '#/components/schemas/HostedTemplateSkillResourceInline' - HostedTemplateFileResourceFileId: + - $ref: '#/components/schemas/ComputerUseApprovalResponseKindResourceBrowserAuthenticationSubmitResource' + - $ref: '#/components/schemas/ComputerUseApprovalResponseKindResourceBrowserAuthenticationCancelResource' + ComputerUseApprovalRequestResultItemResource: type: object properties: + id: + type: string + minLength: 0 + description: The stable history item ID. type: type: string enum: - - file_id - default: file_id + - computer_use_approval_request_result + default: computer_use_approval_request_result x-stainless-const: true - description: The type of the object. Always `file_id`. - file_id: + turn_id: type: string minLength: 0 - description: The ID of the uploaded file. - path: + description: The ID of the turn that contains this item. + request_id: type: string minLength: 0 - description: The file's absolute path inside the environment. + description: The registered request answered by this item. + response: + $ref: '#/components/schemas/ComputerUseApprovalResponseKindResource' + description: The admitted response, without submitted credential values. required: + - id - type - - file_id - - path + - turn_id + - request_id + - response additionalProperties: false - description: A project-scoped Files API reference resolved separately for each session. - HostedTemplateFileResourceInline: + description: A credential-free record of an admitted response, not proof of completion. + WebSearchActionResourceSearch: type: object properties: type: type: string enum: - - inline - default: inline + - search + default: search x-stainless-const: true - description: The type of the object. Always `inline`. - path: - type: string + description: The type of the object. Always `search`. + query: + type: + - string + - 'null' minLength: 0 - description: The file's absolute path inside the environment. - size_bytes: - type: integer - format: int64 - minimum: 0 - description: The decoded size of the inline file in bytes. - required: - - type - - path - - size_bytes - additionalProperties: false - description: Metadata for confidential inline file contents. - HostedTemplateFileResource: - description: Safe metadata for a file configured by an environment template. - discriminator: - propertyName: type - mapping: - file_id: '#/components/schemas/HostedTemplateFileResourceFileId' - inline: '#/components/schemas/HostedTemplateFileResourceInline' - x-oai-discriminator-values: - - file_id - - inline - anyOf: - - $ref: '#/components/schemas/HostedTemplateFileResourceFileId' - - $ref: '#/components/schemas/HostedTemplateFileResourceInline' - EnvironmentTemplateResource: - type: object - properties: - id: - type: string - minLength: 0 - description: The ID of the reusable environment template. - name: + description: The search query, when a single query was used. + queries: type: - - string + - array - 'null' - minLength: 0 - description: An optional human-readable display name for the template. - object: - type: string - enum: - - agent.environment.template - default: agent.environment.template - x-stainless-const: true - description: The object type. Always `agent.environment.template`. - created_at: - type: integer - format: int64 - description: The Unix timestamp, in seconds, when the template was created. - updated_at: - type: integer - format: int64 - description: The Unix timestamp, in seconds, when the template was last updated. - packages: - $ref: '#/components/schemas/EnvironmentPackagesResource' - description: Packages installed in each fresh OpenAI-hosted environment. - network: - $ref: '#/components/schemas/NetworkPolicyResource' - description: Runtime network access for each OpenAI-hosted environment. - desktop: - $ref: '#/components/schemas/DesktopResource' - description: Desktop configuration for each OpenAI-hosted environment. - capability_directories: - type: array items: type: string minLength: 0 minItems: 0 maxItems: 2000 - description: Directories that expose capabilities to the agent. - skills: - type: array - items: - $ref: '#/components/schemas/HostedTemplateSkillResource' - minItems: 0 - maxItems: 200 - description: Safe skill metadata, preserving unresolved version selectors. - plugins: - type: array - items: - $ref: '#/components/schemas/HostedPluginResource' - minItems: 0 - maxItems: 32 - description: Safe plugin metadata, excluding inline archive contents. - files: - type: array - items: - $ref: '#/components/schemas/HostedTemplateFileResource' - minItems: 0 - maxItems: 50 - description: Safe file metadata, excluding contents and session-scoped file IDs. + description: The search queries, when multiple queries were used. required: - - id - - name - - object - - created_at - - updated_at - - packages - - network - - capability_directories - - skills - - plugins - - files + - type + - query + - queries additionalProperties: false - description: Reusable configuration that provisions a fresh OpenAI-hosted environment for each session. - EnvironmentTemplateListResource: + description: A search query or group of search queries. + WebSearchActionResourceOpenPage: type: object properties: - object: + type: type: string enum: - - list - default: list + - open_page + default: open_page x-stainless-const: true - description: The object type, which is always `list`. - data: - type: array - items: - $ref: '#/components/schemas/EnvironmentTemplateResource' - minItems: 0 - maxItems: 2000 - description: The resources returned in this page, in the requested sort order. - first_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the first resource in `data`, or `null` if the page is empty. - last_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - has_more: - type: boolean - description: Whether there are more resources to retrieve after this page. - required: - - object - - data - - first_id - - last_id - - has_more - additionalProperties: false - description: A page of Agents API resources, with IDs for retrieving additional pages. - CreateEnvironmentTemplateParams: - type: object - properties: - packages: - anyOf: - - $ref: '#/components/schemas/EnvironmentPackagesParam' - - type: 'null' - description: Packages to install in the environment. Defaults to empty package lists. - setup_commands: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/SetupCommandParam' - minItems: 0 - maxItems: 16 - description: Ordered, confidential setup commands. Command bodies are never returned. - network: - anyOf: - - $ref: '#/components/schemas/NetworkPolicyParam' - - type: 'null' - description: Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled. - desktop: - anyOf: - - $ref: '#/components/schemas/DesktopParam' - - type: 'null' - description: Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled. - x-openai-go-legacy-bool-fields: - - enabled - env: - type: - - object - - 'null' - additionalProperties: - type: string - minLength: 0 - maxLength: 1048576 - propertyNames: - type: string - minLength: 1 - maxLength: 256 - minProperties: 0 - maxProperties: 1024 - description: Environment variables made available to the agent. - capability_directories: - type: - - array - - 'null' - items: - type: string - minLength: 0 - maxLength: 1048576 - minItems: 0 - maxItems: 16384 - description: Directories that contain capabilities exposed to the agent. Defaults to an empty list. - skills: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/HostedSkillParam' - minItems: 0 - maxItems: 200 - description: Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. - plugins: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/HostedPluginParam' - minItems: 0 - maxItems: 32 - description: Plugins provided as inline ZIP archives. Defaults to an empty list. - files: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/HostedEnvironmentFileParam' - minItems: 0 - maxItems: 50 - description: Files available before the agent starts. Defaults to an empty list. - name: - type: - - string - - 'null' - minLength: 1 - maxLength: 256 - description: An optional human-readable display name for the template. - additionalProperties: false - description: Parameters for creating a reusable, project-scoped OpenAI-hosted environment template. - UpdateEnvironmentTemplateParams: - type: object - properties: - name: + description: The type of the object. Always `open_page`. + url: type: - string - 'null' - minLength: 1 - maxLength: 256 - description: A replacement human-readable display name, or `null` to clear the name. - packages: - anyOf: - - $ref: '#/components/schemas/EnvironmentPackagesParam' - - type: 'null' - description: Packages installed before the runtime network policy applies. - setup_commands: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/SetupCommandParam' - minItems: 0 - maxItems: 16 - description: Replacement confidential setup commands, never included in returned resources. - network: - anyOf: - - $ref: '#/components/schemas/NetworkPolicyParam' - - type: 'null' - description: Network access available after setup completes. Omit to preserve the current policy, or pass `null` to reset to the default policy. - desktop: - anyOf: - - $ref: '#/components/schemas/DesktopParam' - - type: 'null' - description: Replacement desktop configuration, or null to disable the desktop. - x-openai-go-legacy-bool-fields: - - enabled - env: - type: - - object - - 'null' - additionalProperties: - type: string - minLength: 0 - maxLength: 1048576 - propertyNames: - type: string - minLength: 1 - maxLength: 256 - minProperties: 0 - maxProperties: 1024 - description: Replacement confidential environment values. - capability_directories: - type: - - array - - 'null' - items: - type: string - minLength: 0 - maxLength: 1048576 - minItems: 0 - maxItems: 16384 - description: Directories that expose capabilities to the agent. - skills: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/HostedSkillParam' - minItems: 0 - maxItems: 200 - description: Replacement skill configuration installed for each new session. - plugins: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/HostedPluginParam' - minItems: 0 - maxItems: 32 - description: Replacement plugin configuration installed for each new session. - files: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/HostedEnvironmentFileParam' - minItems: 0 - maxItems: 50 - description: Replacement file configuration materialized for each new session. - additionalProperties: false - description: Fields to replace on an existing reusable OpenAI-hosted environment template. - DeletedEnvironmentTemplateResource: - type: object - properties: - id: - type: string minLength: 0 - description: The ID of the deleted environment template. - object: - type: string - enum: - - agent.environment.template.deleted - default: agent.environment.template.deleted - x-stainless-const: true - description: The object type. Always `agent.environment.template.deleted`. - deleted: - type: boolean - description: Whether the environment template was deleted. Always `true`. - required: - - id - - object - - deleted - additionalProperties: false - description: A deleted reusable environment template. - SessionSpendControlResource: - type: object - properties: - limit: - type: integer - format: int64 - minimum: 1 - maximum: 4503599627370495 - description: The configured positive limit in USD cents. - consumed: - type: - - integer - - 'null' - minimum: 0 - description: Best-effort recorded spend floored to whole USD cents, or null when unavailable. + description: The URL of the page that was opened. required: - - limit - - consumed + - type + - url additionalProperties: false - description: Session-wide spending control, present only when a limit is configured. - SessionStatusResource: - type: string - enum: - - idle - - in_progress - - requires_action - - failed - x-enumDescriptions: - - The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - - The session is processing a turn. - - The session is waiting for one or more required actions. - - The session failed. - description: The current status of a session. - ComputerUseApprovalRequestKindResourceBrowserAuthentication: + description: Opens a web page. + WebSearchActionResourceFindInPage: type: object properties: type: type: string enum: - - browser_authentication - default: browser_authentication + - find_in_page + default: find_in_page x-stainless-const: true - description: The type of the object. Always `browser_authentication`. - reason: + description: The type of the object. Always `find_in_page`. + url: type: - string - 'null' minLength: 0 - description: Why the agent needs the user to sign in. - credential_origin: + description: The URL of the page that was searched. + pattern: type: - string - 'null' minLength: 0 - description: The registered form or frame origin where values will be entered. - fields: - type: array - items: - $ref: '#/components/schemas/BrowserAuthenticationFieldResource' - minItems: 0 - maxItems: 2000 - description: Controls to render. All submitted values are sensitive. - options: - type: array - items: - $ref: '#/components/schemas/BrowserAuthenticationOptionResource' - minItems: 0 - maxItems: 2000 - description: Sign-in methods. Empty for a plain form. + description: The text pattern that was searched for. required: - type - - reason - - credential_origin - - fields - - options + - url + - pattern additionalProperties: false - description: A registered form awaiting the application's response. - ComputerUseApprovalRequestKindResourceBrowserOriginAccess: + description: Finds text within a web page. + WebSearchActionResourceOther: type: object properties: type: type: string enum: - - browser_origin_access - default: browser_origin_access + - other + default: other x-stainless-const: true - description: The type of the object. Always `browser_origin_access`. - reason: - type: - - string - - 'null' - minLength: 0 - description: The browser's explanation for this request, or null when unavailable. - origin: - type: string - minLength: 0 - description: The origin the browser needs permission to access. + description: The type of the object. Always `other`. required: - type - - reason - - origin additionalProperties: false - description: A browser origin awaiting the application's approval decision. - ComputerUseApprovalRequestKindResource: - x-oai-discriminator-values: - - browser_authentication - - browser_origin_access + description: Another web search action. + WebSearchActionResource: + description: An action performed by the web search tool. discriminator: propertyName: type mapping: - browser_authentication: '#/components/schemas/ComputerUseApprovalRequestKindResourceBrowserAuthentication' - browser_origin_access: '#/components/schemas/ComputerUseApprovalRequestKindResourceBrowserOriginAccess' + search: '#/components/schemas/WebSearchActionResourceSearch' + open_page: '#/components/schemas/WebSearchActionResourceOpenPage' + find_in_page: '#/components/schemas/WebSearchActionResourceFindInPage' + other: '#/components/schemas/WebSearchActionResourceOther' + x-oai-discriminator-values: + - search + - open_page + - find_in_page + - other anyOf: - - $ref: '#/components/schemas/ComputerUseApprovalRequestKindResourceBrowserAuthentication' - - $ref: '#/components/schemas/ComputerUseApprovalRequestKindResourceBrowserOriginAccess' - SessionRequiredActionResourceComputerUseApprovalRequest: + - $ref: '#/components/schemas/WebSearchActionResourceSearch' + - $ref: '#/components/schemas/WebSearchActionResourceOpenPage' + - $ref: '#/components/schemas/WebSearchActionResourceFindInPage' + - $ref: '#/components/schemas/WebSearchActionResourceOther' + WebSearchCallItemResource: type: object properties: type: type: string enum: - - computer_use_approval_request - default: computer_use_approval_request + - web_search_call + default: web_search_call x-stainless-const: true - description: The type of the object. Always `computer_use_approval_request`. - turn_id: + description: The item type. Always `web_search_call`. + id: type: string minLength: 0 - description: The turn that requested approval. - request_id: + description: The ID of the web search call. + turn_id: type: string minLength: 0 - description: The registered request ID to echo when responding. - request: - $ref: '#/components/schemas/ComputerUseApprovalRequestKindResource' - description: The information needed to render the request. + description: The ID of the turn that contains this item. + status: + $ref: '#/components/schemas/OutputItemStatusResource' + description: The status of the web search call. + action: + anyOf: + - $ref: '#/components/schemas/WebSearchActionResource' + - type: 'null' + description: The action performed by the web search tool. required: - type + - id - turn_id - - request_id - - request + - status + - action additionalProperties: false - description: Respond to a computer-use request. - SessionRequiredActionResourceFunctionCall: + description: A web search call produced by the agent. + CommandExecutionItemResource: type: object properties: type: type: string enum: - - function_call - default: function_call + - command_execution + default: command_execution x-stainless-const: true - description: The type of the object. Always `function_call`. - turn_id: + description: The item type. Always `command_execution`. + id: type: string minLength: 0 - description: The ID of the turn that requested the function call. - call_id: + description: The ID of the command execution item. + turn_id: type: string minLength: 0 - description: The ID to include when submitting the function result. - name: + description: The ID of the turn that contains this item. + command: type: string minLength: 0 - description: The function name. - arguments: - description: The arguments supplied by the model. - required: - - type - - turn_id - - call_id - - name - - arguments - additionalProperties: false - description: Run a function tool and submit its result. - SessionRequiredActionResourceEnvironmentConnection: - type: object - properties: - type: - type: string - enum: - - environment_connection - default: environment_connection - x-stainless-const: true - description: The type of the object. Always `environment_connection`. - environment_id: - type: string + description: The command that was executed. + cwd: + type: + - string + - 'null' minLength: 0 - description: The ID of the environment to reconnect. + description: The working directory used to execute the command. + status: + $ref: '#/components/schemas/FunctionCallStatusResource' + description: The status of the command execution. + output: + type: + - string + - 'null' + minLength: 0 + description: The command output, if available. + exit_code: + type: + - integer + - 'null' + format: int64 + description: The process exit code, if the command completed. + duration_ms: + type: + - integer + - 'null' + format: int64 + description: The command duration in milliseconds. required: - type - - environment_id + - id + - turn_id + - command + - cwd + - status + - output + - exit_code + - duration_ms additionalProperties: false - description: Reconnect a session environment. - SessionRequiredActionResource: - description: An action that must be completed before a session can continue. - discriminator: - propertyName: type - mapping: - computer_use_approval_request: '#/components/schemas/SessionRequiredActionResourceComputerUseApprovalRequest' - function_call: '#/components/schemas/SessionRequiredActionResourceFunctionCall' - environment_connection: '#/components/schemas/SessionRequiredActionResourceEnvironmentConnection' - x-oai-discriminator-values: - - computer_use_approval_request - - function_call - - environment_connection - anyOf: - - $ref: '#/components/schemas/SessionRequiredActionResourceComputerUseApprovalRequest' - - $ref: '#/components/schemas/SessionRequiredActionResourceFunctionCall' - - $ref: '#/components/schemas/SessionRequiredActionResourceEnvironmentConnection' - AgentToolResourceFunction: + description: A command execution produced by the agent. + InterruptSubagentCallItemResource: type: object properties: type: type: string enum: - - function - default: function + - interrupt_subagent_call + default: interrupt_subagent_call x-stainless-const: true - description: The type of the object. Always `function`. - name: + x-enumDescriptions: + - The current public item type. + description: The item type. Always `interrupt_subagent_call`. + id: type: string minLength: 0 - description: The name of the function. - description: + description: The ID of the tool call item. + turn_id: type: string minLength: 0 - description: A description of what the function does. - parameters: - type: object - additionalProperties: {} - propertyNames: - type: string - minLength: 0 - minProperties: 0 - description: A JSON Schema object describing the function's arguments. - defer_loading: - type: boolean - description: Whether the function is deferred and discovered through tool search. - required: - - type - - name - - description - - parameters - - defer_loading - additionalProperties: false - description: A function defined by the application. - AgentToolResourceProgrammaticToolCalling: - type: object - properties: - type: - type: string - enum: - - programmatic_tool_calling - default: programmatic_tool_calling - x-stainless-const: true - description: The type of the object. Always `programmatic_tool_calling`. - enabled: - type: boolean - description: Whether tools can be called from model-generated code. - required: - - type - - enabled - additionalProperties: false - description: Enables calling tools from model-generated code. - McpTransportResourceHttp: - type: object - properties: - type: + description: The ID of the turn that contains this item. + status: + $ref: '#/components/schemas/FunctionCallStatusResource' + description: The status of the tool call. + sender_agent_id: type: string - enum: - - http - default: http - x-stainless-const: true - description: The type of the object. Always `http`. - server_url: + minLength: 0 + description: The ID of the agent requesting the interrupt. + recipient_agent_id: type: string minLength: 0 - description: The URL of the MCP server. + description: The ID of the agent to interrupt. required: - type - - server_url + - id + - turn_id + - status + - sender_agent_id + - recipient_agent_id additionalProperties: false - description: Connects to an MCP server over HTTP. - McpTransportResourceStdio: + description: A request to interrupt a subagent's current turn. The subagent remains available. + CreateSubagentCallItemResource: type: object properties: type: type: string enum: - - stdio - default: stdio + - create_subagent_call + default: create_subagent_call x-stainless-const: true - description: The type of the object. Always `stdio`. - command: + x-enumDescriptions: + - The current public item type. + description: The item type. Always `create_subagent_call`. + id: type: string minLength: 0 - description: The command used to start the MCP server. - args: - type: array - items: - type: string - minLength: 0 - minItems: 0 - maxItems: 2000 - description: Arguments passed to the MCP server command. - cwd: + description: The ID of the tool call item. + turn_id: type: string minLength: 0 - description: The working directory used to start the MCP server. - env_vars: + description: The ID of the turn that contains this item. + status: + $ref: '#/components/schemas/FunctionCallStatusResource' + description: The status of the tool call. + agent_id: + type: string + minLength: 0 + description: The ID of the agent that requested the subagent. + content: type: array items: - type: string - minLength: 0 + $ref: '#/components/schemas/AgentContentResource' minItems: 0 maxItems: 2000 - description: Environment variable names inherited from the execution environment. - required: - - type - - command - - args - - cwd - - env_vars - additionalProperties: false - description: Starts an MCP server as a local process. - McpTransportResource: - description: The transport used to connect to an MCP server. - discriminator: - propertyName: type - mapping: - http: '#/components/schemas/McpTransportResourceHttp' - stdio: '#/components/schemas/McpTransportResourceStdio' - x-oai-discriminator-values: - - http - - stdio - anyOf: - - $ref: '#/components/schemas/McpTransportResourceHttp' - - $ref: '#/components/schemas/McpTransportResourceStdio' - AgentToolResourceMcp: - type: object - properties: - type: - type: string - enum: - - mcp - default: mcp - x-stainless-const: true - description: The type of the object. Always `mcp`. - server_label: - type: string - minLength: 0 - description: A label used to identify the MCP server in tool calls. - credential_id: + description: The task given to the spawned agent. + model: type: - string - 'null' minLength: 0 - description: The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - transport: - $ref: '#/components/schemas/McpTransportResource' - description: The transport used to connect to the MCP server. - request_metadata: - type: object - additionalProperties: {} - propertyNames: - type: string - minLength: 0 - minProperties: 0 - description: Metadata included with requests to this MCP server. - allowed_tools: + description: The model requested for the spawned agent. + reasoning_effort: type: - - array + - string - 'null' - items: - type: string - minLength: 0 - minItems: 0 - maxItems: 2000 - description: The MCP tools the agent may call. - required: - type: boolean - description: Whether this MCP server must initialize before the first turn. - connection_origin: - $ref: '#/components/schemas/McpConnectionOriginResource' - description: Where outbound MCP HTTP connections originate. + minLength: 0 + description: The reasoning effort requested for the spawned agent. required: - type - - server_label - - credential_id - - transport - - request_metadata - - allowed_tools - - required - - connection_origin + - id + - turn_id + - status + - agent_id + - content + - model + - reasoning_effort additionalProperties: false - description: Tools provided by a remote MCP server. - AgentToolResourceWebSearch: + description: A request to spawn a subagent. + SendSubagentInputCallItemResource: type: object properties: type: type: string enum: - - web_search - default: web_search + - send_subagent_input_call + default: send_subagent_input_call x-stainless-const: true - description: The type of the object. Always `web_search`. - mode: - $ref: '#/components/schemas/WebSearchModeResource' - description: The source used for web search results. - context_size: - $ref: '#/components/schemas/WebSearchContextSizeResource' - description: The amount of search context made available to the model. Defaults to `medium`. - allowed_domains: - type: - - array - - 'null' + x-enumDescriptions: + - The current public item type. + description: The item type. Always `send_subagent_input_call`. + id: + type: string + minLength: 0 + description: The ID of the tool call item. + turn_id: + type: string + minLength: 0 + description: The ID of the turn that contains this item. + status: + $ref: '#/components/schemas/FunctionCallStatusResource' + description: The status of the tool call. + sender_agent_id: + type: string + minLength: 0 + description: The ID of the agent sending the input. + recipient_agent_id: + type: string + minLength: 0 + description: The ID of the agent receiving the input. + content: + type: array items: - type: string - minLength: 0 + $ref: '#/components/schemas/AgentContentResource' minItems: 0 maxItems: 2000 - description: Allowed search domains, or `null` when the search is unrestricted. - location: - anyOf: - - $ref: '#/components/schemas/WebSearchLocationResource' - - type: 'null' - description: Approximate location used to localize search results, if provided. + description: The input sent to the receiving agent. required: - type - - mode - - context_size - - allowed_domains - - location + - id + - turn_id + - status + - sender_agent_id + - recipient_agent_id + - content additionalProperties: false - description: Web search. - AgentToolResourceComputerUse: + description: A request to send input to another agent. + ResumeSubagentCallItemResource: type: object properties: type: type: string enum: - - computer_use - default: computer_use + - resume_subagent_call + default: resume_subagent_call x-stainless-const: true - description: The type of the object. Always `computer_use`. - include_screenshots: - type: boolean - description: Whether computer tool outputs include screenshots. - required: - - type - - include_screenshots - additionalProperties: false - description: Browser use in an OpenAI-hosted session. - AgentToolResource: - description: A tool available to the agent. - discriminator: - propertyName: type - mapping: - function: '#/components/schemas/AgentToolResourceFunction' - programmatic_tool_calling: '#/components/schemas/AgentToolResourceProgrammaticToolCalling' - mcp: '#/components/schemas/AgentToolResourceMcp' - web_search: '#/components/schemas/AgentToolResourceWebSearch' - computer_use: '#/components/schemas/AgentToolResourceComputerUse' - x-oai-discriminator-values: - - function - - programmatic_tool_calling - - mcp - - web_search - - computer_use - anyOf: - - $ref: '#/components/schemas/AgentToolResourceFunction' - - $ref: '#/components/schemas/AgentToolResourceProgrammaticToolCalling' - - $ref: '#/components/schemas/AgentToolResourceMcp' - - $ref: '#/components/schemas/AgentToolResourceWebSearch' - - $ref: '#/components/schemas/AgentToolResourceComputerUse' - SessionAgentResource: - type: object - properties: + x-enumDescriptions: + - The current public item type. + description: The item type. Always `resume_subagent_call`. id: type: string minLength: 0 - description: The ID of the agent. - name: - type: - - string - - 'null' + description: The ID of the tool call item. + turn_id: + type: string minLength: 0 - description: The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - model: + description: The ID of the turn that contains this item. + status: + $ref: '#/components/schemas/FunctionCallStatusResource' + description: The status of the tool call. + sender_agent_id: type: string minLength: 0 - description: The model used by the agent. - reasoning: - $ref: '#/components/schemas/ReasoningResource' - description: The agent's reasoning configuration. - text: - $ref: '#/components/schemas/TextResource' - description: Configuration for text generated by the agent. - service_tier: - $ref: '#/components/schemas/ServiceTierResource' - description: The effective service-tier policy for model requests. Defaults to `auto`. - instructions: - type: - - string - - 'null' + description: The ID of the agent requesting the resume. + recipient_agent_id: + type: string minLength: 0 - description: Custom instructions appended to the agent's default base instructions. - tools: - type: array - items: - $ref: '#/components/schemas/AgentToolResource' - minItems: 0 - maxItems: 2000 - description: Tools available to the agent. - multi_agent: - $ref: '#/components/schemas/MultiAgentConfigResource' - description: Configuration for creating and coordinating subagents. + description: The ID of the agent to resume. required: + - type - id - - name - - model - - reasoning - - text - - service_tier - - instructions - - tools - - multi_agent + - turn_id + - status + - sender_agent_id + - recipient_agent_id additionalProperties: false - description: The effective agent configuration for a session. - EnvironmentResourceNone: + description: A request to resume a subagent. + WaitForSubagentsCallItemResource: type: object properties: type: type: string enum: - - none - default: none + - wait_for_subagents_call + default: wait_for_subagents_call x-stainless-const: true - description: The type of the object. Always `none`. + x-enumDescriptions: + - The current public item type. + description: The item type. Always `wait_for_subagents_call`. + id: + type: string + minLength: 0 + description: The ID of the tool call item. + turn_id: + type: string + minLength: 0 + description: The ID of the turn that contains this item. + status: + $ref: '#/components/schemas/FunctionCallStatusResource' + description: The status of the tool call. + sender_agent_id: + type: string + minLength: 0 + description: The ID of the agent waiting for results. + recipient_agent_ids: + type: array + items: + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: The IDs of the agents to wait for. required: - type + - id + - turn_id + - status + - sender_agent_id + - recipient_agent_ids additionalProperties: false - description: The session talks to CCA without selecting or provisioning an execution environment. - ContainerSizeResource: - type: string - enum: - - small - - medium - - large - description: The effective CPU and memory tier of an OpenAI-hosted environment. - EnvironmentResourceOpenaiHosted: + description: A request to wait for one or more subagents. + CloseSubagentCallItemResource: type: object properties: type: type: string enum: - - openai_hosted - default: openai_hosted + - close_subagent_call + default: close_subagent_call x-stainless-const: true - description: The type of the object. Always `openai_hosted`. + x-enumDescriptions: + - The current public item type. + description: The item type. Always `close_subagent_call`. id: type: string minLength: 0 - description: The public ID of the environment. - container_size: - anyOf: - - $ref: '#/components/schemas/ContainerSizeResource' - - type: 'null' - description: The effective CPU and memory tier, or null when unknown or outside the public tiers. - x-stainless-skip: - - cli - packages: - $ref: '#/components/schemas/EnvironmentPackagesResource' - description: Packages installed in the environment. - network: - $ref: '#/components/schemas/NetworkPolicyResource' - description: The effective network access policy for the environment. - desktop: - $ref: '#/components/schemas/DesktopResource' - description: The effective desktop configuration. - capability_directories: - type: array - items: - type: string - minLength: 0 - minItems: 0 - maxItems: 2000 - description: Directories that contain capabilities exposed to the agent. - skills: - type: array - items: - $ref: '#/components/schemas/HostedSkillResource' - minItems: 0 - maxItems: 2000 - description: Skills installed in the environment, excluding their archive contents. - plugins: - type: array - items: - $ref: '#/components/schemas/HostedPluginResource' - minItems: 0 - maxItems: 2000 - description: Plugins installed in the environment, excluding their archive contents. - files: - type: array - items: - $ref: '#/components/schemas/HostedEnvironmentFileResource' - minItems: 0 - maxItems: 50 - description: Files available in the environment, excluding their contents. - required: - - type - - id - - packages - - network - - capability_directories - - skills - - plugins - - files - additionalProperties: false - description: An environment hosted by OpenAI. - EnvironmentResourceSelfHosted: - type: object - properties: - type: - type: string - enum: - - self_hosted - default: self_hosted - x-stainless-const: true - description: The type of the object. Always `self_hosted`. - remote_url: + description: The ID of the tool call item. + turn_id: type: string minLength: 0 - description: Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - id: + description: The ID of the turn that contains this item. + status: + $ref: '#/components/schemas/FunctionCallStatusResource' + description: The status of the tool call. + sender_agent_id: type: string minLength: 0 - description: The public ID of the environment. - workspace_directory: + description: The ID of the agent requesting the close. + recipient_agent_id: type: string minLength: 0 - description: The absolute project directory inside the environment. Defaults to `/workspace`. - capability_directories: - type: array - items: - type: string - minLength: 0 - minItems: 0 - maxItems: 2000 - description: Directories that contain capabilities exposed to the agent. + description: The ID of the agent to close. required: - type - - remote_url - id - - workspace_directory - - capability_directories + - turn_id + - status + - sender_agent_id + - recipient_agent_id additionalProperties: false - description: An environment hosted by the application. - EnvironmentResource: - description: The execution environment for a session. + description: A request to close a subagent. + SessionTurnItemResource: + description: An item associated with a session turn. discriminator: propertyName: type mapping: - none: '#/components/schemas/EnvironmentResourceNone' - openai_hosted: '#/components/schemas/EnvironmentResourceOpenaiHosted' - self_hosted: '#/components/schemas/EnvironmentResourceSelfHosted' + message: '#/components/schemas/MessageItemResource' + reasoning: '#/components/schemas/ReasoningItemResource' + function_call: '#/components/schemas/FunctionCallItemResource' + function_call_output: '#/components/schemas/FunctionCallOutputItemResource' + agent_message: '#/components/schemas/AgentMessageItemResource' + mcp_call: '#/components/schemas/McpCallItemResource' + computer_use_call: '#/components/schemas/ComputerUseCallItemResource' + computer_use_approval_request: '#/components/schemas/BrowserAuthenticationRequestItemResource' + computer_use_approval_request_result: '#/components/schemas/ComputerUseApprovalRequestResultItemResource' + web_search_call: '#/components/schemas/WebSearchCallItemResource' + command_execution: '#/components/schemas/CommandExecutionItemResource' + interrupt_subagent_call: '#/components/schemas/InterruptSubagentCallItemResource' + create_subagent_call: '#/components/schemas/CreateSubagentCallItemResource' + send_subagent_input_call: '#/components/schemas/SendSubagentInputCallItemResource' + resume_subagent_call: '#/components/schemas/ResumeSubagentCallItemResource' + wait_for_subagents_call: '#/components/schemas/WaitForSubagentsCallItemResource' + close_subagent_call: '#/components/schemas/CloseSubagentCallItemResource' x-oai-discriminator-values: - - none - - openai_hosted - - self_hosted + - message + - reasoning + - function_call + - function_call_output + - agent_message + - mcp_call + - computer_use_call + - computer_use_approval_request + - computer_use_approval_request_result + - web_search_call + - command_execution + - create_subagent_call + - send_subagent_input_call + - resume_subagent_call + - wait_for_subagents_call + - interrupt_subagent_call + - close_subagent_call anyOf: - - $ref: '#/components/schemas/EnvironmentResourceNone' - - $ref: '#/components/schemas/EnvironmentResourceOpenaiHosted' - - $ref: '#/components/schemas/EnvironmentResourceSelfHosted' - SessionResource: + - $ref: '#/components/schemas/MessageItemResource' + - $ref: '#/components/schemas/ReasoningItemResource' + - $ref: '#/components/schemas/FunctionCallItemResource' + - $ref: '#/components/schemas/FunctionCallOutputItemResource' + - $ref: '#/components/schemas/AgentMessageItemResource' + - $ref: '#/components/schemas/McpCallItemResource' + - $ref: '#/components/schemas/ComputerUseCallItemResource' + - $ref: '#/components/schemas/BrowserAuthenticationRequestItemResource' + - $ref: '#/components/schemas/ComputerUseApprovalRequestResultItemResource' + - $ref: '#/components/schemas/WebSearchCallItemResource' + - $ref: '#/components/schemas/CommandExecutionItemResource' + - $ref: '#/components/schemas/CreateSubagentCallItemResource' + - $ref: '#/components/schemas/SendSubagentInputCallItemResource' + - $ref: '#/components/schemas/ResumeSubagentCallItemResource' + - $ref: '#/components/schemas/WaitForSubagentsCallItemResource' + - $ref: '#/components/schemas/InterruptSubagentCallItemResource' + - $ref: '#/components/schemas/CloseSubagentCallItemResource' + SessionItemListResource: type: object properties: - spend_control: - $ref: '#/components/schemas/SessionSpendControlResource' - description: Configured spending limit and best-effort consumption, in USD cents. Unlimited sessions omit this object. - metadata: - type: object - additionalProperties: - type: string - minLength: 0 - propertyNames: - type: string - minLength: 0 - minProperties: 0 - description: Custom string key-value pairs attached to the session. - id: - type: string - minLength: 0 - description: The ID of the session. object: type: string enum: - - agent.session - default: agent.session + - list + default: list x-stainless-const: true - description: The object type. Always `agent.session`. - created_at: - type: integer - format: int64 - description: The Unix timestamp, in seconds, when the session was created. - last_active_at: - type: integer - format: int64 - description: The Unix timestamp, in seconds, when the session was last active. - status: - $ref: '#/components/schemas/SessionStatusResource' - description: The current status of the session. - required_actions: + description: The object type, which is always `list`. + data: type: array items: - $ref: '#/components/schemas/SessionRequiredActionResource' + $ref: '#/components/schemas/SessionTurnItemResource' minItems: 0 maxItems: 2000 - description: Actions that must be completed before the session can continue. - error: - description: The error that caused the session to fail, if any. + description: The resources returned in this page, in the requested sort order. + first_id: type: - string - 'null' minLength: 0 - agent: - $ref: '#/components/schemas/SessionAgentResource' - description: The agent running in the session. - environment: - $ref: '#/components/schemas/EnvironmentResource' - description: The execution environment for the session. - vault_ids: - type: array - items: - type: string - minLength: 0 - minItems: 0 - maxItems: 2000 - description: The IDs of vaults made available to the session. + description: The ID of the first resource in `data`, or `null` if the page is empty. + last_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. + has_more: + type: boolean + description: Whether there are more resources to retrieve after this page. + required: + - object + - data + - first_id + - last_id + - has_more + additionalProperties: false + description: A page of messages, reasoning, and tool calls from a session's item history. + TurnObjectResource: + type: string + enum: + - agent.session.turn + default: agent.session.turn + x-stainless-const: true + description: The object type for a turn. + TurnStatusResource: + type: string + enum: + - queued + - in_progress + - waiting + - completed + - failed + - cancelled + x-enumDescriptions: + - The turn is waiting to start. + - The turn is in progress. + - The turn is waiting for external input. + - The turn completed successfully. + - The turn failed. + - The turn was cancelled. + description: The current status of a turn. + SessionTurnErrorCodeResource: + type: string + enum: + - context_length_exceeded + - session_budget_exceeded + - usage_limit_exceeded + - project_spend_limit_exceeded + - organization_spend_limit_exceeded + - organization_usage_limit_exceeded + - billing_not_active + - credit_balance_exhausted + - rate_limit_exceeded + - flex_unavailable + - server_overloaded + - cyber_policy + - misalignment_policy_violation + - connection_failed + - server_error + - authentication_error + - invalid_request + - resource_not_found + - sandbox_error + - executor_version_incompatible + - active_turn_not_steerable + - request_timeout + - internal_error + x-enumDescriptions: + - The request exceeds the model's context window. + - The session has reached its usage budget. + - The organization has reached a usage, plan, or billing limit. + - The project has reached its enforced spend limit. + - The organization has reached its enforced spend limit. + - The organization has reached its OpenAI-assigned usage limit. + - Billing is not active for the account. + - The organization has no API credits remaining. + - The request exceeds the available rate limit. + - Flex processing is temporarily unavailable. + - The model service is temporarily overloaded. + - The request was rejected by a safety policy. + - The request was blocked by the safety systems. + - The request could not connect to the model service. + - The model service encountered an unexpected error. + - The API credentials are invalid or lack the required access. + - The request contains invalid input or configuration. + - The requested model or resource is unavailable. + - The request could not complete in its execution environment. + - The executor must be upgraded before it can run this turn. + - The session cannot accept additional input while a request is running. + - The request timed out before the model service responded. + - An unexpected internal error prevented the session request from completing. + description: Stable public categories for session request failures. + SessionTurnErrorResource: + type: object + properties: + code: + $ref: '#/components/schemas/SessionTurnErrorCodeResource' + description: A stable, machine-readable failure category. + message: + type: string + minLength: 0 + description: A customer-safe explanation of the failure. + required: + - code + - message + additionalProperties: false + description: A customer-safe error describing why a session request failed. + InputTokensDetailsResource-2: + type: object + properties: + cached_tokens: + type: integer + format: int64 + description: The number of input tokens retrieved from the prompt cache. + required: + - cached_tokens + additionalProperties: false + description: A breakdown of input token usage for a session or turn. + OutputTokensDetailsResource-2: + type: object + properties: + reasoning_tokens: + type: integer + format: int64 + description: The number of output tokens used for reasoning. + required: + - reasoning_tokens + additionalProperties: false + description: A breakdown of output token usage for a session or turn. + TokenUsageResource: + type: object + properties: + input_tokens: + type: integer + format: int64 + description: The number of input tokens used by the agent. + input_tokens_details: + $ref: '#/components/schemas/InputTokensDetailsResource-2' + description: A breakdown of the agent's input token usage. + output_tokens: + type: integer + format: int64 + description: The number of output tokens generated by the agent. + output_tokens_details: + $ref: '#/components/schemas/OutputTokensDetailsResource-2' + description: A breakdown of the agent's output token usage. + total_tokens: + type: integer + format: int64 + description: The total number of input and output tokens used by the agent. + required: + - input_tokens + - input_tokens_details + - output_tokens + - output_tokens_details + - total_tokens + additionalProperties: false + description: Recorded token usage for a session or turn. Usage is best effort and may change. + TurnResource: + type: object + properties: + id: + type: string + minLength: 0 + description: The ID of the turn. + object: + $ref: '#/components/schemas/TurnObjectResource' + description: The object type. Always `agent.session.turn`. + session_id: + type: string + minLength: 0 + description: The ID of the session that owns the turn. + agent_id: + type: string + minLength: 0 + description: The ID of the agent that ran the turn. + subagent_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the subagent that ran the turn, if applicable. + status: + $ref: '#/components/schemas/TurnStatusResource' + description: The current status of the turn. + created_at: + type: integer + format: int64 + description: The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. + started_at: + type: + - integer + - 'null' + format: int64 + description: The Unix timestamp, in seconds, when the turn started. + completed_at: + type: + - integer + - 'null' + format: int64 + description: The Unix timestamp, in seconds, when the turn reached a terminal state. + error: + anyOf: + - $ref: '#/components/schemas/SessionTurnErrorResource' + - type: 'null' + description: A customer-safe error. Non-null only for a failed turn. usage: anyOf: - $ref: '#/components/schemas/TokenUsageResource' - type: 'null' - description: Best-effort token usage for the session, or null if unknown. Recorded usage may change. + description: Best-effort token usage for the turn, or null if unknown. Recorded usage may change. required: - - metadata - id - object - - created_at - - last_active_at + - session_id + - agent_id + - subagent_id - status - - required_actions + - created_at + - started_at + - completed_at - error - - agent - - environment - - vault_ids - usage additionalProperties: false - description: A Managed Agents session. - SessionListResource: + description: The canonical public representation of a session turn. + SessionTurnListResource: type: object properties: object: @@ -88114,7 +89142,7 @@ components: data: type: array items: - $ref: '#/components/schemas/SessionResource' + $ref: '#/components/schemas/TurnResource' minItems: 0 maxItems: 2000 description: The resources returned in this page, in the requested sort order. @@ -88141,22 +89169,7 @@ components: - has_more additionalProperties: false description: A page of Agents API resources, with IDs for retrieving additional pages. - SessionSpendControlParam: - type: object - properties: - limit: - type: - - integer - - 'null' - format: int64 - minimum: 1 - maximum: 4503599627370495 - description: Positive USD cents, or null to remove the limit. - required: - - limit - additionalProperties: false - description: Sets the session-wide limit without changing recorded spend. - AgentToolConfigParamFunction: + PersistedAgentToolResourceFunction: type: object properties: type: @@ -88169,35 +89182,31 @@ components: name: type: string minLength: 0 - maxLength: 1048576 description: The name of the function. description: type: string minLength: 0 - maxLength: 1048576 description: A description of what the function does. parameters: type: object additionalProperties: {} propertyNames: type: string - minLength: 1 - maxLength: 256 + minLength: 0 minProperties: 0 - maxProperties: 1024 description: A JSON Schema object describing the function's arguments. defer_loading: type: boolean - default: false - description: Whether this function is deferred and discovered through tool search. Defaults to `false`. + description: Whether the function is deferred and discovered through tool search. required: - type - name - description - parameters + - defer_loading additionalProperties: false description: A function defined by the application. - AgentToolConfigParamToolSearch: + PersistedAgentToolResourceToolSearch: type: object properties: type: @@ -88211,7 +89220,7 @@ components: - type additionalProperties: false description: Discovers deferred function tools and loads them into the model context. - AgentToolConfigParamProgrammaticToolCalling: + PersistedAgentToolResourceProgrammaticToolCalling: type: object properties: type: @@ -88223,13 +89232,13 @@ components: description: The type of the object. Always `programmatic_tool_calling`. enabled: type: boolean - default: true - description: Whether tools can be called from model-generated code. Defaults to `true`. + description: Whether tools can be called from model-generated code. required: - type + - enabled additionalProperties: false description: Enables calling tools from model-generated code. - McpTransportConfigParamHttp: + PersistedMcpTransportResourceHttp: type: object properties: type: @@ -88242,36 +89251,24 @@ components: server_url: type: string minLength: 0 - maxLength: 1048576 description: The URL of the MCP server. - authorization: - type: - - string - - 'null' - minLength: 0 - maxLength: 1048576 - description: The authorization value sent to the MCP server, if any. headers: - type: - - object - - 'null' + type: object additionalProperties: type: string minLength: 0 - maxLength: 1048576 propertyNames: type: string - minLength: 1 - maxLength: 256 + minLength: 0 minProperties: 0 - maxProperties: 1024 - description: Additional HTTP headers sent to the MCP server. + description: Non-secret HTTP headers sent to the MCP server. required: - type - server_url + - headers additionalProperties: false description: Connects to an MCP server over HTTP. - McpTransportConfigParamStdio: + PersistedMcpTransportResourceStdio: type: object properties: type: @@ -88284,70 +89281,49 @@ components: command: type: string minLength: 0 - maxLength: 1048576 description: The command used to start the MCP server. args: - type: - - array - - 'null' + type: array items: type: string minLength: 0 - maxLength: 1048576 minItems: 0 - maxItems: 16384 + maxItems: 2000 description: Arguments passed to the MCP server command. cwd: type: string minLength: 0 - maxLength: 1048576 description: The working directory used to start the MCP server. - env: - type: - - object - - 'null' - additionalProperties: - type: string - minLength: 0 - maxLength: 1048576 - propertyNames: - type: string - minLength: 1 - maxLength: 256 - minProperties: 0 - maxProperties: 1024 - description: Environment variables set for the MCP server process. env_vars: - type: - - array - - 'null' + type: array items: type: string minLength: 0 - maxLength: 1048576 minItems: 0 - maxItems: 16384 - description: Environment variable names to inherit from the selected execution environment. + maxItems: 2000 + description: Environment variable names inherited from the execution environment. required: - type - command + - args - cwd + - env_vars additionalProperties: false description: Starts an MCP server as a local process. - McpTransportConfigParam: - description: The transport used to connect to an MCP server. + PersistedMcpTransportResource: + description: A credential-free transport used to connect to an MCP server. discriminator: propertyName: type mapping: - http: '#/components/schemas/McpTransportConfigParamHttp' - stdio: '#/components/schemas/McpTransportConfigParamStdio' + http: '#/components/schemas/PersistedMcpTransportResourceHttp' + stdio: '#/components/schemas/PersistedMcpTransportResourceStdio' x-oai-discriminator-values: - http - stdio anyOf: - - $ref: '#/components/schemas/McpTransportConfigParamHttp' - - $ref: '#/components/schemas/McpTransportConfigParamStdio' - AgentToolConfigParamMcp: + - $ref: '#/components/schemas/PersistedMcpTransportResourceHttp' + - $ref: '#/components/schemas/PersistedMcpTransportResourceStdio' + PersistedAgentToolResourceMcp: type: object properties: type: @@ -88360,29 +89336,23 @@ components: server_label: type: string minLength: 0 - maxLength: 1048576 description: A label used to identify the MCP server in tool calls. credential_id: type: - string - 'null' minLength: 0 - maxLength: 1048576 - description: The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL. + description: The vault credential selected for this MCP server, if any. transport: - $ref: '#/components/schemas/McpTransportConfigParam' - description: The transport used to connect to the MCP server. + $ref: '#/components/schemas/PersistedMcpTransportResource' + description: The credential-free transport used to connect to the MCP server. request_metadata: - type: - - object - - 'null' + type: object additionalProperties: {} propertyNames: type: string - minLength: 1 - maxLength: 256 + minLength: 0 minProperties: 0 - maxProperties: 1024 description: Metadata included with requests to this MCP server. allowed_tools: type: @@ -88391,26 +89361,27 @@ components: items: type: string minLength: 0 - maxLength: 1048576 minItems: 0 - maxItems: 16384 - description: The MCP tools the agent may call. All server tools are allowed when omitted. + maxItems: 2000 + description: The MCP tools the agent may call, or null when all server tools are allowed. required: type: boolean - default: false - description: Whether this MCP server must initialize before the first turn. Defaults to `false`. + description: Whether this MCP server must initialize before the first turn. connection_origin: - anyOf: - - $ref: '#/components/schemas/McpConnectionOriginParam' - - type: 'null' - description: Selects where outbound MCP HTTP connections originate. Omitted or `service` uses the Managed Agents service network; `environment` uses the session's selected environment. + $ref: '#/components/schemas/McpConnectionOriginResource' + description: Where outbound MCP HTTP connections originate. required: - type - server_label + - credential_id - transport + - request_metadata + - allowed_tools + - required + - connection_origin additionalProperties: false - description: Tools provided by a remote MCP server. - AgentToolConfigParamWebSearch: + description: Tools provided by a remote MCP server without stored credentials. + PersistedAgentToolResourceWebSearch: type: object properties: type: @@ -88421,14 +89392,10 @@ components: x-stainless-const: true description: The type of the object. Always `web_search`. mode: - anyOf: - - $ref: '#/components/schemas/WebSearchModeParam' - - type: 'null' - description: The source used for web search results. Defaults to `live`. + $ref: '#/components/schemas/WebSearchModeResource' + description: The source used for web search results. context_size: - anyOf: - - $ref: '#/components/schemas/WebSearchContextSizeParam' - - type: 'null' + $ref: '#/components/schemas/WebSearchContextSizeResource' description: The amount of search context made available to the model. Defaults to `medium`. allowed_domains: type: @@ -88437,20 +89404,23 @@ components: items: type: string minLength: 0 - maxLength: 1048576 minItems: 0 - maxItems: 16384 - description: Domains the search may include. + maxItems: 2000 + description: Allowed search domains, or `null` when the search is unrestricted. location: anyOf: - - $ref: '#/components/schemas/WebSearchLocationParam' + - $ref: '#/components/schemas/WebSearchLocationResource' - type: 'null' - description: Approximate location used to localize search results. + description: Approximate location used to localize search results, if provided. required: - type + - mode + - context_size + - allowed_domains + - location additionalProperties: false description: Web search. - AgentToolConfigParamComputerUse: + PersistedAgentToolResourceComputerUse: type: object properties: type: @@ -88462,23 +89432,38 @@ components: description: The type of the object. Always `computer_use`. include_screenshots: type: boolean - default: false - description: Whether computer tool outputs include screenshots. Defaults to `false`. + description: Whether computer tool outputs include screenshots. required: - type + - include_screenshots additionalProperties: false description: Browser use in an OpenAI-hosted session. - AgentToolConfigParam: - description: A tool available to the agent. + PersistedAgentToolResourceAutomations: + type: object + properties: + type: + type: string + enum: + - automations + default: automations + x-stainless-const: true + description: The type of the object. Always `automations`. + required: + - type + additionalProperties: false + description: Lets the agent manage its own scheduled wakeups. + PersistedAgentToolResource: + description: A credential-free tool available to a reusable agent. discriminator: propertyName: type mapping: - function: '#/components/schemas/AgentToolConfigParamFunction' - tool_search: '#/components/schemas/AgentToolConfigParamToolSearch' - programmatic_tool_calling: '#/components/schemas/AgentToolConfigParamProgrammaticToolCalling' - mcp: '#/components/schemas/AgentToolConfigParamMcp' - web_search: '#/components/schemas/AgentToolConfigParamWebSearch' - computer_use: '#/components/schemas/AgentToolConfigParamComputerUse' + function: '#/components/schemas/PersistedAgentToolResourceFunction' + tool_search: '#/components/schemas/PersistedAgentToolResourceToolSearch' + programmatic_tool_calling: '#/components/schemas/PersistedAgentToolResourceProgrammaticToolCalling' + mcp: '#/components/schemas/PersistedAgentToolResourceMcp' + web_search: '#/components/schemas/PersistedAgentToolResourceWebSearch' + computer_use: '#/components/schemas/PersistedAgentToolResourceComputerUse' + automations: '#/components/schemas/PersistedAgentToolResourceAutomations' x-oai-discriminator-values: - function - tool_search @@ -88486,117 +89471,227 @@ components: - mcp - web_search - computer_use + - automations anyOf: - - $ref: '#/components/schemas/AgentToolConfigParamFunction' - - $ref: '#/components/schemas/AgentToolConfigParamToolSearch' - - $ref: '#/components/schemas/AgentToolConfigParamProgrammaticToolCalling' - - $ref: '#/components/schemas/AgentToolConfigParamMcp' - - $ref: '#/components/schemas/AgentToolConfigParamWebSearch' - - $ref: '#/components/schemas/AgentToolConfigParamComputerUse' - SessionAgentConfigParam: + - $ref: '#/components/schemas/PersistedAgentToolResourceFunction' + - $ref: '#/components/schemas/PersistedAgentToolResourceToolSearch' + - $ref: '#/components/schemas/PersistedAgentToolResourceProgrammaticToolCalling' + - $ref: '#/components/schemas/PersistedAgentToolResourceMcp' + - $ref: '#/components/schemas/PersistedAgentToolResourceWebSearch' + - $ref: '#/components/schemas/PersistedAgentToolResourceComputerUse' + - $ref: '#/components/schemas/PersistedAgentToolResourceAutomations' + AgentResource: type: object properties: + id: + type: string + minLength: 0 + description: The ID of the reusable agent. + object: + type: string + enum: + - agent + default: agent + x-stainless-const: true + description: The object type. Always `agent`. + created_at: + type: integer + format: int64 + description: The Unix timestamp, in seconds, when the agent was created. + updated_at: + type: integer + format: int64 + description: The Unix timestamp, in seconds, when the agent was last updated. + name: + type: + - string + - 'null' + minLength: 0 + description: A human-readable name for the agent, or null if it is unnamed. + metadata: + type: object + additionalProperties: + type: string + minLength: 0 + propertyNames: + type: string + minLength: 0 + minProperties: 0 + description: Custom string key-value pairs attached to the agent. model: type: string minLength: 0 - maxLength: 1048576 - description: The model to use for the agent. The requested model name is preserved. + description: The requested model name used for inference. reasoning: - anyOf: - - $ref: '#/components/schemas/ReasoningParam' - - type: 'null' - description: Configuration for model reasoning. Omit to keep the current settings; pass `null` to reset to the model's default effort. + $ref: '#/components/schemas/ReasoningResource' + description: The resolved reasoning configuration, including the model default for an omitted effort. text: - anyOf: - - $ref: '#/components/schemas/TextParam' - - type: 'null' - description: Configuration for text generated by the agent. + $ref: '#/components/schemas/TextResource' + description: The resolved configuration for text generated by the agent. service_tier: - anyOf: - - $ref: '#/components/schemas/ServiceTierParam' - - type: 'null' - description: The service tier used for model requests. + $ref: '#/components/schemas/ServiceTierResource' + description: The resolved service-tier policy used for model requests. instructions: type: - string - 'null' minLength: 0 - maxLength: 1048576 - description: Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. - multi_agent: - anyOf: - - $ref: '#/components/schemas/MultiAgentConfigCurrentParam' - - type: 'null' - description: Configuration for creating and coordinating subagents. + description: Custom instructions appended to the agent's default base instructions. tools: - type: - - array - - 'null' + type: array items: - $ref: '#/components/schemas/AgentToolConfigParam' + $ref: '#/components/schemas/PersistedAgentToolResource' minItems: 0 - maxItems: 16384 - description: Tools available to the agent. Omit to inherit, or pass null to clear them. The resolved tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON. + maxItems: 2000 + description: Tools available to the agent. + multi_agent: + $ref: '#/components/schemas/MultiAgentConfigResource' + description: The resolved configuration for creating and coordinating subagents. + required: + - id + - object + - created_at + - updated_at + - name + - metadata + - model + - reasoning + - text + - service_tier + - instructions + - tools + - multi_agent additionalProperties: false - description: Agent configuration for a session. Omitted fields inherit from `agent_id` when supplied. Supplied objects and arrays replace the whole field; null resets nullable fields. - EnvironmentParamNone: + description: A reusable agent scoped to the caller's project. + AgentListResource: + type: object + properties: + object: + type: string + enum: + - list + default: list + x-stainless-const: true + description: The object type, which is always `list`. + data: + type: array + items: + $ref: '#/components/schemas/AgentResource' + minItems: 0 + maxItems: 2000 + description: The resources returned in this page, in the requested sort order. + first_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the first resource in `data`, or `null` if the page is empty. + last_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. + has_more: + type: boolean + description: Whether there are more resources to retrieve after this page. + required: + - object + - data + - first_id + - last_id + - has_more + additionalProperties: false + description: A page of Agents API resources, with IDs for retrieving additional pages. + PersistedAgentToolConfigParamFunction: type: object properties: type: type: string enum: - - none - default: none + - function + default: function x-stainless-const: true - description: The type of the object. Always `none`. + description: The type of the object. Always `function`. + name: + type: string + minLength: 0 + maxLength: 1048576 + description: The name of the function. + description: + type: string + minLength: 0 + maxLength: 1048576 + description: A description of what the function does. + parameters: + type: object + additionalProperties: {} + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: A JSON Schema object describing the function's arguments. + defer_loading: + type: boolean + default: false + description: Whether this function is deferred and discovered through tool search. Defaults to `false`. required: - type + - name + - description + - parameters additionalProperties: false - description: Runs the agent without an execution environment. - ContainerSizeParam: - type: string - enum: - - small - - medium - - large - description: The CPU and memory tier for a new OpenAI-hosted session environment. - EnvironmentParamOpenaiHosted: + description: A function defined by the application. + PersistedAgentToolConfigParamToolSearch: type: object properties: type: type: string enum: - - openai_hosted - default: openai_hosted + - tool_search + default: tool_search x-stainless-const: true - description: The type of the object. Always `openai_hosted`. - packages: - anyOf: - - $ref: '#/components/schemas/EnvironmentPackagesParam' - - type: 'null' - description: Packages to install in the environment. Defaults to empty package lists. - setup_commands: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/SetupCommandParam' - minItems: 0 - maxItems: 16 - description: Ordered, confidential setup commands. Command bodies are never returned. - network: - anyOf: - - $ref: '#/components/schemas/NetworkPolicyParam' - - type: 'null' - description: Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled. - desktop: - anyOf: - - $ref: '#/components/schemas/DesktopParam' - - type: 'null' - description: Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled. - x-openai-go-legacy-bool-fields: - - enabled - env: + description: The type of the object. Always `tool_search`. + required: + - type + additionalProperties: false + description: Discovers deferred function tools and loads them into the model context. + PersistedAgentToolConfigParamProgrammaticToolCalling: + type: object + properties: + type: + type: string + enum: + - programmatic_tool_calling + default: programmatic_tool_calling + x-stainless-const: true + description: The type of the object. Always `programmatic_tool_calling`. + enabled: + type: boolean + default: true + description: Whether tools can be called from model-generated code. Defaults to `true`. + required: + - type + additionalProperties: false + description: Enables calling tools from model-generated code. + PersistedMcpTransportConfigParamHttp: + type: object + properties: + type: + type: string + enum: + - http + default: http + x-stainless-const: true + description: The type of the object. Always `http`. + server_url: + type: string + minLength: 0 + maxLength: 1048576 + description: The URL of the MCP server. + headers: type: - object - 'null' @@ -88610,101 +89705,28 @@ components: maxLength: 256 minProperties: 0 maxProperties: 1024 - description: Environment variables made available to the agent. - capability_directories: - type: - - array - - 'null' - items: - type: string - minLength: 0 - maxLength: 1048576 - minItems: 0 - maxItems: 16384 - description: Directories that contain capabilities exposed to the agent. Defaults to an empty list. - skills: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/HostedSkillParam' - minItems: 0 - maxItems: 200 - description: Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. - plugins: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/HostedPluginParam' - minItems: 0 - maxItems: 32 - description: Plugins provided as inline ZIP archives. Defaults to an empty list. - files: - type: - - array - - 'null' - items: - $ref: '#/components/schemas/HostedEnvironmentFileParam' - minItems: 0 - maxItems: 50 - description: Files available before the agent starts. Defaults to an empty list. - environment_id: - type: string - minLength: 9 - maxLength: 256 - description: An existing prewarmed environment. Cannot be combined with a template or inline configuration. - environment_template_id: - type: string - minLength: 0 - maxLength: 64 - description: A reusable hosted template applied before inline session configuration. Omitted fields inherit the template; network overrides cannot broaden its policy. - container_size: - $ref: '#/components/schemas/ContainerSizeParam' - description: The hosted container size. Omission selects the medium tier. - x-stainless-skip: - - cli + description: Non-secret HTTP headers sent to the MCP server. required: - type + - server_url additionalProperties: false - description: An existing OpenAI-hosted environment or new inline/template-based hosted configuration. - not: - required: - - environment_id - anyOf: - - required: - - packages - - required: - - setup_commands - - required: - - network - - required: - - desktop - - required: - - env - - required: - - capability_directories - - required: - - skills - - required: - - plugins - - required: - - files - - required: - - environment_template_id - - required: - - container_size - EnvironmentParamSelfHosted: + description: Connects to an MCP server over HTTP. + PersistedMcpTransportConfigParamStdio: type: object properties: type: type: string enum: - - self_hosted - default: self_hosted + - stdio + default: stdio x-stainless-const: true - description: The type of the object. Always `self_hosted`. - capability_directories: + description: The type of the object. Always `stdio`. + command: + type: string + minLength: 0 + maxLength: 1048576 + description: The command used to start the MCP server. + args: type: - array - 'null' @@ -88714,134 +89736,208 @@ components: maxLength: 1048576 minItems: 0 maxItems: 16384 - description: Directories that contain capabilities exposed to the agent. Defaults to an empty list. - workspace_directory: + description: Arguments passed to the MCP server command. + cwd: type: string minLength: 0 maxLength: 1048576 - description: Absolute project directory inside the self-hosted environment. + description: The working directory used to start the MCP server. + env_vars: + type: + - array + - 'null' + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: Environment variable names to inherit from the selected execution environment. required: - type - - workspace_directory + - command + - cwd additionalProperties: false - description: An application-hosted environment configured inline. - EnvironmentParam: - description: The execution environment and optional reusable template for a session. + description: Starts an MCP server as a local process. + PersistedMcpTransportConfigParam: + description: A credential-free transport used to connect to an MCP server. discriminator: propertyName: type mapping: - none: '#/components/schemas/EnvironmentParamNone' - openai_hosted: '#/components/schemas/EnvironmentParamOpenaiHosted' - self_hosted: '#/components/schemas/EnvironmentParamSelfHosted' + http: '#/components/schemas/PersistedMcpTransportConfigParamHttp' + stdio: '#/components/schemas/PersistedMcpTransportConfigParamStdio' x-oai-discriminator-values: - - none - - openai_hosted - - self_hosted + - http + - stdio anyOf: - - $ref: '#/components/schemas/EnvironmentParamNone' - - $ref: '#/components/schemas/EnvironmentParamOpenaiHosted' - - $ref: '#/components/schemas/EnvironmentParamSelfHosted' - InputContentParamInputText: + - $ref: '#/components/schemas/PersistedMcpTransportConfigParamHttp' + - $ref: '#/components/schemas/PersistedMcpTransportConfigParamStdio' + PersistedAgentToolConfigParamMcp: type: object properties: type: type: string enum: - - input_text - default: input_text + - mcp + default: mcp x-stainless-const: true - description: The type of the object. Always `input_text`. - text: + description: The type of the object. Always `mcp`. + server_label: type: string minLength: 0 maxLength: 1048576 - description: The text sent to the model. + description: A label used to identify the MCP server in tool calls. + credential_id: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL. + transport: + $ref: '#/components/schemas/PersistedMcpTransportConfigParam' + description: The credential-free transport used to connect to the MCP server. + request_metadata: + type: + - object + - 'null' + additionalProperties: {} + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: Metadata included with requests to this MCP server. + allowed_tools: + type: + - array + - 'null' + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: The MCP tools the agent may call. All server tools are allowed when omitted. + required: + type: boolean + default: false + description: Whether this MCP server must initialize before the first turn. Defaults to `false`. + connection_origin: + anyOf: + - $ref: '#/components/schemas/McpConnectionOriginParam' + - type: 'null' + description: Selects where outbound MCP HTTP connections originate. required: - type - - text + - server_label + - transport additionalProperties: false - description: Text input to the model. - InputContentParamInputImage: + description: Tools provided by a remote MCP server without stored credentials. + PersistedAgentToolConfigParamWebSearch: type: object properties: type: type: string enum: - - input_image - default: input_image + - web_search + default: web_search x-stainless-const: true - description: The type of the object. Always `input_image`. - image_url: - type: string - minLength: 0 - maxLength: 1048576 - description: The URL of the image sent to the model. + description: The type of the object. Always `web_search`. + mode: + anyOf: + - $ref: '#/components/schemas/WebSearchModeParam' + - type: 'null' + description: The source used for web search results. Defaults to `live`. + context_size: + anyOf: + - $ref: '#/components/schemas/WebSearchContextSizeParam' + - type: 'null' + description: The amount of search context made available to the model. Defaults to `medium`. + allowed_domains: + type: + - array + - 'null' + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: Domains the search may include. + location: + anyOf: + - $ref: '#/components/schemas/WebSearchLocationParam' + - type: 'null' + description: Approximate location used to localize search results. required: - type - - image_url additionalProperties: false - description: Image input to the model. - InputContentParam: - description: Content included in an input message. - discriminator: - propertyName: type - mapping: - input_text: '#/components/schemas/InputContentParamInputText' - input_image: '#/components/schemas/InputContentParamInputImage' - x-oai-discriminator-values: - - input_text - - input_image - anyOf: - - $ref: '#/components/schemas/InputContentParamInputText' - - $ref: '#/components/schemas/InputContentParamInputImage' - InputMessageParam: + description: Web search. + PersistedAgentToolConfigParamComputerUse: type: object properties: type: type: string enum: - - message - default: message + - computer_use + default: computer_use x-stainless-const: true - description: The type of the input item. Always `message`. - role: + description: The type of the object. Always `computer_use`. + include_screenshots: + type: boolean + default: false + description: Whether computer tool outputs include screenshots. Defaults to `false`. + required: + - type + additionalProperties: false + description: Browser use in an OpenAI-hosted session. + PersistedAgentToolConfigParamAutomations: + type: object + properties: + type: type: string enum: - - user - default: user + - automations + default: automations x-stainless-const: true - description: The role of the message author. Always `user`. - content: - type: array - items: - $ref: '#/components/schemas/InputContentParam' - minItems: 0 - maxItems: 16384 - description: The content of the message. + description: The type of the object. Always `automations`. required: - - role - - content + - type additionalProperties: false - description: A user message submitted to a session. - CreateSessionInputParam: - description: Initial input submitted when creating a session. + description: Lets the agent manage its own scheduled wakeups. + PersistedAgentToolConfigParam: + description: A tool that can be stored on a reusable agent without session credentials. + discriminator: + propertyName: type + mapping: + function: '#/components/schemas/PersistedAgentToolConfigParamFunction' + tool_search: '#/components/schemas/PersistedAgentToolConfigParamToolSearch' + programmatic_tool_calling: '#/components/schemas/PersistedAgentToolConfigParamProgrammaticToolCalling' + mcp: '#/components/schemas/PersistedAgentToolConfigParamMcp' + web_search: '#/components/schemas/PersistedAgentToolConfigParamWebSearch' + computer_use: '#/components/schemas/PersistedAgentToolConfigParamComputerUse' + automations: '#/components/schemas/PersistedAgentToolConfigParamAutomations' + x-oai-discriminator-values: + - function + - tool_search + - programmatic_tool_calling + - mcp + - web_search + - computer_use + - automations anyOf: - - type: string - minLength: 1 - maxLength: 1048576 - - type: array - items: - $ref: '#/components/schemas/InputMessageParam' - minItems: 0 - maxItems: 16384 - CreateAgentSessionParams: + - $ref: '#/components/schemas/PersistedAgentToolConfigParamFunction' + - $ref: '#/components/schemas/PersistedAgentToolConfigParamToolSearch' + - $ref: '#/components/schemas/PersistedAgentToolConfigParamProgrammaticToolCalling' + - $ref: '#/components/schemas/PersistedAgentToolConfigParamMcp' + - $ref: '#/components/schemas/PersistedAgentToolConfigParamWebSearch' + - $ref: '#/components/schemas/PersistedAgentToolConfigParamComputerUse' + - $ref: '#/components/schemas/PersistedAgentToolConfigParamAutomations' + CreateAgentParams: type: object properties: - spend_control: - anyOf: - - $ref: '#/components/schemas/SessionSpendControlParam' - - type: 'null' - description: Optional spending limit in USD cents. Omission or null creates an unlimited session. metadata: type: - object @@ -88857,602 +89953,1060 @@ components: minProperties: 0 maxProperties: 16 description: Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map. - agent: - $ref: '#/components/schemas/SessionAgentConfigParam' - description: Agent configuration. With `agent_id`, supplied fields override the saved agent for this session. Without `agent_id`, `model` is required. - agent_id: + name: + type: + - string + - 'null' + minLength: 0 + maxLength: 128 + description: A human-readable name for the agent. Omission or null leaves the agent unnamed. + model: type: string minLength: 0 - maxLength: 64 - description: The ID of a saved reusable agent. Omit `agent` to use its configuration unchanged. - environment: - $ref: '#/components/schemas/EnvironmentParam' - description: An inline execution environment or a reference to an environment template. - vault_ids: + maxLength: 1048576 + description: The model to use for the agent. The requested model name is preserved. + reasoning: + anyOf: + - $ref: '#/components/schemas/ReasoningParam' + - type: 'null' + description: Configuration for model reasoning. Omission uses the model's default effort. + text: + anyOf: + - $ref: '#/components/schemas/TextParam' + - type: 'null' + description: Configuration for generated text. Defaults to the `text` format and medium verbosity. + service_tier: + anyOf: + - $ref: '#/components/schemas/ServiceTierParam' + - type: 'null' + description: The service tier used for model requests. Defaults to `auto`. + instructions: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: Additional instructions appended to the agent's default base instructions. Omit or set to null to add no custom instructions. + tools: type: - array - 'null' items: - type: string - minLength: 0 - maxLength: 1048576 + $ref: '#/components/schemas/PersistedAgentToolConfigParam' minItems: 0 - maxItems: 16384 - description: The IDs of vaults made available to the session. - input: + maxItems: 2000 + description: Tools available to the agent. Defaults to an empty list. The tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON. + multi_agent: anyOf: - - $ref: '#/components/schemas/CreateSessionInputParam' + - $ref: '#/components/schemas/MultiAgentConfigCurrentParam' - type: 'null' - description: Initial input to submit when the session is created. A string is shorthand for a single user message. Required when `environment.type` is `none`, or when `stream` is `true` for an environment that is not `self_hosted`; optional for self-hosted and non-streaming execution environments. - stream: - type: boolean - default: false - description: Whether to stream session events as server-sent events. Defaults to `false`. + description: Configuration for creating and coordinating subagents. Subagent tools are disabled by default. required: - - environment + - model additionalProperties: false - description: Parameters for creating a Managed Agents session. - SessionEventAgentSessionTurnReasoningSummaryTextDone: + description: Parameters for creating a reusable agent. + UpdateAgentParams: type: object properties: - type: + model: type: string - enum: - - agent.session.turn.reasoning_summary_text.done - default: agent.session.turn.reasoning_summary_text.done - x-stainless-const: true - description: The type of the object. Always `agent.session.turn.reasoning_summary_text.done`. - event_id: + minLength: 0 + maxLength: 1048576 + description: The model to use for the agent. The requested model name is preserved. + reasoning: + anyOf: + - $ref: '#/components/schemas/ReasoningParam' + - type: 'null' + description: Configuration for model reasoning. Omit to keep the current settings; pass `null` to reset to the model's default effort. + text: + anyOf: + - $ref: '#/components/schemas/TextParam' + - type: 'null' + description: Configuration for text generated by the agent. + service_tier: + anyOf: + - $ref: '#/components/schemas/ServiceTierParam' + - type: 'null' + description: The service tier used for model requests. + instructions: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. + multi_agent: + anyOf: + - $ref: '#/components/schemas/MultiAgentConfigCurrentParam' + - type: 'null' + description: Configuration for creating and coordinating subagents. + metadata: + type: + - object + - 'null' + additionalProperties: + type: string + minLength: 0 + maxLength: 512 + propertyNames: + type: string + minLength: 1 + maxLength: 64 + minProperties: 0 + maxProperties: 16 + description: Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. + name: + type: + - string + - 'null' + minLength: 0 + maxLength: 128 + description: A replacement name. Omit to leave unchanged, or pass null to clear it. + tools: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/PersistedAgentToolConfigParam' + minItems: 0 + maxItems: 2000 + description: Replaces the tool list. Omit to leave it unchanged, or pass null to clear it. The replacement must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON. + additionalProperties: false + description: Fields to replace on an existing reusable agent. + DeletedAgentResource: + type: object + properties: + id: type: string minLength: 0 - description: The unique ID of the event. - session_id: + description: The ID of the deleted agent. + object: + type: string + enum: + - agent.deleted + default: agent.deleted + x-stainless-const: true + description: The object type. Always `agent.deleted`. + deleted: + type: boolean + description: Whether the agent was deleted. Always `true`. + required: + - id + - object + - deleted + additionalProperties: false + description: A deleted reusable agent. + EnvironmentTemplateResource: + type: object + properties: + id: type: string minLength: 0 - description: The ID of the session associated with the event. - turn_id: + description: The ID of the reusable environment template. + name: type: - string - 'null' minLength: 0 - description: The ID of the turn associated with the event, when applicable. - item_id: + description: An optional human-readable display name for the template. + object: type: string - minLength: 0 - description: The ID of the reasoning item. - output_index: + enum: + - agent.environment.template + default: agent.environment.template + x-stainless-const: true + description: The object type. Always `agent.environment.template`. + created_at: type: integer format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the item in the turn output. - summary_index: + description: The Unix timestamp, in seconds, when the template was created. + updated_at: type: integer format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the summary content part. - text: - type: string - minLength: 0 - description: The complete reasoning summary text. + description: The Unix timestamp, in seconds, when the template was last updated. + packages: + $ref: '#/components/schemas/EnvironmentPackagesResource' + description: Packages installed in each fresh OpenAI-hosted environment. + network: + $ref: '#/components/schemas/NetworkPolicyResource' + description: Runtime network access for each OpenAI-hosted environment. + desktop: + $ref: '#/components/schemas/DesktopResource' + description: Desktop configuration for each OpenAI-hosted environment. + capability_directories: + type: array + items: + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: Directories that expose capabilities to the agent. + skills: + type: array + items: + $ref: '#/components/schemas/HostedTemplateSkillResource' + minItems: 0 + maxItems: 200 + description: Safe skill metadata, preserving unresolved version selectors. + plugins: + type: array + items: + $ref: '#/components/schemas/HostedPluginResource' + minItems: 0 + maxItems: 32 + description: Safe plugin metadata, excluding inline archive contents. + files: + type: array + items: + $ref: '#/components/schemas/HostedTemplateFileResource' + minItems: 0 + maxItems: 50 + description: Safe file metadata, excluding contents and session-scoped file IDs. required: - - type - - event_id - - session_id - - turn_id - - item_id - - output_index - - summary_index - - text + - id + - name + - object + - created_at + - updated_at + - packages + - network + - capability_directories + - skills + - plugins + - files additionalProperties: false - description: Emitted when a reasoning summary content part is complete. - SessionErrorResource: + description: Reusable configuration that provisions a fresh OpenAI-hosted environment for each session. + EnvironmentTemplateListResource: type: object properties: - type: + object: type: string - minLength: 0 - description: The error type. - code: + enum: + - list + default: list + x-stainless-const: true + description: The object type, which is always `list`. + data: + type: array + items: + $ref: '#/components/schemas/EnvironmentTemplateResource' + minItems: 0 + maxItems: 2000 + description: The resources returned in this page, in the requested sort order. + first_id: type: - string - 'null' minLength: 0 - description: The machine-readable error code, if any. - message: - type: string - minLength: 0 - description: A customer-safe explanation of the error. - param: + description: The ID of the first resource in `data`, or `null` if the page is empty. + last_id: type: - string - 'null' minLength: 0 - description: The request parameter associated with the error, if any. + description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. + has_more: + type: boolean + description: Whether there are more resources to retrieve after this page. required: - - type - - code - - message - - param + - object + - data + - first_id + - last_id + - has_more additionalProperties: false - description: An error payload with the same public fields as Responses API streaming errors. - SessionEventError: + description: A page of Agents API resources, with IDs for retrieving additional pages. + CreateEnvironmentTemplateParams: type: object properties: - type: - type: string - enum: - - error - default: error - x-stainless-const: true - description: The type of the object. Always `error`. - event_id: - type: string - minLength: 0 - description: The unique ID of the event. - session_id: - type: string - minLength: 0 - description: The ID of the session associated with the event. - error: - $ref: '#/components/schemas/SessionErrorResource' - description: The error that occurred. - required: - - type - - event_id - - session_id - - error + packages: + anyOf: + - $ref: '#/components/schemas/EnvironmentPackagesParam' + - type: 'null' + description: Packages to install in the environment. Defaults to empty package lists. + setup_commands: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/SetupCommandParam' + minItems: 0 + maxItems: 16 + description: Ordered, confidential setup commands. Command bodies are never returned. + network: + anyOf: + - $ref: '#/components/schemas/NetworkPolicyParam' + - type: 'null' + description: Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled. + desktop: + anyOf: + - $ref: '#/components/schemas/DesktopParam' + - type: 'null' + description: Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled. + x-openai-go-legacy-bool-fields: + - enabled + env: + type: + - object + - 'null' + additionalProperties: + type: string + minLength: 0 + maxLength: 1048576 + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: Environment variables made available to the agent. + capability_directories: + type: + - array + - 'null' + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: Directories that contain capabilities exposed to the agent. Defaults to an empty list. + skills: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/HostedSkillParam' + minItems: 0 + maxItems: 200 + description: Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. + plugins: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/HostedPluginParam' + minItems: 0 + maxItems: 32 + description: Plugins provided as inline ZIP archives. Defaults to an empty list. + files: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/HostedEnvironmentFileParam' + minItems: 0 + maxItems: 50 + description: Files available before the agent starts. Defaults to an empty list. + name: + type: + - string + - 'null' + minLength: 1 + maxLength: 256 + description: An optional human-readable display name for the template. additionalProperties: false - description: Emitted when a turn or session fails. - x-oaiMeta: - example: - type: error - event_id: event_123 - session_id: sess_123 - error: - type: server_error - code: null - message: The session failed due to an internal server error. - param: null - SessionEnvironmentStatusResource: - type: string - enum: - - pending - - ready - - connected - - disconnected - - suspended - - expired - - failed - x-enumDescriptions: - - The environment is being prepared. - - The environment is ready to connect. - - The environment is connected. - - The environment is disconnected. - - The environment is stopped and can be resumed from its private checkpoint. - - The environment and its private checkpoint have expired. - - The environment failed to connect. - description: The connection status of a session environment. - SessionEnvironmentErrorResource: + description: Parameters for creating a reusable, project-scoped OpenAI-hosted environment template. + UpdateEnvironmentTemplateParams: type: object properties: - type: - type: string - minLength: 0 - description: The error type. - code: - type: string - minLength: 0 - description: A machine-readable error code. - message: - type: string - minLength: 0 - description: A human-readable error message. - required: - - type - - code - - message + name: + type: + - string + - 'null' + minLength: 1 + maxLength: 256 + description: A replacement human-readable display name, or `null` to clear the name. + packages: + anyOf: + - $ref: '#/components/schemas/EnvironmentPackagesParam' + - type: 'null' + description: Packages installed before the runtime network policy applies. + setup_commands: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/SetupCommandParam' + minItems: 0 + maxItems: 16 + description: Replacement confidential setup commands, never included in returned resources. + network: + anyOf: + - $ref: '#/components/schemas/NetworkPolicyParam' + - type: 'null' + description: Network access available after setup completes. Omit to preserve the current policy, or pass `null` to reset to the default policy. + desktop: + anyOf: + - $ref: '#/components/schemas/DesktopParam' + - type: 'null' + description: Replacement desktop configuration, or null to disable the desktop. + x-openai-go-legacy-bool-fields: + - enabled + env: + type: + - object + - 'null' + additionalProperties: + type: string + minLength: 0 + maxLength: 1048576 + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: Replacement confidential environment values. + capability_directories: + type: + - array + - 'null' + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: Directories that expose capabilities to the agent. + skills: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/HostedSkillParam' + minItems: 0 + maxItems: 200 + description: Replacement skill configuration installed for each new session. + plugins: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/HostedPluginParam' + minItems: 0 + maxItems: 32 + description: Replacement plugin configuration installed for each new session. + files: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/HostedEnvironmentFileParam' + minItems: 0 + maxItems: 50 + description: Replacement file configuration materialized for each new session. additionalProperties: false - description: An error reported while preparing a session environment. - SessionEnvironmentStateResource: + description: Fields to replace on an existing reusable OpenAI-hosted environment template. + DeletedEnvironmentTemplateResource: type: object properties: id: type: string minLength: 0 - description: The public ID of the environment. - type: + description: The ID of the deleted environment template. + object: type: string - minLength: 0 - description: The environment type. - status: - $ref: '#/components/schemas/SessionEnvironmentStatusResource' - description: The environment's connection status. - error: - anyOf: - - $ref: '#/components/schemas/SessionEnvironmentErrorResource' - - type: 'null' - description: The error reported while preparing the environment, if any. + enum: + - agent.environment.template.deleted + default: agent.environment.template.deleted + x-stainless-const: true + description: The object type. Always `agent.environment.template.deleted`. + deleted: + type: boolean + description: Whether the environment template was deleted. Always `true`. required: - id - - type - - status - - error + - object + - deleted additionalProperties: false - description: The current state of a session environment. - SessionEventAgentSessionEnvironmentReady: + description: A deleted reusable environment template. + SessionStatusResource: + type: string + enum: + - idle + - in_progress + - requires_action + - failed + x-enumDescriptions: + - The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. + - The session is processing a turn. + - The session is waiting for one or more required actions. + - The session failed. + description: The current status of a session. + ComputerUseApprovalRequestKindResourceBrowserAuthentication: type: object properties: type: type: string enum: - - agent.session.environment.ready - default: agent.session.environment.ready + - browser_authentication + default: browser_authentication x-stainless-const: true - description: The type of the object. Always `agent.session.environment.ready`. - event_id: - type: string - minLength: 0 - description: The unique ID of the event. - session_id: - type: string + description: The type of the object. Always `browser_authentication`. + reason: + type: + - string + - 'null' minLength: 0 - description: The ID of the session associated with the event. - turn_id: + description: Why the agent needs the user to sign in. + credential_origin: type: - string - 'null' minLength: 0 - description: The ID of the turn associated with the event, when applicable. - environment: - $ref: '#/components/schemas/SessionEnvironmentStateResource' - description: The current environment state. + description: The registered form or frame origin where values will be entered. + fields: + type: array + items: + $ref: '#/components/schemas/BrowserAuthenticationFieldResource' + minItems: 0 + maxItems: 2000 + description: Controls to render. All submitted values are sensitive. + options: + type: array + items: + $ref: '#/components/schemas/BrowserAuthenticationOptionResource' + minItems: 0 + maxItems: 2000 + description: Sign-in methods. Empty for a plain form. required: - type - - event_id - - session_id - - turn_id - - environment + - reason + - credential_origin + - fields + - options additionalProperties: false - description: Emitted when a hosted session environment is ready to connect. - SessionEventAgentSessionEnvironmentSuspended: + description: A registered form awaiting the application's response. + ComputerUseApprovalRequestKindResourceBrowserOriginAccess: type: object properties: type: type: string enum: - - agent.session.environment.suspended - default: agent.session.environment.suspended + - browser_origin_access + default: browser_origin_access x-stainless-const: true - description: The type of the object. Always `agent.session.environment.suspended`. - event_id: - type: string - minLength: 0 - description: The unique ID of the event. - session_id: - type: string - minLength: 0 - description: The ID of the session associated with the event. - turn_id: + description: The type of the object. Always `browser_origin_access`. + reason: type: - string - 'null' minLength: 0 - description: The ID of the turn associated with the event, when applicable. - environment: - $ref: '#/components/schemas/SessionEnvironmentStateResource' - description: The current environment state. + description: The browser's explanation for this request, or null when unavailable. + origin: + type: string + minLength: 0 + description: The origin the browser needs permission to access. required: - type - - event_id - - session_id - - turn_id - - environment + - reason + - origin additionalProperties: false - description: Emitted after an idle hosted session environment is checkpointed and stopped. - SessionEventAgentSessionEnvironmentExpired: + description: A browser origin awaiting the application's approval decision. + ComputerUseApprovalRequestKindResource: + x-oai-discriminator-values: + - browser_authentication + - browser_origin_access + discriminator: + propertyName: type + mapping: + browser_authentication: '#/components/schemas/ComputerUseApprovalRequestKindResourceBrowserAuthentication' + browser_origin_access: '#/components/schemas/ComputerUseApprovalRequestKindResourceBrowserOriginAccess' + anyOf: + - $ref: '#/components/schemas/ComputerUseApprovalRequestKindResourceBrowserAuthentication' + - $ref: '#/components/schemas/ComputerUseApprovalRequestKindResourceBrowserOriginAccess' + SessionRequiredActionResourceComputerUseApprovalRequest: type: object properties: type: type: string enum: - - agent.session.environment.expired - default: agent.session.environment.expired + - computer_use_approval_request + default: computer_use_approval_request x-stainless-const: true - description: The type of the object. Always `agent.session.environment.expired`. - event_id: + description: The type of the object. Always `computer_use_approval_request`. + turn_id: type: string minLength: 0 - description: The unique ID of the event. - session_id: + description: The turn that requested approval. + request_id: type: string minLength: 0 - description: The ID of the session associated with the event. - turn_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the turn associated with the event, when applicable. - environment: - $ref: '#/components/schemas/SessionEnvironmentStateResource' - description: The current environment state. + description: The registered request ID to echo when responding. + request: + $ref: '#/components/schemas/ComputerUseApprovalRequestKindResource' + description: The information needed to render the request. required: - type - - event_id - - session_id - turn_id - - environment + - request_id + - request additionalProperties: false - description: Emitted after a suspended hosted session environment and its checkpoint expire. - SessionEventAgentSessionEnvironmentReset: + description: Respond to a computer-use request. + SessionRequiredActionResourceFunctionCall: type: object properties: type: type: string enum: - - agent.session.environment.reset - default: agent.session.environment.reset + - function_call + default: function_call x-stainless-const: true - description: The type of the object. Always `agent.session.environment.reset`. - event_id: + description: The type of the object. Always `function_call`. + turn_id: type: string minLength: 0 - description: The unique ID of the event. - session_id: + description: The ID of the turn that requested the function call. + call_id: type: string minLength: 0 - description: The ID of the session associated with the event. - turn_id: - type: - - string - - 'null' - minLength: 0 - description: The associated turn, when applicable. - environment_id: + description: The ID to include when submitting the function result. + name: type: string minLength: 0 - description: The stable environment ID, retained across sandbox replacements. - reset_count: - type: integer - format: int64 - minimum: 0 - description: Monotonically increasing reset number. Repeated notifications share this number. + description: The function name. + arguments: + description: The arguments supplied by the model. required: - type - - event_id - - session_id - turn_id - - environment_id - - reset_count + - call_id + - name + - arguments additionalProperties: false - description: Emitted after a hosted sandbox is replaced. Conversation history survives; changes to the previous sandbox's files and processes do not. - SessionEventAgentOutputCommandExecutionOutputDelta: + description: Run a function tool and submit its result. + SessionRequiredActionResourceEnvironmentConnection: type: object properties: type: type: string enum: - - agent.output.command_execution_output.delta - default: agent.output.command_execution_output.delta + - environment_connection + default: environment_connection x-stainless-const: true - description: The type of the object. Always `agent.output.command_execution_output.delta`. - event_id: + description: The type of the object. Always `environment_connection`. + environment_id: type: string minLength: 0 - description: The unique ID of the event. - session_id: + description: The ID of the environment to reconnect. + required: + - type + - environment_id + additionalProperties: false + description: Reconnect a session environment. + SessionRequiredActionResource: + description: An action that must be completed before a session can continue. + discriminator: + propertyName: type + mapping: + computer_use_approval_request: '#/components/schemas/SessionRequiredActionResourceComputerUseApprovalRequest' + function_call: '#/components/schemas/SessionRequiredActionResourceFunctionCall' + environment_connection: '#/components/schemas/SessionRequiredActionResourceEnvironmentConnection' + x-oai-discriminator-values: + - computer_use_approval_request + - function_call + - environment_connection + anyOf: + - $ref: '#/components/schemas/SessionRequiredActionResourceComputerUseApprovalRequest' + - $ref: '#/components/schemas/SessionRequiredActionResourceFunctionCall' + - $ref: '#/components/schemas/SessionRequiredActionResourceEnvironmentConnection' + SessionAgentResource: + type: object + properties: + id: type: string minLength: 0 - description: The ID of the session associated with the event. - turn_id: + description: The ID of the agent. + name: type: - string - 'null' minLength: 0 - description: The ID of the turn associated with the event, when applicable. - item_id: + description: The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. + model: type: string minLength: 0 - description: The ID of the command execution item. - output_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the item in the turn output. - delta: - type: string + description: The model used by the agent. + reasoning: + $ref: '#/components/schemas/ReasoningResource' + description: The agent's reasoning configuration. + text: + $ref: '#/components/schemas/TextResource' + description: Configuration for text generated by the agent. + service_tier: + $ref: '#/components/schemas/ServiceTierResource' + description: The effective service-tier policy for model requests. Defaults to `auto`. + instructions: + type: + - string + - 'null' minLength: 0 - description: The output text that was appended. + description: Custom instructions appended to the agent's default base instructions. + tools: + type: array + items: + $ref: '#/components/schemas/AgentToolResource' + minItems: 0 + maxItems: 2000 + description: Tools available to the agent. + multi_agent: + $ref: '#/components/schemas/MultiAgentConfigResource' + description: Configuration for creating and coordinating subagents. required: - - type - - event_id - - session_id - - turn_id - - item_id - - output_index - - delta + - id + - name + - model + - reasoning + - text + - service_tier + - instructions + - tools + - multi_agent additionalProperties: false - description: Emitted when command execution produces an output delta. - SessionEventAgentSessionCreated: + description: The effective agent configuration for a session. + EnvironmentResourceNone: type: object properties: type: type: string enum: - - agent.session.created - default: agent.session.created + - none + default: none x-stainless-const: true - description: The type of the object. Always `agent.session.created`. - event_id: - type: string - minLength: 0 - description: The unique ID of the event. - session: - $ref: '#/components/schemas/SessionResource' - description: The session that was created. + description: The type of the object. Always `none`. required: - type - - event_id - - session additionalProperties: false - description: Emitted when a session is created. - SessionEventAgentSessionTurnCreated: + description: The session talks to CCA without selecting or provisioning an execution environment. + EnvironmentResourceOpenaiHosted: type: object properties: type: type: string enum: - - agent.session.turn.created - default: agent.session.turn.created + - openai_hosted + default: openai_hosted x-stainless-const: true - description: The type of the object. Always `agent.session.turn.created`. - event_id: - type: string - minLength: 0 - description: The unique ID of the event. - session_id: - type: string - minLength: 0 - description: The ID of the session associated with the event. - turn_id: + description: The type of the object. Always `openai_hosted`. + id: type: string minLength: 0 - description: The ID of the turn associated with the event. - turn: - $ref: '#/components/schemas/TurnResource' - description: The turn at the time it was created. + description: The public ID of the environment. + container_size: + anyOf: + - $ref: '#/components/schemas/ContainerSizeResource' + - type: 'null' + description: The effective CPU and memory tier, or null when unknown or outside the public tiers. + x-stainless-skip: + - cli + packages: + $ref: '#/components/schemas/EnvironmentPackagesResource' + description: Packages installed in the environment. + network: + $ref: '#/components/schemas/NetworkPolicyResource' + description: The effective network access policy for the environment. + desktop: + $ref: '#/components/schemas/DesktopResource' + description: The effective desktop configuration. + capability_directories: + type: array + items: + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: Directories that contain capabilities exposed to the agent. + skills: + type: array + items: + $ref: '#/components/schemas/HostedSkillResource' + minItems: 0 + maxItems: 2000 + description: Skills installed in the environment, excluding their archive contents. + plugins: + type: array + items: + $ref: '#/components/schemas/HostedPluginResource' + minItems: 0 + maxItems: 2000 + description: Plugins installed in the environment, excluding their archive contents. + files: + type: array + items: + $ref: '#/components/schemas/HostedEnvironmentFileResource' + minItems: 0 + maxItems: 50 + description: Files available in the environment, excluding their contents. required: - type - - event_id - - session_id - - turn_id - - turn + - id + - packages + - network + - capability_directories + - skills + - plugins + - files additionalProperties: false - description: Emitted when a turn is created. - SessionEventAgentSessionTurnInProgress: + description: An environment hosted by OpenAI. + EnvironmentResourceSelfHosted: type: object properties: type: type: string enum: - - agent.session.turn.in_progress - default: agent.session.turn.in_progress + - self_hosted + default: self_hosted x-stainless-const: true - description: The type of the object. Always `agent.session.turn.in_progress`. - event_id: + description: The type of the object. Always `self_hosted`. + remote_url: type: string minLength: 0 - description: The unique ID of the event. - session_id: + description: Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. + id: type: string minLength: 0 - description: The ID of the session associated with the event. - turn_id: + description: The public ID of the environment. + workspace_directory: type: string minLength: 0 - description: The ID of the turn associated with the event. - turn: - $ref: '#/components/schemas/TurnResource' - description: The turn at the time it started running. + description: The absolute project directory inside the environment. Defaults to `/workspace`. + capability_directories: + type: array + items: + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: Directories that contain capabilities exposed to the agent. required: - type - - event_id - - session_id - - turn_id - - turn + - remote_url + - id + - workspace_directory + - capability_directories additionalProperties: false - description: Emitted when a turn starts running. - SessionEventAgentSessionTurnCompleted: + description: An environment hosted by the application. + EnvironmentResource: + description: The execution environment for a session. + discriminator: + propertyName: type + mapping: + none: '#/components/schemas/EnvironmentResourceNone' + openai_hosted: '#/components/schemas/EnvironmentResourceOpenaiHosted' + self_hosted: '#/components/schemas/EnvironmentResourceSelfHosted' + x-oai-discriminator-values: + - none + - openai_hosted + - self_hosted + anyOf: + - $ref: '#/components/schemas/EnvironmentResourceNone' + - $ref: '#/components/schemas/EnvironmentResourceOpenaiHosted' + - $ref: '#/components/schemas/EnvironmentResourceSelfHosted' + SessionResource: type: object properties: - type: - type: string - enum: - - agent.session.turn.completed - default: agent.session.turn.completed - x-stainless-const: true - description: The type of the object. Always `agent.session.turn.completed`. - event_id: - type: string - minLength: 0 - description: The unique ID of the event. - session_id: + metadata: + type: object + additionalProperties: + type: string + minLength: 0 + propertyNames: + type: string + minLength: 0 + minProperties: 0 + description: Custom string key-value pairs attached to the session. + id: type: string minLength: 0 - description: The ID of the session associated with the event. - turn_id: + description: The ID of the session. + object: type: string + enum: + - agent.session + default: agent.session + x-stainless-const: true + description: The object type. Always `agent.session`. + created_at: + type: integer + format: int64 + description: The Unix timestamp, in seconds, when the session was created. + last_active_at: + type: integer + format: int64 + description: The Unix timestamp, in seconds, when the session was last active. + status: + $ref: '#/components/schemas/SessionStatusResource' + description: The current status of the session. + required_actions: + type: array + items: + $ref: '#/components/schemas/SessionRequiredActionResource' + minItems: 0 + maxItems: 2000 + description: Actions that must be completed before the session can continue. + error: + description: The error that caused the session to fail, if any. + type: + - string + - 'null' minLength: 0 - description: The ID of the turn associated with the event. - turn: - $ref: '#/components/schemas/TurnResource' - description: The completed turn. + agent: + $ref: '#/components/schemas/SessionAgentResource' + description: The agent running in the session. + environment: + $ref: '#/components/schemas/EnvironmentResource' + description: The execution environment for the session. + vault_ids: + type: array + items: + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: The IDs of vaults made available to the session. usage: anyOf: - $ref: '#/components/schemas/TokenUsageResource' - type: 'null' - description: Token usage by the root agent during the turn, when available. + description: Best-effort token usage for the session, or null if unknown. Recorded usage may change. + spend_control: + $ref: '#/components/schemas/SessionSpendControlResource' + description: Configured spending limit and best-effort consumption, in USD cents. Unlimited sessions omit this object. required: - - type - - event_id - - session_id - - turn_id - - turn + - metadata + - id + - object + - created_at + - last_active_at + - status + - required_actions + - error + - agent + - environment + - vault_ids - usage additionalProperties: false - description: Emitted when a turn completes. - SessionEventAgentSessionTurnFailed: + description: A Managed Agents session. + SessionListResource: type: object properties: - type: + object: type: string enum: - - agent.session.turn.failed - default: agent.session.turn.failed + - list + default: list x-stainless-const: true - description: The type of the object. Always `agent.session.turn.failed`. - event_id: - type: string + description: The object type, which is always `list`. + data: + type: array + items: + $ref: '#/components/schemas/SessionResource' + minItems: 0 + maxItems: 2000 + description: The resources returned in this page, in the requested sort order. + first_id: + type: + - string + - 'null' minLength: 0 - description: The unique ID of the event. - session_id: - type: string + description: The ID of the first resource in `data`, or `null` if the page is empty. + last_id: + type: + - string + - 'null' minLength: 0 - description: The ID of the session associated with the event. - turn_id: + description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. + has_more: + type: boolean + description: Whether there are more resources to retrieve after this page. + required: + - object + - data + - first_id + - last_id + - has_more + additionalProperties: false + description: A page of Agents API resources, with IDs for retrieving additional pages. + CreateSessionInputParam: + description: Initial input submitted when creating a session. + anyOf: + - type: string + minLength: 1 + maxLength: 1048576 + - type: array + items: + $ref: '#/components/schemas/InputMessageParam' + minItems: 0 + maxItems: 16384 + CreateAgentSessionParams: + type: object + properties: + metadata: + type: + - object + - 'null' + additionalProperties: + type: string + minLength: 0 + maxLength: 512 + propertyNames: + type: string + minLength: 1 + maxLength: 64 + minProperties: 0 + maxProperties: 16 + description: Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map. + agent: + $ref: '#/components/schemas/SessionAgentConfigParam' + description: Agent configuration. With `agent_id`, supplied fields override the saved agent for this session. Without `agent_id`, `model` is required. + agent_id: type: string minLength: 0 - description: The ID of the turn associated with the event. - turn: - $ref: '#/components/schemas/TurnResource' - description: The failed turn. - usage: + maxLength: 64 + description: The ID of a saved reusable agent. Omit `agent` to use its configuration unchanged. + environment: + $ref: '#/components/schemas/EnvironmentParam' + description: An inline execution environment or a reference to an environment template. + vault_ids: + type: + - array + - 'null' + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: The IDs of vaults made available to the session. + input: anyOf: - - $ref: '#/components/schemas/TokenUsageResource' + - $ref: '#/components/schemas/CreateSessionInputParam' - type: 'null' - description: Token usage by the root agent during the turn, when available. + description: Initial input to submit when the session is created. A string is shorthand for a single user message. Required when `environment.type` is `none`, or when `stream` is `true` for an environment that is not `self_hosted`; optional for self-hosted and non-streaming execution environments. + stream: + type: boolean + default: false + description: Whether to stream session events as server-sent events. Defaults to `false`. + spend_control: + anyOf: + - $ref: '#/components/schemas/SessionSpendControlParam' + - type: 'null' + description: Optional spending limit in USD cents. Omission or null creates an unlimited session. required: - - type - - event_id - - session_id - - turn_id - - turn - - usage + - environment additionalProperties: false - description: Emitted when a turn fails. - SessionEventAgentSessionTurnCancelled: + description: Parameters for creating a Managed Agents session. + SessionEventAgentSessionTurnReasoningSummaryTextDelta: type: object properties: type: type: string enum: - - agent.session.turn.cancelled - default: agent.session.turn.cancelled + - agent.session.turn.reasoning_summary_text.delta + default: agent.session.turn.reasoning_summary_text.delta x-stainless-const: true - description: The type of the object. Always `agent.session.turn.cancelled`. + description: The type of the object. Always `agent.session.turn.reasoning_summary_text.delta`. event_id: type: string minLength: 0 @@ -89462,36 +91016,52 @@ components: minLength: 0 description: The ID of the session associated with the event. turn_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the turn associated with the event, when applicable. + item_id: type: string minLength: 0 - description: The ID of the turn associated with the event. - turn: - $ref: '#/components/schemas/TurnResource' - description: The cancelled turn. - usage: - anyOf: - - $ref: '#/components/schemas/TokenUsageResource' - - type: 'null' - description: Token usage by the root agent during the turn, when available. + description: The ID of the reasoning item. + output_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the item in the turn output. + summary_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the summary content part. + delta: + type: string + minLength: 0 + description: The summary text that was appended. required: - type - event_id - session_id - turn_id - - turn - - usage + - item_id + - output_index + - summary_index + - delta additionalProperties: false - description: Emitted when a turn is cancelled. - SessionEventAgentSessionTurnItemAdded: + description: Emitted when text is appended to a reasoning summary. + SessionEventAgentSessionTurnReasoningSummaryPartDone: type: object properties: type: type: string enum: - - agent.session.turn.item.added - default: agent.session.turn.item.added + - agent.session.turn.reasoning_summary_part.done + default: agent.session.turn.reasoning_summary_part.done x-stainless-const: true - description: The type of the object. Always `agent.session.turn.item.added`. + description: The type of the object. Always `agent.session.turn.reasoning_summary_part.done`. event_id: type: string minLength: 0 @@ -89506,128 +91076,245 @@ components: - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. + item_id: + type: string + minLength: 0 + description: The ID of the reasoning item. output_index: - type: - - integer - - 'null' + type: integer format: int64 minimum: 0 maximum: 4294967295 - description: The index of the item in the turn output, when the item is agent output. - item: - $ref: '#/components/schemas/SessionTurnItemResource' - description: The item that was added. + description: The index of the item in the turn output. + summary_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the summary part. + part: + $ref: '#/components/schemas/SummaryTextResource' + description: The completed summary part. + status: + type: + - string + - 'null' + enum: + - incomplete + - null + description: Present as `incomplete` when summary generation was interrupted. + x-stainless-const: true required: - type - event_id - session_id - turn_id + - item_id - output_index - - item + - summary_index + - part + - status additionalProperties: false - description: Emitted when an item is added to a turn. - SessionEventAgentSessionIdle: + description: Emitted when a reasoning summary part is complete. + SessionEventAgentSessionTurnReasoningSummaryTextDone: type: object properties: type: type: string enum: - - agent.session.idle - default: agent.session.idle + - agent.session.turn.reasoning_summary_text.done + default: agent.session.turn.reasoning_summary_text.done x-stainless-const: true - description: The type of the object. Always `agent.session.idle`. + description: The type of the object. Always `agent.session.turn.reasoning_summary_text.done`. event_id: type: string minLength: 0 description: The unique ID of the event. - session: - $ref: '#/components/schemas/SessionResource' - description: The session that became idle. + session_id: + type: string + minLength: 0 + description: The ID of the session associated with the event. + turn_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the turn associated with the event, when applicable. + item_id: + type: string + minLength: 0 + description: The ID of the reasoning item. + output_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the item in the turn output. + summary_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the summary content part. + text: + type: string + minLength: 0 + description: The complete reasoning summary text. required: - type - event_id - - session + - session_id + - turn_id + - item_id + - output_index + - summary_index + - text additionalProperties: false - description: Emitted when a session becomes idle. - SessionEventAgentSessionInProgress: + description: Emitted when a reasoning summary content part is complete. + SessionErrorResource: type: object properties: type: type: string - enum: - - agent.session.in_progress - default: agent.session.in_progress - x-stainless-const: true - description: The type of the object. Always `agent.session.in_progress`. - event_id: + minLength: 0 + description: The error type. + code: + type: + - string + - 'null' + minLength: 0 + description: The machine-readable error code, if any. + message: type: string minLength: 0 - description: The unique ID of the event. - session: - $ref: '#/components/schemas/SessionResource' - description: The session that started processing. + description: A customer-safe explanation of the error. + param: + type: + - string + - 'null' + minLength: 0 + description: The request parameter associated with the error, if any. required: - type - - event_id - - session + - code + - message + - param additionalProperties: false - description: Emitted when a session starts processing a turn. - SessionEventAgentSessionRequiresAction: + description: An error payload with the same public fields as Responses API streaming errors. + SessionEventError: type: object properties: type: type: string enum: - - agent.session.requires_action - default: agent.session.requires_action + - error + default: error x-stainless-const: true - description: The type of the object. Always `agent.session.requires_action`. + description: The type of the object. Always `error`. event_id: type: string minLength: 0 description: The unique ID of the event. - session: - $ref: '#/components/schemas/SessionResource' - description: The session and its current required actions. + session_id: + type: string + minLength: 0 + description: The ID of the session associated with the event. + error: + $ref: '#/components/schemas/SessionErrorResource' + description: The error that occurred. required: - type - event_id - - session + - session_id + - error additionalProperties: false - description: Emitted when a session is waiting for one or more required actions. - SessionEventAgentSessionFailed: + description: Emitted when a turn or session fails. + x-oaiMeta: + example: + type: error + event_id: event_123 + session_id: sess_123 + error: + type: server_error + code: null + message: The session failed due to an internal server error. + param: null + SessionEnvironmentStatusResource: + type: string + enum: + - pending + - ready + - connected + - disconnected + - suspended + - expired + - failed + x-enumDescriptions: + - The environment is being prepared. + - The environment is ready to connect. + - The environment is connected. + - The environment is disconnected. + - The environment is stopped and can be resumed from its private checkpoint. + - The environment and its private checkpoint have expired. + - The environment failed to connect. + description: The connection status of a session environment. + SessionEnvironmentErrorResource: type: object properties: type: type: string - enum: - - agent.session.failed - default: agent.session.failed - x-stainless-const: true - description: The type of the object. Always `agent.session.failed`. - event_id: + minLength: 0 + description: The error type. + code: type: string minLength: 0 - description: The unique ID of the event. - session: - $ref: '#/components/schemas/SessionResource' - description: The failed session. + description: A machine-readable error code. + message: + type: string + minLength: 0 + description: A human-readable error message. required: - type - - event_id - - session + - code + - message additionalProperties: false - description: Emitted when a session fails. - SessionEventAgentSessionEnvironmentPending: + description: An error reported while preparing a session environment. + SessionEnvironmentStateResource: + type: object + properties: + id: + type: string + minLength: 0 + description: The public ID of the environment. + type: + type: string + minLength: 0 + description: The environment type. + status: + $ref: '#/components/schemas/SessionEnvironmentStatusResource' + description: The environment's connection status. + error: + anyOf: + - $ref: '#/components/schemas/SessionEnvironmentErrorResource' + - type: 'null' + description: The error reported while preparing the environment, if any. + required: + - id + - type + - status + - error + additionalProperties: false + description: The current state of a session environment. + SessionEventAgentSessionEnvironmentReady: type: object properties: type: type: string enum: - - agent.session.environment.pending - default: agent.session.environment.pending + - agent.session.environment.ready + default: agent.session.environment.ready x-stainless-const: true - description: The type of the object. Always `agent.session.environment.pending`. + description: The type of the object. Always `agent.session.environment.ready`. event_id: type: string minLength: 0 @@ -89652,17 +91339,17 @@ components: - turn_id - environment additionalProperties: false - description: Emitted while a session environment is being prepared. - SessionEventAgentSessionEnvironmentConnected: + description: Emitted when a hosted session environment is ready to connect. + SessionEventAgentSessionEnvironmentSuspended: type: object properties: type: type: string enum: - - agent.session.environment.connected - default: agent.session.environment.connected + - agent.session.environment.suspended + default: agent.session.environment.suspended x-stainless-const: true - description: The type of the object. Always `agent.session.environment.connected`. + description: The type of the object. Always `agent.session.environment.suspended`. event_id: type: string minLength: 0 @@ -89687,17 +91374,17 @@ components: - turn_id - environment additionalProperties: false - description: Emitted when a session environment connects. - SessionEventAgentSessionEnvironmentDisconnected: + description: Emitted after an idle hosted session environment is checkpointed and stopped. + SessionEventAgentSessionEnvironmentExpired: type: object properties: type: type: string enum: - - agent.session.environment.disconnected - default: agent.session.environment.disconnected + - agent.session.environment.expired + default: agent.session.environment.expired x-stainless-const: true - description: The type of the object. Always `agent.session.environment.disconnected`. + description: The type of the object. Always `agent.session.environment.expired`. event_id: type: string minLength: 0 @@ -89722,17 +91409,17 @@ components: - turn_id - environment additionalProperties: false - description: Emitted when a session environment disconnects. - SessionEventAgentSessionEnvironmentFailed: + description: Emitted after a suspended hosted session environment and its checkpoint expire. + SessionEventAgentSessionEnvironmentReset: type: object properties: type: type: string enum: - - agent.session.environment.failed - default: agent.session.environment.failed + - agent.session.environment.reset + default: agent.session.environment.reset x-stainless-const: true - description: The type of the object. Always `agent.session.environment.failed`. + description: The type of the object. Always `agent.session.environment.reset`. event_id: type: string minLength: 0 @@ -89746,196 +91433,139 @@ components: - string - 'null' minLength: 0 - description: The ID of the turn associated with the event, when applicable. - environment: - $ref: '#/components/schemas/SessionEnvironmentStateResource' - description: The current environment state. + description: The associated turn, when applicable. + environment_id: + type: string + minLength: 0 + description: The stable environment ID, retained across sandbox replacements. + reset_count: + type: integer + format: int64 + minimum: 0 + description: Monotonically increasing reset number. Repeated notifications share this number. required: - type - event_id - session_id - turn_id - - environment + - environment_id + - reset_count additionalProperties: false - description: Emitted when a session environment fails. - SessionEventAgentSessionSubagentCreated: + description: Emitted after a hosted sandbox is replaced. Conversation history survives; changes to the previous sandbox's files and processes do not. + SessionEventAgentOutputCommandExecutionOutputDelta: type: object properties: type: type: string enum: - - agent.session.subagent.created - default: agent.session.subagent.created + - agent.output.command_execution_output.delta + default: agent.output.command_execution_output.delta x-stainless-const: true - description: The type of the object. Always `agent.session.subagent.created`. + description: The type of the object. Always `agent.output.command_execution_output.delta`. event_id: type: string minLength: 0 description: The unique ID of the event. - subagent: - $ref: '#/components/schemas/SubagentResource' - description: The subagent that was created. + session_id: + type: string + minLength: 0 + description: The ID of the session associated with the event. + turn_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the turn associated with the event, when applicable. + item_id: + type: string + minLength: 0 + description: The ID of the command execution item. + output_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the item in the turn output. + delta: + type: string + minLength: 0 + description: The output text that was appended. required: - type - event_id - - subagent + - session_id + - turn_id + - item_id + - output_index + - delta additionalProperties: false - description: Emitted when a subagent is created. - SessionEventAgentSessionSubagentActive: + description: Emitted when command execution produces an output delta. + SessionEventAgentSessionCreated: type: object properties: type: type: string enum: - - agent.session.subagent.active - default: agent.session.subagent.active + - agent.session.created + default: agent.session.created x-stainless-const: true - description: The type of the object. Always `agent.session.subagent.active`. + description: The type of the object. Always `agent.session.created`. event_id: type: string minLength: 0 description: The unique ID of the event. - subagent: - $ref: '#/components/schemas/SubagentResource' - description: The subagent that resumed. + session: + $ref: '#/components/schemas/SessionResource' + description: The session that was created. required: - type - event_id - - subagent + - session additionalProperties: false - description: Emitted when a closed subagent successfully resumes. - SessionEventAgentSessionSubagentClosed: + description: Emitted when a session is created. + SessionEventAgentSessionTurnCreated: type: object properties: type: type: string enum: - - agent.session.subagent.closed - default: agent.session.subagent.closed + - agent.session.turn.created + default: agent.session.turn.created x-stainless-const: true - description: The type of the object. Always `agent.session.subagent.closed`. + description: The type of the object. Always `agent.session.turn.created`. event_id: type: string minLength: 0 description: The unique ID of the event. - subagent: - $ref: '#/components/schemas/SubagentResource' - description: The subagent that was closed. - required: - - type - - event_id - - subagent - additionalProperties: false - description: Emitted when a subagent is closed. - AssistantMessageItemResource: - type: object - properties: - type: - type: string - enum: - - message - default: message - x-stainless-const: true - description: The item type. Always `message`. - id: + session_id: type: string minLength: 0 - description: The ID of the message. + description: The ID of the session associated with the event. turn_id: type: string minLength: 0 - description: The ID of the turn that contains this item. - role: - type: string - enum: - - assistant - default: assistant - x-stainless-const: true - description: The role of the message author. Always `assistant`. - status: - $ref: '#/components/schemas/OutputItemStatusResource' - description: The status of the message. - content: - type: array - items: - $ref: '#/components/schemas/OutputTextResource' - minItems: 0 - maxItems: 2000 - description: The content of the message. - phase: - anyOf: - - $ref: '#/components/schemas/MessagePhaseResource' - - type: 'null' - description: The phase of the assistant message. + description: The ID of the turn associated with the event. + turn: + $ref: '#/components/schemas/TurnResource' + description: The turn at the time it was created. required: - type - - id + - event_id + - session_id - turn_id - - role - - status - - content - - phase + - turn additionalProperties: false - description: An assistant message produced by the agent. - AgentOutputItemResource: - description: An output item produced by an agent. - discriminator: - propertyName: type - mapping: - message: '#/components/schemas/AssistantMessageItemResource' - reasoning: '#/components/schemas/ReasoningItemResource' - function_call: '#/components/schemas/FunctionCallItemResource' - mcp_call: '#/components/schemas/McpCallItemResource' - computer_use_call: '#/components/schemas/ComputerUseCallItemResource' - computer_use_approval_request: '#/components/schemas/BrowserAuthenticationRequestItemResource' - web_search_call: '#/components/schemas/WebSearchCallItemResource' - command_execution: '#/components/schemas/CommandExecutionItemResource' - interrupt_subagent_call: '#/components/schemas/InterruptSubagentCallItemResource' - create_subagent_call: '#/components/schemas/CreateSubagentCallItemResource' - send_subagent_input_call: '#/components/schemas/SendSubagentInputCallItemResource' - resume_subagent_call: '#/components/schemas/ResumeSubagentCallItemResource' - wait_for_subagents_call: '#/components/schemas/WaitForSubagentsCallItemResource' - close_subagent_call: '#/components/schemas/CloseSubagentCallItemResource' - x-oai-discriminator-values: - - message - - reasoning - - function_call - - mcp_call - - computer_use_call - - computer_use_approval_request - - web_search_call - - command_execution - - create_subagent_call - - send_subagent_input_call - - resume_subagent_call - - wait_for_subagents_call - - interrupt_subagent_call - - close_subagent_call - anyOf: - - $ref: '#/components/schemas/AssistantMessageItemResource' - - $ref: '#/components/schemas/ReasoningItemResource' - - $ref: '#/components/schemas/FunctionCallItemResource' - - $ref: '#/components/schemas/McpCallItemResource' - - $ref: '#/components/schemas/ComputerUseCallItemResource' - - $ref: '#/components/schemas/BrowserAuthenticationRequestItemResource' - - $ref: '#/components/schemas/WebSearchCallItemResource' - - $ref: '#/components/schemas/CommandExecutionItemResource' - - $ref: '#/components/schemas/CreateSubagentCallItemResource' - - $ref: '#/components/schemas/SendSubagentInputCallItemResource' - - $ref: '#/components/schemas/ResumeSubagentCallItemResource' - - $ref: '#/components/schemas/WaitForSubagentsCallItemResource' - - $ref: '#/components/schemas/InterruptSubagentCallItemResource' - - $ref: '#/components/schemas/CloseSubagentCallItemResource' - SessionEventAgentSessionTurnItemDone: + description: Emitted when a turn is created. + SessionEventAgentSessionTurnInProgress: type: object properties: type: type: string enum: - - agent.session.turn.item.done - default: agent.session.turn.item.done + - agent.session.turn.in_progress + default: agent.session.turn.in_progress x-stainless-const: true - description: The type of the object. Always `agent.session.turn.item.done`. + description: The type of the object. Always `agent.session.turn.in_progress`. event_id: type: string minLength: 0 @@ -89945,39 +91575,30 @@ components: minLength: 0 description: The ID of the session associated with the event. turn_id: - type: - - string - - 'null' + type: string minLength: 0 - description: The ID of the turn associated with the event, when applicable. - output_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the output item in the turn output. - item: - $ref: '#/components/schemas/AgentOutputItemResource' - description: The completed output item. + description: The ID of the turn associated with the event. + turn: + $ref: '#/components/schemas/TurnResource' + description: The turn at the time it started running. required: - type - event_id - session_id - turn_id - - output_index - - item + - turn additionalProperties: false - description: Emitted when an output item is complete. - SessionEventAgentSessionTurnContentPartAdded: + description: Emitted when a turn starts running. + SessionEventAgentSessionTurnCompleted: type: object properties: type: type: string enum: - - agent.session.turn.content_part.added - default: agent.session.turn.content_part.added + - agent.session.turn.completed + default: agent.session.turn.completed x-stainless-const: true - description: The type of the object. Always `agent.session.turn.content_part.added`. + description: The type of the object. Always `agent.session.turn.completed`. event_id: type: string minLength: 0 @@ -89987,51 +91608,36 @@ components: minLength: 0 description: The ID of the session associated with the event. turn_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the turn associated with the event, when applicable. - item_id: type: string minLength: 0 - description: The ID of the message item. - output_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the item in the turn output. - content_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the content part in the message. - part: - $ref: '#/components/schemas/OutputTextResource' - description: The initial content part. + description: The ID of the turn associated with the event. + turn: + $ref: '#/components/schemas/TurnResource' + description: The completed turn. + usage: + anyOf: + - $ref: '#/components/schemas/TokenUsageResource' + - type: 'null' + description: Token usage by the root agent during the turn, when available. required: - type - event_id - session_id - turn_id - - item_id - - output_index - - content_index - - part + - turn + - usage additionalProperties: false - description: Emitted when an output text content part is added. - SessionEventAgentSessionTurnContentPartDone: + description: Emitted when a turn completes. + SessionEventAgentSessionTurnFailed: type: object properties: type: type: string enum: - - agent.session.turn.content_part.done - default: agent.session.turn.content_part.done + - agent.session.turn.failed + default: agent.session.turn.failed x-stainless-const: true - description: The type of the object. Always `agent.session.turn.content_part.done`. + description: The type of the object. Always `agent.session.turn.failed`. event_id: type: string minLength: 0 @@ -90041,51 +91647,36 @@ components: minLength: 0 description: The ID of the session associated with the event. turn_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the turn associated with the event, when applicable. - item_id: type: string minLength: 0 - description: The ID of the message item. - output_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the item in the turn output. - content_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the content part in the message. - part: - $ref: '#/components/schemas/OutputTextResource' - description: The completed content part. + description: The ID of the turn associated with the event. + turn: + $ref: '#/components/schemas/TurnResource' + description: The failed turn. + usage: + anyOf: + - $ref: '#/components/schemas/TokenUsageResource' + - type: 'null' + description: Token usage by the root agent during the turn, when available. required: - type - event_id - session_id - turn_id - - item_id - - output_index - - content_index - - part + - turn + - usage additionalProperties: false - description: Emitted when an output content part is complete. - SessionEventAgentSessionTurnOutputTextDelta: + description: Emitted when a turn fails. + SessionEventAgentSessionTurnCancelled: type: object properties: type: type: string enum: - - agent.session.turn.output_text.delta - default: agent.session.turn.output_text.delta + - agent.session.turn.cancelled + default: agent.session.turn.cancelled x-stainless-const: true - description: The type of the object. Always `agent.session.turn.output_text.delta`. + description: The type of the object. Always `agent.session.turn.cancelled`. event_id: type: string minLength: 0 @@ -90095,52 +91686,36 @@ components: minLength: 0 description: The ID of the session associated with the event. turn_id: - type: - - string - - 'null' - minLength: 0 - description: The ID of the turn associated with the event, when applicable. - item_id: - type: string - minLength: 0 - description: The ID of the message item. - output_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the item in the turn output. - content_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the content part in the message. - delta: type: string minLength: 0 - description: The text that was appended. + description: The ID of the turn associated with the event. + turn: + $ref: '#/components/schemas/TurnResource' + description: The cancelled turn. + usage: + anyOf: + - $ref: '#/components/schemas/TokenUsageResource' + - type: 'null' + description: Token usage by the root agent during the turn, when available. required: - type - event_id - session_id - turn_id - - item_id - - output_index - - content_index - - delta + - turn + - usage additionalProperties: false - description: Emitted when text is appended to an output text content part. - SessionEventAgentSessionTurnOutputTextDone: + description: Emitted when a turn is cancelled. + SessionEventAgentSessionTurnItemAdded: type: object properties: type: type: string enum: - - agent.session.turn.output_text.done - default: agent.session.turn.output_text.done + - agent.session.turn.item.added + default: agent.session.turn.item.added x-stainless-const: true - description: The type of the object. Always `agent.session.turn.output_text.done`. + description: The type of the object. Always `agent.session.turn.item.added`. event_id: type: string minLength: 0 @@ -90155,47 +91730,128 @@ components: - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. - item_id: - type: string - minLength: 0 - description: The ID of the message item. output_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the item in the turn output. - content_index: - type: integer + type: + - integer + - 'null' format: int64 minimum: 0 maximum: 4294967295 - description: The index of the content part in the message. - text: - type: string - minLength: 0 - description: The complete output text. + description: The index of the item in the turn output, when the item is agent output. + item: + $ref: '#/components/schemas/SessionTurnItemResource' + description: The item that was added. required: - type - event_id - session_id - turn_id - - item_id - output_index - - content_index - - text + - item additionalProperties: false - description: Emitted when an output text content part is complete. - SessionEventAgentSessionTurnReasoningSummaryPartAdded: + description: Emitted when an item is added to a turn. + SessionEventAgentSessionIdle: type: object properties: type: type: string enum: - - agent.session.turn.reasoning_summary_part.added - default: agent.session.turn.reasoning_summary_part.added + - agent.session.idle + default: agent.session.idle x-stainless-const: true - description: The type of the object. Always `agent.session.turn.reasoning_summary_part.added`. + description: The type of the object. Always `agent.session.idle`. + event_id: + type: string + minLength: 0 + description: The unique ID of the event. + session: + $ref: '#/components/schemas/SessionResource' + description: The session that became idle. + required: + - type + - event_id + - session + additionalProperties: false + description: Emitted when a session becomes idle. + SessionEventAgentSessionInProgress: + type: object + properties: + type: + type: string + enum: + - agent.session.in_progress + default: agent.session.in_progress + x-stainless-const: true + description: The type of the object. Always `agent.session.in_progress`. + event_id: + type: string + minLength: 0 + description: The unique ID of the event. + session: + $ref: '#/components/schemas/SessionResource' + description: The session that started processing. + required: + - type + - event_id + - session + additionalProperties: false + description: Emitted when a session starts processing a turn. + SessionEventAgentSessionRequiresAction: + type: object + properties: + type: + type: string + enum: + - agent.session.requires_action + default: agent.session.requires_action + x-stainless-const: true + description: The type of the object. Always `agent.session.requires_action`. + event_id: + type: string + minLength: 0 + description: The unique ID of the event. + session: + $ref: '#/components/schemas/SessionResource' + description: The session and its current required actions. + required: + - type + - event_id + - session + additionalProperties: false + description: Emitted when a session is waiting for one or more required actions. + SessionEventAgentSessionFailed: + type: object + properties: + type: + type: string + enum: + - agent.session.failed + default: agent.session.failed + x-stainless-const: true + description: The type of the object. Always `agent.session.failed`. + event_id: + type: string + minLength: 0 + description: The unique ID of the event. + session: + $ref: '#/components/schemas/SessionResource' + description: The failed session. + required: + - type + - event_id + - session + additionalProperties: false + description: Emitted when a session fails. + SessionEventAgentSessionEnvironmentPending: + type: object + properties: + type: + type: string + enum: + - agent.session.environment.pending + default: agent.session.environment.pending + x-stainless-const: true + description: The type of the object. Always `agent.session.environment.pending`. event_id: type: string minLength: 0 @@ -90210,46 +91866,27 @@ components: - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. - item_id: - type: string - minLength: 0 - description: The ID of the reasoning item. - output_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the item in the turn output. - summary_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the summary content part. - part: - $ref: '#/components/schemas/SummaryTextResource' - description: The initial summary part. + environment: + $ref: '#/components/schemas/SessionEnvironmentStateResource' + description: The current environment state. required: - type - event_id - session_id - turn_id - - item_id - - output_index - - summary_index - - part + - environment additionalProperties: false - description: Emitted when a reasoning summary content part is added. - SessionEventAgentSessionTurnReasoningSummaryPartDone: + description: Emitted while a session environment is being prepared. + SessionEventAgentSessionEnvironmentConnected: type: object properties: type: type: string enum: - - agent.session.turn.reasoning_summary_part.done - default: agent.session.turn.reasoning_summary_part.done + - agent.session.environment.connected + default: agent.session.environment.connected x-stainless-const: true - description: The type of the object. Always `agent.session.turn.reasoning_summary_part.done`. + description: The type of the object. Always `agent.session.environment.connected`. event_id: type: string minLength: 0 @@ -90264,56 +91901,62 @@ components: - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. - item_id: + environment: + $ref: '#/components/schemas/SessionEnvironmentStateResource' + description: The current environment state. + required: + - type + - event_id + - session_id + - turn_id + - environment + additionalProperties: false + description: Emitted when a session environment connects. + SessionEventAgentSessionEnvironmentDisconnected: + type: object + properties: + type: + type: string + enum: + - agent.session.environment.disconnected + default: agent.session.environment.disconnected + x-stainless-const: true + description: The type of the object. Always `agent.session.environment.disconnected`. + event_id: type: string minLength: 0 - description: The ID of the reasoning item. - output_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the item in the turn output. - summary_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the summary part. - part: - $ref: '#/components/schemas/SummaryTextResource' - description: The completed summary part. - status: + description: The unique ID of the event. + session_id: + type: string + minLength: 0 + description: The ID of the session associated with the event. + turn_id: type: - string - 'null' - enum: - - incomplete - - null - description: Present as `incomplete` when summary generation was interrupted. - x-stainless-const: true + minLength: 0 + description: The ID of the turn associated with the event, when applicable. + environment: + $ref: '#/components/schemas/SessionEnvironmentStateResource' + description: The current environment state. required: - type - event_id - session_id - turn_id - - item_id - - output_index - - summary_index - - part - - status + - environment additionalProperties: false - description: Emitted when a reasoning summary part is complete. - SessionEventAgentSessionTurnReasoningSummaryTextDelta: + description: Emitted when a session environment disconnects. + SessionEventAgentSessionEnvironmentFailed: type: object properties: type: type: string enum: - - agent.session.turn.reasoning_summary_text.delta - default: agent.session.turn.reasoning_summary_text.delta + - agent.session.environment.failed + default: agent.session.environment.failed x-stainless-const: true - description: The type of the object. Always `agent.session.turn.reasoning_summary_text.delta`. + description: The type of the object. Always `agent.session.environment.failed`. event_id: type: string minLength: 0 @@ -90328,439 +91971,901 @@ components: - 'null' minLength: 0 description: The ID of the turn associated with the event, when applicable. - item_id: - type: string - minLength: 0 - description: The ID of the reasoning item. - output_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the item in the turn output. - summary_index: - type: integer - format: int64 - minimum: 0 - maximum: 4294967295 - description: The index of the summary content part. - delta: - type: string - minLength: 0 - description: The summary text that was appended. + environment: + $ref: '#/components/schemas/SessionEnvironmentStateResource' + description: The current environment state. required: - type - event_id - session_id - turn_id - - item_id - - output_index - - summary_index - - delta + - environment additionalProperties: false - description: Emitted when text is appended to a reasoning summary. - SessionEvent: - description: An event emitted by a Managed Agents session. - discriminator: - propertyName: type - mapping: - agent.session.turn.reasoning_summary_text.done: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDone' - error: '#/components/schemas/SessionEventError' - agent.session.environment.ready: '#/components/schemas/SessionEventAgentSessionEnvironmentReady' - agent.session.environment.suspended: '#/components/schemas/SessionEventAgentSessionEnvironmentSuspended' - agent.session.environment.expired: '#/components/schemas/SessionEventAgentSessionEnvironmentExpired' - agent.session.environment.reset: '#/components/schemas/SessionEventAgentSessionEnvironmentReset' - agent.output.command_execution_output.delta: '#/components/schemas/SessionEventAgentOutputCommandExecutionOutputDelta' - agent.session.created: '#/components/schemas/SessionEventAgentSessionCreated' - agent.session.turn.created: '#/components/schemas/SessionEventAgentSessionTurnCreated' - agent.session.turn.in_progress: '#/components/schemas/SessionEventAgentSessionTurnInProgress' - agent.session.turn.completed: '#/components/schemas/SessionEventAgentSessionTurnCompleted' - agent.session.turn.failed: '#/components/schemas/SessionEventAgentSessionTurnFailed' - agent.session.turn.cancelled: '#/components/schemas/SessionEventAgentSessionTurnCancelled' - agent.session.turn.item.added: '#/components/schemas/SessionEventAgentSessionTurnItemAdded' - agent.session.idle: '#/components/schemas/SessionEventAgentSessionIdle' - agent.session.in_progress: '#/components/schemas/SessionEventAgentSessionInProgress' - agent.session.requires_action: '#/components/schemas/SessionEventAgentSessionRequiresAction' - agent.session.failed: '#/components/schemas/SessionEventAgentSessionFailed' - agent.session.environment.pending: '#/components/schemas/SessionEventAgentSessionEnvironmentPending' - agent.session.environment.connected: '#/components/schemas/SessionEventAgentSessionEnvironmentConnected' - agent.session.environment.disconnected: '#/components/schemas/SessionEventAgentSessionEnvironmentDisconnected' - agent.session.environment.failed: '#/components/schemas/SessionEventAgentSessionEnvironmentFailed' - agent.session.subagent.created: '#/components/schemas/SessionEventAgentSessionSubagentCreated' - agent.session.subagent.active: '#/components/schemas/SessionEventAgentSessionSubagentActive' - agent.session.subagent.closed: '#/components/schemas/SessionEventAgentSessionSubagentClosed' - agent.session.turn.item.done: '#/components/schemas/SessionEventAgentSessionTurnItemDone' - agent.session.turn.content_part.added: '#/components/schemas/SessionEventAgentSessionTurnContentPartAdded' - agent.session.turn.content_part.done: '#/components/schemas/SessionEventAgentSessionTurnContentPartDone' - agent.session.turn.output_text.delta: '#/components/schemas/SessionEventAgentSessionTurnOutputTextDelta' - agent.session.turn.output_text.done: '#/components/schemas/SessionEventAgentSessionTurnOutputTextDone' - agent.session.turn.reasoning_summary_part.added: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartAdded' - agent.session.turn.reasoning_summary_part.done: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartDone' - agent.session.turn.reasoning_summary_text.delta: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDelta' - x-oai-discriminator-values: - - error - - agent.session.environment.ready - - agent.session.environment.suspended - - agent.session.environment.expired - - agent.session.environment.reset - - agent.output.command_execution_output.delta - - agent.session.created - - agent.session.turn.created - - agent.session.turn.in_progress - - agent.session.turn.completed - - agent.session.turn.failed - - agent.session.turn.cancelled - - agent.session.turn.item.added - - agent.session.idle - - agent.session.in_progress - - agent.session.requires_action - - agent.session.failed - - agent.session.environment.pending - - agent.session.environment.connected - - agent.session.environment.disconnected - - agent.session.environment.failed - - agent.session.subagent.created - - agent.session.subagent.active - - agent.session.subagent.closed - - agent.session.turn.item.done - - agent.session.turn.content_part.added - - agent.session.turn.content_part.done - - agent.session.turn.output_text.delta - - agent.session.turn.output_text.done - - agent.session.turn.reasoning_summary_part.added - - agent.session.turn.reasoning_summary_part.done - - agent.session.turn.reasoning_summary_text.delta - - agent.session.turn.reasoning_summary_text.done - anyOf: - - $ref: '#/components/schemas/SessionEventError' - - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentReady' - - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentSuspended' - - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentExpired' - - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentReset' - - $ref: '#/components/schemas/SessionEventAgentOutputCommandExecutionOutputDelta' - - $ref: '#/components/schemas/SessionEventAgentSessionCreated' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnCreated' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnInProgress' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnCompleted' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnFailed' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnCancelled' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnItemAdded' - - $ref: '#/components/schemas/SessionEventAgentSessionIdle' - - $ref: '#/components/schemas/SessionEventAgentSessionInProgress' - - $ref: '#/components/schemas/SessionEventAgentSessionRequiresAction' - - $ref: '#/components/schemas/SessionEventAgentSessionFailed' - - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentPending' - - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentConnected' - - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentDisconnected' - - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentFailed' - - $ref: '#/components/schemas/SessionEventAgentSessionSubagentCreated' - - $ref: '#/components/schemas/SessionEventAgentSessionSubagentActive' - - $ref: '#/components/schemas/SessionEventAgentSessionSubagentClosed' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnItemDone' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnContentPartAdded' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnContentPartDone' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnOutputTextDelta' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnOutputTextDone' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartAdded' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartDone' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDelta' - - $ref: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDone' - UpdateSessionReasoningParam: + description: Emitted when a session environment fails. + SessionEventAgentSessionSubagentCreated: type: object properties: - effort: - anyOf: - - $ref: '#/components/schemas/ReasoningEffortParam' - - type: 'null' - description: Omit to keep the current effort. Null selects the model's default effort. - x-openai-go-optional-enum: true + type: + type: string + enum: + - agent.session.subagent.created + default: agent.session.subagent.created + x-stainless-const: true + description: The type of the object. Always `agent.session.subagent.created`. + event_id: + type: string + minLength: 0 + description: The unique ID of the event. + subagent: + $ref: '#/components/schemas/SubagentResource' + description: The subagent that was created. + required: + - type + - event_id + - subagent additionalProperties: false - description: Reasoning effort for subsequent turns. The reasoning summary stays unchanged. - UpdateSessionAgentParam: + description: Emitted when a subagent is created. + SessionEventAgentSessionSubagentActive: type: object properties: - model: + type: type: string - minLength: 0 - maxLength: 1048576 - description: The model for subsequent turns. Omit to keep the current model. - reasoning: - $ref: '#/components/schemas/UpdateSessionReasoningParam' - description: Reasoning settings to update. Omit to keep the current effort. - service_tier: - anyOf: - - $ref: '#/components/schemas/ServiceTierParam' - - type: 'null' - description: Omit to keep the current tier. Null resets it to auto. - x-openai-go-optional-enum: true + enum: + - agent.session.subagent.active + default: agent.session.subagent.active + x-stainless-const: true + description: The type of the object. Always `agent.session.subagent.active`. + event_id: + type: string + minLength: 0 + description: The unique ID of the event. + subagent: + $ref: '#/components/schemas/SubagentResource' + description: The subagent that resumed. + required: + - type + - event_id + - subagent additionalProperties: false - description: Model settings that can change after session creation. - UpdateAgentSessionParams: + description: Emitted when a closed subagent successfully resumes. + SessionEventAgentSessionSubagentClosed: type: object properties: - spend_control: - anyOf: - - $ref: '#/components/schemas/SessionSpendControlParam' - - type: 'null' - description: Omit to retain the limit; null or a null limit removes it without resetting spend. - agent: - $ref: '#/components/schemas/UpdateSessionAgentParam' - description: Model settings for subsequent turns. Omitted fields stay unchanged. - metadata: - type: - - object - - 'null' - additionalProperties: - type: string - minLength: 0 - maxLength: 512 - propertyNames: - type: string - minLength: 1 - maxLength: 64 - minProperties: 0 - maxProperties: 16 - description: Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. + type: + type: string + enum: + - agent.session.subagent.closed + default: agent.session.subagent.closed + x-stainless-const: true + description: The type of the object. Always `agent.session.subagent.closed`. + event_id: + type: string + minLength: 0 + description: The unique ID of the event. + subagent: + $ref: '#/components/schemas/SubagentResource' + description: The subagent that was closed. + required: + - type + - event_id + - subagent additionalProperties: false - description: Fields to update on an existing session. - DeletedSessionResource: + description: Emitted when a subagent is closed. + AssistantMessageItemResource: type: object properties: + type: + type: string + enum: + - message + default: message + x-stainless-const: true + description: The item type. Always `message`. id: type: string minLength: 0 - description: The ID of the deleted session. - object: + description: The ID of the message. + turn_id: + type: string + minLength: 0 + description: The ID of the turn that contains this item. + role: type: string enum: - - agent.session.deleted - default: agent.session.deleted + - assistant + default: assistant x-stainless-const: true - description: The object type. Always `agent.session.deleted`. - deleted: - type: boolean - description: Whether the session has been removed from the public API. Always `true`. Physical cleanup may still be in progress. + description: The role of the message author. Always `assistant`. + status: + $ref: '#/components/schemas/OutputItemStatusResource' + description: The status of the message. + content: + type: array + items: + $ref: '#/components/schemas/OutputTextResource' + minItems: 0 + maxItems: 2000 + description: The content of the message. + phase: + anyOf: + - $ref: '#/components/schemas/MessagePhaseResource' + - type: 'null' + description: The phase of the assistant message. required: + - type - id - - object - - deleted + - turn_id + - role + - status + - content + - phase additionalProperties: false - description: A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously. - SessionArtifactResource: + description: An assistant message produced by the agent. + AgentOutputItemResource: + description: An output item produced by an agent. + discriminator: + propertyName: type + mapping: + message: '#/components/schemas/AssistantMessageItemResource' + reasoning: '#/components/schemas/ReasoningItemResource' + function_call: '#/components/schemas/FunctionCallItemResource' + mcp_call: '#/components/schemas/McpCallItemResource' + computer_use_call: '#/components/schemas/ComputerUseCallItemResource' + computer_use_approval_request: '#/components/schemas/BrowserAuthenticationRequestItemResource' + web_search_call: '#/components/schemas/WebSearchCallItemResource' + command_execution: '#/components/schemas/CommandExecutionItemResource' + interrupt_subagent_call: '#/components/schemas/InterruptSubagentCallItemResource' + create_subagent_call: '#/components/schemas/CreateSubagentCallItemResource' + send_subagent_input_call: '#/components/schemas/SendSubagentInputCallItemResource' + resume_subagent_call: '#/components/schemas/ResumeSubagentCallItemResource' + wait_for_subagents_call: '#/components/schemas/WaitForSubagentsCallItemResource' + close_subagent_call: '#/components/schemas/CloseSubagentCallItemResource' + x-oai-discriminator-values: + - message + - reasoning + - function_call + - mcp_call + - computer_use_call + - computer_use_approval_request + - web_search_call + - command_execution + - create_subagent_call + - send_subagent_input_call + - resume_subagent_call + - wait_for_subagents_call + - interrupt_subagent_call + - close_subagent_call + anyOf: + - $ref: '#/components/schemas/AssistantMessageItemResource' + - $ref: '#/components/schemas/ReasoningItemResource' + - $ref: '#/components/schemas/FunctionCallItemResource' + - $ref: '#/components/schemas/McpCallItemResource' + - $ref: '#/components/schemas/ComputerUseCallItemResource' + - $ref: '#/components/schemas/BrowserAuthenticationRequestItemResource' + - $ref: '#/components/schemas/WebSearchCallItemResource' + - $ref: '#/components/schemas/CommandExecutionItemResource' + - $ref: '#/components/schemas/CreateSubagentCallItemResource' + - $ref: '#/components/schemas/SendSubagentInputCallItemResource' + - $ref: '#/components/schemas/ResumeSubagentCallItemResource' + - $ref: '#/components/schemas/WaitForSubagentsCallItemResource' + - $ref: '#/components/schemas/InterruptSubagentCallItemResource' + - $ref: '#/components/schemas/CloseSubagentCallItemResource' + SessionEventAgentSessionTurnItemDone: type: object properties: - id: - type: string - minLength: 0 - description: The immutable artifact ID. - object: + type: type: string enum: - - agent.session.artifact - default: agent.session.artifact + - agent.session.turn.item.done + default: agent.session.turn.item.done x-stainless-const: true - description: The object type. Always `agent.session.artifact`. - session_id: + description: The type of the object. Always `agent.session.turn.item.done`. + event_id: type: string minLength: 0 - description: The ID of the session that owns the artifact. - environment_id: + description: The unique ID of the event. + session_id: type: string minLength: 0 - description: The ID of the environment that produced the artifact. + description: The ID of the session associated with the event. turn_id: - type: string - minLength: 0 - description: The ID of the completed turn that published the artifact. - path: - type: string + type: + - string + - 'null' minLength: 0 - description: The original absolute file path in the execution environment. - size_bytes: + description: The ID of the turn associated with the event, when applicable. + output_index: type: integer format: int64 minimum: 0 - description: The immutable artifact size in bytes. - created_at: - type: integer - format: int64 - description: The Unix timestamp, in seconds, when the artifact was published. + maximum: 4294967295 + description: The index of the output item in the turn output. + item: + $ref: '#/components/schemas/AgentOutputItemResource' + description: The completed output item. required: - - id - - object + - type + - event_id - session_id - - environment_id - turn_id - - path - - size_bytes - - created_at + - output_index + - item additionalProperties: false - description: An immutable file published by a completed hosted session turn. - SessionArtifactListResource: + description: Emitted when an output item is complete. + SessionEventAgentSessionTurnContentPartAdded: type: object properties: - object: + type: type: string enum: - - list - default: list + - agent.session.turn.content_part.added + default: agent.session.turn.content_part.added x-stainless-const: true - description: The object type, which is always `list`. - data: - type: array - items: - $ref: '#/components/schemas/SessionArtifactResource' - minItems: 0 - maxItems: 2000 - description: The resources returned in this page, in the requested sort order. - first_id: - type: - - string - - 'null' + description: The type of the object. Always `agent.session.turn.content_part.added`. + event_id: + type: string minLength: 0 - description: The ID of the first resource in `data`, or `null` if the page is empty. - last_id: + description: The unique ID of the event. + session_id: + type: string + minLength: 0 + description: The ID of the session associated with the event. + turn_id: type: - string - 'null' minLength: 0 - description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - has_more: - type: boolean - description: Whether there are more resources to retrieve after this page. + description: The ID of the turn associated with the event, when applicable. + item_id: + type: string + minLength: 0 + description: The ID of the message item. + output_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the item in the turn output. + content_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the content part in the message. + part: + $ref: '#/components/schemas/OutputTextResource' + description: The initial content part. required: - - object - - data - - first_id - - last_id - - has_more + - type + - event_id + - session_id + - turn_id + - item_id + - output_index + - content_index + - part additionalProperties: false - description: A page of Agents API resources, with IDs for retrieving additional pages. - DeletedSessionArtifactResource: + description: Emitted when an output text content part is added. + SessionEventAgentSessionTurnContentPartDone: type: object properties: - id: - type: string - minLength: 0 - description: The ID of the deleted session artifact. - object: + type: type: string enum: - - agent.session.artifact.deleted - default: agent.session.artifact.deleted + - agent.session.turn.content_part.done + default: agent.session.turn.content_part.done x-stainless-const: true - description: The object type. Always `agent.session.artifact.deleted`. - deleted: - type: boolean - description: Whether the session artifact was deleted. Always `true`. - required: - - id - - object - - deleted - additionalProperties: false - description: Confirmation that an immutable session artifact was deleted. - BrowserAuthenticationFieldValueParam: - type: object - properties: - field_id: + description: The type of the object. Always `agent.session.turn.content_part.done`. + event_id: type: string minLength: 0 - maxLength: 1048576 - description: The field ID from the required action. - value: + description: The unique ID of the event. + session_id: type: string minLength: 0 - maxLength: 16384 - description: The value to enter into the registered control. + description: The ID of the session associated with the event. + turn_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the turn associated with the event, when applicable. + item_id: + type: string + minLength: 0 + description: The ID of the message item. + output_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the item in the turn output. + content_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the content part in the message. + part: + $ref: '#/components/schemas/OutputTextResource' + description: The completed content part. required: - - field_id - - value + - type + - event_id + - session_id + - turn_id + - item_id + - output_index + - content_index + - part additionalProperties: false - description: One user-entered value, including non-password fields such as an email address. - ComputerUseApprovalResponseParamBrowserAuthenticationSubmitParam: + description: Emitted when an output content part is complete. + SessionEventAgentSessionTurnOutputTextDelta: type: object properties: type: type: string enum: - - browser_authentication - default: browser_authentication + - agent.session.turn.output_text.delta + default: agent.session.turn.output_text.delta x-stainless-const: true - action: + description: The type of the object. Always `agent.session.turn.output_text.delta`. + event_id: type: string - enum: - - submit - default: submit - x-stainless-const: true - fields: - type: array - items: - $ref: '#/components/schemas/BrowserAuthenticationFieldValueParam' - minItems: 0 - maxItems: 6 - description: Values for up to six active fields in the required action. The submitted field-value mapping and selected option must fit within 120 KiB of JSON. - selected_option: + minLength: 0 + description: The unique ID of the event. + session_id: + type: string + minLength: 0 + description: The ID of the session associated with the event. + turn_id: type: - string - 'null' minLength: 0 - maxLength: 1048576 - description: The chosen method. Required when the required action contains options. + description: The ID of the turn associated with the event, when applicable. + item_id: + type: string + minLength: 0 + description: The ID of the message item. + output_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the item in the turn output. + content_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the content part in the message. + delta: + type: string + minLength: 0 + description: The text that was appended. required: - type - - action - - fields + - event_id + - session_id + - turn_id + - item_id + - output_index + - content_index + - delta additionalProperties: false - ComputerUseApprovalResponseParamBrowserAuthenticationCancelParam: + description: Emitted when text is appended to an output text content part. + SessionEventAgentSessionTurnOutputTextDone: type: object properties: type: type: string enum: - - browser_authentication - default: browser_authentication + - agent.session.turn.output_text.done + default: agent.session.turn.output_text.done x-stainless-const: true - action: + description: The type of the object. Always `agent.session.turn.output_text.done`. + event_id: type: string - enum: - - cancel - default: cancel - x-stainless-const: true + minLength: 0 + description: The unique ID of the event. + session_id: + type: string + minLength: 0 + description: The ID of the session associated with the event. + turn_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the turn associated with the event, when applicable. + item_id: + type: string + minLength: 0 + description: The ID of the message item. + output_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the item in the turn output. + content_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the content part in the message. + text: + type: string + minLength: 0 + description: The complete output text. required: - type - - action + - event_id + - session_id + - turn_id + - item_id + - output_index + - content_index + - text additionalProperties: false - ComputerUseApprovalResponseParamBrowserAuthentication: - required: - - type - discriminator: - propertyName: action - mapping: - submit: '#/components/schemas/ComputerUseApprovalResponseParamBrowserAuthenticationSubmitParam' - cancel: '#/components/schemas/ComputerUseApprovalResponseParamBrowserAuthenticationCancelParam' - x-oai-discriminator-values: - - submit - - cancel + description: Emitted when an output text content part is complete. + SessionEventAgentSessionTurnReasoningSummaryPartAdded: + type: object properties: type: type: string enum: - - browser_authentication - anyOf: - - $ref: '#/components/schemas/ComputerUseApprovalResponseParamBrowserAuthenticationSubmitParam' - - $ref: '#/components/schemas/ComputerUseApprovalResponseParamBrowserAuthenticationCancelParam' - BrowserOriginAccessDecisionParam: - type: string - enum: - - approve - - deny - - cancel - x-enumDescriptions: - - Allow the browser to access this origin. - - Deny access to this origin. - - Dismiss this request without approving access. - description: The user's decision for a browser origin access request. - ComputerUseApprovalResponseParamBrowserOriginAccessParam: + - agent.session.turn.reasoning_summary_part.added + default: agent.session.turn.reasoning_summary_part.added + x-stainless-const: true + description: The type of the object. Always `agent.session.turn.reasoning_summary_part.added`. + event_id: + type: string + minLength: 0 + description: The unique ID of the event. + session_id: + type: string + minLength: 0 + description: The ID of the session associated with the event. + turn_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the turn associated with the event, when applicable. + item_id: + type: string + minLength: 0 + description: The ID of the reasoning item. + output_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the item in the turn output. + summary_index: + type: integer + format: int64 + minimum: 0 + maximum: 4294967295 + description: The index of the summary content part. + part: + $ref: '#/components/schemas/SummaryTextResource' + description: The initial summary part. + required: + - type + - event_id + - session_id + - turn_id + - item_id + - output_index + - summary_index + - part + additionalProperties: false + description: Emitted when a reasoning summary content part is added. + SessionEvent: + description: An event emitted by a Managed Agents session. + discriminator: + propertyName: type + mapping: + agent.session.turn.reasoning_summary_text.delta: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDelta' + agent.session.turn.reasoning_summary_part.done: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartDone' + agent.session.turn.reasoning_summary_text.done: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDone' + error: '#/components/schemas/SessionEventError' + agent.session.environment.ready: '#/components/schemas/SessionEventAgentSessionEnvironmentReady' + agent.session.environment.suspended: '#/components/schemas/SessionEventAgentSessionEnvironmentSuspended' + agent.session.environment.expired: '#/components/schemas/SessionEventAgentSessionEnvironmentExpired' + agent.session.environment.reset: '#/components/schemas/SessionEventAgentSessionEnvironmentReset' + agent.output.command_execution_output.delta: '#/components/schemas/SessionEventAgentOutputCommandExecutionOutputDelta' + agent.session.created: '#/components/schemas/SessionEventAgentSessionCreated' + agent.session.turn.created: '#/components/schemas/SessionEventAgentSessionTurnCreated' + agent.session.turn.in_progress: '#/components/schemas/SessionEventAgentSessionTurnInProgress' + agent.session.turn.completed: '#/components/schemas/SessionEventAgentSessionTurnCompleted' + agent.session.turn.failed: '#/components/schemas/SessionEventAgentSessionTurnFailed' + agent.session.turn.cancelled: '#/components/schemas/SessionEventAgentSessionTurnCancelled' + agent.session.turn.item.added: '#/components/schemas/SessionEventAgentSessionTurnItemAdded' + agent.session.idle: '#/components/schemas/SessionEventAgentSessionIdle' + agent.session.in_progress: '#/components/schemas/SessionEventAgentSessionInProgress' + agent.session.requires_action: '#/components/schemas/SessionEventAgentSessionRequiresAction' + agent.session.failed: '#/components/schemas/SessionEventAgentSessionFailed' + agent.session.environment.pending: '#/components/schemas/SessionEventAgentSessionEnvironmentPending' + agent.session.environment.connected: '#/components/schemas/SessionEventAgentSessionEnvironmentConnected' + agent.session.environment.disconnected: '#/components/schemas/SessionEventAgentSessionEnvironmentDisconnected' + agent.session.environment.failed: '#/components/schemas/SessionEventAgentSessionEnvironmentFailed' + agent.session.subagent.created: '#/components/schemas/SessionEventAgentSessionSubagentCreated' + agent.session.subagent.active: '#/components/schemas/SessionEventAgentSessionSubagentActive' + agent.session.subagent.closed: '#/components/schemas/SessionEventAgentSessionSubagentClosed' + agent.session.turn.item.done: '#/components/schemas/SessionEventAgentSessionTurnItemDone' + agent.session.turn.content_part.added: '#/components/schemas/SessionEventAgentSessionTurnContentPartAdded' + agent.session.turn.content_part.done: '#/components/schemas/SessionEventAgentSessionTurnContentPartDone' + agent.session.turn.output_text.delta: '#/components/schemas/SessionEventAgentSessionTurnOutputTextDelta' + agent.session.turn.output_text.done: '#/components/schemas/SessionEventAgentSessionTurnOutputTextDone' + agent.session.turn.reasoning_summary_part.added: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartAdded' + x-oai-discriminator-values: + - error + - agent.session.environment.ready + - agent.session.environment.suspended + - agent.session.environment.expired + - agent.session.environment.reset + - agent.output.command_execution_output.delta + - agent.session.created + - agent.session.turn.created + - agent.session.turn.in_progress + - agent.session.turn.completed + - agent.session.turn.failed + - agent.session.turn.cancelled + - agent.session.turn.item.added + - agent.session.idle + - agent.session.in_progress + - agent.session.requires_action + - agent.session.failed + - agent.session.environment.pending + - agent.session.environment.connected + - agent.session.environment.disconnected + - agent.session.environment.failed + - agent.session.subagent.created + - agent.session.subagent.active + - agent.session.subagent.closed + - agent.session.turn.item.done + - agent.session.turn.content_part.added + - agent.session.turn.content_part.done + - agent.session.turn.output_text.delta + - agent.session.turn.output_text.done + - agent.session.turn.reasoning_summary_part.added + - agent.session.turn.reasoning_summary_part.done + - agent.session.turn.reasoning_summary_text.delta + - agent.session.turn.reasoning_summary_text.done + anyOf: + - $ref: '#/components/schemas/SessionEventError' + - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentReady' + - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentSuspended' + - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentExpired' + - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentReset' + - $ref: '#/components/schemas/SessionEventAgentOutputCommandExecutionOutputDelta' + - $ref: '#/components/schemas/SessionEventAgentSessionCreated' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnCreated' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnInProgress' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnCompleted' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnFailed' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnCancelled' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnItemAdded' + - $ref: '#/components/schemas/SessionEventAgentSessionIdle' + - $ref: '#/components/schemas/SessionEventAgentSessionInProgress' + - $ref: '#/components/schemas/SessionEventAgentSessionRequiresAction' + - $ref: '#/components/schemas/SessionEventAgentSessionFailed' + - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentPending' + - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentConnected' + - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentDisconnected' + - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentFailed' + - $ref: '#/components/schemas/SessionEventAgentSessionSubagentCreated' + - $ref: '#/components/schemas/SessionEventAgentSessionSubagentActive' + - $ref: '#/components/schemas/SessionEventAgentSessionSubagentClosed' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnItemDone' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnContentPartAdded' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnContentPartDone' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnOutputTextDelta' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnOutputTextDone' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartAdded' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartDone' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDelta' + - $ref: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDone' + UpdateSessionReasoningParam: + type: object + properties: + effort: + anyOf: + - $ref: '#/components/schemas/ReasoningEffortParam' + - type: 'null' + description: Omit to keep the current effort. Null selects the model's default effort. + x-openai-go-optional-enum: true + additionalProperties: false + description: Reasoning effort for subsequent turns. The reasoning summary stays unchanged. + UpdateSessionAgentParam: + type: object + properties: + model: + type: string + minLength: 0 + maxLength: 1048576 + description: The model for subsequent turns. Omit to keep the current model. + reasoning: + $ref: '#/components/schemas/UpdateSessionReasoningParam' + description: Reasoning settings to update. Omit to keep the current effort. + service_tier: + anyOf: + - $ref: '#/components/schemas/ServiceTierParam' + - type: 'null' + description: Omit to keep the current tier. Null resets it to auto. + x-openai-go-optional-enum: true + additionalProperties: false + description: Model settings that can change after session creation. + UpdateAgentSessionParams: + type: object + properties: + agent: + $ref: '#/components/schemas/UpdateSessionAgentParam' + description: Model settings for subsequent turns. Omitted fields stay unchanged. + metadata: + type: + - object + - 'null' + additionalProperties: + type: string + minLength: 0 + maxLength: 512 + propertyNames: + type: string + minLength: 1 + maxLength: 64 + minProperties: 0 + maxProperties: 16 + description: Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. + spend_control: + anyOf: + - $ref: '#/components/schemas/SessionSpendControlParam' + - type: 'null' + description: Omit to retain the limit; null or a null limit removes it without resetting spend. + additionalProperties: false + description: Fields to update on an existing session. + DeletedSessionResource: + type: object + properties: + id: + type: string + minLength: 0 + description: The ID of the deleted session. + object: + type: string + enum: + - agent.session.deleted + default: agent.session.deleted + x-stainless-const: true + description: The object type. Always `agent.session.deleted`. + deleted: + type: boolean + description: Whether the session has been removed from the public API. Always `true`. Physical cleanup may still be in progress. + required: + - id + - object + - deleted + additionalProperties: false + description: A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously. + SessionArtifactResource: + type: object + properties: + id: + type: string + minLength: 0 + description: The immutable artifact ID. + object: + type: string + enum: + - agent.session.artifact + default: agent.session.artifact + x-stainless-const: true + description: The object type. Always `agent.session.artifact`. + session_id: + type: string + minLength: 0 + description: The ID of the session that owns the artifact. + environment_id: + type: string + minLength: 0 + description: The ID of the environment that produced the artifact. + turn_id: + type: string + minLength: 0 + description: The ID of the completed turn that published the artifact. + path: + type: string + minLength: 0 + description: The original absolute file path in the execution environment. + size_bytes: + type: integer + format: int64 + minimum: 0 + description: The immutable artifact size in bytes. + created_at: + type: integer + format: int64 + description: The Unix timestamp, in seconds, when the artifact was published. + required: + - id + - object + - session_id + - environment_id + - turn_id + - path + - size_bytes + - created_at + additionalProperties: false + description: An immutable file published by a completed hosted session turn. + SessionArtifactListResource: + type: object + properties: + object: + type: string + enum: + - list + default: list + x-stainless-const: true + description: The object type, which is always `list`. + data: + type: array + items: + $ref: '#/components/schemas/SessionArtifactResource' + minItems: 0 + maxItems: 2000 + description: The resources returned in this page, in the requested sort order. + first_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the first resource in `data`, or `null` if the page is empty. + last_id: + type: + - string + - 'null' + minLength: 0 + description: The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. + has_more: + type: boolean + description: Whether there are more resources to retrieve after this page. + required: + - object + - data + - first_id + - last_id + - has_more + additionalProperties: false + description: A page of Agents API resources, with IDs for retrieving additional pages. + DeletedSessionArtifactResource: + type: object + properties: + id: + type: string + minLength: 0 + description: The ID of the deleted session artifact. + object: + type: string + enum: + - agent.session.artifact.deleted + default: agent.session.artifact.deleted + x-stainless-const: true + description: The object type. Always `agent.session.artifact.deleted`. + deleted: + type: boolean + description: Whether the session artifact was deleted. Always `true`. + required: + - id + - object + - deleted + additionalProperties: false + description: Confirmation that an immutable session artifact was deleted. + BrowserAuthenticationFieldValueParam: + type: object + properties: + field_id: + type: string + minLength: 0 + maxLength: 1048576 + description: The field ID from the required action. + value: + type: string + minLength: 0 + maxLength: 16384 + description: The value to enter into the registered control. + required: + - field_id + - value + additionalProperties: false + description: One user-entered value, including non-password fields such as an email address. + ComputerUseApprovalResponseParamBrowserAuthenticationSubmitParam: + type: object + properties: + type: + type: string + enum: + - browser_authentication + default: browser_authentication + x-stainless-const: true + action: + type: string + enum: + - submit + default: submit + x-stainless-const: true + fields: + type: array + items: + $ref: '#/components/schemas/BrowserAuthenticationFieldValueParam' + minItems: 0 + maxItems: 6 + description: Values for up to six active fields in the required action. The submitted field-value mapping and selected option must fit within 120 KiB of JSON. + selected_option: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The chosen method. Required when the required action contains options. + required: + - type + - action + - fields + additionalProperties: false + ComputerUseApprovalResponseParamBrowserAuthenticationCancelParam: + type: object + properties: + type: + type: string + enum: + - browser_authentication + default: browser_authentication + x-stainless-const: true + action: + type: string + enum: + - cancel + default: cancel + x-stainless-const: true + required: + - type + - action + additionalProperties: false + ComputerUseApprovalResponseParamBrowserAuthentication: + required: + - type + discriminator: + propertyName: action + mapping: + submit: '#/components/schemas/ComputerUseApprovalResponseParamBrowserAuthenticationSubmitParam' + cancel: '#/components/schemas/ComputerUseApprovalResponseParamBrowserAuthenticationCancelParam' + x-oai-discriminator-values: + - submit + - cancel + properties: + type: + type: string + enum: + - browser_authentication + anyOf: + - $ref: '#/components/schemas/ComputerUseApprovalResponseParamBrowserAuthenticationSubmitParam' + - $ref: '#/components/schemas/ComputerUseApprovalResponseParamBrowserAuthenticationCancelParam' + BrowserOriginAccessDecisionParam: + type: string + enum: + - approve + - deny + - cancel + x-enumDescriptions: + - Allow the browser to access this origin. + - Deny access to this origin. + - Dismiss this request without approving access. + description: The user's decision for a browser origin access request. + ComputerUseApprovalResponseParamBrowserOriginAccessParam: type: object properties: type: @@ -92494,6 +94599,76 @@ components: description: The voice used for speech generated by the Live model. $ref: '#/components/schemas/LiveInitialSessionAudioOutputParam' required: [] + LiveDecisionsSettingsInputParam-2: + type: object + properties: + questions: + description: Native Decision API questions evaluated together, in order. + type: array + items: + $ref: '#/components/schemas/QuestionParam' + minItems: 1 + maxItems: 64 + model: + type: string + minLength: 1 + required: + - questions + - model + LiveDecisionsDelegationParam-2: + type: object + properties: + acknowledgement_delay_ms: + description: Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400. Updates apply to subsequent delegations. + type: integer + minimum: 0 + maximum: 800 + type: + default: decisions + x-stainless-const: true + type: string + enum: + - decisions + decisions: + $ref: '#/components/schemas/LiveDecisionsSettingsInputParam-2' + required: + - type + - decisions + LiveDecisionQuestionsInputParam-2: + description: Questions evaluated using the current transcript and the session's shared Decision items. + type: object + properties: + questions: + description: Native Decision API questions evaluated together, in order. + type: array + items: + $ref: '#/components/schemas/QuestionParam' + minItems: 1 + maxItems: 64 + required: + - questions + LiveDecisionTriggerInputParam-2: + type: object + properties: + type: + default: decisions + x-stainless-const: true + type: string + enum: + - decisions + event_type: + type: string + enum: + - session.input_transcript.delta + - session.output_transcript.delta + decisions: + description: Questions evaluated using the current transcript and the session's shared Decision items. + $ref: '#/components/schemas/LiveDecisionQuestionsInputParam-2' + required: + - type + - event_type + - decisions + additionalProperties: false LiveSessionCreateParams: description: Initial configuration for a Live session, including its model, conversation instructions, audio, and delegated task handling. type: object @@ -92524,18 +94699,18 @@ components: - $ref: '#/components/schemas/LiveResponsesDelegationParam' - $ref: '#/components/schemas/LiveDecisionsDelegationParam' - type: 'null' - store: - description: Whether to store the session for later forking and recording download. Defaults to false for new sessions. - type: boolean - client: - description: Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected. - $ref: '#/components/schemas/LiveClientConfigParam' triggers: description: At most one Decisions trigger per transcript event type. Triggers run independently of delegation. On update, omit triggers to keep the current configuration, send a list to replace it, or send an empty list to disable triggers. type: array items: $ref: '#/components/schemas/LiveDecisionTriggerInputParam' maxItems: 2 + store: + description: Whether to store the session for later forking and recording download. Defaults to false for new sessions. + type: boolean + client: + description: Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected. + $ref: '#/components/schemas/LiveClientConfigParam' required: - model LiveSessionStartEvent: @@ -92590,6 +94765,38 @@ components: voice: marin delegation: type: client + LiveDecisionsSettingsUpdateParam: + type: object + properties: + model: + type: string + minLength: 1 + questions: + description: Native Decision API questions evaluated together, in order. + type: array + items: + $ref: '#/components/schemas/QuestionParam' + minItems: 1 + maxItems: 64 + required: [] + LiveDecisionsDelegationUpdateParam: + type: object + properties: + acknowledgement_delay_ms: + description: Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400 for Decisions sessions and 0 (request immediately) for other sessions. Omission in a session update preserves the current value. Updates apply to subsequent delegations. + type: integer + minimum: 0 + maximum: 800 + type: + default: decisions + x-stainless-const: true + type: string + enum: + - decisions + decisions: + $ref: '#/components/schemas/LiveDecisionsSettingsUpdateParam' + required: + - type LiveSessionUpdateParams: description: Changes to an active Live session's delegation settings and transcript triggers. type: object @@ -92707,7 +94914,7 @@ components: type: session.input_audio.mute event_id: evt_mute_001 LiveInputAudioUnmuteParam: - description: Resume audio input to a Live model after muting it. The server acknowledges with `session.input_audio.unmuted`. + description: Resume audio input to a Live model after muting it. The server acknowledges with `session.input_audio.unmuted`. An active audio fixture still pauses inference until playback finishes. example: type: session.input_audio.unmute event_id: evt_unmute_001 @@ -92766,7 +94973,7 @@ components: event_id: evt_play_001 audio: AAAAAA== LiveInstructionsAppendParam: - description: Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation. + description: Append developer instructions to the Live conversation while it is running, optionally associating them with an existing client delegation. Rejected while an audio fixture is active. These instructions remain in conversation history through compaction and are included in future backend delegations. For external audio, describe content already delivered so the assistant does not repeat it. example: type: session.instructions.append event_id: evt_instructions_001 @@ -92807,7 +95014,7 @@ components: delegation_id: null content: The caller prefers outdoor seating. LiveThinkingAppendParam: - description: Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation. + description: Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation. Rejected while an audio fixture is active. example: type: session.thinking.append event_id: evt_thinking_001 @@ -92848,7 +95055,7 @@ components: delegation_id: del_abc123 content: Checking availability for two guests at 7 PM. LiveCommentaryAppendParam: - description: Provide context the Live model can communicate to the user, optionally for an existing client delegation. + description: Provide context the Live model can communicate to the user, optionally for an existing client delegation. Rejected while an audio fixture is active. example: type: session.commentary.append event_id: evt_commentary_001 @@ -92888,6 +95095,189 @@ components: event_id: evt_commentary_001 delegation_id: del_abc123 content: There is an outdoor table for two at 7 PM. Ask whether to reserve it. + LiveDecisionCreateParam: + description: Evaluate the configured questions using the current conversation and Decision inputs. Reusing an event_id is rejected for the lifetime of the session. + example: + type: decision.create + event_id: decision_1 + type: object + properties: + event_id: + type: string + minLength: 1 + maxLength: 256 + type: + default: decision.create + x-stainless-const: true + type: string + enum: + - decision.create + required: + - event_id + - type + x-oaiMeta: + example: + type: decision.create + event_id: decision_1 + LiveDecisionInputTextParam: + type: object + properties: + type: + description: The type of the input item. Always `input_text`. + default: input_text + x-stainless-const: true + type: string + enum: + - input_text + text: + description: The text input to the model. + type: string + maxLength: 10485760 + required: + - type + - text + LiveDetailEnum: + type: string + enum: + - low + - high + - auto + - original + LiveDecisionInputImageParam: + type: object + properties: + type: + description: The type of the input item. Always `input_image`. + default: input_image + x-stainless-const: true + type: string + enum: + - input_image + image_url: + description: An inline image encoded as a data URL. + type: string + maxLength: 20971520 + pattern: '^data:' + detail: + anyOf: + - description: The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + $ref: '#/components/schemas/LiveDetailEnum' + - type: 'null' + required: + - type + - image_url + LiveDecisionInputItemParam: + type: object + properties: + id: + anyOf: + - description: The unique ID of this message item. + type: string + - type: 'null' + type: + default: message + x-stainless-const: true + type: string + enum: + - message + role: + description: The message role. Always `user`. + default: user + x-stainless-const: true + type: string + enum: + - user + content: + anyOf: + - description: The text input to the model. + type: string + maxLength: 10485760 + - type: array + items: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/LiveDecisionInputTextParam' + - $ref: '#/components/schemas/LiveDecisionInputImageParam' + x-stainless-variantName: parts + x-stainless-naming: + java: + variant_constructor: DecisionItemCreateEventItemContentItems + required: + - role + - content + LiveDecisionItemCreateParam: + description: Append an input item for future decisions without starting an evaluation or changing Live voice context. + example: + type: decision.item.create + event_id: browser_1 + item: + type: message + role: user + content: + - type: input_text + text: Wikipedia is open. + type: object + properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' + type: + default: decision.item.create + x-stainless-const: true + type: string + enum: + - decision.item.create + item: + $ref: '#/components/schemas/LiveDecisionInputItemParam' + x-openai-go-skip-union-projection: true + required: + - type + - item + x-oaiMeta: + example: + type: decision.item.create + event_id: browser_1 + item: + type: message + role: user + content: + - type: input_text + text: Wikipedia is open. + LiveDecisionItemDeleteParam: + description: Delete an input item from future decisions without starting an evaluation or changing Live voice context. + example: + type: decision.item.delete + event_id: remove_browser_1 + item_id: msg_browser_1 + type: object + properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' + type: + default: decision.item.delete + x-stainless-const: true + type: string + enum: + - decision.item.delete + item_id: + type: string + minLength: 1 + required: + - type + - item_id + x-oaiMeta: + example: + type: decision.item.delete + event_id: remove_browser_1 + item_id: msg_browser_1 LiveResponseItemCreateParam: description: Add an input item to the Live session’s Responses backend. Requires Responses delegation; use `response.create` to request a response. example: @@ -93067,6 +95457,8 @@ components: - $ref: '#/components/schemas/LiveResponsesDelegationParam' - $ref: '#/components/schemas/LiveDecisionsDelegationParam' - type: 'null' + triggers: + $ref: '#/components/schemas/LiveSessionCreateParams/properties/triggers' store: description: Whether to store the session for later forking and recording download. Defaults to false for new sessions. type: boolean @@ -93086,8 +95478,6 @@ components: type: string enum: - active - triggers: - $ref: '#/components/schemas/LiveSessionCreateParams/properties/triggers' required: - model - id @@ -93228,7 +95618,7 @@ components: max_output_tokens: 1024 tools: [] LiveInputAudioMuted: - description: Returned when a session.input_audio.mute command is accepted. Input audio is no longer sent to the model; sideband audio reflection continues. + description: Acknowledges a session.input_audio.mute command. An independent input mute sends silence to the model and preserves sideband audio reflection. Fixture playback does not emit this event. example: type: session.input_audio.muted event_id: evt_muted_001 @@ -93257,7 +95647,7 @@ components: event_id: evt_muted_001 client_event_id: evt_mute_001 LiveInputAudioUnmuted: - description: Returned when a session.input_audio.unmute command is accepted. Input audio is sent to the model again. + description: Acknowledges a session.input_audio.unmute command, removing the independent input mute. An active audio fixture still pauses inference until playback finishes. Fixture playback does not emit this event. example: type: session.input_audio.unmuted event_id: evt_unmuted_001 @@ -93696,6 +96086,239 @@ components: id: del_abc123 type: delegation target: client + LiveDecisionCompleted: + type: object + properties: + type: + default: decision.completed + x-stainless-const: true + type: string + enum: + - decision.completed + decision: + description: The native Decision API response, including its model, ordered answers, and token usage. + $ref: '#/components/schemas/DecisionResponse' + required: + - type + - decision + LiveDecisionEvent: + description: A Decision API event for a Live delegation or transcript trigger. For a trigger, source_event_id identifies the transcript delta that caused this evaluation. + example: + type: decision.event + event_id: evt_decision_1 + delegation_id: del_abc123 + trigger_id: null + source_event_type: null + source_event_id: null + event: + type: decision.completed + decision: + model: gpt-6-luna + answers: + - type: predicate + name: damaged + probability: 0.95 + usage: + input_tokens: 42 + input_tokens_details: + cached_tokens: 0 + cache_write_tokens: 0 + output_tokens: 0 + output_tokens_details: + reasoning_tokens: 0 + total_tokens: 42 + type: object + properties: + type: + default: decision.event + x-stainless-const: true + type: string + enum: + - decision.event + event_id: + description: The unique ID of this Live server event. + type: string + delegation_id: + anyOf: + - description: The Live delegation ID, or null for a transcript trigger. + type: string + - type: 'null' + trigger_id: + anyOf: + - description: The Live-assigned ID of this trigger firing, or null for a delegation. + type: string + - type: 'null' + source_event_type: + anyOf: + - anyOf: + - default: session.input_transcript.delta + x-stainless-const: true + type: string + enum: + - session.input_transcript.delta + - default: session.output_transcript.delta + x-stainless-const: true + type: string + enum: + - session.output_transcript.delta + - type: 'null' + source_event_id: + anyOf: + - description: The event_id of the transcript delta that fired this trigger, or null for a delegation. + type: string + - type: 'null' + event: + $ref: '#/components/schemas/LiveDecisionCompleted' + required: + - type + - event_id + - delegation_id + - trigger_id + - source_event_type + - source_event_id + - event + x-oaiMeta: + example: + type: decision.event + event_id: evt_decision_1 + delegation_id: del_abc123 + trigger_id: null + source_event_type: null + source_event_id: null + event: + type: decision.completed + decision: + model: gpt-6-luna + answers: + - type: predicate + name: damaged + probability: 0.95 + usage: + input_tokens: 42 + input_tokens_details: + cached_tokens: 0 + cache_write_tokens: 0 + output_tokens: 0 + output_tokens_details: + reasoning_tokens: 0 + total_tokens: 42 + LiveDecisionStoredInputItemParam: + type: object + properties: + id: + description: The ID of the stored Decision input item. + type: string + type: + default: message + x-stainless-const: true + type: string + enum: + - message + role: + description: The message role. Always `user`. + default: user + x-stainless-const: true + type: string + enum: + - user + content: + anyOf: + - description: The text input to the model. + type: string + maxLength: 10485760 + - type: array + items: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/LiveDecisionInputTextParam' + - $ref: '#/components/schemas/LiveDecisionInputImageParam' + x-stainless-variantName: parts + x-stainless-naming: + java: + variant_constructor: DecisionItemCreatedEventItemContentItems + required: + - id + - role + - content + LiveDecisionItemCreated: + description: An input item was appended for future decisions. + example: + type: decision.item.created + event_id: evt_item_1 + client_event_id: browser_1 + item: + id: msg_browser_1 + type: message + role: user + content: + - type: input_text + text: Wikipedia is open. + type: object + properties: + event_id: + description: The unique ID of the Live server event. + type: string + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + type: + default: decision.item.created + x-stainless-const: true + type: string + enum: + - decision.item.created + item: + $ref: '#/components/schemas/LiveDecisionStoredInputItemParam' + required: + - event_id + - type + - item + x-oaiMeta: + example: + type: decision.item.created + event_id: evt_item_1 + client_event_id: browser_1 + item: + id: msg_browser_1 + type: message + role: user + content: + - type: input_text + text: Wikipedia is open. + LiveDecisionItemDeleted: + description: An input item was removed from future decisions. + example: + type: decision.item.deleted + event_id: evt_item_deleted_1 + client_event_id: remove_browser_1 + item_id: msg_browser_1 + type: object + properties: + event_id: + description: The unique ID of the Live server event. + type: string + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + type: + default: decision.item.deleted + x-stainless-const: true + type: string + enum: + - decision.item.deleted + item_id: + type: string + required: + - event_id + - type + - item_id + x-oaiMeta: + example: + type: decision.item.deleted + event_id: evt_item_deleted_1 + client_event_id: remove_browser_1 + item_id: msg_browser_1 LiveResponseEvent: description: A streaming Responses API event from a backend delegated to by the Live session. Use the outer delegation_id to associate the nested stream with its Live delegation. example: @@ -93935,6 +96558,9 @@ components: - type - code - message + x-stainless-naming: + go: + model_name: LiveError LiveErrorEvent: description: Reports an error in the Live session, such as an invalid client command. Use error.client_event_id, when present, to identify the command that caused the error. example: @@ -96563,6 +99189,12 @@ components: description: The breakpoint mode. Always `explicit`. default: explicit x-stainless-const: true + ttl: + type: string + enum: + - 30m + - 12h + description: The minimum lifetime of this cache breakpoint. Defaults to the request TTL. type: object required: - mode @@ -97549,9 +100181,6 @@ components: description: The logs output from the code interpreter. BetaImageGenToolCall: properties: - error: - $ref: '#/components/schemas/BetaImageGenToolCallError' - description: Details of a moderation failure, when available. agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' @@ -97579,6 +100208,10 @@ components: - type: string description: The generated image encoded in base64. - type: 'null' + error: + $ref: '#/components/schemas/BetaImageGenToolCallError' + description: Details of a moderation failure, when available. + x-openai-go-skip-union-projection: true size: anyOf: - anyOf: @@ -97645,6 +100278,51 @@ components: - transparent - opaque - auto + BetaImageGenToolCallError: + properties: + code: + anyOf: + - type: string + description: The error code. + - type: 'null' + type: + type: string + description: The error type. + message: + type: string + description: A description of the error. + param: + anyOf: + - type: string + description: The related request parameter. + - type: 'null' + moderation_details: + $ref: '#/components/schemas/BetaImageGenToolCallModerationDetails' + description: Public details for a `moderation_blocked` error, when available. + type: object + required: + - code + - type + - message + - param + BetaImageGenToolCallModerationDetails: + properties: + moderation_stage: + type: string + enum: + - input + - output + - unknown + description: The stage where moderation blocked the image generation call. + categories: + items: + type: string + type: array + description: Public moderation categories. New category values may be added over time. + type: object + required: + - moderation_stage + - categories BetaCompactionSummaryItemParam: properties: agent: @@ -98368,6 +101046,12 @@ components: description: The breakpoint mode. Always `explicit`. default: explicit x-stainless-const: true + ttl: + type: string + enum: + - 30m + - 12h + description: The minimum lifetime of this cache breakpoint. Defaults to the request TTL. type: object required: - mode @@ -99905,6 +102589,9 @@ components: BetaItemResource: description: | Content item used to generate a response. + x-openai-go-public-shape: + dispatch: + message: '#/components/schemas/BetaOutputMessage' discriminator: propertyName: type anyOf: @@ -101796,6 +104483,16 @@ components: description: | An error object returned when the model fails to generate a Response. properties: + type: + anyOf: + - type: string + - type: 'null' + description: The original error type, or null if it was not recorded. + param: + anyOf: + - type: string + - type: 'null' + description: The request parameter associated with the error, or null if none was recorded. code: $ref: '#/components/schemas/BetaResponseErrorCode' message: @@ -101804,16 +104501,6 @@ components: A human-readable description of the error. misalignment: $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' - param: - anyOf: - - type: string - - type: 'null' - description: The request parameter associated with the error, or null if none was recorded. - type: - anyOf: - - type: string - - type: 'null' - description: The original error type, or null if it was not recorded. required: - code - message @@ -103543,6 +106230,7 @@ components: delta: $ref: '#/components/schemas/BetaShellCallOutputDelta' description: The stdout/stderr delta that was emitted. + x-openai-go-skip-union-projection: true type: object required: - type @@ -106739,880 +109427,255 @@ components: - type: 'null' max_output_tokens: anyOf: - - description: | - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning). - type: integer - minimum: 16 - - type: 'null' - multi_agent: - anyOf: - - $ref: '#/components/schemas/BetaMultiAgentParam' - description: Configuration for server-hosted multi-agent execution. - - type: 'null' - x-openai-go-legacy-bool-fields: - - enabled - BetaMultiAgentParam: - properties: - enabled: - type: boolean - description: Whether to enable server-hosted multi-agent execution for this response. - max_concurrent_subagents: - type: integer - minimum: 1 - description: |- - `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. - type: object - required: - - enabled - description: Configuration for server-hosted multi-agent execution. - x-oai-beta: responses_multi_agent=v1 - BetaContextManagementParam: - properties: - type: - type: string - description: The context management entry type. Currently only 'compaction' is supported. - compact_threshold: - anyOf: - - type: integer - minimum: 1000 - description: Token threshold at which compaction should be triggered for this entry. - - type: 'null' - type: object - required: - - type - BetaResponseStreamOptions: - anyOf: - - description: | - Options for streaming responses. Only set this when you set `stream: true`. - type: object - properties: - include_obfuscation: - type: boolean - description: | - 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. - - type: 'null' - BetaModerationParam: - properties: - model: - type: string - description: The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - policy: - anyOf: - - $ref: '#/components/schemas/BetaModerationPolicyParam' - description: The policy to apply to moderated response input and output. - - type: 'null' - type: object - required: - - model - description: Configuration for running moderation on the input and output of this response. - BetaModerationPolicyParam: - properties: - input: - anyOf: - - $ref: '#/components/schemas/BetaModerationConfigParam' - description: The moderation policy for the response input. - - type: 'null' - output: - anyOf: - - $ref: '#/components/schemas/BetaModerationConfigParam' - description: The moderation policy for the response output. - - type: 'null' - type: object - required: [] - description: The policy to apply to moderated response input and output. - BetaModerationConfigParam: - properties: - mode: - $ref: '#/components/schemas/BetaModerationMode' - type: object - required: - - mode - description: The moderation policy for the response input. - BetaModerationMode: - type: string - enum: - - score - - block - BetaResponsePromptCacheOptionsParam: - properties: - ttl: - $ref: '#/components/schemas/BetaPromptCacheTTLEnum' - description: 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. - mode: - $ref: '#/components/schemas/BetaPromptCacheModeEnum' - description: 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. - prewarm: - type: boolean - description: Prepares the prompt cache without generating output. Defaults to `false`. When set to `true`, overrides the `generate` field to `false`. - comparison_response_id: - anyOf: - - type: string - description: The ID of a response to compare when diagnosing prompt cache reuse. Supplying this field requests prompt cache diagnostics when the feature is enabled. - example: resp_123 - - type: 'null' - type: object - required: [] - title: Prompt cache options - description: 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://developers.openai.com/api/docs/guides/prompt-caching) for current details. - BetaAccessProgramsParam: - properties: - cyber: - $ref: '#/components/schemas/BetaCyberAccessProgramEnum' - description: The Cyber access program to use for this request. Supported values are `standard`, `daybreak_blue`, and `daybreak_red`. If omitted, the API resolves the program from the model's Cyber tier and your organization and project access, subject to model-specific eligibility restrictions. By default, models without a Cyber tier use Standard. Blue-tier models use Daybreak Blue when authorized; otherwise they fall back to Standard unless the model requires Daybreak access. Red-tier models use Daybreak Red and require authorization. Requests that require unavailable Daybreak access return 403. An implicit Standard fallback is represented by null in the response's access_programs field, rather than an explicit Standard selection. - additionalProperties: false - type: object - required: [] - description: Domain-specific access programs to use for this request. - BetaCreateModelResponseProperties: - allOf: - - $ref: '#/components/schemas/BetaModelResponseProperties' - - type: object - properties: - prompt_cache_options: - $ref: '#/components/schemas/BetaPromptCacheOptionsParam' - top_logprobs: - description: | - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. - type: integer - minimum: 0 - maximum: 20 - BetaResponseStreamEvent: - description: Event emitted while a response is streamed. - anyOf: - - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' - - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' - - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' - - $ref: '#/components/schemas/BetaResponseCompletedEvent' - - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' - - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' - - $ref: '#/components/schemas/BetaResponseCreatedEvent' - - $ref: '#/components/schemas/BetaResponseErrorEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' - x-stainless-skip: - - go - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' - - $ref: '#/components/schemas/BetaResponseInProgressEvent' - - $ref: '#/components/schemas/BetaResponseFailedEvent' - - $ref: '#/components/schemas/BetaResponseIncompleteEvent' - - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' - - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' - - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' - - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' - - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' - - $ref: '#/components/schemas/BetaResponseQueuedEvent' - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' - discriminator: - propertyName: type - LiveDecisionChoiceParam: - type: object - properties: - value: - anyOf: - - type: string - - type: boolean - description: - type: string - required: - - value - LiveDecisionChoiceQuestionParam: - type: object - properties: - type: - default: choice - x-stainless-const: true - type: string - enum: - - choice - name: - type: string - instructions: - type: string - choices: - type: array - items: - $ref: '#/components/schemas/LiveDecisionChoiceParam' - minItems: 2 - maxItems: 255 - required: - - type - - instructions - - choices - LiveDecisionPredicateQuestionParam: - type: object - properties: - type: - default: predicate - x-stainless-const: true - type: string - enum: - - predicate - name: - type: string - instructions: - type: string - required: - - type - - instructions - LiveDecisionScoreLevelParam: - type: object - properties: - label: - type: string - description: - type: string - required: - - label - LiveDecisionScoreQuestionParam: - type: object - properties: - type: - default: score - x-stainless-const: true - type: string - enum: - - score - name: - type: string - instructions: - type: string - levels: - type: array - items: - $ref: '#/components/schemas/LiveDecisionScoreLevelParam' - minItems: 2 - maxItems: 10 - required: - - type - - instructions - - levels - LiveDecisionQuestion: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/LiveDecisionChoiceQuestionParam' - - $ref: '#/components/schemas/LiveDecisionPredicateQuestionParam' - - $ref: '#/components/schemas/LiveDecisionScoreQuestionParam' - LiveDecisionsSettingsInputParam: - type: object - properties: - questions: - description: Native Decision API questions evaluated together, in order. - type: array - items: - $ref: '#/components/schemas/QuestionParam' - minItems: 1 - maxItems: 64 - model: - type: string - minLength: 1 - required: - - questions - - model - LiveDecisionsDelegationParam: - type: object - properties: - type: - default: decisions - x-stainless-const: true - type: string - enum: - - decisions - decisions: - $ref: '#/components/schemas/LiveDecisionsSettingsInputParam' - required: - - type - - decisions - LiveDecisionQuestionsInputParam: - description: Questions evaluated using the current transcript and the session's shared Decision items. - type: object - properties: - questions: - description: Native Decision API questions evaluated together, in order. - type: array - items: - $ref: '#/components/schemas/QuestionParam' - minItems: 1 - maxItems: 64 - required: - - questions - LiveDecisionTriggerInputParam: - type: object - properties: - type: - default: decisions - x-stainless-const: true - type: string - enum: - - decisions - event_type: - type: string - enum: - - session.input_transcript.delta - - session.output_transcript.delta - decisions: - description: Questions evaluated using the current transcript and the session's shared Decision items. - $ref: '#/components/schemas/LiveDecisionQuestionsInputParam' - required: - - type - - event_type - - decisions - additionalProperties: false - triggers: - description: At most one Decisions trigger per transcript event type. Triggers run independently of delegation. On update, omit triggers to keep the current configuration, send a list to replace it, or send an empty list to disable triggers. - type: array - items: - $ref: '#/components/schemas/LiveDecisionTriggerInputParam' - maxItems: 2 - LiveDecisionsSettingsInputParam-2: - type: object - properties: - questions: - description: Native Decision API questions evaluated together, in order. - type: array - items: - $ref: '#/components/schemas/QuestionParam' - minItems: 1 - maxItems: 64 - model: - type: string - minLength: 1 - required: - - questions - - model - LiveDecisionsDelegationParam-2: - type: object - properties: - type: - default: decisions - x-stainless-const: true - type: string - enum: - - decisions - decisions: - $ref: '#/components/schemas/LiveDecisionsSettingsInputParam-2' - required: - - type - - decisions - LiveDecisionQuestionsInputParam-2: - description: Questions evaluated using the current transcript and the session's shared Decision items. - type: object - properties: - questions: - description: Native Decision API questions evaluated together, in order. - type: array - items: - $ref: '#/components/schemas/QuestionParam' - minItems: 1 - maxItems: 64 - required: - - questions - LiveDecisionTriggerInputParam-2: - type: object - properties: - type: - default: decisions - x-stainless-const: true - type: string - enum: - - decisions - event_type: - type: string - enum: - - session.input_transcript.delta - - session.output_transcript.delta - decisions: - description: Questions evaluated using the current transcript and the session's shared Decision items. - $ref: '#/components/schemas/LiveDecisionQuestionsInputParam-2' - required: - - type - - event_type - - decisions - additionalProperties: false - LiveDecisionsSettingsUpdateParam: - type: object - properties: - model: - type: string - minLength: 1 - questions: - description: Native Decision API questions evaluated together, in order. - type: array - items: - $ref: '#/components/schemas/QuestionParam' - minItems: 1 - maxItems: 64 - required: [] - LiveDecisionsDelegationUpdateParam: - type: object - properties: - type: - default: decisions - x-stainless-const: true - type: string - enum: - - decisions - decisions: - $ref: '#/components/schemas/LiveDecisionsSettingsUpdateParam' - required: - - type - LiveDecisionCreateParam: - description: Evaluate the configured questions using the current conversation and Decision inputs. Reusing an event_id is rejected for the lifetime of the session. - example: - type: decision.create - event_id: decision_1 - type: object - properties: - event_id: - type: string - minLength: 1 - maxLength: 256 - type: - default: decision.create - x-stainless-const: true - type: string - enum: - - decision.create - required: - - event_id - - type - x-oaiMeta: - example: - type: decision.create - event_id: decision_1 - LiveDecisionInputTextParam: - type: object - properties: - type: - description: The type of the input item. Always `input_text`. - default: input_text - x-stainless-const: true - type: string - enum: - - input_text - text: - description: The text input to the model. - type: string - maxLength: 10485760 - required: - - type - - text - LiveDetailEnum: - type: string - enum: - - low - - high - - auto - - original - LiveDecisionInputImageParam: - type: object - properties: - type: - description: The type of the input item. Always `input_image`. - default: input_image - x-stainless-const: true - type: string - enum: - - input_image - image_url: - description: An inline image encoded as a data URL. - type: string - maxLength: 20971520 - pattern: '^data:' - detail: - anyOf: - - description: The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - $ref: '#/components/schemas/LiveDetailEnum' - - type: 'null' - required: - - type - - image_url - LiveDecisionInputItemParam: - type: object - properties: - id: - anyOf: - - description: The unique ID of this message item. - type: string - - type: 'null' - type: - default: message - x-stainless-const: true - type: string - enum: - - message - role: - description: The message role. Always `user`. - default: user - x-stainless-const: true - type: string - enum: - - user - content: - anyOf: - - description: The text input to the model. - type: string - maxLength: 10485760 - - type: array - items: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/LiveDecisionInputTextParam' - - $ref: '#/components/schemas/LiveDecisionInputImageParam' - x-stainless-variantName: parts - required: - - role - - content - LiveDecisionItemCreateParam: - description: Append an input item for future decisions without starting an evaluation or changing Live voice context. - example: - type: decision.item.create - event_id: browser_1 - item: - type: message - role: user - content: - - type: input_text - text: Wikipedia is open. - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - default: decision.item.create - x-stainless-const: true - type: string - enum: - - decision.item.create - item: - $ref: '#/components/schemas/LiveDecisionInputItemParam' - required: - - type - - item - x-oaiMeta: - example: - type: decision.item.create - event_id: browser_1 - item: - type: message - role: user - content: - - type: input_text - text: Wikipedia is open. - LiveDecisionItemDeleteParam: - description: Delete an input item from future decisions without starting an evaluation or changing Live voice context. - example: - type: decision.item.delete - event_id: remove_browser_1 - item_id: msg_browser_1 - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - default: decision.item.delete - x-stainless-const: true - type: string - enum: - - decision.item.delete - item_id: - type: string - minLength: 1 - required: - - type - - item_id - x-oaiMeta: - example: - type: decision.item.delete - event_id: remove_browser_1 - item_id: msg_browser_1 - LiveDecisionCompleted: - type: object - properties: - type: - default: decision.completed - x-stainless-const: true - type: string - enum: - - decision.completed - decision: - description: The native Decision API response, including its model, ordered answers, and token usage. - $ref: '#/components/schemas/DecisionResponse' - required: - - type - - decision - LiveDecisionEvent: - description: A Decision API event for a Live delegation or transcript trigger. For a trigger, source_event_id identifies the transcript delta that caused this evaluation. - example: - type: decision.event - event_id: evt_decision_1 - delegation_id: del_abc123 - trigger_id: null - source_event_type: null - source_event_id: null - event: - type: decision.completed - decision: - model: gpt-6-luna - answers: - - type: predicate - name: damaged - probability: 0.95 - usage: - input_tokens: 42 - input_tokens_details: - cached_tokens: 0 - cache_write_tokens: 0 - output_tokens: 0 - output_tokens_details: - reasoning_tokens: 0 - total_tokens: 42 + - description: | + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning). + type: integer + minimum: 16 + - type: 'null' + multi_agent: + anyOf: + - $ref: '#/components/schemas/BetaMultiAgentParam' + description: Configuration for server-hosted multi-agent execution. + - type: 'null' + x-openai-go-legacy-bool-fields: + - enabled + BetaMultiAgentParam: + properties: + enabled: + type: boolean + description: Whether to enable server-hosted multi-agent execution for this response. + max_concurrent_subagents: + type: integer + minimum: 1 + description: |- + `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. type: object + required: + - enabled + description: Configuration for server-hosted multi-agent execution. + x-oai-beta: responses_multi_agent=v1 + BetaContextManagementParam: properties: type: - default: decision.event - x-stainless-const: true - type: string - enum: - - decision.event - event_id: - description: The unique ID of this Live server event. type: string - delegation_id: + description: The context management entry type. Currently only 'compaction' is supported. + compact_threshold: anyOf: - - description: The Live delegation ID, or null for a transcript trigger. - type: string + - type: integer + minimum: 1000 + description: Token threshold at which compaction should be triggered for this entry. - type: 'null' - trigger_id: + type: object + required: + - type + BetaResponseStreamOptions: + anyOf: + - description: | + Options for streaming responses. Only set this when you set `stream: true`. + type: object + properties: + include_obfuscation: + type: boolean + description: | + 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. + - type: 'null' + BetaModerationParam: + properties: + model: + type: string + description: The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + policy: anyOf: - - description: The Live-assigned ID of this trigger firing, or null for a delegation. - type: string + - $ref: '#/components/schemas/BetaModerationPolicyParam' + description: The policy to apply to moderated response input and output. - type: 'null' - source_event_type: + type: object + required: + - model + description: Configuration for running moderation on the input and output of this response. + BetaModerationPolicyParam: + properties: + input: anyOf: - - anyOf: - - default: session.input_transcript.delta - x-stainless-const: true - type: string - enum: - - session.input_transcript.delta - - default: session.output_transcript.delta - x-stainless-const: true - type: string - enum: - - session.output_transcript.delta + - $ref: '#/components/schemas/BetaModerationConfigParam' + description: The moderation policy for the response input. - type: 'null' - source_event_id: + output: anyOf: - - description: The event_id of the transcript delta that fired this trigger, or null for a delegation. - type: string + - $ref: '#/components/schemas/BetaModerationConfigParam' + description: The moderation policy for the response output. - type: 'null' - event: - $ref: '#/components/schemas/LiveDecisionCompleted' - required: - - type - - event_id - - delegation_id - - trigger_id - - source_event_type - - source_event_id - - event - x-oaiMeta: - example: - type: decision.event - event_id: evt_decision_1 - delegation_id: del_abc123 - trigger_id: null - source_event_type: null - source_event_id: null - event: - type: decision.completed - decision: - model: gpt-6-luna - answers: - - type: predicate - name: damaged - probability: 0.95 - usage: - input_tokens: 42 - input_tokens_details: - cached_tokens: 0 - cache_write_tokens: 0 - output_tokens: 0 - output_tokens_details: - reasoning_tokens: 0 - total_tokens: 42 - LiveDecisionStoredInputItemParam: type: object + required: [] + description: The policy to apply to moderated response input and output. + BetaModerationConfigParam: properties: - id: - description: The ID of the stored Decision input item. - type: string - type: - default: message - x-stainless-const: true - type: string - enum: - - message - role: - description: The message role. Always `user`. - default: user - x-stainless-const: true - type: string - enum: - - user - content: - anyOf: - - description: The text input to the model. - type: string - maxLength: 10485760 - - type: array - items: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/LiveDecisionInputTextParam' - - $ref: '#/components/schemas/LiveDecisionInputImageParam' - x-stainless-variantName: parts + mode: + $ref: '#/components/schemas/BetaModerationMode' + type: object required: - - id - - role - - content - LiveDecisionItemCreated: - description: An input item was appended for future decisions. - example: - type: decision.item.created - event_id: evt_item_1 - client_event_id: browser_1 - item: - id: msg_browser_1 - type: message - role: user - content: - - type: input_text - text: Wikipedia is open. + - mode + description: The moderation policy for the response input. + BetaModerationMode: + type: string + enum: + - score + - block + BetaResponsePromptCacheOptionsParam: + properties: + ttl: + $ref: '#/components/schemas/BetaPromptCacheTTLEnum' + description: 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. + mode: + $ref: '#/components/schemas/BetaPromptCacheModeEnum' + description: 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. + prewarm: + type: boolean + description: Prepares the prompt cache without generating output. Defaults to `false`. When set to `true`, overrides the `generate` field to `false`. + comparison_response_id: + anyOf: + - type: string + description: The ID of a response to compare when diagnosing prompt cache reuse. Supplying this field requests prompt cache diagnostics when the feature is enabled. + example: resp_123 + - type: 'null' type: object + required: [] + title: Prompt cache options + description: 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://developers.openai.com/api/docs/guides/prompt-caching) for current details. + BetaAccessProgramsParam: properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - default: decision.item.created - x-stainless-const: true - type: string - enum: - - decision.item.created - item: - $ref: '#/components/schemas/LiveDecisionStoredInputItemParam' + cyber: + $ref: '#/components/schemas/BetaCyberAccessProgramEnum' + description: The Cyber access program to use for this request. Supported values are `standard`, `daybreak_blue`, and `daybreak_red`. If omitted, the API resolves the program from the model's Cyber tier and your organization and project access, subject to model-specific eligibility restrictions. By default, models without a Cyber tier use Standard. Blue-tier models use Daybreak Blue when authorized; otherwise they fall back to Standard unless the model requires Daybreak access. Red-tier models use Daybreak Red and require authorization. Requests that require unavailable Daybreak access return 403. An implicit Standard fallback is represented by null in the response's access_programs field, rather than an explicit Standard selection. + additionalProperties: false + type: object + required: [] + description: Domain-specific access programs to use for this request. + BetaCreateModelResponseProperties: + allOf: + - $ref: '#/components/schemas/BetaModelResponseProperties' + - type: object + properties: + prompt_cache_options: + $ref: '#/components/schemas/BetaPromptCacheOptionsParam' + top_logprobs: + description: | + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + type: integer + minimum: 0 + maximum: 20 + BetaResponseStreamEvent: + description: Event emitted while a response is streamed. + anyOf: + - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' + - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' + - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' + - $ref: '#/components/schemas/BetaResponseCompletedEvent' + - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' + - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' + - $ref: '#/components/schemas/BetaResponseCreatedEvent' + - $ref: '#/components/schemas/BetaResponseErrorEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' + x-stainless-skip: + - go + x-openai-go-include-union-variant: true + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' + - $ref: '#/components/schemas/BetaResponseInProgressEvent' + - $ref: '#/components/schemas/BetaResponseFailedEvent' + - $ref: '#/components/schemas/BetaResponseIncompleteEvent' + - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' + - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' + - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' + - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' + - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' + - $ref: '#/components/schemas/BetaResponseQueuedEvent' + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' + discriminator: + propertyName: type + SessionSpendControlResource: + type: object + properties: + limit: + type: integer + format: int64 + minimum: 1 + maximum: 4503599627370495 + description: The configured positive limit in USD cents. + consumed: + type: + - integer + - 'null' + minimum: 0 + description: Best-effort recorded spend floored to whole USD cents, or null when unavailable. required: - - event_id - - type - - item - x-oaiMeta: - example: - type: decision.item.created - event_id: evt_item_1 - client_event_id: browser_1 - item: - id: msg_browser_1 - type: message - role: user - content: - - type: input_text - text: Wikipedia is open. - LiveDecisionItemDeleted: - description: An input item was removed from future decisions. - example: - type: decision.item.deleted - event_id: evt_item_deleted_1 - client_event_id: remove_browser_1 - item_id: msg_browser_1 + - limit + - consumed + additionalProperties: false + description: Session-wide spending control, present only when a limit is configured. + SessionSpendControlParam: type: object properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - default: decision.item.deleted - x-stainless-const: true - type: string - enum: - - decision.item.deleted - item_id: - type: string + limit: + type: + - integer + - 'null' + format: int64 + minimum: 1 + maximum: 4503599627370495 + description: Positive USD cents, or null to remove the limit. required: - - event_id - - type - - item_id - x-oaiMeta: - example: - type: decision.item.deleted - event_id: evt_item_deleted_1 - client_event_id: remove_browser_1 - item_id: msg_browser_1 + - limit + additionalProperties: false + description: Sets the session-wide limit without changing recorded spend. DecisionPromptCacheBreakpoint: type: object properties: @@ -107628,80 +109691,24 @@ components: additionalProperties: false title: Prompt cache breakpoint description: Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - CreateVoicePromptRequest: - type: object - title: Prompt - description: Creates a synthetic voice from a text description. Supports application/json or multipart/form-data. - additionalProperties: false - properties: - type: - type: string - enum: - - prompt - description: Set to `prompt` to create a voice from a text description. - name: - type: string - minLength: 1 - maxLength: 256 - description: The name of the new voice. - prompt: - type: string - minLength: 1 - maxLength: 2000 - description: A description of the desired voice. Must not contain only whitespace. - script_hint: - type: string - minLength: 1 - maxLength: 2000 - description: Optional text for the voice to speak during creation. If omitted, a script is generated from the prompt. Must not be blank after trimming whitespace; scripts that are too short are rejected. - model: - anyOf: - - type: string - - type: string - enum: - - auto - - 2026-10-08 - default: auto - description: The voice creation model to use. Defaults to `auto`. - required: - - type - - name - - prompt - VoiceDeletedResource: - type: object - additionalProperties: false - properties: - id: - type: string - description: The voice identifier. - example: voice_1234 - object: - type: string - enum: - - audio.voice.deleted - x-stainless-const: true - description: The object type, which is always `audio.voice.deleted`. - deleted: - type: boolean - description: Whether the voice was deleted. - required: - - id - - object - - deleted - x-oaiMeta: - name: The voice deletion object - example: | - { - "id": "voice_1234", - "object": "audio.voice.deleted", - "deleted": true - } OAuthErrorCode: anyOf: - enum: - invalid_grant - invalid_subject_token - type: string + AutomationMetadataParam: + type: object + additionalProperties: + type: string + minLength: 0 + maxLength: 512 + propertyNames: + type: string + minLength: 1 + maxLength: 64 + minProperties: 0 + maxProperties: 16 ResponseSteerInputContent: discriminator: propertyName: type @@ -107938,6 +109945,28 @@ components: - gpt-3.5-turbo-0125 - gpt-3.5-turbo-16k-0613 x-openai-enum-deprecations: + gpt-5.4-nano: + message: 'Announced shutdown date: 2027-04-01. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-5.1: + message: 'Announced shutdown date: 2027-04-01. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-4.1-2025-04-14: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-4.1: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-4.1-mini: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-4.1-mini-2025-04-14: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-4o: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-4o-2024-08-06: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-4o-2024-11-20: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-4o-mini: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' + gpt-4o-mini-2024-07-18: + message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' gpt-5.3-chat-latest: message: 'Announced shutdown date: 2026-08-10. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' gpt-5.2-chat-latest: @@ -108058,28 +110087,6 @@ components: message: 'Announced shutdown date: 2027-01-20. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' gpt-5.1-mini: message: Not a supported model ID. Retained for SDK compatibility. - gpt-4.1-2025-04-14: - message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' - gpt-4.1-mini-2025-04-14: - message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' - gpt-4o-2024-08-06: - message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' - gpt-4o-2024-11-20: - message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' - gpt-4o-mini-2024-07-18: - message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' - gpt-5.1: - message: 'Announced shutdown date: 2027-04-01. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' - gpt-5.4-nano: - message: 'Announced shutdown date: 2027-04-01. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' - gpt-4.1: - message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' - gpt-4.1-mini: - message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' - gpt-4o: - message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' - gpt-4o-mini: - message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.' x-stainless-nominal: false LiveBuiltInVoice: type: string diff --git a/scripts/castiron/custom_code_policy.py b/scripts/castiron/custom_code_policy.py index 65cec8053e..59314c434c 100755 --- a/scripts/castiron/custom_code_policy.py +++ b/scripts/castiron/custom_code_policy.py @@ -221,6 +221,61 @@ def require_human_policy_review(repository: str, head: str) -> int: return int(pull["number"]) +def requires_human_policy_review( + repo: Path, repository: str, base: str, head: str, authenticated_main: str +) -> bool: + """Decide review requirements from Git data using the selector's policy rules.""" + base_policy = read_policy(repo, base) + candidate_policy = read_policy(repo, head) + candidate_base_policy = read_policy(repo, merge_base(repo, base, head)) + budget_increased = ( + candidate_policy["max_custom_patch_lines"] > candidate_base_policy["max_custom_patch_lines"] + ) + ratchet_activated = ( + candidate_policy.get("ratchet") == "go" and candidate_base_policy.get("ratchet") != "go" + ) + pin_changed = candidate_policy.get("next_policy") != candidate_base_policy.get("next_policy") + if not pin_changed: + return budget_increased or ratchet_activated + policy = ( + next_policy_sha(repo, repository, base, authenticated_main) + if "next_policy" in base_policy + else authenticated_main + ) + candidate = head + proposed = read_policy(repo, next_policy_sha(repo, repository, candidate, authenticated_main)) + # Authored changes come from the merge base, but their safety must be + # measured against the active policy: the protected target's pin, or + # authenticated main during bootstrap. + previous = read_policy(repo, policy) + # Bootstrap executes authenticated main; initial adoption must not silently + # replace it with older checker code, even when policy fields match. + previous_checker = ( + base_policy["next_policy"]["main_sha"] + if "next_policy" in base_policy + else authenticated_main + ) + rolled_back = bool( + report.git( + repo, + "rev-list", + "--first-parent", + f"{candidate_policy['next_policy']['main_sha']}..{previous_checker}", + ).strip() + ) + # Compare effective policies, not the candidate's unchanged local ceiling. + # Schema/strictness or ratchet transitions also retain human authorization. + pin_requires_human = ( + not supports_effective_pin_review(repo, previous_checker) + or rolled_back + or proposed["max_custom_patch_lines"] > previous["max_custom_patch_lines"] + or proposed["schema_version"] != previous["schema_version"] + or proposed.get("generated_files") != previous.get("generated_files") + or proposed.get("ratchet") != previous.get("ratchet") + ) + return budget_increased or ratchet_activated or pin_requires_human + + def select_policy( repo: Path, repository: str, @@ -286,41 +341,7 @@ def select_policy( repo, base, candidate ) != {POLICY.encode()}: raise ValueError("each next policy activation or increase must be policy-only") - pin_requires_human = False - if pin_changed: - proposed = read_policy( - repo, next_policy_sha(repo, repository, candidate, authenticated_main) - ) - # Authored changes come from the merge base, but their safety must be - # measured against the active policy: the protected target's pin, or - # authenticated main during bootstrap. - previous = read_policy(repo, policy) - # Bootstrap executes authenticated main; initial adoption must not silently - # replace it with older checker code, even when policy fields match. - previous_checker = ( - base_policy["next_policy"]["main_sha"] - if "next_policy" in base_policy - else authenticated_main - ) - rolled_back = bool( - report.git( - repo, - "rev-list", - "--first-parent", - f"{candidate_policy['next_policy']['main_sha']}..{previous_checker}", - ).strip() - ) - # Compare effective policies, not the candidate's unchanged local ceiling. - # Schema/strictness or ratchet transitions also retain human authorization. - pin_requires_human = ( - not supports_effective_pin_review(repo, previous_checker) - or rolled_back - or proposed["max_custom_patch_lines"] > previous["max_custom_patch_lines"] - or proposed["schema_version"] != previous["schema_version"] - or proposed.get("generated_files") != previous.get("generated_files") - or proposed.get("ratchet") != previous.get("ratchet") - ) - if budget_increased or ratchet_activated or pin_requires_human: + if requires_human_policy_review(repo, repository, base, candidate, authenticated_main): number = require_human_policy_review(repository, candidate) policy_reviews.append({"number": number, "head_sha": candidate}) return { @@ -509,6 +530,12 @@ def queued_entries(repository: str, branch: str) -> list[tuple[str, str]]: def main(argv: list[str] | None = None) -> int: parser = argparse.ArgumentParser(description=__doc__) commands = parser.add_subparsers(dest="command", required=True) + review = commands.add_parser("review-required") + review.add_argument("--repo", type=Path, required=True) + review.add_argument("--repository", required=True) + review.add_argument("--base", required=True) + review.add_argument("--head", required=True) + review.add_argument("--main", required=True) selection = commands.add_parser("select-policy") selection.add_argument("--repo", type=Path, required=True) selection.add_argument("--repository", required=True) @@ -521,6 +548,39 @@ def main(argv: list[str] | None = None) -> int: default=".github/workflows/castiron-custom-code.yml", ) args = parser.parse_args(argv) + if args.command == "review-required": + if not report.REPOSITORY.fullmatch(args.repository): + raise ValueError("invalid policy repository") + base, head, main = map(report.require_sha, (args.base, args.head, args.main)) + if args.repo.exists(): + raise ValueError("policy object directory must be fresh") + args.repo.mkdir() + report.git(args.repo, "init", "--quiet", "--bare") + report.git( + args.repo, "remote", "add", "origin", f"https://github.com/{args.repository}.git" + ) + report.git( + args.repo, + "fetch", + "--quiet", + "--no-tags", + "origin", + "+refs/heads/main:refs/remotes/origin/main", + base, + head, + ) + if report.git(args.repo, "rev-parse", "refs/remotes/origin/main").decode().strip() != main: + raise ValueError("authenticated main changed during review evaluation; retry") + print( + json.dumps( + { + "requires_human": requires_human_policy_review( + args.repo, args.repository, base, head, main + ) + } + ) + ) + return 0 selected = select_github_policy( args.repo, args.repository, diff --git a/scripts/castiron/custom_code_test_support.py b/scripts/castiron/custom_code_test_support.py index bd7f1885d3..9db89fd564 100644 --- a/scripts/castiron/custom_code_test_support.py +++ b/scripts/castiron/custom_code_test_support.py @@ -9,7 +9,7 @@ import tempfile import unittest from pathlib import Path -from typing import Any +from typing import Any, cast import custom_code_report as report @@ -73,3 +73,30 @@ def source_run(head: str, event: str = "pull_request") -> dict[str, Any]: "pull_requests": [{"number": 3}] if event == "pull_request" else [], "conclusion": "failure", # The candidate's result is deliberately ignored. } + + +WORKFLOW = ( + Path(__file__).resolve().parents[2] / ".github/workflows/castiron-custom-code-comment.yml" +) + + +def run_publisher(step: str, payload: dict[str, Any]) -> list[dict[str, Any]]: + section = WORKFLOW.read_text().split(f"- name: {step}\n", 1)[1] + script = section.split(" script: |\n", 1)[1] + lines: list[str] = [] + for line in script.splitlines(): + if line and not line.startswith(" "): + break + lines.append(line[12:]) + return run_workflow_script("\n".join(lines), payload) + + +def run_workflow_script(script: str, payload: dict[str, Any]) -> list[dict[str, Any]]: + output = subprocess.run( + ["node", str(Path(__file__).with_name("fixtures") / "github_publisher.cjs")], + input=json.dumps({**payload, "script": script}), + text=True, + capture_output=True, + check=True, + ) + return cast(list[dict[str, Any]], json.loads(output.stdout)) diff --git a/scripts/castiron/fixtures/github_publisher.cjs b/scripts/castiron/fixtures/github_publisher.cjs index 69664de46d..c831f52970 100644 --- a/scripts/castiron/fixtures/github_publisher.cjs +++ b/scripts/castiron/fixtures/github_publisher.cjs @@ -47,36 +47,28 @@ const github = { }), }, repos: { - getCommit: async () => ({ data: data.merge_commit }), - compareCommitsWithBasehead: async ({ basehead }) => ({ - data: data.comparisons?.[basehead] || { - merge_base_commit: { sha: basehead.split('...')[0] }, - }, - }), getContent: async ({ path, ref }) => { - let source; - if (path === 'scripts/castiron/custom_code_policy.py') { - if (data.checker_lookup_error) - throw Object.assign(new Error('Checker lookup failed'), { - status: data.checker_lookup_error, - }); - source = data.checker_sources_by_sha?.[ref]; - if (typeof source !== 'string') throw Object.assign(new Error('Missing checker'), { status: 404 }); - } else if (path === '.castiron-ratchet.json' && data.policies_by_sha?.[ref]) { - source = JSON.stringify(data.policies_by_sha[ref]); - } else { - throw new Error('Unexpected policy lookup'); - } - const content = Buffer.from(source); + if ( + !['scripts/castiron/custom_code_policy.py', 'scripts/castiron/custom_code_report.py'].includes(path) + ) + throw new Error('Unexpected trusted policy path'); + const content = Buffer.from(JSON.stringify({ ref, path })); return { data: { type: 'file', encoding: 'base64', size: content.length, content: content.toString('base64'), + ...(data.policy_file_override || {}), }, }; }, + getCommit: async () => ({ data: data.merge_commit }), + compareCommitsWithBasehead: async ({ basehead }) => ({ + data: data.comparisons?.[basehead] || { + merge_base_commit: { sha: basehead.split('...')[0] }, + }, + }), createCommitStatus: async (value) => { writes.push(value); data.statuses_by_sha ||= {}; @@ -138,12 +130,45 @@ const github = { throw new Error(`Unexpected GitHub lookup: ${method}`); }, }; +const exec = { + getExecOutput: async (command, args) => { + if ( + command !== 'python3' || + args[0] !== '-I' || + require('node:path').basename(args[1]) !== 'custom_code_policy.py' || + args[2] !== 'review-required' || + args[3] !== '--repository' || + args[4] !== 'openai/example' || + args[5] !== '--repo' || + args[7] !== '--base' || + args[9] !== '--head' || + args[11] !== '--main' || + ![args[8], args[10], args[12]].every((value) => /^[0-9a-f]{40}$/.test(value)) + ) { + throw new Error('Unexpected trusted policy invocation'); + } + for (const name of ['custom_code_policy.py', 'custom_code_report.py']) { + const file = require('node:path').join(require('node:path').dirname(args[1]), name); + const source = JSON.parse(fs.readFileSync(file, 'utf8')); + if (source.ref !== args[12] || source.path !== `scripts/castiron/${name}`) + throw new Error('Executed stale or mismatched trusted policy'); + } + if (data.policy_error_sequence?.shift() || data.policy_error) + throw new Error('Trusted policy evaluation failed'); + return { + stdout: JSON.stringify({ + requires_human: data.requires_human_by_main?.[args[12]] ?? data.requires_human ?? true, + }), + }; + }, +}; const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor; -new AsyncFunction('github', 'context', 'process', 'require', data.script)( +new AsyncFunction('github', 'context', 'process', 'require', 'exec', data.script)( github, data.context, - { env: data.env || {} }, + { env: { RUNNER_TEMP: require('node:os').tmpdir(), ...(data.env || {}) } }, require, + exec, ) .then(() => process.stdout.write(JSON.stringify(writes))) .catch((error) => { diff --git a/scripts/castiron/generated-files.json b/scripts/castiron/generated-files.json index 0b9e2ba745..eb69584464 100644 --- a/scripts/castiron/generated-files.json +++ b/scripts/castiron/generated-files.json @@ -3,7 +3,7 @@ "files": { ".github/workflows/castiron-custom-code-comment.yml": { "mode": "100644", - "sha256": "87fdffd260f458095f3a0e13e1290a80d9ce484e516092b7fbf5f34fb3847fb3" + "sha256": "bdde9eec1ff9c0e842ddc0f69df5611ad4eb0336602489e2dcddfbcf8ad86e37" }, ".github/workflows/castiron-custom-code.yml": { "mode": "100644", @@ -11,7 +11,7 @@ }, "api.md": { "mode": "100644", - "sha256": "7f3ace74d18fd67547db65e2ce65295ffacb6e834096192dd30debfcf9378447" + "sha256": "fc38e1d873ac4544fa16fe74478a228d86058ad681f2c7b939dff463015c928b" }, "scripts/castiron/CUSTOM_CODE.md": { "mode": "100644", @@ -27,7 +27,7 @@ }, "scripts/castiron/custom_code_policy.py": { "mode": "100755", - "sha256": "c78f07ddab38a9c9b4724fad4ba8cdd21626a03319f4f48ebc3c11b292f546cc" + "sha256": "e16c211407c9d236e3bdf0c00a5fe252e4509a14a0fdfe4dacbb891e33a55c57" }, "scripts/castiron/custom_code_report.py": { "mode": "100755", @@ -35,11 +35,11 @@ }, "scripts/castiron/custom_code_test_support.py": { "mode": "100644", - "sha256": "15b2c1243f1cbec53b73707e5806a8566d40f78763fe85c4ab7dc48bc1405a6c" + "sha256": "8fc5147352025e2c874ae855ac8f3ac649d531d2c1bd80c532bc4e9ec4fafa3f" }, "scripts/castiron/fixtures/github_publisher.cjs": { "mode": "100644", - "sha256": "232fd17ff25eb0680f71f82a04d210e9b2da4dd7fae6071058dc7108e3deecc6" + "sha256": "162963b9a13c24443ac1a97f852f269fcde5fb011a0871d428f4585cbaac2dab" }, "scripts/castiron/ruff.toml": { "mode": "100644", @@ -55,16 +55,20 @@ }, "scripts/castiron/test_custom_code_policy.py": { "mode": "100644", - "sha256": "3afb8ebe20bb82661b3fc7772717e4454e7e9655c51f967f577b37da7311a071" + "sha256": "a9b4dcabec71c66e1e280fd54f46f78eea9bc664f8dca500f5da418e27114602" }, "scripts/castiron/test_custom_code_publication.py": { "mode": "100644", - "sha256": "dc4492599c1c1b6cf9403b200ab105de10cc95ba91a45e566eb1bb673024d9fa" + "sha256": "0e7628d6906153029fea156273094a3d0b17846abd0894a91ab0833241bfdf31" }, "scripts/castiron/test_custom_code_report.py": { "mode": "100644", "sha256": "f4d90fd38b17aac59096488391b65ef9da5493d2049d4c038d5926a960257ca7" }, + "scripts/castiron/test_custom_code_review_revocation.py": { + "mode": "100644", + "sha256": "6d971965f6b4da770f4d49b3587dbd136c5be549453ae0d220150fc537b2736a" + }, "src/client.ts": { "mode": "100644", "sha256": "2c261bd7faffbd847f45acaa5f0dbd433764b638431ad05d4e841cae6061b0f5" @@ -307,7 +311,7 @@ }, "src/resources/audio/voices.ts": { "mode": "100644", - "sha256": "d1fbc87fc02c984f534203a739fa1272b11a4ee8ccc5cf40a990b44d6b2795d9" + "sha256": "c6a233088632dd5820a53e14c27de571b450d6ab05b960c2089697ec098cc603" }, "src/resources/batches.ts": { "mode": "100644", @@ -323,7 +327,23 @@ }, "src/resources/beta/agents/agents.ts": { "mode": "100644", - "sha256": "1e5e5c580f3d9b928f5bad05f145ccd9ac4f4ceeec1d34cf3ff0c8936a33d2ca" + "sha256": "714c91057ad64df6c1697d1fd27cf66349e032356392bbb00cadd440536dd355" + }, + "src/resources/beta/agents/automations.ts": { + "mode": "100644", + "sha256": "5557d5672ce886f05b89f04a4dbc8b6a4313165b95dd351af44bc5153398dcdb" + }, + "src/resources/beta/agents/automations/automations.ts": { + "mode": "100644", + "sha256": "f897ac6633a772a6678c3535b4ae10fbe4fb21f0cd016e748c22bf675905552b" + }, + "src/resources/beta/agents/automations/index.ts": { + "mode": "100644", + "sha256": "a40c3446eee900d7e6a28c74e2f02687ea0d333d4e456c71538d19effabc231b" + }, + "src/resources/beta/agents/automations/invocations.ts": { + "mode": "100644", + "sha256": "5dd1cdfde23803e372609af76f768ba4c25422baf88fa8559bd4a255d4e6a125" }, "src/resources/beta/agents/environments.ts": { "mode": "100644", @@ -347,7 +367,7 @@ }, "src/resources/beta/agents/index.ts": { "mode": "100644", - "sha256": "86edb99c6fede18d53f419b5d34455c9374789588d7f458e0eb694506cb844bb" + "sha256": "1e23637b879d65c36e63da969b10d6020c69dc6554ee174c08429cd69e91a0de" }, "src/resources/beta/agents/sessions.ts": { "mode": "100644", @@ -495,7 +515,7 @@ }, "src/resources/beta/responses/responses.ts": { "mode": "100644", - "sha256": "0703481b89557b35549b81e5be3e885c533d085523a9e059b98c981e1f48ba27" + "sha256": "4e6f9124bb4e9b73276e1179ead22dde793146a567b9b9b3d4382c12550006fa" }, "src/resources/beta/responses/ws-base.ts": { "mode": "100644", @@ -551,7 +571,7 @@ }, "src/resources/chat/completions/completions.ts": { "mode": "100644", - "sha256": "a3a03f20a836ffd33fd6403f324bfbe5447c565fdabbc178f8121c91bfe80f60" + "sha256": "f94193ba2e17d801992740f0ba7097f27895ca6b72865b0c61fd63a4e9cd8f47" }, "src/resources/chat/completions/index.ts": { "mode": "100644", @@ -611,7 +631,7 @@ }, "src/resources/conversations/conversations.ts": { "mode": "100644", - "sha256": "b07f01f0cea6bf4294e274952213537de1b5ee5a7359e2020a95a1d3850e200e" + "sha256": "33af13247dc5afa3add17ae5efba07cd26dfb41f9096bab90f0c6aa4814189c6" }, "src/resources/conversations/index.ts": { "mode": "100644", @@ -755,7 +775,7 @@ }, "src/resources/live/api.md": { "mode": "100644", - "sha256": "f0baec2e9db6362ca067d6024a069a3180b6fc1f1d98a794cfb4644bd961f0fe" + "sha256": "625d3002cc1c8037ad3322b2acf8394a63674e14532397023a2fdb0b858a0781" }, "src/resources/live/forks.ts": { "mode": "100644", @@ -783,7 +803,7 @@ }, "src/resources/live/index.ts": { "mode": "100644", - "sha256": "f1cb5ec7afece8caf075f3dddecf0bc92594279e138d0148e892bb51e4783501" + "sha256": "aa22942701acbe6b04e5fd83db0a94cdc071257478ac2605e830a95a8c851857" }, "src/resources/live/internal-base.ts": { "mode": "100644", @@ -791,11 +811,11 @@ }, "src/resources/live/live.ts": { "mode": "100644", - "sha256": "a0284e09dd558feaf6abebf7204a20e293b0b3593984875b2f653376fb19d9c9" + "sha256": "324543c5b76cce5e49ed6dc110c016abec72ac7ff677200356ba361209cb10c1" }, "src/resources/live/sessions.ts": { "mode": "100644", - "sha256": "5ae7100978acd80444b13c11bfbc4cf547b8edc35de9666eb87d12342f952ae1" + "sha256": "458b39453858e732e11d87227cb97de52f980ef833aae1c2d0510dae2a1d7486" }, "src/resources/live/sideband.ts": { "mode": "100644", @@ -803,7 +823,7 @@ }, "src/resources/live/sideband/index.ts": { "mode": "100644", - "sha256": "75336d22779badefd7ffe73019486c16f745eb1b6ccaf90faad1da2f7a5fcf57" + "sha256": "6c42bb78bd6b29e0261ee48915543d65017649daa1fc574b3d1284e126ebd4f4" }, "src/resources/live/sideband/internal-base.ts": { "mode": "100644", @@ -811,7 +831,7 @@ }, "src/resources/live/sideband/sideband.ts": { "mode": "100644", - "sha256": "dbc6a4578db73879b615135fb74439164d9b74b0a57bb422c6ae63cf97ac7bab" + "sha256": "6f9f8ab532ab205a1f0191ce60b63ab9944aafaf766e5e9d13a246c1bfbe21f7" }, "src/resources/live/sideband/ws-base.ts": { "mode": "100644", @@ -859,7 +879,7 @@ }, "src/resources/realtime/realtime.ts": { "mode": "100644", - "sha256": "e01414625ab3fb5c15d3b8088d475721c5ef7e961f51fcb3d044148bbb7f5220" + "sha256": "9f296305e3a9f1fb07c015e055f159133537468c47ce7170cc3f7f90f9ca9978" }, "src/resources/realtime/translations.ts": { "mode": "100644", @@ -907,7 +927,7 @@ }, "src/resources/responses/responses.ts": { "mode": "100644", - "sha256": "c3c9fd497fc25c9df8ee9750beeb002b6d116fdcf3ab57bcf900ab3b5df2e768" + "sha256": "a40364a1a99860dc583994db228627aa9313b96fd0a55a256b826c0c25f7cb59" }, "src/resources/responses/ws-base.ts": { "mode": "100644", @@ -1185,6 +1205,14 @@ "mode": "100644", "sha256": "8394c93dcc5f99e797724b953427d73b63a00e2df6880c628d2b6ba3c52e5196" }, + "tests/api-resources/beta/agents/automations/automations.test.ts": { + "mode": "100644", + "sha256": "1e0fb9501bb73e92e5c00fe2d9020dc0017bbdfc6541feec6dad8c906d826e80" + }, + "tests/api-resources/beta/agents/automations/invocations.test.ts": { + "mode": "100644", + "sha256": "5757f1373e047d955aa32071dac05e1d9a4a1135c3fb56409faee6536f07727c" + }, "tests/api-resources/beta/agents/environments/environments.test.ts": { "mode": "100644", "sha256": "048d835885716f711bb5b213389d6469ee27a5ed63ccae8b6c03073316fc5ecb" @@ -1371,11 +1399,11 @@ }, "tests/api-resources/live/live.test.ts": { "mode": "100644", - "sha256": "2793cf951c6d0a025fdd5b5ac5139d88970591d6b5b8e50441cb85929c2ffc74" + "sha256": "f858c25ad6c3c0fd41bfbcae049dd92cc91c6fe9ed237d1793bf62934f882a74" }, "tests/api-resources/live/sessions.test.ts": { "mode": "100644", - "sha256": "51d2dc8718c5979ec968836b26e49b4eb6d5e5d8bb7ef558aea419df8912d889" + "sha256": "b894d053390ffe38595da502cc9e08bb61bcc42412a02020223533cbb192719a" }, "tests/api-resources/models.test.ts": { "mode": "100644", diff --git a/scripts/castiron/test_custom_code_policy.py b/scripts/castiron/test_custom_code_policy.py index f8ecc67df7..00517cb549 100644 --- a/scripts/castiron/test_custom_code_policy.py +++ b/scripts/castiron/test_custom_code_policy.py @@ -4,6 +4,7 @@ from __future__ import annotations import copy +import io import json import sys import tempfile @@ -41,6 +42,52 @@ def setUp(self) -> None: # pyright: ignore[reportImplicitOverride] (self.repo / "sdk.txt").write_text("candidate SDK bytes") self.head = self.commit("sdk change") + def test_review_command_uses_git_policies_and_rejects_stale_main(self) -> None: + git: Callable[..., bytes] = selector.report.git + + def local_fetch(repo: Path, *args: str, **kwargs: Any) -> bytes: + if args[0] == "fetch": + return git( + repo, + "fetch", + "--quiet", + str(self.repo), + f"{self.main}:refs/remotes/origin/main", + self.base, + self.head, + ) + return git(repo, *args, **kwargs) + + with ( + tempfile.TemporaryDirectory() as directory, + mock.patch.object(selector.report, "git", side_effect=local_fetch), + ): + for stale in (False, True): + with ( + self.subTest(stale=stale), + mock.patch("sys.stdout", new_callable=io.StringIO) as output, + ): + args = [ + "review-required", + "--repo", + str(Path(directory) / str(stale)), + "--repository", + REPO, + "--base", + self.base, + "--head", + self.head, + "--main", + self.base if stale else self.main, + ] + if stale: + with self.assertRaisesRegex(ValueError, "authenticated main changed"): + selector.main(args) + self.assertEqual(output.getvalue(), "") + else: + self.assertEqual(selector.main(args), 0) + self.assertEqual(json.loads(output.getvalue()), {"requires_human": False}) + def write_policy(self, value: dict[str, Any]) -> None: (self.repo / ".castiron-ratchet.json").write_text(json.dumps(value)) diff --git a/scripts/castiron/test_custom_code_publication.py b/scripts/castiron/test_custom_code_publication.py index 15069d795d..4387e6cd9f 100644 --- a/scripts/castiron/test_custom_code_publication.py +++ b/scripts/castiron/test_custom_code_publication.py @@ -6,44 +6,22 @@ import hashlib import json import shutil -import subprocess -import tempfile import unittest from pathlib import Path -from typing import Any, cast +from typing import Any from unittest import mock import custom_code_policy as policy import custom_code_report as report -from custom_code_test_support import GitTestCase, source_run - -WORKFLOW = ( - Path(__file__).resolve().parents[2] / ".github/workflows/castiron-custom-code-comment.yml" +from custom_code_test_support import ( + WORKFLOW, + GitTestCase, + run_publisher, + run_workflow_script, + source_run, ) -def run_publisher(step: str, payload: dict[str, Any]) -> list[dict[str, Any]]: - section = WORKFLOW.read_text().split(f"- name: {step}\n", 1)[1] - script = section.split(" script: |\n", 1)[1] - lines: list[str] = [] - for line in script.splitlines(): - if line and not line.startswith(" "): - break - lines.append(line[12:]) - return run_workflow_script("\n".join(lines), payload) - - -def run_workflow_script(script: str, payload: dict[str, Any]) -> list[dict[str, Any]]: - output = subprocess.run( - ["node", str(Path(__file__).with_name("fixtures") / "github_publisher.cjs")], - input=json.dumps({**payload, "script": script}), - text=True, - capture_output=True, - check=True, - ) - return cast(list[dict[str, Any]], json.loads(output.stdout)) - - class WorkflowTests(unittest.TestCase): @unittest.skipUnless(shutil.which("node"), "GitHub Actions JavaScript runtime") def test_workflow_path_filters_accept_refs_without_accepting_other_files(self) -> None: @@ -984,704 +962,5 @@ def test_publication_guard_allows_current_retry_and_ignores_unrelated_statuses(s self.assertTrue(all(len(r["description"]) <= 140 for r in results)) -@unittest.skipUnless( - shutil.which("node"), "Node is needed to execute the review-revocation fixture" -) -class ReviewRevocationTests(unittest.TestCase): - def payload(self) -> dict[str, Any]: - head, base, queue = "a" * 40, "b" * 40, "c" * 40 - pull = { - "number": 3, - "user": {"login": "author"}, - "state": "open", - "head": {"sha": head}, - "base": {"ref": "next", "sha": base, "repo": {"full_name": "openai/example"}}, - } - run = { - **source_run(head), - "id": 20, - "actor": {"login": "outsider", "type": "User"}, - "event": "pull_request_review", - "status": "completed", - "pull_requests": [{"number": 3, "head": {"sha": head}}], - } - - def original(sha: str, event: str, identity: int) -> dict[str, Any]: - return {**run, "head_sha": sha, "id": identity, "event": event} - - return { - "run": run, - "policies_by_sha": { - base: {"schema_version": 1, "max_custom_patch_lines": 0}, - head: {"schema_version": 1, "max_custom_patch_lines": 1}, - }, - "previous_statuses": [ - { - "context": name, - "state": "success", - "creator": {"login": "github-actions[bot]"}, - "target_url": "https://github.com/openai/example/actions/runs/19", - } - for name in ( - "Castiron next / budget-only change", - "Castiron next / custom-code budget", - ) - ], - "current": pull, - "queue_nodes": [ - {"headCommit": {"oid": queue}, "pullRequest": {"number": 3, "headRefOid": head}} - ], - "runs_by_sha": { - head: [original(head, "pull_request", 12)], - queue: [original(queue, "merge_group", 14)], - }, - "context": { - "payload": {"workflow_run": dict(run)}, - "runId": 21, - "repo": {"owner": "openai", "repo": "example"}, - "serverUrl": "https://github.com", - }, - } - - def invoke(self, payload: dict[str, Any]) -> list[dict[str, Any]]: - return run_publisher("Re-evaluate current PR and queue after review changes", payload) - - def test_revokes_pr_and_queue_before_requesting_normal_re_evaluation(self) -> None: - result = self.invoke(self.payload()) - self.assertEqual([item.get("state") for item in result[:4]], ["pending"] * 4) - self.assertEqual({item["sha"] for item in result[:4]}, {"a" * 40, "c" * 40}) - self.assertTrue(all(item["context"].startswith("Castiron next /") for item in result[:4])) - self.assertEqual([item["run_id"] for item in result[4:]], [12, 14]) - self.assertNotIn("success", [item.get("state") for item in result]) - - def approval(self) -> dict[str, Any]: - return { - "fullDatabaseId": "101", - "state": "APPROVED", - "body": policy.HUMAN_REVIEW_RULES["attestation_prefix"] + "a" * 40, - "author": {"login": "reviewer", "__typename": "User"}, - "authorAssociation": "MEMBER", - "commit": {"oid": "a" * 40}, - "updatedAt": "2026-10-22T01:00:00Z", - } - - def recovery(self) -> dict[str, Any]: - payload = self.payload() - payload["review_nodes"] = [self.approval()] - payload["run"]["actor"] = {"login": "reviewer", "type": "User"} - for status in payload["previous_statuses"]: - status["state"] = "failure" - return payload - - def history(self, payload: dict[str, Any], writes: list[dict[str, Any]]) -> None: - payload["statuses_by_sha"] = { - sha: [ - {**item, "creator": {"login": "github-actions[bot]"}} - for item in writes - if item.get("sha") == sha - ] - for sha in ("a" * 40, "c" * 40) - } - payload["runs_by_id"] = { - "21": { - "id": 21, - "workflow_id": 789, - "status": "completed", - "conclusion": "success", - "repository": {"full_name": "openai/example"}, - "event": "workflow_run", - } - } - - def test_unrelated_comment_cannot_invalidate_valid_approval_or_request_recovery(self) -> None: - for state in ("success", "failure", "pending"): - payload = self.recovery() - payload["run"]["actor"]["login"] = "outsider" - payload["review_nodes"].append( - { - **self.approval(), - "fullDatabaseId": "102", - "author": {"login": "outsider", "__typename": "User"}, - "state": "COMMENTED", - "body": "hello", - } - ) - for status in payload["previous_statuses"]: - status["state"] = state - payload["forbid_queue"] = True - self.assertEqual(self.invoke(payload), []) - - def test_ineligible_review_cannot_request_recovery(self) -> None: - for overrides in ( - {"state": "COMMENTED"}, - {"body": ""}, - {"authorAssociation": "CONTRIBUTOR"}, - {"commit": {"oid": "b" * 40}}, - {"author": {"login": "author", "__typename": "User"}}, - {"author": {"login": "reviewer", "__typename": "Bot"}}, - ): - with self.subTest(overrides=overrides): - payload = self.recovery() - payload["review_nodes"][0].update(overrides) - self.assertEqual(self.invoke(payload), []) - - def test_repeated_invalid_signals_do_not_rerun_already_revoked_heads(self) -> None: - payload = self.payload() - writes = self.invoke(payload) - self.history(payload, writes) - self.assertEqual(self.invoke(payload), []) - for statuses in payload["statuses_by_sha"].values(): - for status in statuses: - status["state"] = "failure" - self.assertEqual(self.invoke(payload), []) - - def test_approval_recovery_coalesces_and_edited_restoration_recovers_again(self) -> None: - payload = self.recovery() - writes = self.invoke(payload) - self.assertEqual(len(writes), 6) - self.assertTrue(all(len(item["description"]) <= 140 for item in writes[:4])) - self.history(payload, writes) - self.assertEqual(self.invoke(payload), []) - payload["review_nodes"][0]["updatedAt"] = "2026-10-22T01:02:00Z" - restored = self.invoke(payload) - self.assertEqual(len(restored), 6) - self.assertNotEqual(writes[0]["description"], restored[0]["description"]) - - def test_new_revocation_supersedes_old_recovery_even_with_equal_edit_timestamp(self) -> None: - payload = self.recovery() - approved = self.invoke(payload) - self.history(payload, approved) - for statuses in payload["statuses_by_sha"].values(): - statuses[:0] = [ - {**status, "state": "success", "description": "Successful evaluation"} - for status in statuses - ] - payload["review_nodes"][0]["body"] = "" - revoked = self.invoke(payload) - self.assertEqual(len(revoked), 6) - self.history(payload, revoked) - for sha, statuses in payload["statuses_by_sha"].items(): - statuses.extend( - {**item, "creator": {"login": "github-actions[bot]"}} - for item in approved - if item.get("sha") == sha - ) - payload["review_nodes"][0] = ( - self.approval() - ) # Same ID, body and second-precision update time. - self.assertEqual(len(self.invoke(payload)), 6) - - def test_full_review_id_handles_current_and_beyond_safe_integer_ids(self) -> None: - payload = self.recovery() - payload["review_nodes"][0].update(databaseId=None, fullDatabaseId="5614624241") - self.assertEqual(len(self.invoke(payload)), 6) - payload = self.payload() - payload["review_nodes"] = [ - {**self.approval(), "databaseId": None, "fullDatabaseId": "9007199254740992"}, - { - **self.approval(), - "databaseId": None, - "fullDatabaseId": "9007199254740993", - "state": "COMMENTED", - }, - ] - self.assertEqual(len(self.invoke(payload)), 6) - payload["review_nodes"][0]["fullDatabaseId"] = 9007199254740992 - with self.assertRaises(subprocess.CalledProcessError): - self.invoke(payload) - - def test_publisher_failure_supersedes_recovery_without_observed_revocation(self) -> None: - payload = self.recovery() - approved = self.invoke(payload) - self.history(payload, approved) - for statuses in payload["statuses_by_sha"].values(): - statuses[:0] = [ - {**status, "state": "failure", "description": "Approval missing during publication"} - for status in statuses - ] - # Publisher observed invalid body; review jobs only see its same-second restoration. - # No new review identity/timestamp and no review-handler revocation marker exists. - recovered = self.invoke(payload) - self.assertEqual(len(recovered), 6) - self.history(payload, recovered) - self.assertEqual(self.invoke(payload), []) - - def test_deleted_marker_writer_is_untrusted_but_service_errors_propagate(self) -> None: - payload = self.recovery() - approved = self.invoke(payload) - self.history(payload, approved) - payload["run_errors"] = {"21": 404} - self.assertEqual(len(self.invoke(payload)), 6) - for status in (403, 429, 500): - payload["run_errors"]["21"] = status - with self.subTest(status=status), self.assertRaises(subprocess.CalledProcessError): - self.invoke(payload) - - def test_failed_partial_dispatch_is_retried_before_signals_coalesce(self) -> None: - for authorized in (False, True): - for conclusion in ("failure", "cancelled", "timed_out"): - payload = self.recovery() if authorized else self.payload() - payload["fail_rerun"] = True - # The fixture persists actual pending writes before the simulated API error. - with tempfile.TemporaryDirectory() as directory: - capture = Path(directory) / "pending.json" - payload["capture_writes"] = str(capture) - with self.assertRaises(subprocess.CalledProcessError): - self.invoke(payload) - pending = json.loads(capture.read_text()) - self.assertEqual(len(pending), 4) - self.history(payload, pending) - payload.pop("capture_writes") - payload.pop("fail_rerun") - payload["runs_by_id"]["21"]["conclusion"] = conclusion - payload["context"]["runId"] = 22 - retried = self.invoke(payload) - self.assertEqual([item["run_id"] for item in retried if "run_id" in item], [12, 14]) - self.history(payload, retried) - payload["runs_by_id"]["22"] = {**payload["runs_by_id"]["21"], "id": 22} - self.assertEqual(self.invoke(payload), []) - - def test_untrusted_marker_cannot_suppress_recovery(self) -> None: - for field, value in ( - ("workflow_id", 999), - ("event", "pull_request"), - ("repository", {"full_name": "attacker/example"}), - ): - payload = self.recovery() - self.history(payload, self.invoke(payload)) - payload["runs_by_id"]["21"][field] = value - self.assertEqual(len(self.invoke(payload)), 6) - - def test_dismissal_edit_away_and_later_comment_revoke_even_for_other_signal_actor(self) -> None: - for changed in ( - {"state": "DISMISSED"}, - {"body": ""}, - {"state": "COMMENTED", "fullDatabaseId": "102"}, - ): - payload = self.payload() - payload["review_nodes"] = [{**self.approval(), **changed}] - self.assertEqual(len(self.invoke(payload)), 6) - payload = self.payload() - payload["review_pages"] = [ - { - "expected_cursor": None, - "nodes": [{**self.approval(), "fullDatabaseId": "102", "state": "COMMENTED"}], - "pageInfo": {"hasNextPage": True, "endCursor": "more"}, - }, - { - "expected_cursor": "more", - "nodes": [self.approval()], - "pageInfo": {"hasNextPage": False}, - }, - ] - self.assertEqual(len(self.invoke(payload)), 6) - - def test_missing_authoritative_edit_time_rejects_recovery(self) -> None: - payload = self.recovery() - payload["review_nodes"][0]["updatedAt"] = None - with self.assertRaises(subprocess.CalledProcessError): - self.invoke(payload) - - def test_review_signal_requires_canonical_workflow_identity_before_writes(self) -> None: - for identity in (None, "456", 999): - for path in ( - ".github/workflows/castiron-custom-code.yml", - ".github/workflows/castiron-custom-code.yml@evil.yml", - ): - with self.subTest(identity=identity, path=path): - payload = self.payload() - payload["run"].update({"workflow_id": identity, "path": path}) - payload["context"]["payload"]["workflow_run"] = dict(payload["run"]) - self.assertEqual(self.invoke(payload), []) - - def test_rejects_forged_or_superseded_review_signals(self) -> None: - for field, value in [ - ("path", ".github/workflows/other.yml"), - ("run_attempt", 9), - ("head_sha", "d" * 40), - ("event", "pull_request"), - ]: - with self.subTest(field=field): - payload = self.payload() - payload["run"][field] = value - with self.assertRaises(subprocess.CalledProcessError): - self.invoke(payload) - payload = self.payload() - payload["run"]["repository"] = {"full_name": "attacker/example"} - with self.assertRaises(subprocess.CalledProcessError): - self.invoke(payload) - - def test_head_change_keeps_observed_statuses_revoked_without_stale_reruns(self) -> None: - payload = self.payload() - changed = {**payload["current"], "head": {"sha": "d" * 40}} - payload["current_sequence"] = [payload["current"], changed] - payload["current"] = changed - result = self.invoke(payload) - self.assertEqual(len(result), 4) - self.assertTrue(all(item["state"] == "pending" for item in result)) - self.assertNotIn("d" * 40, {item["sha"] for item in result}) - - def test_queue_change_retries_and_invalidates_new_snapshot(self) -> None: - payload = self.payload() - old = list(payload["queue_nodes"]) - payload["queue_nodes"].append( - { - "headCommit": {"oid": "d" * 40}, - "pullRequest": {"number": 4, "headRefOid": "e" * 40}, - } - ) - payload["runs_by_sha"]["d" * 40] = [ - { - **payload["runs_by_sha"]["c" * 40][0], - "head_sha": "d" * 40, - "id": 16, - } - ] - payload["queue_pages"] = [ - { - "expected_cursor": None, - "nodes": old, - "pageInfo": {"hasNextPage": False}, - } - ] - result = self.invoke(payload) - pending = [item for item in result if item.get("state") == "pending"] - self.assertEqual({item["sha"] for item in pending}, {"a" * 40, "c" * 40, "d" * 40}) - self.assertEqual([item["run_id"] for item in result if "run_id" in item], [12, 14, 16]) - self.assertTrue(all(item.get("state") == "pending" for item in result[:-3])) - - def test_empty_review_pr_list_uses_authenticated_fork_discovery(self) -> None: - for associated in ([], [{"number": 3}]): - payload = self.payload() - payload["run"].update( - { - "pull_requests": [], - "head_repository": {"owner": {"login": "contributor"}}, - "head_branch": "sdk", - } - ) - payload["associated_pulls"] = associated - payload["fallback_pulls"] = [{"number": 3}] - self.assertEqual(len(self.invoke(payload)), 6) - payload["current"]["head"]["sha"] = "d" * 40 - payload["merge_sha"] = "e" * 40 - payload["merge_commit"] = {"parents": []} - self.assertEqual(self.invoke(payload), []) - - def test_shared_head_revokes_the_run_source_pr(self) -> None: - payload = self.payload() - payload["run"]["pull_requests"] = [] - payload["run"]["head_repository"]["id"] = 101 - payload["current"]["head"].update(ref="sdk", repo={"id": 101}) - payload["associated_pulls"] = [{"number": number} for number in (3, 4, 5)] - payload["pulls_by_number"] = { - str(number): { - **payload["current"], - "number": number, - "head": {**payload["current"]["head"], **change}, - } - for number, change in ((4, {"ref": "other"}), (5, {"repo": {"id": 102}})) - } - result = self.invoke(payload) - self.assertEqual([item.get("state") for item in result[:4]], ["pending"] * 4) - self.assertEqual({item["sha"] for item in result[:4]}, {"a" * 40, "c" * 40}) - - def test_branch_only_merge_signal_requires_current_merge_and_base(self) -> None: - payload = self.payload() - payload["run"]["pull_requests"] = [] - payload["run"]["head_sha"] = payload["context"]["payload"]["workflow_run"]["head_sha"] = ( - "e" * 40 - ) - payload["fallback_pulls"] = [{"number": 3}] - payload["merge_commit"] = {"parents": [{"sha": "b" * 40}, {"sha": "a" * 40}]} - payload["merge_sha"] = "f" * 40 - self.assertEqual(self.invoke(payload), []) - - payload["merge_sha"] = "e" * 40 - self.assertEqual(len(self.invoke(payload)), 6) - payload["current"]["base"]["sha"] = "d" * 40 - payload["comparisons"] = { - f"{'d' * 40}...{'a' * 40}": {"merge_base_commit": {"sha": "b" * 40}} - } - self.assertEqual(self.invoke(payload), []) - - def test_merge_sha_signal_survives_base_advance_and_rejects_wrong_parents(self) -> None: - payload = self.payload() - payload["run"]["head_sha"] = payload["context"]["payload"]["workflow_run"]["head_sha"] = ( - "e" * 40 - ) - payload["current"]["base"]["sha"] = "d" * 40 - payload["comparisons"] = { - f"{'d' * 40}...{'a' * 40}": {"merge_base_commit": {"sha": "b" * 40}} - } - payload["merge_commit"] = {"parents": [{"sha": "b" * 40}, {"sha": "a" * 40}]} - self.assertEqual(len(self.invoke(payload)), 6) - payload["comparisons"][f"{'b' * 40}...{'d' * 40}"] = { - "merge_base_commit": {"sha": "f" * 40} - } - self.assertEqual(self.invoke(payload), []) - payload["merge_commit"]["parents"].reverse() - self.assertEqual(self.invoke(payload), []) - - def test_policy_changes_without_human_attestation_do_not_invalidate_statuses(self) -> None: - cases = ( - ( - {"schema_version": 1, "max_custom_patch_lines": 2}, - {"schema_version": 1, "max_custom_patch_lines": 1}, - ), - ( - {"schema_version": 1, "max_custom_patch_lines": 0}, - {"schema_version": 2, "max_custom_patch_lines": 0, "generated_files": "strict"}, - ), - ) - for base_policy, head_policy in cases: - with self.subTest(base_policy=base_policy, head_policy=head_policy): - payload = self.payload() - payload["policies_by_sha"] = {"b" * 40: base_policy, "a" * 40: head_policy} - self.assertEqual(self.invoke(payload), []) - - def test_go_ratchet_activation_invalidates_statuses(self) -> None: - payload = self.payload() - payload["policies_by_sha"]["a" * 40] = { - **payload["policies_by_sha"]["b" * 40], - "ratchet": "go", - } - self.assertEqual(len(self.invoke(payload)), 6) - - def test_policy_pin_reviews_follow_effective_protected_target(self) -> None: - historical_checker, target_checker, proposed_checker = "e" * 40, "f" * 40, "0" * 40 - target = "d" * 40 - - def pinned(checker: str) -> dict[str, Any]: - return { - "schema_version": 1, - "max_custom_patch_lines": 0, - "next_policy": {"repository": "openai/example", "main_sha": checker}, - } - - payload = self.payload() - payload["current"]["base"]["sha"] = target - payload["main_sha"] = proposed_checker - payload["comparisons"] = { - f"{target}...{'a' * 40}": {"merge_base_commit": {"sha": "b" * 40}} - } - payload["policies_by_sha"] = { - "a" * 40: pinned(proposed_checker), - "b" * 40: pinned(historical_checker), - target: pinned(target_checker), - historical_checker: {"schema_version": 1, "max_custom_patch_lines": 10}, - target_checker: {"schema_version": 1, "max_custom_patch_lines": 5}, - proposed_checker: {"schema_version": 1, "max_custom_patch_lines": 5}, - } - payload["checker_sources_by_sha"] = {target_checker: Path(policy.__file__).read_text()} - self.assertEqual(self.invoke(payload), []) - payload["policies_by_sha"][proposed_checker]["max_custom_patch_lines"] = 7 - self.assertEqual(len(self.invoke(payload)), 6) - payload["policies_by_sha"][proposed_checker]["max_custom_patch_lines"] = 5 - payload["comparisons"][f"{target_checker}...{proposed_checker}"] = { - "merge_base_commit": {"sha": proposed_checker} - } - self.assertEqual(len(self.invoke(payload)), 6) - - def test_legacy_checker_pin_reviews_still_invalidate_statuses(self) -> None: - previous, proposed = "e" * 40, "f" * 40 - for changed in ({"state": "DISMISSED"}, {"body": ""}): - with self.subTest(changed=changed): - payload = self.payload() - payload["main_sha"] = proposed - unchanged_policy = {"schema_version": 1, "max_custom_patch_lines": 0} - payload["policies_by_sha"] = { - "b" * 40: { - **unchanged_policy, - "next_policy": {"repository": "openai/example", "main_sha": previous}, - }, - "a" * 40: { - **unchanged_policy, - "next_policy": {"repository": "openai/example", "main_sha": proposed}, - }, - previous: unchanged_policy, - proposed: unchanged_policy, - } - payload["checker_sources_by_sha"] = { - previous: "NEXT_POLICY_VERSION = 1\n", - proposed: Path(policy.__file__).read_text(), - } - payload["review_nodes"] = [{**self.approval(), **changed}] - writes = self.invoke(payload) - self.assertCountEqual( - [(item["sha"], item["state"]) for item in writes if "state" in item], - [("a" * 40, "pending")] * 2 + [("c" * 40, "pending")] * 2, - ) - self.assertCountEqual( - [item["run_id"] for item in writes if "run_id" in item], [12, 14] - ) - - def test_unknown_or_missing_checker_contract_retains_review(self) -> None: - previous, proposed = "e" * 40, "f" * 40 - for source in ( - None, - 'PIN_REVIEW_POLICY = "unknown"\n', - 'PIN_REVIEW_POLICY = "effective-policy-v1"\n' * 2, - ): - with self.subTest(source=source): - payload = self.payload() - payload["main_sha"] = proposed - unchanged = {"schema_version": 1, "max_custom_patch_lines": 0} - payload["policies_by_sha"] = { - "b" * 40: { - **unchanged, - "next_policy": {"repository": "openai/example", "main_sha": previous}, - }, - "a" * 40: { - **unchanged, - "next_policy": {"repository": "openai/example", "main_sha": proposed}, - }, - previous: unchanged, - proposed: unchanged, - } - payload["checker_sources_by_sha"] = {} if source is None else {previous: source} - self.assertEqual(len(self.invoke(payload)), 6) - for status in (403, 429, 500): - payload["checker_lookup_error"] = status - with self.assertRaises(subprocess.CalledProcessError): - self.invoke(payload) - - def test_initial_pin_at_current_main_keeps_statuses(self) -> None: - payload = self.payload() - checker = "f" * 40 - payload["main_sha"] = checker - payload["policies_by_sha"]["b" * 40] = { - "schema_version": 1, - "max_custom_patch_lines": 4000, - } - payload["policies_by_sha"][checker] = { - "schema_version": 2, - "max_custom_patch_lines": 0, - "generated_files": "strict", - } - payload["policies_by_sha"]["a" * 40] = { - **payload["policies_by_sha"]["b" * 40], - "next_policy": {"repository": "openai/example", "main_sha": checker}, - } - payload["checker_sources_by_sha"] = {checker: Path(policy.__file__).read_text()} - self.assertEqual(self.invoke(payload), []) - advanced_main = "e" * 40 - payload["checker_sources_by_sha"][advanced_main] = Path(policy.__file__).read_text() - payload["policies_by_sha"][advanced_main] = payload["policies_by_sha"][checker] - payload["main_sha_sequence"] = [checker, advanced_main] - payload["main_sha"] = advanced_main - payload["comparisons"] = { - f"{advanced_main}...{checker}": {"merge_base_commit": {"sha": checker}} - } - self.assertEqual(len(self.invoke(payload)), 6) - - def test_revoked_go_ratchet_activation_invalidates_pr_and_queue_statuses(self) -> None: - for changed in ({"state": "DISMISSED"}, {"body": ""}): - with self.subTest(changed=changed): - payload = self.payload() - payload["policies_by_sha"]["a" * 40] = { - **payload["policies_by_sha"]["b" * 40], - "ratchet": "go", - } - payload["review_nodes"] = [{**self.approval(), **changed}] - writes = self.invoke(payload) - self.assertCountEqual( - [(item["sha"], item["state"]) for item in writes if "state" in item], - [("a" * 40, "pending")] * 2 + [("c" * 40, "pending")] * 2, - ) - self.assertCountEqual( - [item["run_id"] for item in writes if "run_id" in item], [12, 14] - ) - - def test_closed_or_superseded_review_is_a_no_op(self) -> None: - for changed in ({"state": "closed"}, {"head": {"sha": "f" * 40}}): - payload = self.payload() - payload["current"].update(changed) - self.assertEqual(self.invoke(payload), []) - - def test_null_queue_association_does_not_block_revocation(self) -> None: - payload = self.payload() - payload["queue_nodes"].insert(0, {"headCommit": {"oid": "f" * 40}, "pullRequest": None}) - result = self.invoke(payload) - self.assertEqual(len(result), 6) - self.assertNotIn("f" * 40, {item.get("sha") for item in result}) - payload["queue_nodes"] = payload["queue_nodes"][:1] - self.assertEqual(len(self.invoke(payload)), 3) - - def test_rerun_requires_the_reviewed_pr_not_just_shared_head(self) -> None: - payload = self.payload() - correct = payload["runs_by_sha"]["a" * 40][0] - main = { - **payload["current"], - "number": 4, - "base": {**payload["current"]["base"], "ref": "main"}, - } - payload["pulls_by_number"] = {"4": main} - other: dict[str, Any] = { - **correct, - "id": 30, - "pull_requests": [{"number": 4, "head": {"sha": "a" * 40}}], - } - payload["runs_by_sha"]["a" * 40].append(other) - result = self.invoke(payload) - self.assertEqual([item["run_id"] for item in result if "run_id" in item], [12, 14]) - # Empty fork associations may rerun only if canonical discovery selects this next PR. - fork: dict[str, Any] = { - **correct, - "pull_requests": [], - "head_repository": {"owner": {"login": "contributor"}}, - "head_branch": "sdk", - } - payload["fallback_pulls"] = [{"number": 3}] - payload["runs_by_sha"]["a" * 40] = [fork, other] - result = self.invoke(payload) - self.assertEqual([item["run_id"] for item in result if "run_id" in item], [12, 14]) - association_cases: tuple[list[dict[str, Any]], ...] = ( - [], - [*correct["pull_requests"], *other["pull_requests"]], - ) - for associations in association_cases: - payload["associated_pulls"] = [{"number": 3}, {"number": 4}] - payload["runs_by_sha"]["a" * 40] = [{**fork, "pull_requests": associations}, other] - result = self.invoke(payload) - self.assertEqual([item["run_id"] for item in result if "run_id" in item], [14]) - self.assertTrue(all(item["state"] == "pending" for item in result[:4])) - - def test_unprepared_queue_entry_still_revokes_pr_statuses(self) -> None: - payload = self.payload() - payload["queue_nodes"][0]["headCommit"] = None - result = self.invoke(payload) - self.assertEqual([item.get("state") for item in result], ["pending", "pending", None]) - self.assertEqual(result[-1]["run_id"], 12) - - def test_unrelated_review_does_not_restart_reporter(self) -> None: - payload = self.payload() - payload["files"] = [{"filename": "src/client.ts"}] - self.assertEqual(self.invoke(payload), []) - - def test_no_success_or_foreign_run_can_be_published(self) -> None: - payload = self.payload() - payload["runs_by_sha"]["a" * 40][0]["repository"] = {"full_name": "other/repo"} - result = self.invoke(payload) - self.assertEqual( - [item["run_id"] for item in result if item.get("operation") == "rerun"], [14] - ) - self.assertTrue(all(item.get("state") != "success" for item in result)) - - def test_signal_is_unprivileged_and_writers_serialize(self) -> None: - producer = (WORKFLOW.parent / "castiron-custom-code.yml").read_text() - self.assertIn("pull_request_review:\n types: [submitted, edited, dismissed]", producer) - signal = producer.split(" queue-signal:\n", 1)[1].split(" candidate-tests:\n", 1)[0] - self.assertIn("permissions: {}", signal) - self.assertNotIn("checkout@", signal) - handler = WORKFLOW.read_text() - revoke = handler.split(" review-change:\n", 1)[1].split(" compute:\n", 1)[0] - self.assertNotIn("checkout@", revoke) - self.assertNotIn("download-artifact", revoke) - self.assertEqual( - handler.count("group: castiron-budget-writes-${{ github.repository_id }}"), 2 - ) - - if __name__ == "__main__": unittest.main() diff --git a/scripts/castiron/test_custom_code_review_revocation.py b/scripts/castiron/test_custom_code_review_revocation.py new file mode 100644 index 0000000000..4baa11512e --- /dev/null +++ b/scripts/castiron/test_custom_code_review_revocation.py @@ -0,0 +1,619 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. +"""Exercise review revocation and target freshness against offline GitHub state.""" + +from __future__ import annotations + +import json +import shutil +import subprocess +import tempfile +import unittest +from pathlib import Path +from typing import Any + +import custom_code_policy as policy +from custom_code_test_support import WORKFLOW, run_publisher, source_run + + +@unittest.skipUnless( + shutil.which("node"), "Node is needed to execute the review-revocation fixture" +) +class ReviewRevocationTests(unittest.TestCase): + def payload(self) -> dict[str, Any]: + head, base, queue = "a" * 40, "b" * 40, "c" * 40 + pull = { + "number": 3, + "user": {"login": "author"}, + "state": "open", + "head": {"sha": head}, + "base": {"ref": "next", "sha": base, "repo": {"full_name": "openai/example"}}, + } + run = { + **source_run(head), + "id": 20, + "actor": {"login": "outsider", "type": "User"}, + "event": "pull_request_review", + "status": "completed", + "pull_requests": [{"number": 3, "head": {"sha": head}}], + } + + def original(sha: str, event: str, identity: int) -> dict[str, Any]: + return {**run, "head_sha": sha, "id": identity, "event": event} + + return { + "run": run, + "policies_by_sha": { + base: {"schema_version": 1, "max_custom_patch_lines": 0}, + head: {"schema_version": 1, "max_custom_patch_lines": 1}, + }, + "previous_statuses": [ + { + "context": name, + "state": "success", + "creator": {"login": "github-actions[bot]"}, + "target_url": "https://github.com/openai/example/actions/runs/19", + } + for name in ( + "Castiron next / budget-only change", + "Castiron next / custom-code budget", + ) + ], + "current": pull, + "queue_nodes": [ + {"headCommit": {"oid": queue}, "pullRequest": {"number": 3, "headRefOid": head}} + ], + "runs_by_sha": { + head: [original(head, "pull_request", 12)], + queue: [original(queue, "merge_group", 14)], + }, + "context": { + "payload": {"workflow_run": dict(run)}, + "runId": 21, + "repo": {"owner": "openai", "repo": "example"}, + "serverUrl": "https://github.com", + }, + } + + def invoke(self, payload: dict[str, Any]) -> list[dict[str, Any]]: + return run_publisher("Re-evaluate current PR and queue after review changes", payload) + + def test_revokes_pr_and_queue_before_requesting_normal_re_evaluation(self) -> None: + result = self.invoke(self.payload()) + self.assertEqual([item.get("state") for item in result[:4]], ["pending"] * 4) + self.assertEqual({item["sha"] for item in result[:4]}, {"a" * 40, "c" * 40}) + self.assertTrue(all(item["context"].startswith("Castiron next /") for item in result[:4])) + self.assertEqual([item["run_id"] for item in result[4:]], [12, 14]) + self.assertNotIn("success", [item.get("state") for item in result]) + + def test_retries_policy_failure_when_main_advances_before_revocation(self) -> None: + payload = self.payload() + payload["main_sha_sequence"] = ["d" * 40, "e" * 40] + payload["main_sha"] = "e" * 40 + payload["policy_error_sequence"] = [True, False] + result = self.invoke(payload) + self.assertEqual([item.get("state") for item in result[:4]], ["pending"] * 4) + self.assertEqual({item["sha"] for item in result[:4]}, {"a" * 40, "c" * 40}) + self.assertEqual([item["run_id"] for item in result[4:]], [12, 14]) + + def test_refreshes_executable_policy_when_main_changes_review_requirement(self) -> None: + payload = self.payload() + payload["main_sha_sequence"] = ["d" * 40, "e" * 40] + payload["main_sha"] = "e" * 40 + payload["requires_human_by_main"] = {"d" * 40: False, "e" * 40: True} + result = self.invoke(payload) + self.assertEqual([item.get("state") for item in result[:4]], ["pending"] * 4) + self.assertEqual({item["sha"] for item in result[:4]}, {"a" * 40, "c" * 40}) + self.assertEqual([item["run_id"] for item in result[4:]], [12, 14]) + + def test_rejects_invalid_trusted_policy_downloads(self) -> None: + for override in [ + {"type": "symlink"}, + {"encoding": "none"}, + {"size": 1048577}, + {"size": 0}, + {"content": ""}, + ]: + with self.subTest(override=override): + payload = self.payload() + payload["policy_file_override"] = override + with self.assertRaises(subprocess.CalledProcessError): + self.invoke(payload) + + def approval(self) -> dict[str, Any]: + return { + "fullDatabaseId": "101", + "state": "APPROVED", + "body": policy.HUMAN_REVIEW_RULES["attestation_prefix"] + "a" * 40, + "author": {"login": "reviewer", "__typename": "User"}, + "authorAssociation": "MEMBER", + "commit": {"oid": "a" * 40}, + "updatedAt": "2026-10-22T01:00:00Z", + } + + def recovery(self) -> dict[str, Any]: + payload = self.payload() + payload["review_nodes"] = [self.approval()] + payload["run"]["actor"] = {"login": "reviewer", "type": "User"} + for status in payload["previous_statuses"]: + status["state"] = "failure" + return payload + + def history(self, payload: dict[str, Any], writes: list[dict[str, Any]]) -> None: + payload["statuses_by_sha"] = { + sha: [ + {**item, "creator": {"login": "github-actions[bot]"}} + for item in writes + if item.get("sha") == sha + ] + for sha in ("a" * 40, "c" * 40) + } + payload["runs_by_id"] = { + "21": { + "id": 21, + "workflow_id": 789, + "status": "completed", + "conclusion": "success", + "repository": {"full_name": "openai/example"}, + "event": "workflow_run", + } + } + + def test_unrelated_comment_cannot_invalidate_valid_approval_or_request_recovery(self) -> None: + for state in ("success", "failure", "pending"): + payload = self.recovery() + payload["run"]["actor"]["login"] = "outsider" + payload["review_nodes"].append( + { + **self.approval(), + "fullDatabaseId": "102", + "author": {"login": "outsider", "__typename": "User"}, + "state": "COMMENTED", + "body": "hello", + } + ) + for status in payload["previous_statuses"]: + status["state"] = state + payload["forbid_queue"] = True + self.assertEqual(self.invoke(payload), []) + + def test_ineligible_review_cannot_request_recovery(self) -> None: + for overrides in ( + {"state": "COMMENTED"}, + {"body": ""}, + {"authorAssociation": "CONTRIBUTOR"}, + {"commit": {"oid": "b" * 40}}, + {"author": {"login": "author", "__typename": "User"}}, + {"author": {"login": "reviewer", "__typename": "Bot"}}, + ): + with self.subTest(overrides=overrides): + payload = self.recovery() + payload["review_nodes"][0].update(overrides) + self.assertEqual(self.invoke(payload), []) + + def test_repeated_invalid_signals_do_not_rerun_already_revoked_heads(self) -> None: + payload = self.payload() + writes = self.invoke(payload) + self.history(payload, writes) + self.assertEqual(self.invoke(payload), []) + for statuses in payload["statuses_by_sha"].values(): + for status in statuses: + status["state"] = "failure" + self.assertEqual(self.invoke(payload), []) + + def test_approval_recovery_coalesces_and_edited_restoration_recovers_again(self) -> None: + payload = self.recovery() + writes = self.invoke(payload) + self.assertEqual(len(writes), 6) + self.assertTrue(all(len(item["description"]) <= 140 for item in writes[:4])) + self.history(payload, writes) + self.assertEqual(self.invoke(payload), []) + payload["review_nodes"][0]["updatedAt"] = "2026-10-22T01:02:00Z" + restored = self.invoke(payload) + self.assertEqual(len(restored), 6) + self.assertNotEqual(writes[0]["description"], restored[0]["description"]) + + def test_new_revocation_supersedes_old_recovery_even_with_equal_edit_timestamp(self) -> None: + payload = self.recovery() + approved = self.invoke(payload) + self.history(payload, approved) + for statuses in payload["statuses_by_sha"].values(): + statuses[:0] = [ + {**status, "state": "success", "description": "Successful evaluation"} + for status in statuses + ] + payload["review_nodes"][0]["body"] = "" + revoked = self.invoke(payload) + self.assertEqual(len(revoked), 6) + self.history(payload, revoked) + for sha, statuses in payload["statuses_by_sha"].items(): + statuses.extend( + {**item, "creator": {"login": "github-actions[bot]"}} + for item in approved + if item.get("sha") == sha + ) + payload["review_nodes"][0] = ( + self.approval() + ) # Same ID, body and second-precision update time. + self.assertEqual(len(self.invoke(payload)), 6) + + def test_full_review_id_handles_current_and_beyond_safe_integer_ids(self) -> None: + payload = self.recovery() + payload["review_nodes"][0].update(databaseId=None, fullDatabaseId="5614624241") + self.assertEqual(len(self.invoke(payload)), 6) + payload = self.payload() + payload["review_nodes"] = [ + {**self.approval(), "databaseId": None, "fullDatabaseId": "9007199254740992"}, + { + **self.approval(), + "databaseId": None, + "fullDatabaseId": "9007199254740993", + "state": "COMMENTED", + }, + ] + self.assertEqual(len(self.invoke(payload)), 6) + payload["review_nodes"][0]["fullDatabaseId"] = 9007199254740992 + with self.assertRaises(subprocess.CalledProcessError): + self.invoke(payload) + + def test_publisher_failure_supersedes_recovery_without_observed_revocation(self) -> None: + payload = self.recovery() + approved = self.invoke(payload) + self.history(payload, approved) + for statuses in payload["statuses_by_sha"].values(): + statuses[:0] = [ + {**status, "state": "failure", "description": "Approval missing during publication"} + for status in statuses + ] + # Publisher observed invalid body; review jobs only see its same-second restoration. + # No new review identity/timestamp and no review-handler revocation marker exists. + recovered = self.invoke(payload) + self.assertEqual(len(recovered), 6) + self.history(payload, recovered) + self.assertEqual(self.invoke(payload), []) + + def test_deleted_marker_writer_is_untrusted_but_service_errors_propagate(self) -> None: + payload = self.recovery() + approved = self.invoke(payload) + self.history(payload, approved) + payload["run_errors"] = {"21": 404} + self.assertEqual(len(self.invoke(payload)), 6) + for status in (403, 429, 500): + payload["run_errors"]["21"] = status + with self.subTest(status=status), self.assertRaises(subprocess.CalledProcessError): + self.invoke(payload) + + def test_failed_partial_dispatch_is_retried_before_signals_coalesce(self) -> None: + for authorized in (False, True): + for conclusion in ("failure", "cancelled", "timed_out"): + payload = self.recovery() if authorized else self.payload() + payload["fail_rerun"] = True + # The fixture persists actual pending writes before the simulated API error. + with tempfile.TemporaryDirectory() as directory: + capture = Path(directory) / "pending.json" + payload["capture_writes"] = str(capture) + with self.assertRaises(subprocess.CalledProcessError): + self.invoke(payload) + pending = json.loads(capture.read_text()) + self.assertEqual(len(pending), 4) + self.history(payload, pending) + payload.pop("capture_writes") + payload.pop("fail_rerun") + payload["runs_by_id"]["21"]["conclusion"] = conclusion + payload["context"]["runId"] = 22 + retried = self.invoke(payload) + self.assertEqual([item["run_id"] for item in retried if "run_id" in item], [12, 14]) + self.history(payload, retried) + payload["runs_by_id"]["22"] = {**payload["runs_by_id"]["21"], "id": 22} + self.assertEqual(self.invoke(payload), []) + + def test_untrusted_marker_cannot_suppress_recovery(self) -> None: + for field, value in ( + ("workflow_id", 999), + ("event", "pull_request"), + ("repository", {"full_name": "attacker/example"}), + ): + payload = self.recovery() + self.history(payload, self.invoke(payload)) + payload["runs_by_id"]["21"][field] = value + self.assertEqual(len(self.invoke(payload)), 6) + + def test_dismissal_edit_away_and_later_comment_revoke_even_for_other_signal_actor(self) -> None: + for changed in ( + {"state": "DISMISSED"}, + {"body": ""}, + {"state": "COMMENTED", "fullDatabaseId": "102"}, + ): + payload = self.payload() + payload["review_nodes"] = [{**self.approval(), **changed}] + self.assertEqual(len(self.invoke(payload)), 6) + payload = self.payload() + payload["review_pages"] = [ + { + "expected_cursor": None, + "nodes": [{**self.approval(), "fullDatabaseId": "102", "state": "COMMENTED"}], + "pageInfo": {"hasNextPage": True, "endCursor": "more"}, + }, + { + "expected_cursor": "more", + "nodes": [self.approval()], + "pageInfo": {"hasNextPage": False}, + }, + ] + self.assertEqual(len(self.invoke(payload)), 6) + + def test_missing_authoritative_edit_time_rejects_recovery(self) -> None: + payload = self.recovery() + payload["review_nodes"][0]["updatedAt"] = None + with self.assertRaises(subprocess.CalledProcessError): + self.invoke(payload) + + def test_review_signal_requires_canonical_workflow_identity_before_writes(self) -> None: + for identity in (None, "456", 999): + for path in ( + ".github/workflows/castiron-custom-code.yml", + ".github/workflows/castiron-custom-code.yml@evil.yml", + ): + with self.subTest(identity=identity, path=path): + payload = self.payload() + payload["run"].update({"workflow_id": identity, "path": path}) + payload["context"]["payload"]["workflow_run"] = dict(payload["run"]) + self.assertEqual(self.invoke(payload), []) + + def test_rejects_forged_or_superseded_review_signals(self) -> None: + for field, value in [ + ("path", ".github/workflows/other.yml"), + ("run_attempt", 9), + ("head_sha", "d" * 40), + ("event", "pull_request"), + ]: + with self.subTest(field=field): + payload = self.payload() + payload["run"][field] = value + with self.assertRaises(subprocess.CalledProcessError): + self.invoke(payload) + payload = self.payload() + payload["run"]["repository"] = {"full_name": "attacker/example"} + with self.assertRaises(subprocess.CalledProcessError): + self.invoke(payload) + + def test_head_change_keeps_observed_statuses_revoked_without_stale_reruns(self) -> None: + payload = self.payload() + changed = {**payload["current"], "head": {"sha": "d" * 40}} + payload["current_sequence"] = [payload["current"], changed] + payload["current"] = changed + result = self.invoke(payload) + self.assertEqual(len(result), 4) + self.assertTrue(all(item["state"] == "pending" for item in result)) + self.assertNotIn("d" * 40, {item["sha"] for item in result}) + + def test_queue_change_retries_and_invalidates_new_snapshot(self) -> None: + payload = self.payload() + old = list(payload["queue_nodes"]) + payload["queue_nodes"].append( + { + "headCommit": {"oid": "d" * 40}, + "pullRequest": {"number": 4, "headRefOid": "e" * 40}, + } + ) + payload["runs_by_sha"]["d" * 40] = [ + { + **payload["runs_by_sha"]["c" * 40][0], + "head_sha": "d" * 40, + "id": 16, + } + ] + payload["queue_pages"] = [ + { + "expected_cursor": None, + "nodes": old, + "pageInfo": {"hasNextPage": False}, + } + ] + result = self.invoke(payload) + pending = [item for item in result if item.get("state") == "pending"] + self.assertEqual({item["sha"] for item in pending}, {"a" * 40, "c" * 40, "d" * 40}) + self.assertEqual([item["run_id"] for item in result if "run_id" in item], [12, 14, 16]) + self.assertTrue(all(item.get("state") == "pending" for item in result[:-3])) + + def test_empty_review_pr_list_uses_authenticated_fork_discovery(self) -> None: + for associated in ([], [{"number": 3}]): + payload = self.payload() + payload["run"].update( + { + "pull_requests": [], + "head_repository": {"owner": {"login": "contributor"}}, + "head_branch": "sdk", + } + ) + payload["associated_pulls"] = associated + payload["fallback_pulls"] = [{"number": 3}] + self.assertEqual(len(self.invoke(payload)), 6) + payload["current"]["head"]["sha"] = "d" * 40 + payload["merge_sha"] = "e" * 40 + payload["merge_commit"] = {"parents": []} + self.assertEqual(self.invoke(payload), []) + + def test_shared_head_revokes_the_run_source_pr(self) -> None: + payload = self.payload() + payload["run"]["pull_requests"] = [] + payload["run"]["head_repository"]["id"] = 101 + payload["current"]["head"].update(ref="sdk", repo={"id": 101}) + payload["associated_pulls"] = [{"number": number} for number in (3, 4, 5)] + payload["pulls_by_number"] = { + str(number): { + **payload["current"], + "number": number, + "head": {**payload["current"]["head"], **change}, + } + for number, change in ((4, {"ref": "other"}), (5, {"repo": {"id": 102}})) + } + result = self.invoke(payload) + self.assertEqual([item.get("state") for item in result[:4]], ["pending"] * 4) + self.assertEqual({item["sha"] for item in result[:4]}, {"a" * 40, "c" * 40}) + + def test_branch_only_merge_signal_requires_current_merge_and_base(self) -> None: + payload = self.payload() + payload["run"]["pull_requests"] = [] + payload["run"]["head_sha"] = payload["context"]["payload"]["workflow_run"]["head_sha"] = ( + "e" * 40 + ) + payload["fallback_pulls"] = [{"number": 3}] + payload["merge_commit"] = {"parents": [{"sha": "b" * 40}, {"sha": "a" * 40}]} + payload["merge_sha"] = "f" * 40 + self.assertEqual(self.invoke(payload), []) + + payload["merge_sha"] = "e" * 40 + self.assertEqual(len(self.invoke(payload)), 6) + payload["current"]["base"]["sha"] = "d" * 40 + payload["comparisons"] = { + f"{'d' * 40}...{'a' * 40}": {"merge_base_commit": {"sha": "b" * 40}} + } + self.assertEqual(self.invoke(payload), []) + + def test_merge_sha_signal_survives_base_advance_and_rejects_wrong_parents(self) -> None: + payload = self.payload() + payload["run"]["head_sha"] = payload["context"]["payload"]["workflow_run"]["head_sha"] = ( + "e" * 40 + ) + payload["current"]["base"]["sha"] = "d" * 40 + payload["comparisons"] = { + f"{'d' * 40}...{'a' * 40}": {"merge_base_commit": {"sha": "b" * 40}} + } + payload["merge_commit"] = {"parents": [{"sha": "b" * 40}, {"sha": "a" * 40}]} + self.assertEqual(len(self.invoke(payload)), 6) + payload["comparisons"][f"{'b' * 40}...{'d' * 40}"] = { + "merge_base_commit": {"sha": "f" * 40} + } + self.assertEqual(self.invoke(payload), []) + payload["merge_commit"]["parents"].reverse() + self.assertEqual(self.invoke(payload), []) + + def test_trusted_policy_decision_controls_revocation(self) -> None: + payload = self.payload() + payload["requires_human"] = False + self.assertEqual(self.invoke(payload), []) + payload["requires_human"] = True + self.assertEqual(len(self.invoke(payload)), 6) + + def test_policy_failure_or_malformed_decision_cannot_write_statuses(self) -> None: + for result in ({"policy_error": True}, {"requires_human": "false"}): + with self.subTest(result=result), tempfile.TemporaryDirectory() as directory: + payload = {**self.payload(), **result} + capture = Path(directory) / "writes.json" + payload["capture_writes"] = str(capture) + with self.assertRaises(subprocess.CalledProcessError): + self.invoke(payload) + self.assertEqual(json.loads(capture.read_text()), []) + + def test_revoked_go_ratchet_activation_invalidates_pr_and_queue_statuses(self) -> None: + for changed in ({"state": "DISMISSED"}, {"body": ""}): + with self.subTest(changed=changed): + payload = self.payload() + payload["policies_by_sha"]["a" * 40] = { + **payload["policies_by_sha"]["b" * 40], + "ratchet": "go", + } + payload["review_nodes"] = [{**self.approval(), **changed}] + writes = self.invoke(payload) + self.assertCountEqual( + [(item["sha"], item["state"]) for item in writes if "state" in item], + [("a" * 40, "pending")] * 2 + [("c" * 40, "pending")] * 2, + ) + self.assertCountEqual( + [item["run_id"] for item in writes if "run_id" in item], [12, 14] + ) + + def test_closed_or_superseded_review_is_a_no_op(self) -> None: + for changed in ({"state": "closed"}, {"head": {"sha": "f" * 40}}): + payload = self.payload() + payload["current"].update(changed) + self.assertEqual(self.invoke(payload), []) + + def test_null_queue_association_does_not_block_revocation(self) -> None: + payload = self.payload() + payload["queue_nodes"].insert(0, {"headCommit": {"oid": "f" * 40}, "pullRequest": None}) + result = self.invoke(payload) + self.assertEqual(len(result), 6) + self.assertNotIn("f" * 40, {item.get("sha") for item in result}) + payload["queue_nodes"] = payload["queue_nodes"][:1] + self.assertEqual(len(self.invoke(payload)), 3) + + def test_rerun_requires_the_reviewed_pr_not_just_shared_head(self) -> None: + payload = self.payload() + correct = payload["runs_by_sha"]["a" * 40][0] + main = { + **payload["current"], + "number": 4, + "base": {**payload["current"]["base"], "ref": "main"}, + } + payload["pulls_by_number"] = {"4": main} + other: dict[str, Any] = { + **correct, + "id": 30, + "pull_requests": [{"number": 4, "head": {"sha": "a" * 40}}], + } + payload["runs_by_sha"]["a" * 40].append(other) + result = self.invoke(payload) + self.assertEqual([item["run_id"] for item in result if "run_id" in item], [12, 14]) + # Empty fork associations may rerun only if canonical discovery selects this next PR. + fork: dict[str, Any] = { + **correct, + "pull_requests": [], + "head_repository": {"owner": {"login": "contributor"}}, + "head_branch": "sdk", + } + payload["fallback_pulls"] = [{"number": 3}] + payload["runs_by_sha"]["a" * 40] = [fork, other] + result = self.invoke(payload) + self.assertEqual([item["run_id"] for item in result if "run_id" in item], [12, 14]) + association_cases: tuple[list[dict[str, Any]], ...] = ( + [], + [*correct["pull_requests"], *other["pull_requests"]], + ) + for associations in association_cases: + payload["associated_pulls"] = [{"number": 3}, {"number": 4}] + payload["runs_by_sha"]["a" * 40] = [{**fork, "pull_requests": associations}, other] + result = self.invoke(payload) + self.assertEqual([item["run_id"] for item in result if "run_id" in item], [14]) + self.assertTrue(all(item["state"] == "pending" for item in result[:4])) + + def test_unprepared_queue_entry_still_revokes_pr_statuses(self) -> None: + payload = self.payload() + payload["queue_nodes"][0]["headCommit"] = None + result = self.invoke(payload) + self.assertEqual([item.get("state") for item in result], ["pending", "pending", None]) + self.assertEqual(result[-1]["run_id"], 12) + + def test_unrelated_review_does_not_restart_reporter(self) -> None: + payload = self.payload() + payload["files"] = [{"filename": "src/client.ts"}] + self.assertEqual(self.invoke(payload), []) + + def test_no_success_or_foreign_run_can_be_published(self) -> None: + payload = self.payload() + payload["runs_by_sha"]["a" * 40][0]["repository"] = {"full_name": "other/repo"} + result = self.invoke(payload) + self.assertEqual( + [item["run_id"] for item in result if item.get("operation") == "rerun"], [14] + ) + self.assertTrue(all(item.get("state") != "success" for item in result)) + + def test_signal_is_unprivileged_and_writers_serialize(self) -> None: + producer = (WORKFLOW.parent / "castiron-custom-code.yml").read_text() + self.assertIn("pull_request_review:\n types: [submitted, edited, dismissed]", producer) + signal = producer.split(" queue-signal:\n", 1)[1].split(" candidate-tests:\n", 1)[0] + self.assertIn("permissions: {}", signal) + self.assertNotIn("checkout@", signal) + handler = WORKFLOW.read_text() + revoke = handler.split(" review-change:\n", 1)[1].split(" compute:\n", 1)[0] + self.assertNotIn("checkout@", revoke) + self.assertNotIn("ref: ${{ github.event", revoke) + self.assertIn("path.join(root, 'custom_code_policy.py'), 'review-required'", revoke) + self.assertNotIn("download-artifact", revoke) + self.assertEqual( + handler.count("group: castiron-budget-writes-${{ github.repository_id }}"), 2 + ) + + +if __name__ == "__main__": + unittest.main() diff --git a/src/helpers/browser.ts b/src/helpers/browser.ts index 0a2cbb5e6e..85cbf9b71b 100644 --- a/src/helpers/browser.ts +++ b/src/helpers/browser.ts @@ -573,14 +573,19 @@ function readText(value: unknown, limit: number, allowEmpty: boolean): string { return value; } -function validImageBreakpoint(value: unknown): boolean { - return ( - value === undefined || - value === null || - (isObj(value) && - configuredOption(value, 'mode') === 'explicit' && - Object.keys(value).every((key) => key === 'mode')) - ); +function snapshotImageBreakpoint(value: unknown): ResponseInputImageContent['prompt_cache_breakpoint'] { + if (value === undefined || value === null) { + return value; + } + if (!isObj(value) || Object.keys(value).some((key) => key !== 'mode' && key !== 'ttl')) { + throw new TypeError('Invalid browser image breakpoint.'); + } + const mode = configuredOption(value, 'mode'); + const ttl = configuredOption(value, 'ttl'); + if (mode !== 'explicit' || (ttl !== undefined && ttl !== '30m' && ttl !== '12h')) { + throw new TypeError('Invalid browser image breakpoint.'); + } + return { mode, ...(ttl === undefined ? {} : { ttl }) }; } function validImageSource(value: unknown): value is string | null | undefined { @@ -613,14 +618,15 @@ function snapshotImage(value: unknown, member: 'screenshot' | 'zoom'): ResponseI const detail = configuredOption(value, 'detail'); const image_url = configuredOption(value, 'image_url'); const file_id = configuredOption(value, 'file_id'); - const prompt_cache_breakpoint = configuredOption(value, 'prompt_cache_breakpoint'); + const prompt_cache_breakpoint = snapshotImageBreakpoint( + configuredOption(value, 'prompt_cache_breakpoint'), + ); if ( type !== 'input_image' || !validImageDetail(detail) || !validImageSource(image_url) || !validImageSource(file_id) || - (typeof image_url !== 'string' && typeof file_id !== 'string') || - !validImageBreakpoint(prompt_cache_breakpoint) + (typeof image_url !== 'string' && typeof file_id !== 'string') ) { throw new TypeError('Invalid browser image.'); } @@ -629,9 +635,7 @@ function snapshotImage(value: unknown, member: 'screenshot' | 'zoom'): ResponseI ...(detail === undefined ? {} : { detail }), ...(image_url === undefined ? {} : { image_url }), ...(file_id === undefined ? {} : { file_id }), - ...(prompt_cache_breakpoint === undefined - ? {} - : { prompt_cache_breakpoint: prompt_cache_breakpoint === null ? null : { mode: 'explicit' } }), + ...(prompt_cache_breakpoint === undefined ? {} : { prompt_cache_breakpoint }), }; } catch { throw new OpenAIError( diff --git a/src/helpers/responses-tool-runner.ts b/src/helpers/responses-tool-runner.ts index eb10844dd0..0b230982a4 100644 --- a/src/helpers/responses-tool-runner.ts +++ b/src/helpers/responses-tool-runner.ts @@ -479,6 +479,15 @@ function outputRecord(value: unknown, keys: readonly string[]): Record [key, field.value])); } +function suppliedBreakpoint(cache: unknown) { + const breakpoint = outputRecord(cache, ['mode', 'ttl']); + const { ttl } = breakpoint; + if (breakpoint['mode'] !== 'explicit' || (ttl !== undefined && ttl !== '30m' && ttl !== '12h')) { + throw new TypeError('Supplied output has an invalid cache breakpoint.'); + } + return { mode: 'explicit', ...(ttl === undefined ? {} : { ttl }) }; +} + function suppliedBlock(value: unknown): ResponseFunctionCallOutputItem { const block = outputRecord(value, [ 'type', @@ -537,11 +546,7 @@ function suppliedBlock(value: unknown): ResponseFunctionCallOutputItem { } const cache = block['prompt_cache_breakpoint']; if (cache !== undefined && cache !== null) { - const breakpoint = outputRecord(cache, ['mode']); - if (breakpoint['mode'] !== 'explicit') { - throw new TypeError('Supplied output has an invalid cache breakpoint.'); - } - block['prompt_cache_breakpoint'] = { mode: 'explicit' }; + block['prompt_cache_breakpoint'] = suppliedBreakpoint(cache); } if (type === 'input_text') { const { text } = block; diff --git a/src/resources/audio/voices.ts b/src/resources/audio/voices.ts index d5fcc44c30..418980b5aa 100644 --- a/src/resources/audio/voices.ts +++ b/src/resources/audio/voices.ts @@ -161,10 +161,6 @@ export declare namespace VoiceCreateParams { type?: 'audio_sample'; } - /** - * Creates a synthetic voice from a text description. Supports application/json or - * multipart/form-data. - */ export interface Prompt { /** * The name of the new voice. @@ -184,7 +180,7 @@ export declare namespace VoiceCreateParams { /** * The voice creation model to use. Defaults to `auto`. */ - model?: string | 'auto' | '2026-10-08'; + model?: (string & {}) | 'auto' | '2026-10-08'; /** * Optional text for the voice to speak during creation. If omitted, a script is diff --git a/src/resources/beta/agents/agents.ts b/src/resources/beta/agents/agents.ts index 783f019ad8..10398606c8 100644 --- a/src/resources/beta/agents/agents.ts +++ b/src/resources/beta/agents/agents.ts @@ -3,6 +3,25 @@ import { APIResource } from '../../../core/resource'; import * as AgentsAPI from './agents'; import * as TurnsAPI from './sessions/turns/turns'; +import * as AutomationsAPI from './automations/automations'; +import { + Automation, + AutomationAgentConfig, + AutomationCreateParams, + AutomationCreatedBy, + AutomationDeleted, + AutomationEnvironment, + AutomationListParams, + AutomationTarget, + AutomationTargetParam, + AutomationUpdateParams, + Automations, + AutomationsPage, + CreateAutomationParamsOnce, + CreateAutomationParamsPeriodic, + OneTimeAutomation, + PeriodicAutomation, +} from './automations/automations'; import * as EnvironmentsAPI from './environments/environments'; import { EnvironmentCreateParams, @@ -153,6 +172,7 @@ function normalizeRequestOptionsForQuery( } export class Agents extends APIResource { + automations: AutomationsAPI.Automations = new AutomationsAPI.Automations(this._client); environments: EnvironmentsAPI.Environments = new EnvironmentsAPI.Environments(this._client); vaults: VaultsAPI.Vaults = new VaultsAPI.Vaults(this._client); sessions: SessionsAPI.Sessions = new SessionsAPI.Sessions(this._client); @@ -3268,7 +3288,8 @@ export type AgentTool = | AgentTool.AgentToolResourceProgrammaticToolCalling | AgentTool.AgentToolResourceMcp | AgentTool.AgentToolResourceWebSearch - | AgentTool.AgentToolResourceComputerUse; + | AgentTool.AgentToolResourceComputerUse + | AgentTool.AgentToolResourceAutomations; export namespace AgentTool { /** @@ -3433,6 +3454,16 @@ export namespace AgentTool { */ type: 'computer_use'; } + + /** + * Lets the agent manage its own scheduled wakeups. + */ + export interface AgentToolResourceAutomations { + /** + * The type of the object. Always `automations`. + */ + type: 'automations'; + } } /** @@ -3444,7 +3475,8 @@ export type AgentToolParam = | AgentToolParam.AgentToolConfigParamProgrammaticToolCalling | AgentToolParam.AgentToolConfigParamMcp | AgentToolParam.AgentToolConfigParamWebSearch - | AgentToolParam.AgentToolConfigParamComputerUse; + | AgentToolParam.AgentToolConfigParamComputerUse + | AgentToolParam.AgentToolConfigParamAutomations; export namespace AgentToolParam { /** @@ -3630,6 +3662,16 @@ export namespace AgentToolParam { */ include_screenshots?: boolean; } + + /** + * Lets the agent manage its own scheduled wakeups. + */ + export interface AgentToolConfigParamAutomations { + /** + * The type of the object. Always `automations`. + */ + type: 'automations'; + } } /** @@ -4578,7 +4620,8 @@ export type PersistedAgentTool = | PersistedAgentTool.PersistedAgentToolResourceProgrammaticToolCalling | PersistedAgentTool.PersistedAgentToolResourceMcp | PersistedAgentTool.PersistedAgentToolResourceWebSearch - | PersistedAgentTool.PersistedAgentToolResourceComputerUse; + | PersistedAgentTool.PersistedAgentToolResourceComputerUse + | PersistedAgentTool.PersistedAgentToolResourceAutomations; export namespace PersistedAgentTool { /** @@ -4752,6 +4795,16 @@ export namespace PersistedAgentTool { */ type: 'computer_use'; } + + /** + * Lets the agent manage its own scheduled wakeups. + */ + export interface PersistedAgentToolResourceAutomations { + /** + * The type of the object. Always `automations`. + */ + type: 'automations'; + } } /** @@ -4763,7 +4816,8 @@ export type PersistedAgentToolParam = | PersistedAgentToolParam.PersistedAgentToolConfigParamProgrammaticToolCalling | PersistedAgentToolParam.PersistedAgentToolConfigParamMcp | PersistedAgentToolParam.PersistedAgentToolConfigParamWebSearch - | PersistedAgentToolParam.PersistedAgentToolConfigParamComputerUse; + | PersistedAgentToolParam.PersistedAgentToolConfigParamComputerUse + | PersistedAgentToolParam.PersistedAgentToolConfigParamAutomations; export namespace PersistedAgentToolParam { /** @@ -4947,6 +5001,16 @@ export namespace PersistedAgentToolParam { */ include_screenshots?: boolean; } + + /** + * Lets the agent manage its own scheduled wakeups. + */ + export interface PersistedAgentToolConfigParamAutomations { + /** + * The type of the object. Always `automations`. + */ + type: 'automations'; + } } /** @@ -5576,6 +5640,7 @@ export namespace EnvironmentParam { }; } +Agents.Automations = Automations; Agents.Environments = Environments; Agents.Vaults = Vaults; Agents.Sessions = Sessions; @@ -5690,6 +5755,25 @@ export declare namespace Agents { type AgentListParams as AgentListParams, }; + export { + Automations as Automations, + type Automation as Automation, + type AutomationAgentConfig as AutomationAgentConfig, + type AutomationCreatedBy as AutomationCreatedBy, + type AutomationDeleted as AutomationDeleted, + type AutomationEnvironment as AutomationEnvironment, + type AutomationTarget as AutomationTarget, + type AutomationTargetParam as AutomationTargetParam, + type OneTimeAutomation as OneTimeAutomation, + type PeriodicAutomation as PeriodicAutomation, + type CreateAutomationParamsPeriodic as CreateAutomationParamsPeriodic, + type CreateAutomationParamsOnce as CreateAutomationParamsOnce, + type AutomationsPage as AutomationsPage, + type AutomationCreateParams as AutomationCreateParams, + type AutomationUpdateParams as AutomationUpdateParams, + type AutomationListParams as AutomationListParams, + }; + export { Environments as Environments, type EnvironmentInfo as EnvironmentInfo, diff --git a/src/resources/beta/agents/automations.ts b/src/resources/beta/agents/automations.ts new file mode 100644 index 0000000000..f5d3b06cf6 --- /dev/null +++ b/src/resources/beta/agents/automations.ts @@ -0,0 +1,3 @@ +// File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +export * from './automations/index'; diff --git a/src/resources/beta/agents/automations/automations.ts b/src/resources/beta/agents/automations/automations.ts new file mode 100644 index 0000000000..a64bf07676 --- /dev/null +++ b/src/resources/beta/agents/automations/automations.ts @@ -0,0 +1,1198 @@ +// File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +import { APIResource } from '../../../../core/resource'; +import * as AutomationsAPI from './automations'; +import * as AgentsAPI from '../agents'; +import * as InvocationsAPI from './invocations'; +import { + AutomationInvocation, + AutomationInvocationSource, + AutomationInvocationsPage, + InvocationListParams, + InvocationRetrieveParams, + Invocations, +} from './invocations'; +import { APIPromise } from '../../../../core/api-promise'; +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'; + +function resolveResourceRequestOptions( + options: RequestOptions | undefined, + buildOptions: (options: RequestOptions | undefined) => RequestOptions | Promise, +): Promise { + return Promise.resolve(options).then(buildOptions); +} + +// Recognizable options across SDK runtime versions. Keep this independent of +// private RequestOptions fields so older handwritten runtimes still compile. +const normalizeRequestOptionsForQueryKeys = new Set([ + 'method', + 'path', + 'query', + 'body', + 'headers', + 'maxRetries', + 'stream', + 'timeout', + 'httpAgent', + 'fetchOptions', + 'signal', + 'idempotencyKey', + 'defaultBaseURL', + '__metadata', + '__binaryRequest', + '__binaryResponse', + '__streamClass', + '__security', + '__synthesizeEventData', +]); + +function normalizeRequestOptionsForQuery( + value: unknown, + queryKeys: ReadonlyArray, + options: RequestOptions | undefined, +): + | ({ + [K in 'headers' | 'maxRetries' | 'timeout' | 'signal' | 'idempotencyKey' | 'query']?: RequestOptions[K]; + } & { + [ + K in + | 'method' + | 'path' + | 'body' + | 'stream' + | 'httpAgent' + | 'fetchOptions' + | 'defaultBaseURL' + | '__metadata' + | '__binaryRequest' + | '__binaryResponse' + | '__streamClass' + | '__security' + | '__synthesizeEventData' + ]?: never; + }) + | undefined { + if (typeof value !== 'object' || value === null) return undefined; + // Optional never fields can still be explicitly undefined unless consumers + // enable exactOptionalPropertyTypes. Snapshot data without invoking getters. + const entries = Object.entries(Object.getOwnPropertyDescriptors(value)).filter( + ([, descriptor]) => descriptor.enumerable && (!('value' in descriptor) || descriptor.value !== undefined), + ); + const keys = entries.map(([key]) => key); + const requestOnly = keys.some( + (key) => normalizeRequestOptionsForQueryKeys.has(key) && !queryKeys.includes(key), + ); + if (!requestOnly) return undefined; + // Declared query fields, including stream, must use the query argument. + // Mixing them with request-only options is ambiguous and could change the return type. + if ( + options !== undefined || + keys.some((key) => !normalizeRequestOptionsForQueryKeys.has(key) || queryKeys.includes(key)) + ) { + throw new TypeError('Query parameters and request options must be passed as separate arguments.'); + } + // The query position must not gain authority to change the request destination + // or transport. Those overrides require the explicit request options argument. + if ( + keys.some( + (key) => !['headers', 'maxRetries', 'timeout', 'signal', 'idempotencyKey', 'query'].includes(key), + ) + ) { + throw new TypeError('Pass transport overrides in the explicit request options argument.'); + } + // Copy only the validated fields. Spreading value would reintroduce undefined + // transport overrides, and deleting them would mutate the caller's object. + return Object.fromEntries( + entries.map(([key, descriptor]) => { + if ('value' in descriptor) return [key, descriptor.value]; + return [key, descriptor.get ? Reflect.apply(descriptor.get, value, []) : undefined]; + }), + ) as { + [K in 'headers' | 'maxRetries' | 'timeout' | 'signal' | 'idempotencyKey' | 'query']?: RequestOptions[K]; + } & { + [ + K in + | 'method' + | 'path' + | 'body' + | 'stream' + | 'httpAgent' + | 'fetchOptions' + | 'defaultBaseURL' + | '__metadata' + | '__binaryRequest' + | '__binaryResponse' + | '__streamClass' + | '__security' + | '__synthesizeEventData' + ]?: never; + }; +} + +export class Automations extends APIResource { + invocations: InvocationsAPI.Invocations = new InvocationsAPI.Invocations(this._client); + + /** + * Saves an active automation without invoking it immediately. + * + * @example + * ```ts + * const automation = + * await client.beta.agents.automations.create({ + * expression: 'x', + * name: 'x', + * target: { + * environment: { type: 'none' }, + * input: [ + * { + * content: [{ text: 'text', type: 'input_text' }], + * role: 'user', + * }, + * ], + * type: 'new_session', + * }, + * timezone: 'x', + * type: 'periodic', + * }); + * ``` + */ + create(body: AutomationCreateParams, options?: RequestOptions): APIPromise { + return this._client.post( + '/agents/automations', + resolveResourceRequestOptions(options, (options) => ({ + body, + ...options, + headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]), + __security: { bearerAuth: true }, + })), + ); + } + + /** + * Retrieves a project-owned automation. + * + * @example + * ```ts + * const automation = + * await client.beta.agents.automations.retrieve( + * 'automation_id', + * ); + * ``` + */ + retrieve(automationID: string, options?: RequestOptions): APIPromise { + return this._client.get( + path`/agents/automations/${automationID}`, + resolveResourceRequestOptions(options, (options) => ({ + ...options, + headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]), + __security: { bearerAuth: true }, + })), + ); + } + + /** + * Updates supplied fields; target and metadata replace the whole field. + * + * @example + * ```ts + * const automation = + * await client.beta.agents.automations.update( + * 'automation_id', + * ); + * ``` + */ + update( + automationID: string, + body: AutomationUpdateParams, + options?: RequestOptions, + ): APIPromise { + return this._client.post( + path`/agents/automations/${automationID}`, + resolveResourceRequestOptions(options, (options) => ({ + body, + ...options, + headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]), + __security: { bearerAuth: true }, + })), + ); + } + + /** + * Lists project-owned automations, optionally filtered by target session. + * + * @example + * ```ts + * // Automatically fetches more pages as needed. + * for await (const automation of client.beta.agents.automations.list()) { + * // ... + * } + * ``` + */ + list( + query?: + | (AutomationListParams & + ( + | { + [ + K in + | 'method' + | 'path' + | 'query' + | 'body' + | 'headers' + | 'maxRetries' + | 'stream' + | 'timeout' + | 'httpAgent' + | 'fetchOptions' + | 'signal' + | 'idempotencyKey' + | 'defaultBaseURL' + | '__metadata' + | '__binaryRequest' + | '__binaryResponse' + | '__streamClass' + | '__security' + | '__synthesizeEventData' + ]?: never; + } + | null + | undefined + )) + | null + | undefined, + options?: RequestOptions, + ): PagePromise; + list( + options?: { + [K in 'headers' | 'maxRetries' | 'timeout' | 'signal' | 'idempotencyKey' | 'query']?: RequestOptions[K]; + } & { + [ + K in + | 'method' + | 'path' + | 'body' + | 'stream' + | 'httpAgent' + | 'fetchOptions' + | 'defaultBaseURL' + | '__metadata' + | '__binaryRequest' + | '__binaryResponse' + | '__streamClass' + | '__security' + | '__synthesizeEventData' + ]?: never; + }, + ): PagePromise; + list( + query: + | AutomationListParams + | ({ + [ + K in 'headers' | 'maxRetries' | 'timeout' | 'signal' | 'idempotencyKey' | 'query' + ]?: RequestOptions[K]; + } & { + [ + K in + | 'method' + | 'path' + | 'body' + | 'stream' + | 'httpAgent' + | 'fetchOptions' + | 'defaultBaseURL' + | '__metadata' + | '__binaryRequest' + | '__binaryResponse' + | '__streamClass' + | '__security' + | '__synthesizeEventData' + ]?: never; + }) + | null + | undefined = {}, + options?: RequestOptions, + ): PagePromise { + const normalizeRequestOptionsForQueryOptions = normalizeRequestOptionsForQuery( + query, + ['after', 'limit', 'order', 'session_id'], + options, + ); + if (normalizeRequestOptionsForQueryOptions !== undefined) { + options = normalizeRequestOptionsForQueryOptions; + query = {}; + } + query = query as AutomationListParams | null | undefined; + return this._client.getAPIList( + '/agents/automations', + CursorPage, + resolveResourceRequestOptions(options, (options) => ({ + query, + ...options, + headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]), + __security: { bearerAuth: true }, + })), + ); + } + + /** + * Deletes the automation and prevents future invocations without deleting its + * target session. + * + * @example + * ```ts + * const automationDeleted = + * await client.beta.agents.automations.delete( + * 'automation_id', + * ); + * ``` + */ + delete(automationID: string, options?: RequestOptions): APIPromise { + return this._client.delete( + path`/agents/automations/${automationID}`, + resolveResourceRequestOptions(options, (options) => ({ + ...options, + headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]), + __security: { bearerAuth: true }, + })), + ); + } + + /** + * Pauses future scheduled delivery without stopping an active session. + * + * @example + * ```ts + * const automation = + * await client.beta.agents.automations.pause( + * 'automation_id', + * ); + * ``` + */ + pause(automationID: string, options?: RequestOptions): APIPromise { + return this._client.post( + path`/agents/automations/${automationID}/pause`, + resolveResourceRequestOptions(options, (options) => ({ + ...options, + headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]), + __security: { bearerAuth: true }, + })), + ); + } + + /** + * Resumes scheduled delivery; one-time automations without a pending invocation + * require a future run_at. + * + * @example + * ```ts + * const automation = + * await client.beta.agents.automations.resume( + * 'automation_id', + * ); + * ``` + */ + resume(automationID: string, options?: RequestOptions): APIPromise { + return this._client.post( + path`/agents/automations/${automationID}/resume`, + resolveResourceRequestOptions(options, (options) => ({ + ...options, + headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]), + __security: { bearerAuth: true }, + })), + ); + } +} + +export type AutomationsPage = CursorPage; + +/** + * A saved automation and its schedule. + */ +export type Automation = PeriodicAutomation | OneTimeAutomation; + +/** + * Inline agent configuration without a generated session-local identity. + */ +export interface AutomationAgentConfig { + /** + * Custom instructions, or null when absent. + */ + instructions: string | null; + + /** + * The requested model name. + */ + model: string; + + /** + * The configuration for creating and coordinating subagents. + */ + multi_agent: AgentsAPI.MultiAgentConfig; + + /** + * The configured reasoning policy. + */ + reasoning: AgentsAPI.AgentReasoning; + + /** + * The configured service-tier policy. + */ + service_tier: 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast'; + + /** + * The configured output format and verbosity. + */ + text: AgentsAPI.AgentText; + + /** + * Configured tools, excluding confidential credentials. + */ + tools: Array; +} + +/** + * How the automation was created, independently of how an invocation started. + */ +export type AutomationCreatedBy = + | AutomationCreatedBy.AutomationCreatedByResourceDeveloper + | AutomationCreatedBy.AutomationCreatedByResourceAgent; + +export namespace AutomationCreatedBy { + export interface AutomationCreatedByResourceDeveloper { + /** + * The type of the object. Always `developer`. + */ + type: 'developer'; + } + + export interface AutomationCreatedByResourceAgent { + /** + * The creator session, which is also the automation's target. + */ + session_id: string; + + /** + * The tool call that created the automation. + */ + tool_call_id: string; + + /** + * The type of the object. Always `agent`. + */ + type: 'agent'; + } +} + +export interface AutomationDeleted { + /** + * The deleted automation ID. + */ + id: string; + + /** + * Always true. + */ + deleted: boolean; + + /** + * Always `agent.automation.deleted`. + */ + object: 'agent.automation.deleted'; +} + +/** + * Environment selection saved before an invocation creates its session. + */ +export type AutomationEnvironment = + | AutomationEnvironment.AutomationEnvironmentResourceNone + | AutomationEnvironment.AutomationEnvironmentResourceOpenAIHosted + | AutomationEnvironment.AutomationEnvironmentResourceSelfHosted; + +export namespace AutomationEnvironment { + export interface AutomationEnvironmentResourceNone { + /** + * The type of the object. Always `none`. + */ + type: 'none'; + } + + /** + * Hosted environment selection with confidential setup commands and variables + * omitted. + */ + export interface AutomationEnvironmentResourceOpenAIHosted { + /** + * Directory overrides, or null to inherit the template or creation default. + */ + capability_directories: Array | null; + + /** + * The configured container size, or null to use the creation default. + */ + container_size: 'small' | 'medium' | 'large' | null; + + /** + * Desktop overrides, or null to inherit the template or creation default. + */ + desktop: AutomationEnvironmentResourceOpenAIHosted.Desktop | null; + + /** + * An existing environment reference, or null when provisioning a new environment. + */ + environment_id: string | null; + + /** + * A template reference, or null when no template is selected. + */ + environment_template_id: string | null; + + /** + * File overrides, excluding contents, or null to inherit. + */ + files: Array< + | AutomationEnvironmentResourceOpenAIHosted.HostedTemplateFileResourceFileID + | AutomationEnvironmentResourceOpenAIHosted.HostedTemplateFileResourceInline + > | null; + + /** + * Network overrides, or null to inherit the template or creation default. + */ + network: AutomationEnvironmentResourceOpenAIHosted.Network | null; + + /** + * Package overrides, or null to inherit the template or creation default. + */ + packages: AutomationEnvironmentResourceOpenAIHosted.Packages | null; + + /** + * Plugin overrides, excluding archive contents, or null to inherit. + */ + plugins: Array | null; + + /** + * Skill overrides, excluding archive contents, or null to inherit. + */ + skills: Array< + | AutomationEnvironmentResourceOpenAIHosted.HostedTemplateSkillResourceSkillReference + | AutomationEnvironmentResourceOpenAIHosted.HostedTemplateSkillResourceInline + > | null; + + /** + * The type of the object. Always `openai_hosted`. + */ + type: 'openai_hosted'; + } + + export namespace AutomationEnvironmentResourceOpenAIHosted { + /** + * Desktop overrides, or null to inherit the template or creation default. + */ + export interface Desktop { + /** + * Whether the environment provisions a desktop and browser proxy. + */ + enabled: boolean; + } + + /** + * A project-scoped Files API reference resolved separately for each session. + */ + export interface HostedTemplateFileResourceFileID { + /** + * The ID of the uploaded file. + */ + file_id: string; + + /** + * The file's absolute path inside the environment. + */ + path: string; + + /** + * The type of the object. Always `file_id`. + */ + type: 'file_id'; + } + + /** + * Metadata for confidential inline file contents. + */ + export interface HostedTemplateFileResourceInline { + /** + * The file's absolute path inside the environment. + */ + path: string; + + /** + * The decoded size of the inline file in bytes. + */ + size_bytes: number; + + /** + * The type of the object. Always `inline`. + */ + type: 'inline'; + } + + /** + * Network overrides, or null to inherit the template or creation default. + */ + export interface Network { + /** + * The environment's network access mode. + * + * - `enabled` - Allows unrestricted network access. + * - `disabled` - Disables network access. + * - `restricted` - Applies the configured domain restrictions. + */ + access: 'enabled' | 'disabled' | 'restricted'; + + /** + * Domains the environment may access when network access is restricted. + */ + allowed_domains: Array; + } + + /** + * Package overrides, or null to inherit the template or creation default. + */ + export interface Packages { + /** + * npm packages installed globally in the environment. + */ + npm: Array; + + /** + * Python packages installed in the environment. + */ + python: Array; + + /** + * System packages installed in the environment. + */ + system: Array; + } + + /** + * A skill resolved afresh from the Skills API whenever a session starts. + */ + export interface HostedTemplateSkillResourceSkillReference { + /** + * The referenced skill ID. + */ + skill_id: string; + + /** + * The type of the object. Always `skill_reference`. + */ + type: 'skill_reference'; + + /** + * The requested version selector, including `latest`. + */ + version: string | null; + } + + /** + * Safe metadata for an inline skill archive. + */ + export interface HostedTemplateSkillResourceInline { + /** + * The skill description declared in `SKILL.md`. + */ + description: string; + + /** + * The skill name declared in `SKILL.md`. + */ + name: string; + + /** + * The type of the object. Always `inline`. + */ + type: 'inline'; + } + } + + export interface AutomationEnvironmentResourceSelfHosted { + /** + * Directories that expose capabilities to the agent. + */ + capability_directories: Array; + + /** + * An existing registration, or null to create a session-owned environment. + */ + environment_id: string | null; + + /** + * The type of the object. Always `self_hosted`. + */ + type: 'self_hosted'; + + /** + * The absolute project directory in the environment. + */ + workspace_directory: string; + } +} + +/** + * Saved target configuration, excluding confidential request-only values. + */ +export type AutomationTarget = + | AutomationTarget.AutomationTargetResourceNewSession + | AutomationTarget.AutomationTargetResourceExistingSession; + +export namespace AutomationTarget { + export interface AutomationTargetResourceNewSession { + /** + * The inline agent configuration, or null when agent_id is configured. + */ + agent: AutomationsAPI.AutomationAgentConfig | null; + + /** + * The saved agent reference, or null when an inline agent is configured. + */ + agent_id: string | null; + + /** + * Configuration or references used to select the execution environment. + */ + environment: AutomationsAPI.AutomationEnvironment; + + /** + * Initial input delivered to each new session. + */ + input: Array; + + /** + * Metadata attached to each new session. + */ + metadata: { [key: string]: string }; + + /** + * The type of the object. Always `new_session`. + */ + type: 'new_session'; + + /** + * Vaults made available to each new session. + */ + vault_ids: Array; + } + + export namespace AutomationTargetResourceNewSession { + /** + * A user message recorded in a session. + */ + export interface Input { + /** + * The content of the message. + */ + content: Array; + + /** + * The role of the message author. Always `user`. + */ + role: 'user'; + + /** + * The type of the input item. Always `message`. + */ + type: 'message'; + } + } + + export interface AutomationTargetResourceExistingSession { + /** + * Saved instructions delivered as an automation notification. + */ + instructions: string; + + /** + * The session receiving each invocation. + */ + session_id: string; + + /** + * The type of the object. Always `existing_session`. + */ + type: 'existing_session'; + } +} + +/** + * The session an automation invocation targets. + */ +export type AutomationTargetParam = + | AutomationTargetParam.AutomationTargetParamNewSession + | AutomationTargetParam.AutomationTargetParamExistingSession; + +export namespace AutomationTargetParam { + /** + * Create a session for each invocation. + */ + export interface AutomationTargetParamNewSession { + /** + * The execution environment for each new session. + */ + environment: AgentsAPI.EnvironmentParam; + + /** + * Initial user messages submitted with each new session. + */ + input: Array; + + /** + * The type of the object. Always `new_session`. + */ + type: 'new_session'; + + /** + * Inline agent configuration. Provide exactly one of agent and agent_id. + */ + agent?: AutomationTargetParamNewSession.Agent; + + /** + * A saved agent ID. Provide exactly one of agent and agent_id. + */ + agent_id?: string; + + /** + * Metadata attached to each new session. + */ + metadata?: { [key: string]: string } | null; + + /** + * The IDs of vaults made available to each new session. + */ + vault_ids?: Array | null; + } + + export namespace AutomationTargetParamNewSession { + /** + * Inline agent configuration. Provide exactly one of agent and agent_id. + */ + export interface Agent { + /** + * Additional instructions appended to the agent's default base instructions. Omit + * to leave unchanged. + */ + instructions?: string | null; + + /** + * The model to use for the agent. The requested model name is preserved. + */ + model?: string; + + /** + * Configuration for creating and coordinating subagents. + */ + multi_agent?: AgentsAPI.MultiAgentConfigParam | null; + + /** + * Configuration for model reasoning. Omit to keep the current settings; pass + * `null` to reset to the model's default effort. + */ + reasoning?: AgentsAPI.AgentReasoningParam | null; + + /** + * The service tier used for model requests. + * + * - `auto` - Selects the service tier automatically. + * - `default` - Uses the default service tier. + * - `flex` - Uses the flex service tier. + * - `priority` - Uses the priority service tier. + * - `fast` - Uses the fast service tier. + * - `ultrafast` - Uses the ultrafast service tier. + */ + service_tier?: 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast' | null; + + /** + * Configuration for text generated by the agent. + */ + text?: AgentsAPI.AgentTextParam | null; + + /** + * Tools available to the agent. Omit to inherit, or pass null to clear them. The + * resolved tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 + * JSON. + */ + tools?: Array | null; + } + } + + /** + * Deliver instructions to an existing session. + */ + export interface AutomationTargetParamExistingSession { + /** + * Instructions delivered as an automation notification. + */ + instructions: string; + + /** + * The session receiving each invocation. + */ + session_id: string; + + /** + * The type of the object. Always `existing_session`. + */ + type: 'existing_session'; + } +} + +/** + * Fields shared by periodic and one-time automations. + */ +export interface OneTimeAutomation { + /** + * The automation ID. + */ + id: string; + + /** + * The creation time as a Unix timestamp in seconds. + */ + created_at: number; + + /** + * Service-recorded provenance; callers cannot supply this field. + */ + created_by: AutomationCreatedBy; + + /** + * Custom string key-value pairs attached to the automation. + */ + metadata: { [key: string]: string }; + + /** + * The automation's display name. + */ + name: string; + + /** + * Always `agent.automation`. + */ + object: 'agent.automation'; + + /** + * The Unix timestamp, in seconds, of the scheduled occurrence. + */ + run_at: number; + + /** + * Completion means the schedule has finished, not the agent's work. + */ + status: 'active' | 'paused' | 'completed'; + + /** + * The session configuration or existing session receiving invocations. + */ + target: AutomationTarget; + + /** + * The type of the object. Always `once`. + */ + type: 'once'; +} + +/** + * Fields shared by periodic and one-time automations. + */ +export interface PeriodicAutomation { + /** + * The automation ID. + */ + id: string; + + /** + * The creation time as a Unix timestamp in seconds. + */ + created_at: number; + + /** + * Service-recorded provenance; callers cannot supply this field. + */ + created_by: AutomationCreatedBy; + + /** + * The cron expression determining scheduled occurrences. + */ + expression: string; + + /** + * Custom string key-value pairs attached to the automation. + */ + metadata: { [key: string]: string }; + + /** + * The automation's display name. + */ + name: string; + + /** + * Always `agent.automation`. + */ + object: 'agent.automation'; + + /** + * Whether scheduled delivery is active or paused. + */ + status: 'active' | 'paused'; + + /** + * The session configuration or existing session receiving invocations. + */ + target: AutomationTarget; + + /** + * The timezone used to interpret the expression. + */ + timezone: string; + + /** + * The type of the object. Always `periodic`. + */ + type: 'periodic'; +} + +export type AutomationCreateParams = CreateAutomationParamsPeriodic | CreateAutomationParamsOnce; + +export interface AutomationCreateParamsBase { + /** + * A standard five-field cron expression defining scheduled occurrences. + */ + expression: string; + + /** + * A human-readable name for the automation. + */ + name: string; + + /** + * The session an automation invocation targets. + */ + target: AutomationTargetParam; + + /** + * The IANA timezone used to interpret the cron expression. + */ + timezone: string; + + /** + * The type of the object. Always `periodic`. + */ + type: 'periodic'; + + metadata?: { [key: string]: string }; +} + +export interface CreateAutomationParamsPeriodic extends AutomationCreateParamsBase {} + +export interface CreateAutomationParamsOnce { + /** + * A human-readable name for the automation. + */ + name: string; + + /** + * A future Unix timestamp in seconds. + */ + run_at: number; + + /** + * The session an automation invocation targets. + */ + target: AutomationTargetParam; + + /** + * The type of the object. Always `once`. + */ + type: 'once'; + + metadata?: { [key: string]: string }; +} + +export interface AutomationUpdateParams { + /** + * Only accepted for periodic automations. + */ + expression?: string; + + /** + * Replaces all metadata; omit to leave unchanged. + */ + metadata?: { [key: string]: string }; + + name?: string; + + /** + * A future Unix timestamp in seconds; accepted only before a one-time scheduled + * invocation exists. + */ + run_at?: number; + + /** + * Replaces the complete target, retaining its type and any creator session. + */ + target?: AutomationTargetParam; + + /** + * Only accepted for periodic automations. + */ + timezone?: string; +} + +export interface AutomationListParams extends CursorPageParams { + /** + * The order in which resources are returned. Defaults to `desc`. + * + * - `asc` - Returns resources in ascending order. + * - `desc` - Returns resources in descending order. + */ + order?: 'asc' | 'desc'; + + /** + * Matches existing-session targets, including agent-created automations. + */ + session_id?: string; +} + +Automations.Invocations = Invocations; + +export declare namespace Automations { + export { + type Automation as Automation, + type AutomationAgentConfig as AutomationAgentConfig, + type AutomationCreatedBy as AutomationCreatedBy, + type AutomationDeleted as AutomationDeleted, + type AutomationEnvironment as AutomationEnvironment, + type AutomationTarget as AutomationTarget, + type AutomationTargetParam as AutomationTargetParam, + type OneTimeAutomation as OneTimeAutomation, + type PeriodicAutomation as PeriodicAutomation, + type CreateAutomationParamsPeriodic as CreateAutomationParamsPeriodic, + type CreateAutomationParamsOnce as CreateAutomationParamsOnce, + type AutomationsPage as AutomationsPage, + type AutomationCreateParams as AutomationCreateParams, + type AutomationUpdateParams as AutomationUpdateParams, + type AutomationListParams as AutomationListParams, + }; + + export { + Invocations as Invocations, + type AutomationInvocation as AutomationInvocation, + type AutomationInvocationSource as AutomationInvocationSource, + type AutomationInvocationsPage as AutomationInvocationsPage, + type InvocationRetrieveParams as InvocationRetrieveParams, + type InvocationListParams as InvocationListParams, + }; +} diff --git a/src/resources/beta/agents/automations/index.ts b/src/resources/beta/agents/automations/index.ts new file mode 100644 index 0000000000..0ec42d6508 --- /dev/null +++ b/src/resources/beta/agents/automations/index.ts @@ -0,0 +1,28 @@ +// File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +export { + Automations, + type Automation, + type AutomationAgentConfig, + type AutomationCreatedBy, + type AutomationDeleted, + type AutomationEnvironment, + type AutomationTarget, + type AutomationTargetParam, + type OneTimeAutomation, + type PeriodicAutomation, + type AutomationCreateParams, + type CreateAutomationParamsPeriodic, + type CreateAutomationParamsOnce, + type AutomationUpdateParams, + type AutomationListParams, + type AutomationsPage, +} from './automations'; +export { + Invocations, + type AutomationInvocation, + type AutomationInvocationSource, + type InvocationRetrieveParams, + type InvocationListParams, + type AutomationInvocationsPage, +} from './invocations'; diff --git a/src/resources/beta/agents/automations/invocations.ts b/src/resources/beta/agents/automations/invocations.ts new file mode 100644 index 0000000000..69ae37f6fa --- /dev/null +++ b/src/resources/beta/agents/automations/invocations.ts @@ -0,0 +1,422 @@ +// File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +import { APIResource } from '../../../../core/resource'; +import * as AutomationsAPI from './automations'; +import { APIPromise } from '../../../../core/api-promise'; +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'; + +function resolveResourceRequestOptions( + options: RequestOptions | undefined, + buildOptions: (options: RequestOptions | undefined) => RequestOptions | Promise, +): Promise { + return Promise.resolve(options).then(buildOptions); +} + +// Recognizable options across SDK runtime versions. Keep this independent of +// private RequestOptions fields so older handwritten runtimes still compile. +const normalizeRequestOptionsForQueryKeys = new Set([ + 'method', + 'path', + 'query', + 'body', + 'headers', + 'maxRetries', + 'stream', + 'timeout', + 'httpAgent', + 'fetchOptions', + 'signal', + 'idempotencyKey', + 'defaultBaseURL', + '__metadata', + '__binaryRequest', + '__binaryResponse', + '__streamClass', + '__security', + '__synthesizeEventData', +]); + +function normalizeRequestOptionsForQuery( + value: unknown, + queryKeys: ReadonlyArray, + options: RequestOptions | undefined, +): + | ({ + [K in 'headers' | 'maxRetries' | 'timeout' | 'signal' | 'idempotencyKey' | 'query']?: RequestOptions[K]; + } & { + [ + K in + | 'method' + | 'path' + | 'body' + | 'stream' + | 'httpAgent' + | 'fetchOptions' + | 'defaultBaseURL' + | '__metadata' + | '__binaryRequest' + | '__binaryResponse' + | '__streamClass' + | '__security' + | '__synthesizeEventData' + ]?: never; + }) + | undefined { + if (typeof value !== 'object' || value === null) return undefined; + // Optional never fields can still be explicitly undefined unless consumers + // enable exactOptionalPropertyTypes. Snapshot data without invoking getters. + const entries = Object.entries(Object.getOwnPropertyDescriptors(value)).filter( + ([, descriptor]) => descriptor.enumerable && (!('value' in descriptor) || descriptor.value !== undefined), + ); + const keys = entries.map(([key]) => key); + const requestOnly = keys.some( + (key) => normalizeRequestOptionsForQueryKeys.has(key) && !queryKeys.includes(key), + ); + if (!requestOnly) return undefined; + // Declared query fields, including stream, must use the query argument. + // Mixing them with request-only options is ambiguous and could change the return type. + if ( + options !== undefined || + keys.some((key) => !normalizeRequestOptionsForQueryKeys.has(key) || queryKeys.includes(key)) + ) { + throw new TypeError('Query parameters and request options must be passed as separate arguments.'); + } + // The query position must not gain authority to change the request destination + // or transport. Those overrides require the explicit request options argument. + if ( + keys.some( + (key) => !['headers', 'maxRetries', 'timeout', 'signal', 'idempotencyKey', 'query'].includes(key), + ) + ) { + throw new TypeError('Pass transport overrides in the explicit request options argument.'); + } + // Copy only the validated fields. Spreading value would reintroduce undefined + // transport overrides, and deleting them would mutate the caller's object. + return Object.fromEntries( + entries.map(([key, descriptor]) => { + if ('value' in descriptor) return [key, descriptor.value]; + return [key, descriptor.get ? Reflect.apply(descriptor.get, value, []) : undefined]; + }), + ) as { + [K in 'headers' | 'maxRetries' | 'timeout' | 'signal' | 'idempotencyKey' | 'query']?: RequestOptions[K]; + } & { + [ + K in + | 'method' + | 'path' + | 'body' + | 'stream' + | 'httpAgent' + | 'fetchOptions' + | 'defaultBaseURL' + | '__metadata' + | '__binaryRequest' + | '__binaryResponse' + | '__streamClass' + | '__security' + | '__synthesizeEventData' + ]?: never; + }; +} + +export class Invocations extends APIResource { + /** + * Queues a manual delivery without changing the saved schedule. + * + * @example + * ```ts + * const automationInvocation = + * await client.beta.agents.automations.invocations.create( + * 'automation_id', + * ); + * ``` + */ + create(automationID: string, options?: RequestOptions): APIPromise { + return this._client.post( + path`/agents/automations/${automationID}/invocations`, + resolveResourceRequestOptions(options, (options) => ({ + ...options, + headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]), + __security: { bearerAuth: true }, + })), + ); + } + + /** + * Retrieves a delivery record for a project-owned automation. + * + * @example + * ```ts + * const automationInvocation = + * await client.beta.agents.automations.invocations.retrieve( + * 'invocation_id', + * { automation_id: 'automation_id' }, + * ); + * ``` + */ + retrieve( + invocationID: string, + params: InvocationRetrieveParams, + options?: RequestOptions, + ): APIPromise { + const { automation_id } = params; + return this._client.get( + path`/agents/automations/${automation_id}/invocations/${invocationID}`, + resolveResourceRequestOptions(options, (options) => ({ + ...options, + headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]), + __security: { bearerAuth: true }, + })), + ); + } + + /** + * Lists delivery records for a project-owned automation. + * + * @example + * ```ts + * // Automatically fetches more pages as needed. + * for await (const automationInvocation of client.beta.agents.automations.invocations.list( + * 'automation_id', + * )) { + * // ... + * } + * ``` + */ + list( + automationID: string, + query?: + | (InvocationListParams & + ( + | { + [ + K in + | 'method' + | 'path' + | 'query' + | 'body' + | 'headers' + | 'maxRetries' + | 'stream' + | 'timeout' + | 'httpAgent' + | 'fetchOptions' + | 'signal' + | 'idempotencyKey' + | 'defaultBaseURL' + | '__metadata' + | '__binaryRequest' + | '__binaryResponse' + | '__streamClass' + | '__security' + | '__synthesizeEventData' + ]?: never; + } + | null + | undefined + )) + | null + | undefined, + options?: RequestOptions, + ): PagePromise; + list( + automationID: string, + options?: { + [K in 'headers' | 'maxRetries' | 'timeout' | 'signal' | 'idempotencyKey' | 'query']?: RequestOptions[K]; + } & { + [ + K in + | 'method' + | 'path' + | 'body' + | 'stream' + | 'httpAgent' + | 'fetchOptions' + | 'defaultBaseURL' + | '__metadata' + | '__binaryRequest' + | '__binaryResponse' + | '__streamClass' + | '__security' + | '__synthesizeEventData' + ]?: never; + }, + ): PagePromise; + list( + automationID: string, + query: + | InvocationListParams + | ({ + [ + K in 'headers' | 'maxRetries' | 'timeout' | 'signal' | 'idempotencyKey' | 'query' + ]?: RequestOptions[K]; + } & { + [ + K in + | 'method' + | 'path' + | 'body' + | 'stream' + | 'httpAgent' + | 'fetchOptions' + | 'defaultBaseURL' + | '__metadata' + | '__binaryRequest' + | '__binaryResponse' + | '__streamClass' + | '__security' + | '__synthesizeEventData' + ]?: never; + }) + | null + | undefined = {}, + options?: RequestOptions, + ): PagePromise { + const normalizeRequestOptionsForQueryOptions = normalizeRequestOptionsForQuery( + query, + ['after', 'limit', 'order'], + options, + ); + if (normalizeRequestOptionsForQueryOptions !== undefined) { + options = normalizeRequestOptionsForQueryOptions; + query = {}; + } + query = query as InvocationListParams | null | undefined; + return this._client.getAPIList( + path`/agents/automations/${automationID}/invocations`, + CursorPage, + resolveResourceRequestOptions(options, (options) => ({ + query, + ...options, + headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]), + __security: { bearerAuth: true }, + })), + ); + } +} + +export type AutomationInvocationsPage = CursorPage; + +/** + * One attempted delivery by an automation. + */ +export interface AutomationInvocation { + /** + * The invocation ID. + */ + id: string; + + /** + * The automation that owns the invocation. + */ + automation_id: string; + + /** + * The creation time as a Unix timestamp in seconds. + */ + created_at: number; + + /** + * The permanent delivery failure, or null when no failure occurred. + */ + error: AutomationInvocation.Error | null; + + /** + * Always `agent.automation.invocation`. + */ + object: 'agent.automation.invocation'; + + /** + * The intended occurrence as a Unix timestamp in seconds, or null for manual runs. + */ + scheduled_at: number | null; + + /** + * The target or newly created session ID, or null before one is available. + */ + session_id: string | null; + + /** + * Why an occurrence was skipped, or null when it was not skipped. + */ + skip_reason: 'pending_delivery' | null; + + /** + * Whether the invocation was manual or scheduled. + */ + source: AutomationInvocationSource; + + /** + * Delivery status; completed does not mean the agent's work has finished. + */ + status: 'queued' | 'completed' | 'failed' | 'skipped'; +} + +export namespace AutomationInvocation { + /** + * The permanent delivery failure, or null when no failure occurred. + */ + export interface Error { + /** + * A machine-readable error code. + */ + code: string; + + /** + * A public explanation of the delivery failure. + */ + message: string; + } +} + +export type AutomationInvocationSource = + | AutomationInvocationSource.AutomationInvocationSourceResourceManual + | AutomationInvocationSource.AutomationInvocationSourceResourceAutomation; + +export namespace AutomationInvocationSource { + export interface AutomationInvocationSourceResourceManual { + /** + * The type of the object. Always `manual`. + */ + type: 'manual'; + } + + export interface AutomationInvocationSourceResourceAutomation { + /** + * The automation snapshot for this occurrence, excluding confidential values. + */ + automation: AutomationsAPI.Automation; + + /** + * The type of the object. Always `automation`. + */ + type: 'automation'; + } +} + +export interface InvocationRetrieveParams { + automation_id: string; +} + +export interface InvocationListParams extends CursorPageParams { + /** + * The order in which resources are returned. Defaults to `desc`. + * + * - `asc` - Returns resources in ascending order. + * - `desc` - Returns resources in descending order. + */ + order?: 'asc' | 'desc'; +} + +export declare namespace Invocations { + export { + type AutomationInvocation as AutomationInvocation, + type AutomationInvocationSource as AutomationInvocationSource, + type AutomationInvocationsPage as AutomationInvocationsPage, + type InvocationRetrieveParams as InvocationRetrieveParams, + type InvocationListParams as InvocationListParams, + }; +} diff --git a/src/resources/beta/agents/index.ts b/src/resources/beta/agents/index.ts index f38452fd06..408086792c 100644 --- a/src/resources/beta/agents/index.ts +++ b/src/resources/beta/agents/index.ts @@ -112,6 +112,24 @@ export { type AgentSessionItemsPage, type AgentsPage, } from './agents'; +export { + Automations, + type Automation, + type AutomationAgentConfig, + type AutomationCreatedBy, + type AutomationDeleted, + type AutomationEnvironment, + type AutomationTarget, + type AutomationTargetParam, + type OneTimeAutomation, + type PeriodicAutomation, + type AutomationCreateParams, + type CreateAutomationParamsPeriodic, + type CreateAutomationParamsOnce, + type AutomationUpdateParams, + type AutomationListParams, + type AutomationsPage, +} from './automations/index'; export { Environments, type EnvironmentInfo, diff --git a/src/resources/beta/responses/responses.ts b/src/resources/beta/responses/responses.ts index 2e63a45cef..3e1fd85491 100644 --- a/src/resources/beta/responses/responses.ts +++ b/src/resources/beta/responses/responses.ts @@ -5355,6 +5355,11 @@ export namespace BetaResponseInputFile { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -5415,6 +5420,11 @@ export namespace BetaResponseInputFileContent { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -5464,6 +5474,11 @@ export namespace BetaResponseInputImage { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -5513,6 +5528,11 @@ export namespace BetaResponseInputImageContent { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -7223,6 +7243,11 @@ export namespace BetaResponseInputText { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -7259,6 +7284,11 @@ export namespace BetaResponseInputTextContent { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -7429,6 +7459,11 @@ export namespace BetaResponseItem { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -8716,6 +8751,11 @@ export namespace BetaResponseOutputItem { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } diff --git a/src/resources/chat/completions/completions.ts b/src/resources/chat/completions/completions.ts index f224cbb55d..d3b31e8a45 100644 --- a/src/resources/chat/completions/completions.ts +++ b/src/resources/chat/completions/completions.ts @@ -1514,6 +1514,11 @@ export namespace ChatCompletionContentPart { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } } @@ -1562,6 +1567,11 @@ export namespace ChatCompletionContentPartImage { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -1607,6 +1617,11 @@ export namespace ChatCompletionContentPartInputAudio { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -1655,6 +1670,11 @@ export namespace ChatCompletionContentPartText { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } diff --git a/src/resources/conversations/conversations.ts b/src/resources/conversations/conversations.ts index 2e5b124e45..09a0dae22f 100644 --- a/src/resources/conversations/conversations.ts +++ b/src/resources/conversations/conversations.ts @@ -132,6 +132,11 @@ export namespace ComputerScreenshotContent { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } diff --git a/src/resources/live/api.md b/src/resources/live/api.md index 45078275d0..e80b385e6b 100644 --- a/src/resources/live/api.md +++ b/src/resources/live/api.md @@ -74,7 +74,9 @@ Methods: Types: - ConnectClientEvent +- SidebandClientEvent - ConnectServerEvent +- SidebandServerEvent ## Forks diff --git a/src/resources/live/index.ts b/src/resources/live/index.ts index e511e7a306..eeb0841dcd 100644 --- a/src/resources/live/index.ts +++ b/src/resources/live/index.ts @@ -13,7 +13,9 @@ export { export { Sideband, type ConnectClientEvent, + type SidebandClientEvent, type ConnectServerEvent, + type SidebandServerEvent, type SidebandConnectParams, } from './sideband'; export { type LiveWSClientOptions } from './ws'; diff --git a/src/resources/live/live.ts b/src/resources/live/live.ts index fa803ecccc..9b255ffb70 100644 --- a/src/resources/live/live.ts +++ b/src/resources/live/live.ts @@ -17,7 +17,14 @@ import * as ResponsesAPI from '../responses/responses'; import * as ForksAPI from './forks/forks'; import { ForkClientEvent, ForkServerEvent, Forks } from './forks/forks'; import * as SidebandAPI from './sideband/sideband'; -import { ConnectClientEvent, ConnectServerEvent, Sideband, SidebandConnectParams } from './sideband/sideband'; +import { + ConnectClientEvent, + ConnectServerEvent, + Sideband, + SidebandClientEvent, + SidebandConnectParams, + SidebandServerEvent, +} from './sideband/sideband'; import { APIPromise } from '../../core/api-promise'; import { RequestOptions } from '../../internal/request-options'; @@ -158,6 +165,16 @@ export interface ClientDelegation { * The delegation owner. Always `client` for tasks handled by your application. */ type: 'client'; + + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400 for Decisions sessions and 0 + * (request immediately) for other sessions. Omission in a session update preserves + * the current value. Updates apply to subsequent delegations. + */ + acknowledgement_delay_ms?: number; } /** @@ -186,7 +203,7 @@ export type ClientEvent = /** * Provide context the Live model can communicate to the user, optionally for an - * existing client delegation. + * existing client delegation. Rejected while an audio fixture is active. */ export interface CommentaryAppendEvent { /** @@ -954,6 +971,16 @@ export namespace ForkSessionConfig { */ type: 'responses'; + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400 for Decisions sessions and 0 + * (request immediately) for other sessions. Omission in a session update preserves + * the current value. Updates apply to subsequent delegations. + */ + acknowledgement_delay_ms?: number; + /** * Responses backend settings to update. Omitted settings keep their existing * values. @@ -1269,8 +1296,9 @@ export interface InputAudioMuteEvent { } /** - * Returned when a session.input_audio.mute command is accepted. Input audio is no - * longer sent to the model; sideband audio reflection continues. + * Acknowledges a session.input_audio.mute command. An independent input mute sends + * silence to the model and preserves sideband audio reflection. Fixture playback + * does not emit this event. */ export interface InputAudioMutedEvent { /** @@ -1292,7 +1320,8 @@ export interface InputAudioMutedEvent { /** * Resume audio input to a Live model after muting it. The server acknowledges with - * `session.input_audio.unmuted`. + * `session.input_audio.unmuted`. An active audio fixture still pauses inference + * until playback finishes. */ export interface InputAudioUnmuteEvent { /** @@ -1308,8 +1337,9 @@ export interface InputAudioUnmuteEvent { } /** - * Returned when a session.input_audio.unmute command is accepted. Input audio is - * sent to the model again. + * Acknowledges a session.input_audio.unmute command, removing the independent + * input mute. An active audio fixture still pauses inference until playback + * finishes. Fixture playback does not emit this event. */ export interface InputAudioUnmutedEvent { /** @@ -1371,8 +1401,11 @@ export interface InputTranscriptDeltaEvent { } /** - * Append instructions to the Live conversation while it is running, optionally - * associating them with an existing client delegation. + * Append developer instructions to the Live conversation while it is running, + * optionally associating them with an existing client delegation. Rejected while + * an audio fixture is active. These instructions remain in conversation history + * through compaction and are included in future backend delegations. For external + * audio, describe content already delivered so the assistant does not repeat it. */ export interface InstructionsAppendEvent { /** @@ -1541,12 +1574,31 @@ export namespace MediaSessionConfig { * The delegation owner. Always `responses` for tasks handled by the Responses API. */ type: 'responses'; + + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400 for Decisions sessions and 0 + * (request immediately) for other sessions. Omission in a session update preserves + * the current value. Updates apply to subsequent delegations. + */ + acknowledgement_delay_ms?: number; } export interface Decisions { decisions: LiveAPI.DecisionsDelegationConfig; type: 'decisions'; + + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400. Updates apply to subsequent + * delegations. + */ + acknowledgement_delay_ms?: number; } } @@ -1587,6 +1639,16 @@ export namespace MediaSessionForkConfig { */ type: 'responses'; + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400 for Decisions sessions and 0 + * (request immediately) for other sessions. Omission in a session update preserves + * the current value. Updates apply to subsequent delegations. + */ + acknowledgement_delay_ms?: number; + /** * Responses backend settings to update. Omitted settings keep their existing * values. @@ -2375,12 +2437,31 @@ export namespace SessionConfig { * The delegation owner. Always `responses` for tasks handled by the Responses API. */ type: 'responses'; + + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400 for Decisions sessions and 0 + * (request immediately) for other sessions. Omission in a session update preserves + * the current value. Updates apply to subsequent delegations. + */ + acknowledgement_delay_ms?: number; } export interface Decisions { decisions: LiveAPI.DecisionsDelegationConfig; type: 'decisions'; + + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400. Updates apply to subsequent + * delegations. + */ + acknowledgement_delay_ms?: number; } } @@ -2511,12 +2592,31 @@ export namespace SessionResource { * The delegation owner. Always `responses` for tasks handled by the Responses API. */ type: 'responses'; + + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400 for Decisions sessions and 0 + * (request immediately) for other sessions. Omission in a session update preserves + * the current value. Updates apply to subsequent delegations. + */ + acknowledgement_delay_ms?: number; } export interface Decisions { decisions: LiveAPI.DecisionsDelegationConfig; type: 'decisions'; + + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400. Updates apply to subsequent + * delegations. + */ + acknowledgement_delay_ms?: number; } } @@ -2601,6 +2701,16 @@ export namespace SessionUpdateConfig { */ type: 'responses'; + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400 for Decisions sessions and 0 + * (request immediately) for other sessions. Omission in a session update preserves + * the current value. Updates apply to subsequent delegations. + */ + acknowledgement_delay_ms?: number; + /** * Responses backend settings to update. Omitted settings keep their existing * values. @@ -2611,6 +2721,16 @@ export namespace SessionUpdateConfig { export interface Decisions { type: 'decisions'; + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400 for Decisions sessions and 0 + * (request immediately) for other sessions. Omission in a session update preserves + * the current value. Updates apply to subsequent delegations. + */ + acknowledgement_delay_ms?: number; + decisions?: LiveAPI.DecisionsDelegationUpdateConfig; } } @@ -2728,7 +2848,7 @@ export namespace SessionUsageUpdatedEvent { /** * Provide silent reasoning or progress context to the Live model, optionally for - * an existing client delegation. + * an existing client delegation. Rejected while an audio fixture is active. */ export interface ThinkingAppendEvent { /** @@ -2942,7 +3062,9 @@ export declare namespace Live { export { Sideband as Sideband, type ConnectClientEvent as ConnectClientEvent, + type SidebandClientEvent as SidebandClientEvent, type ConnectServerEvent as ConnectServerEvent, + type SidebandServerEvent as SidebandServerEvent, type SidebandConnectParams as SidebandConnectParams, }; diff --git a/src/resources/live/sessions.ts b/src/resources/live/sessions.ts index 60db4ff659..90dd0db428 100644 --- a/src/resources/live/sessions.ts +++ b/src/resources/live/sessions.ts @@ -317,12 +317,31 @@ export namespace SessionAcceptParams { * The delegation owner. Always `responses` for tasks handled by the Responses API. */ type: 'responses'; + + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400 for Decisions sessions and 0 + * (request immediately) for other sessions. Omission in a session update preserves + * the current value. Updates apply to subsequent delegations. + */ + acknowledgement_delay_ms?: number; } export interface Decisions { decisions: LiveAPI.DecisionsDelegationConfig; type: 'decisions'; + + /** + * Milliseconds to wait before requesting an automatic spoken acknowledgement for a + * delegation. The model may still speak before this delay. Any commentary or + * thinking appended to the session cancels all pending acknowledgements, including + * those for other delegations. Defaults to 400. Updates apply to subsequent + * delegations. + */ + acknowledgement_delay_ms?: number; } } } diff --git a/src/resources/live/sideband/index.ts b/src/resources/live/sideband/index.ts index 46c83c8d49..4faa304828 100644 --- a/src/resources/live/sideband/index.ts +++ b/src/resources/live/sideband/index.ts @@ -3,7 +3,9 @@ export { Sideband, type ConnectClientEvent, + type SidebandClientEvent, type ConnectServerEvent, + type SidebandServerEvent, type SidebandConnectParams, } from './sideband'; export { type SidebandWSClientOptions } from './ws'; diff --git a/src/resources/live/sideband/sideband.ts b/src/resources/live/sideband/sideband.ts index 8640291c15..7d6ae70523 100644 --- a/src/resources/live/sideband/sideband.ts +++ b/src/resources/live/sideband/sideband.ts @@ -5,6 +5,10 @@ import * as LiveAPI from '../live'; export class Sideband extends APIResource {} +export type SidebandClientEvent = ConnectClientEvent; + +export type SidebandServerEvent = ConnectServerEvent; + /** * Client events accepted by an attached Live sideband WebSocket. The session has * already started. Send input audio over the primary connection. @@ -182,7 +186,9 @@ export interface SidebandConnectParams { export declare namespace Sideband { export { type ConnectClientEvent as ConnectClientEvent, + type SidebandClientEvent as SidebandClientEvent, type ConnectServerEvent as ConnectServerEvent, + type SidebandServerEvent as SidebandServerEvent, type SidebandConnectParams as SidebandConnectParams, }; } diff --git a/src/resources/realtime/realtime.ts b/src/resources/realtime/realtime.ts index decfba6aff..48309b5182 100644 --- a/src/resources/realtime/realtime.ts +++ b/src/resources/realtime/realtime.ts @@ -476,12 +476,11 @@ export interface ConversationItemInputAudioTranscriptionDeltaEvent { delta?: string; /** - * The log probabilities of the transcription. These can be enabled by - * configurating the session with - * `"include": ["item.input_audio_transcription.logprobs"]`. Each entry in the - * array corresponds a log probability of which token would be selected for this - * chunk of transcription. This can help to identify if it was possible there were - * multiple valid options for a given chunk of transcription. + * The log probabilities of the transcription. These can be enabled by configuring + * the session with `"include": ["item.input_audio_transcription.logprobs"]`. Each + * entry in the array corresponds a log probability of which token would be + * selected for this chunk of transcription. This can help to identify if it was + * possible there were multiple valid options for a given chunk of transcription. */ logprobs?: Array | null; } @@ -1831,7 +1830,7 @@ export interface RealtimeError { /** * Returned when an error occurs, which could be a client problem or a server * problem. Most errors are recoverable and the session will stay open, we - * recommend to implementors to monitor and log error messages by default. + * recommend to implementers to monitor and log error messages by default. */ export interface RealtimeErrorEvent { /** diff --git a/src/resources/responses/responses.ts b/src/resources/responses/responses.ts index 16029b397d..f79372d787 100644 --- a/src/resources/responses/responses.ts +++ b/src/resources/responses/responses.ts @@ -4424,6 +4424,11 @@ export namespace ResponseInputFile { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -4484,6 +4489,11 @@ export namespace ResponseInputFileContent { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -4533,6 +4543,11 @@ export namespace ResponseInputImage { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -4582,6 +4597,11 @@ export namespace ResponseInputImageContent { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -5683,6 +5703,11 @@ export namespace ResponseInputText { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } @@ -5719,6 +5744,11 @@ export namespace ResponseInputTextContent { * The breakpoint mode. Always `explicit`. */ mode: 'explicit'; + + /** + * The minimum lifetime of this cache breakpoint. Defaults to the request TTL. + */ + ttl?: '30m' | '12h'; } } diff --git a/tests/api-resources/beta/agents/automations/automations.test.ts b/tests/api-resources/beta/agents/automations/automations.test.ts new file mode 100644 index 0000000000..6ac4dd35f5 --- /dev/null +++ b/tests/api-resources/beta/agents/automations/automations.test.ts @@ -0,0 +1,163 @@ +// File generated from our OpenAPI spec by Castiron. 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 automations', () => { + test('create: only required params', async () => { + const responsePromise = client.beta.agents.automations.create({ + expression: 'x', + name: 'x', + target: { + environment: { type: 'none' }, + input: [ + { + content: [{ text: 'text', type: 'input_text' }], + role: 'user', + type: 'message', + }, + ], + type: 'new_session', + }, + timezone: 'x', + type: 'periodic', + }); + 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('create: required and optional params', async () => { + await client.beta.agents.automations.create({ + expression: 'x', + name: 'x', + target: { + environment: { type: 'none' }, + input: [ + { + content: [{ text: 'text', type: 'input_text' }], + role: 'user', + type: 'message', + }, + ], + type: 'new_session', + agent: { + instructions: 'instructions', + model: 'model', + multi_agent: { enabled: true, max_concurrent_subagents: 1 }, + reasoning: { effort: 'none', summary: 'concise' }, + service_tier: 'auto', + text: { + format: { type: 'text' }, + verbosity: 'low', + }, + tools: [ + { + description: 'description', + name: 'name', + parameters: { foo: 'bar' }, + type: 'function', + defer_loading: true, + }, + ], + }, + agent_id: 'agent_id', + metadata: { foo: 'string' }, + vault_ids: ['string'], + }, + timezone: 'x', + type: 'periodic', + metadata: { foo: 'string' }, + }); + }); + + test('retrieve', async () => { + const responsePromise = client.beta.agents.automations.retrieve('automation_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('update', async () => { + const responsePromise = client.beta.agents.automations.update('automation_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', async () => { + const responsePromise = client.beta.agents.automations.list(); + 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.agents.automations.list( + { + after: 'after', + limit: 1, + order: 'asc', + session_id: 'session_id', + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(OpenAI.NotFoundError); + }); + + test('delete', async () => { + const responsePromise = client.beta.agents.automations.delete('automation_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('pause', async () => { + const responsePromise = client.beta.agents.automations.pause('automation_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('resume', async () => { + const responsePromise = client.beta.agents.automations.resume('automation_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); + }); +}); diff --git a/tests/api-resources/beta/agents/automations/invocations.test.ts b/tests/api-resources/beta/agents/automations/invocations.test.ts new file mode 100644 index 0000000000..1adde36f37 --- /dev/null +++ b/tests/api-resources/beta/agents/automations/invocations.test.ts @@ -0,0 +1,67 @@ +// File generated from our OpenAPI spec by Castiron. 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 invocations', () => { + test('create', async () => { + const responsePromise = client.beta.agents.automations.invocations.create('automation_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('retrieve: only required params', async () => { + const responsePromise = client.beta.agents.automations.invocations.retrieve('invocation_id', { + automation_id: 'automation_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('retrieve: required and optional params', async () => { + await client.beta.agents.automations.invocations.retrieve('invocation_id', { + automation_id: 'automation_id', + }); + }); + + test('list', async () => { + const responsePromise = client.beta.agents.automations.invocations.list('automation_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.agents.automations.invocations.list( + 'automation_id', + { + after: 'after', + limit: 1, + order: 'asc', + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(OpenAI.NotFoundError); + }); +}); diff --git a/tests/api-resources/live/live.test.ts b/tests/api-resources/live/live.test.ts index c39571a37d..491bf223ac 100644 --- a/tests/api-resources/live/live.test.ts +++ b/tests/api-resources/live/live.test.ts @@ -29,7 +29,7 @@ describe('resource live', () => { model: 'gpt-live-1', audio: { output: { voice: 'string' } }, client: { data_channel: { allowed_client_events: 'all', allowed_server_events: 'all' } }, - delegation: { type: 'client' }, + delegation: { type: 'client', acknowledgement_delay_ms: 0 }, input: [ { content: [{ text: 'text', type: 'input_text' }], diff --git a/tests/api-resources/live/sessions.test.ts b/tests/api-resources/live/sessions.test.ts index a1b492966d..4612839272 100644 --- a/tests/api-resources/live/sessions.test.ts +++ b/tests/api-resources/live/sessions.test.ts @@ -28,7 +28,7 @@ describe('resource sessions', () => { model: 'gpt-live-1', type: 'live', audio: { output: { voice: 'string' } }, - delegation: { type: 'client' }, + delegation: { type: 'client', acknowledgement_delay_ms: 0 }, input: [ { content: [{ text: 'text', type: 'input_text' }], @@ -79,6 +79,7 @@ describe('resource sessions', () => { client: { data_channel: { allowed_client_events: 'all', allowed_server_events: 'all' } }, delegation: { type: 'responses', + acknowledgement_delay_ms: 0, responses: { instructions: 'instructions', max_output_tokens: 16, diff --git a/tests/helpers/browser-capabilities.test.ts b/tests/helpers/browser-capabilities.test.ts index 1c6655e2b9..77ec2c6737 100644 --- a/tests/helpers/browser-capabilities.test.ts +++ b/tests/helpers/browser-capabilities.test.ts @@ -1001,14 +1001,19 @@ describe('explicit browser capabilities', () => { expect(helper.close()).toEqual({ status: 'closed' }); }); - test.each(['screenshot', 'zoom'] as const)( - 'projects the native image breakpoint on %s before reading final state', - async (member) => { + test.each([ + ['screenshot', '30m'], + ['screenshot', '12h'], + ['zoom', '30m'], + ['zoom', '12h'], + ] as const)( + 'projects the native image breakpoint on %s with ttl %s before reading final state', + async (member, ttl) => { const image = { type: 'input_image' as const, detail: 'auto' as const, file_id: 'file_observed', - prompt_cache_breakpoint: { mode: 'explicit' as const }, + prompt_cache_breakpoint: { mode: 'explicit' as const, ttl }, }; const original = structuredClone(image); let reports = 0; @@ -1017,6 +1022,7 @@ describe('explicit browser capabilities', () => { reports += 1; if (reports === 2) { Reflect.set(image.prompt_cache_breakpoint, 'mode', 'changed'); + Reflect.set(image.prompt_cache_breakpoint, 'ttl', 'changed'); } return state(); }, @@ -1115,6 +1121,8 @@ describe('explicit browser capabilities', () => { { image_url: ' ' }, { file_id: 'file_ok', prompt_cache_breakpoint: { mode: 'automatic' } }, { file_id: 'file_ok', prompt_cache_breakpoint: {} }, + { file_id: 'file_ok', prompt_cache_breakpoint: { mode: 'explicit', ttl: '1h' } }, + { file_id: 'file_ok', prompt_cache_breakpoint: { mode: 'explicit', ttl: null } }, { file_id: 'file_ok', prompt_cache_breakpoint: { mode: 'explicit', private: 'omit' } }, ].map(async (invalid) => { const image = { type: 'input_image' as const, detail: 'auto' as const }; diff --git a/tests/helpers/browser-runner.test.ts b/tests/helpers/browser-runner.test.ts index 51f445235c..f3a73a42a6 100644 --- a/tests/helpers/browser-runner.test.ts +++ b/tests/helpers/browser-runner.test.ts @@ -8779,85 +8779,89 @@ describe('ResponsesToolRunner iteration', () => { }, ); - test('supplies permitted native results without changing call IDs, mixed order or pending arguments', async () => { - const effects: string[] = []; - const browser = new BrowserToolset( - { - state, - click: ({ target }) => { - effects.push(target); + test.each(['30m', '12h'] as const)( + 'supplies native results with ttl %s without changing call IDs, mixed order or pending arguments', + async (ttl) => { + const effects: string[] = []; + const browser = new BrowserToolset( + { + state, + click: ({ target }) => { + effects.push(target); + }, }, - }, - { confirm: () => true }, - ); - const execute = vi.fn(() => 'automatic'); - const runner = new ResponsesToolRunner({ - browser, - functions: [ + { confirm: () => true }, + ); + const execute = vi.fn(() => 'automatic'); + const runner = new ResponsesToolRunner({ + browser, + functions: [ + { + tool: { type: 'function', name: 'record', parameters: {}, strict: false }, + execute, + allowOutputOverride: true, + }, + ], + }); + const h = harness([ + { output: [wireCall('record', {}), wireCall('browser_click', { target: 'original', tab_id: null })] }, + { output: [message] }, + ]); + const iterator = runner.iterate(h.client, input); + const first = await iterator.next(); + expect(first.done).toBe(false); + if (first.done) { + throw new Error('Missing turn'); + } + const supplied = [ { - tool: { type: 'function', name: 'record', parameters: {}, strict: false }, - execute, - allowOutputOverride: true, + type: 'input_text' as const, + text: 'human result', + prompt_cache_breakpoint: { mode: 'explicit' as const, ttl }, }, - ], - }); - const h = harness([ - { output: [wireCall('record', {}), wireCall('browser_click', { target: 'original', tab_id: null })] }, - { output: [message] }, - ]); - const iterator = runner.iterate(h.client, input); - const first = await iterator.next(); - expect(first.done).toBe(false); - if (first.done) { - throw new Error('Missing turn'); - } - const supplied = [ - { - type: 'input_text' as const, - text: 'human result', - prompt_cache_breakpoint: { mode: 'explicit' as const }, - }, - { - type: 'input_image' as const, - image_url: 'https://fixture.invalid/image', - detail: 'original' as const, - }, - { type: 'input_file' as const, file_id: 'file_fixture' }, - ]; - first.value.supplyOutputs([{ type: 'function_call_output', call_id: 'call_record', output: supplied }]); - const [text] = supplied; - if (text?.type !== 'input_text') { - throw new Error('Missing text output'); - } - text.text = 'changed later'; - const [, pending] = first.value.response.output; - if (pending?.type !== 'function_call') { - throw new Error('Missing pending call'); - } - pending.arguments = JSON.stringify({ target: 'retargeted', tab_id: null }); - pending.call_id = 'changed'; - const final = await iterator.next(); - expect(final.value).toMatchObject({ - step: 2, - final: true, - attemptedCallIds: ['call_record', 'call_browser_click'], - completedCallIds: ['call_record', 'call_browser_click'], - }); - expect(execute).not.toHaveBeenCalled(); - expect(effects).toEqual(['original']); - expect(h.bodies[1]?.['input']).toContainEqual({ - type: 'function_call_output', - call_id: 'call_record', - output: [ - { type: 'input_text', text: 'human result', prompt_cache_breakpoint: { mode: 'explicit' } }, - { type: 'input_image', image_url: 'https://fixture.invalid/image', detail: 'original' }, - { type: 'input_file', file_id: 'file_fixture' }, - ], - }); - expect(JSON.stringify(h.bodies[1]?.['input'])).not.toContain('retargeted'); - expect(() => first.value.supplyOutputs([])).toThrow('does not accept'); - await iterator.return(); - }); + { + type: 'input_image' as const, + image_url: 'https://fixture.invalid/image', + detail: 'original' as const, + }, + { type: 'input_file' as const, file_id: 'file_fixture' }, + ]; + first.value.supplyOutputs([{ type: 'function_call_output', call_id: 'call_record', output: supplied }]); + const [text] = supplied; + if (text?.type !== 'input_text') { + throw new Error('Missing text output'); + } + text.text = 'changed later'; + Reflect.set(text.prompt_cache_breakpoint, 'ttl', 'changed'); + const [, pending] = first.value.response.output; + if (pending?.type !== 'function_call') { + throw new Error('Missing pending call'); + } + pending.arguments = JSON.stringify({ target: 'retargeted', tab_id: null }); + pending.call_id = 'changed'; + const final = await iterator.next(); + expect(final.value).toMatchObject({ + step: 2, + final: true, + attemptedCallIds: ['call_record', 'call_browser_click'], + completedCallIds: ['call_record', 'call_browser_click'], + }); + expect(execute).not.toHaveBeenCalled(); + expect(effects).toEqual(['original']); + expect(h.bodies[1]?.['input']).toContainEqual({ + type: 'function_call_output', + call_id: 'call_record', + output: [ + { type: 'input_text', text: 'human result', prompt_cache_breakpoint: { mode: 'explicit', ttl } }, + { type: 'input_image', image_url: 'https://fixture.invalid/image', detail: 'original' }, + { type: 'input_file', file_id: 'file_fixture' }, + ], + }); + expect(JSON.stringify(h.bodies[1]?.['input'])).not.toContain('retargeted'); + expect(() => first.value.supplyOutputs([])).toThrow('does not accept'); + await iterator.return(); + }, + ); test.each(['executor', 'supplied'] as const)('rejects hidden output fields from %s', async (source) => { const block = Object.defineProperty( @@ -8942,6 +8946,22 @@ describe('ResponsesToolRunner iteration', () => { [allowed, { ...allowed, call_id: 'unknown' }], [{ ...allowed, output: [{ type: 'input_text', text: 42 }] }], [{ ...allowed, output: [{ type: 'input_image', image_url: { private: true } }] }], + [ + { + ...allowed, + output: [ + { type: 'input_text', text: 'value', prompt_cache_breakpoint: { mode: 'explicit', ttl: '1h' } }, + ], + }, + ], + [ + { + ...allowed, + output: [ + { type: 'input_text', text: 'value', prompt_cache_breakpoint: { mode: 'explicit', ttl: null } }, + ], + }, + ], [{ ...allowed, output: cyclic }], [{ ...allowed, toJSON: () => ({}) }], [accessor],