diff --git a/.castiron.stats.yml b/.castiron.stats.yml index 5a0a93c080..ec8370d25f 100644 --- a/.castiron.stats.yml +++ b/.castiron.stats.yml @@ -1,8 +1,8 @@ schema_version: 1 -generation_id: 592b2cad-c398-46a9-9df6-7858c09f3b65 -openapi_spec_hash: d6717da751735789c482f47d6613cea0 -openapi_transformed_spec_hash: 46e4f19c824b10d620e3c7bc4a7d569e -config_hash: 0fe55890f9499fed76b60662804e30f7 -codegen_sha: f028b1b011d31cf0cd8a1939e83bf7ec5d2b8762 -codegen_hash: 2e485073ea1166bc85b3b8c04a512d221b82ef5c490801250ffc209d6292e201 -public_codegen_sha: b045ae7e94f055f952b812dfc4ddee314a691df7 +generation_id: c6c71409-c9d1-487b-ad35-c8973d3274a6 +openapi_spec_hash: 23f0bfa58ad53fef090bea6a72a05dda +openapi_transformed_spec_hash: 39f2336a30336863627b56624b390f24 +config_hash: 249b5f41fe1b916955299cea75cddfbf +codegen_sha: 73e15aa409d55f8731c775cab5a85c9e93d66b3c +codegen_hash: 166545ad5fafe31085bb865842a68c605eea009ccfec4e4247b851e46d7c34fb +public_codegen_sha: 74fb1f948524997714d02fb52f387e0ab93ce338 diff --git a/.github/workflows/castiron-custom-code-comment.yml b/.github/workflows/castiron-custom-code-comment.yml index b0128ef689..c0f9e37ee4 100644 --- a/.github/workflows/castiron-custom-code-comment.yml +++ b/.github/workflows/castiron-custom-code-comment.yml @@ -29,8 +29,21 @@ jobs: pull-requests: read statuses: write steps: - # Trusted main definition: no candidate checkout, artifacts, or executable inputs. + # Execute only the helper belonging to this immutable workflow revision. + - name: Check out the trusted review policy + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ github.workflow_sha }} + persist-credentials: false + - 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: | @@ -48,12 +61,37 @@ jobs: run.head_sha !== signal.head_sha || run.path.split('@', 1)[0] !== '.github/workflows/castiron-custom-code.yml') { throw new Error('Unexpected or superseded review signal'); } + async function mergeBase(base, head) { + const {data: comparison} = await github.rest.repos.compareCommitsWithBasehead({ + ...context.repo, basehead: `${base}...${head}`, per_page: 1, + }); + const sha = comparison.merge_base_commit?.sha; + if (!/^[0-9a-f]{40}$/.test(sha || '')) throw new Error('Invalid policy merge base'); + return sha; + } + async function requiresHuman(pr, mainSha) { + const path = require('node:path'); + const fs = require('node:fs'); + const root = fs.mkdtempSync(path.join(process.env.RUNNER_TEMP, 'castiron-review-')); + try { + const result = await exec.getExecOutput('python3', ['-I', + 'scripts/castiron/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}); + } + } const dirtyTargets = new Set(); // Retry discovery within this job timeout while targets are changing. while (true) { const candidates = []; let pulls = run.pull_requests?.length ? run.pull_requests : await github.paginate( github.rest.repos.listPullRequestsAssociatedWithCommit, {...context.repo, commit_sha: run.head_sha}); + const hasAssociation = pulls.length > 0; if (!pulls.length) pulls = await github.paginate(github.rest.pulls.list, { ...context.repo, state: 'open', head: `${run.head_repository.owner.login}:${run.head_branch}`, }); @@ -62,18 +100,48 @@ jobs: if (pr.state !== 'open' || pr.base.ref !== 'next' || pr.base.repo.full_name !== repo || (item.head?.sha && pr.head.sha !== item.head.sha) || !/^[0-9a-f]{40}$/.test(pr.head.sha)) continue; if (run.head_sha !== pr.head.sha) { - const {data: merge} = await github.rest.git.getRef({...context.repo, ref: `pull/${pr.number}/merge`}); const {data: commit} = await github.rest.repos.getCommit({...context.repo, ref: run.head_sha}); - if (merge.object.sha !== run.head_sha || commit.parents.length !== 2 || - commit.parents[0].sha !== pr.base.sha || commit.parents[1].sha !== pr.head.sha) continue; + if (commit.parents.length !== 2 || commit.parents[1].sha !== pr.head.sha || + !/^[0-9a-f]{40}$/.test(commit.parents[0].sha) || + await mergeBase(commit.parents[0].sha, pr.base.sha) !== commit.parents[0].sha) continue; + // Without a commit association, the live merge ref must identify this PR. + if (!hasAssociation) { + const {data: merge} = await github.rest.git.getRef({...context.repo, ref: `pull/${pr.number}/merge`}); + if (merge.object.sha !== run.head_sha || commit.parents[0].sha !== pr.base.sha) continue; + } } candidates.push(pr); } if (!candidates.length) return; // Main, closed, and superseded PR reviews have no next target. - if (candidates.length !== 1) throw new Error('Review signal identifies ambiguous next PRs'); - const pr = candidates[0]; + // Commit associations may include other PRs sharing the same head. + const matching = candidates.length === 1 ? candidates : candidates.filter(pr => + Number.isSafeInteger(run.head_repository?.id) && run.head_repository.id > 0 && + pr.head.repo?.id === run.head_repository.id && typeof run.head_branch === 'string' && + run.head_branch.length > 0 && pr.head.ref === run.head_branch); + if (matching.length !== 1) throw new Error('Review signal identifies ambiguous next PRs'); + 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 {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 (!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'}), + mainSha && github.rest.git.getRef({...context.repo, ref: 'heads/main'}), + ]); + if (current.head.sha !== pr.head.sha || current.base.sha !== pr.base.sha || + target.object.sha !== pr.base.sha || (main && main.data.object.sha !== mainSha)) continue; + return; + } // Read authoritative reviews, including edits: submittedAt alone misses // removal/restoration of an attestation. Never trust candidate event artifacts. let reviewCursor = null; diff --git a/api.md b/api.md index 7e6990c2fa..9430f4789c 100644 --- a/api.md +++ b/api.md @@ -257,12 +257,13 @@ Methods: Types: ```python -from openai.types.audio import Voice +from openai.types.audio import Voice, VoiceDeleted ``` Methods: - client.audio.voices.create(\*\*params) -> Voice +- client.audio.voices.delete(voice_id) -> VoiceDeleted ## VoiceConsents @@ -637,6 +638,49 @@ Methods: - client.beta.agents.list(\*\*params) -> SyncCursorPage[Agent] - client.beta.agents.delete(agent_id) -> AgentDeleted +### Automations + +Types: + +```python +from openai.types.beta.agents import ( + Automation, + AutomationAgentConfig, + AutomationCreatedBy, + AutomationDeleted, + AutomationEnvironment, + AutomationMetadataParam, + AutomationTarget, + AutomationTargetParam, + OneTimeAutomation, + PeriodicAutomation, +) +``` + +Methods: + +- client.beta.agents.automations.create(\*\*params) -> Automation +- client.beta.agents.automations.retrieve(automation_id) -> Automation +- client.beta.agents.automations.update(automation_id, \*\*params) -> Automation +- client.beta.agents.automations.list(\*\*params) -> SyncCursorPage[Automation] +- client.beta.agents.automations.delete(automation_id) -> AutomationDeleted +- client.beta.agents.automations.pause(automation_id) -> Automation +- client.beta.agents.automations.resume(automation_id) -> Automation + +#### Invocations + +Types: + +```python +from openai.types.beta.agents.automations import AutomationInvocation, AutomationInvocationSource +``` + +Methods: + +- client.beta.agents.automations.invocations.create(automation_id) -> AutomationInvocation +- client.beta.agents.automations.invocations.retrieve(invocation_id, \*, automation_id) -> AutomationInvocation +- client.beta.agents.automations.invocations.list(automation_id, \*\*params) -> SyncCursorPage[AutomationInvocation] + ### Environments Types: diff --git a/api_reference/openapi.transformed.yml b/api_reference/openapi.transformed.yml index 1053ca1b53..7f9682c8a2 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: @@ -21216,6 +21379,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: @@ -21709,6 +21875,9 @@ paths: application/json: schema: $ref: '#/components/schemas/RunObject' + text/event-stream: + schema: + $ref: '#/components/schemas/AssistantStreamEvent' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -22993,6 +23162,9 @@ paths: application/json: schema: $ref: '#/components/schemas/RunObject' + text/event-stream: + schema: + $ref: '#/components/schemas/AssistantStreamEvent' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -23933,6 +24105,9 @@ paths: application/json: schema: $ref: '#/components/schemas/RunObject' + text/event-stream: + schema: + $ref: '#/components/schemas/AssistantStreamEvent' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: @@ -30357,194 +30532,26 @@ paths: "total_tokens": 42 } } - /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 - 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: type - in: query - required: false - schema: - $ref: '#/components/schemas/EnvironmentTypeParam' - description: The hosting type to list. Defaults to `openai_hosted`. - responses: - '200': - description: A page of owned environments. - content: - application/json: - schema: - $ref: '#/components/schemas/AgentEnvironmentListResource' - description: An ID-paginated list of owned environments. - '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 environment or referenced resource 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' - '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/automations: post: - operationId: createAgentEnvironment - summary: Create an agent environment - description: Creates an OpenAI-hosted environment before creating a session. Requires access to the prewarming beta. + operationId: createAgentAutomation + summary: Create an automation + description: Saves an active automation without invoking it immediately. tags: - Agents - parameters: - - name: Idempotency-Key - in: header - required: false - 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' + $ref: '#/components/schemas/CreateAutomationParams' required: true responses: '201': - description: The created OpenAI-hosted environment. + description: The created automation. content: application/json: schema: - $ref: '#/components/schemas/PublicEnvironmentResource' - '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 environment or referenced resource 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. - 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/{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). - tags: - - Agents - parameters: - - name: environment_id - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the environment. - responses: - '200': - description: The requested environment. - content: - application/json: - schema: - $ref: '#/components/schemas/PublicEnvironmentResource' + $ref: '#/components/schemas/AutomationResource' '400': description: The request was invalid. content: @@ -30587,64 +30594,91 @@ 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). + operationId: listAgentAutomations + summary: List automations + description: Lists project-owned automations, optionally filtered by target session. 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 - - 'null' + type: integer format: int64 minimum: 1 maximum: 100 - description: The maximum number of files to return, between 1 and 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' - description: Sort by case-sensitive path components. Defaults to descending. - - name: page + 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 opaque token from the previous page. Keep the same path, order, and limit. + description: Return resources after this resource ID in the selected order. + - name: session_id + in: query + required: false + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: Matches existing-session targets, including agent-created automations. responses: '200': - description: A page of live environment files. + description: The automations. content: application/json: schema: - $ref: '#/components/schemas/EnvironmentFileListResource' + 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: @@ -30681,39 +30715,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: 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). + /agents/automations/{automation_id}: + get: + operationId: getAgentAutomation + summary: Get an automation + description: Retrieves a project-owned automation. 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' 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: @@ -30744,12 +30779,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: @@ -30762,92 +30791,33 @@ 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). + post: + operationId: updateAgentAutomation + summary: Update an automation + description: Updates supplied fields; target and metadata replace the whole field. 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. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAutomationParams' + required: true 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: @@ -30890,37 +30860,27 @@ 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). + delete: + operationId: deleteAgentAutomation + summary: Delete an automation + description: Deletes the automation and prevents future invocations without deleting its target session. 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: Successful response. content: application/json: schema: - $ref: '#/components/schemas/SubagentResource' + $ref: '#/components/schemas/DeletedAutomationResource' '400': description: The request was invalid. content: @@ -30963,62 +30923,28 @@ 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). + /agents/automations/{automation_id}/pause: + post: + operationId: pauseAgentAutomation + summary: Pause an automation + description: Pauses future scheduled delivery without stopping an active session. 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 - 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 subagent history. + description: Successful response. content: application/json: schema: - $ref: '#/components/schemas/SessionItemListResource' + $ref: '#/components/schemas/AutomationResource' '400': description: The request was invalid. content: @@ -31061,63 +30987,28 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/subagents/{subagent_id}/turns: - 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). + /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 - 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 - 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 subagent history. + description: Successful response. content: application/json: schema: - $ref: '#/components/schemas/SessionTurnListResource' - description: A page of turns from an agent session or subagent. + $ref: '#/components/schemas/AutomationResource' '400': description: The request was invalid. content: @@ -31160,45 +31051,28 @@ 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). + /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 - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the subagent in this session. - - name: turn_id + - name: automation_id in: path 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. + description: The queued invocation. content: application/json: schema: - $ref: '#/components/schemas/TurnResource' + $ref: '#/components/schemas/AutomationInvocationResource' '400': description: The request was invalid. content: @@ -31241,38 +31115,20 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items: 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: 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 - in: path - required: true - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the subagent in this session. - - name: turn_id + - name: automation_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 @@ -31300,11 +31156,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: @@ -31341,53 +31235,47 @@ 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: + /agents/automations/{automation_id}/invocations/{invocation_id}: 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: getAgentAutomationInvocation + summary: Get an automation invocation + description: Retrieves a delivery record for a project-owned automation. 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 + - name: automation_id + in: path + required: true schema: - $ref: '#/components/schemas/ListOrderParam' - default: desc - description: The order in which resources are returned. Defaults to `desc`. - - name: after - in: query - required: false + type: string + minLength: 0 + maxLength: 1048576 + - name: invocation_id + in: path + required: true schema: type: string minLength: 0 maxLength: 1048576 - description: Return resources after this resource ID in the selected order. responses: '200': - description: A page of agents. + description: The invocation. content: application/json: schema: - $ref: '#/components/schemas/AgentListResource' - description: A page of reusable agents. + $ref: '#/components/schemas/AutomationInvocationResource' '400': description: The request was invalid. content: @@ -31430,24 +31318,53 @@ paths: application/json: 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). + /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 - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateAgentParams' + 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: type + in: query + required: false + schema: + $ref: '#/components/schemas/EnvironmentTypeParam' + description: The hosting type to list. Defaults to `openai_hosted`. responses: - '201': - description: The created agent. + '200': + description: A page of owned environments. content: application/json: schema: - $ref: '#/components/schemas/AgentResource' + $ref: '#/components/schemas/AgentEnvironmentListResource' + description: An ID-paginated list of owned environments. '400': description: The request was invalid. content: @@ -31467,13 +31384,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: @@ -31490,29 +31407,34 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/{agent_id}: - 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). + 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: agent_id - in: path - required: true + - name: Idempotency-Key + in: header + required: false schema: type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the reusable agent. + 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 responses: - '200': - description: The requested agent. + '201': + description: The created OpenAI-hosted environment. content: application/json: schema: - $ref: '#/components/schemas/AgentResource' + $ref: '#/components/schemas/PublicEnvironmentResource' '400': description: The request was invalid. content: @@ -31532,13 +31454,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: @@ -31555,33 +31483,29 @@ 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/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). tags: - Agents parameters: - - name: agent_id + - name: environment_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 environment. responses: '200': - description: The updated agent. + description: The requested environment. content: application/json: schema: - $ref: '#/components/schemas/AgentResource' + $ref: '#/components/schemas/PublicEnvironmentResource' '400': description: The request was invalid. content: @@ -31624,256 +31548,64 @@ 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/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). tags: - Agents parameters: - - name: agent_id + - name: environment_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The ID of the reusable agent. - responses: - '200': - description: The deleted agent. - content: - application/json: - schema: - $ref: '#/components/schemas/DeletedAgentResource' - '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/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: + 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 environment templates. + description: A page of live environment files. content: application/json: schema: - $ref: '#/components/schemas/EnvironmentTemplateListResource' - description: A page of reusable environment templates. + $ref: '#/components/schemas/EnvironmentFileListResource' '400': description: The request was invalid. content: @@ -31887,13 +31619,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: @@ -31911,23 +31649,32 @@ paths: 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). + 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/CreateEnvironmentTemplateParams' + $ref: '#/components/schemas/HostedEnvironmentFileParam' responses: '201': - description: The created environment template. + description: The written live environment file. content: application/json: schema: - $ref: '#/components/schemas/EnvironmentTemplateResource' + $ref: '#/components/schemas/EnvironmentFileResource' '400': description: The request was invalid. content: @@ -31941,13 +31688,25 @@ 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: + $ref: '#/components/schemas/ErrorResponse-2' + '429': + description: The Files API rate limit for your user has been exceeded. content: application/json: schema: @@ -31964,29 +31723,92 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/environments/templates/{environment_template_id}: + /agents/sessions/{session_id}/subagents: 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: 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: 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: 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 subagents. content: application/json: schema: - $ref: '#/components/schemas/EnvironmentTemplateResource' + 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: @@ -32000,13 +31822,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: @@ -32023,33 +31851,37 @@ 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/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: 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. - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateEnvironmentTemplateParams' + 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 environment template. + description: The requested subagent. content: application/json: schema: - $ref: '#/components/schemas/EnvironmentTemplateResource' + $ref: '#/components/schemas/SubagentResource' '400': description: The request was invalid. content: @@ -32063,19 +31895,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: @@ -32092,28 +31924,62 @@ 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). + /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: 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: 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 environment template. + description: The requested subagent history. content: application/json: schema: - $ref: '#/components/schemas/DeletedEnvironmentTemplateResource' + $ref: '#/components/schemas/SessionItemListResource' '400': description: The request was invalid. content: @@ -32127,19 +31993,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: @@ -32156,18 +32022,34 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions: + /agents/sessions/{session_id}/subagents/{subagent_id}/turns: 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: 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: limit - in: query - required: false - schema: + - 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 + schema: type: integer format: int64 minimum: 1 @@ -32189,22 +32071,14 @@ paths: minLength: 0 maxLength: 1048576 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: Only return sessions whose root agent has this ID. Omit to return sessions for all agents. responses: '200': - description: A page of sessions. + description: The requested subagent history. content: application/json: schema: - $ref: '#/components/schemas/SessionListResource' - description: A paginated list of sessions. + $ref: '#/components/schemas/SessionTurnListResource' + description: A page of turns from an agent session or subagent. '400': description: The request was invalid. content: @@ -32247,27 +32121,45 @@ paths: application/json: 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). + /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/CreateAgentSessionParams' + 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 session or its event stream. + '200': + description: The requested subagent history. content: application/json: schema: - $ref: '#/components/schemas/SessionResource' - text/event-stream: - schema: - $ref: '#/components/schemas/SessionEvent' + $ref: '#/components/schemas/TurnResource' '400': description: The request was invalid. content: @@ -32298,12 +32190,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: @@ -32316,14 +32202,11 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - x-oai-streaming: - request_field: stream - response_status_code: 201 - /agents/sessions/{session_id}: + /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items: 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). + 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: @@ -32335,13 +32218,54 @@ paths: 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. + - 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 session. + description: The requested subagent history. content: application/json: schema: - $ref: '#/components/schemas/SessionResource' + $ref: '#/components/schemas/SessionItemListResource' '400': description: The request was invalid. content: @@ -32384,33 +32308,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: + 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: 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 agents. content: application/json: schema: - $ref: '#/components/schemas/SessionResource' + $ref: '#/components/schemas/AgentListResource' + description: A page of reusable agents. '400': description: The request was invalid. content: @@ -32453,28 +32391,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: 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: 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/CreateAgentParams' responses: - '200': - description: The deleted session. + '201': + description: The created agent. content: application/json: schema: - $ref: '#/components/schemas/DeletedSessionResource' + $ref: '#/components/schemas/AgentResource' '400': description: The request was invalid. content: @@ -32517,65 +32451,29 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/artifacts: + /agents/{agent_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: 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: session_id + - name: agent_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 agent. responses: '200': - description: A page of durable session artifacts. + description: The requested agent. content: application/json: schema: - $ref: '#/components/schemas/SessionArtifactListResource' - description: A page of durable artifacts published by a session. + $ref: '#/components/schemas/AgentResource' '400': description: The request was invalid. content: @@ -32618,37 +32516,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: 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: 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: agent_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The immutable session artifact ID. + description: The ID of the reusable agent. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAgentParams' responses: '200': - description: The requested session artifact. + description: The updated agent. content: application/json: schema: - $ref: '#/components/schemas/SessionArtifactResource' + $ref: '#/components/schemas/AgentResource' '400': description: The request was invalid. content: @@ -32691,36 +32585,173 @@ 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: 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: 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 - 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: agent_id in: path required: true schema: type: string minLength: 0 maxLength: 1048576 - description: The immutable session artifact ID. + description: The ID of the reusable agent. responses: '200': - description: The deleted session artifact. + description: The deleted agent. content: application/json: schema: - $ref: '#/components/schemas/DeletedSessionArtifactResource' + $ref: '#/components/schemas/DeletedAgentResource' '400': description: The request was invalid. content: @@ -32763,38 +32794,47 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/artifacts/{artifact_id}/content: + /agents/environments/templates: 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: 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: string - minLength: 0 - maxLength: 1048576 - description: The ID of the session that owns the artifact. - - name: artifact_id - in: path - required: true + 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 immutable session artifact ID. + description: Return resources after this resource ID in the selected order. responses: '200': - description: The immutable artifact contents. + description: A page of environment templates. content: - application/octet-stream: + application/json: schema: - type: string - format: binary + $ref: '#/components/schemas/EnvironmentTemplateListResource' + description: A page of reusable environment templates. '400': description: The request was invalid. content: @@ -32808,19 +32848,67 @@ 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. + '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: 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 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateEnvironmentTemplateParams' + responses: + '201': + description: The created environment template. + content: + application/json: + schema: + $ref: '#/components/schemas/EnvironmentTemplateResource' + '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 environment definition was not found. content: application/json: schema: @@ -32837,29 +32925,29 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/events: + /agents/environments/templates/{environment_template_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: 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. + description: The ID of the reusable environment template. responses: '200': - description: A live stream of session events. + description: The requested environment template. content: - text/event-stream: + application/json: schema: - $ref: '#/components/schemas/SessionEvent' + $ref: '#/components/schemas/EnvironmentTemplateResource' '400': description: The request was invalid. content: @@ -32873,19 +32961,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: @@ -32902,40 +32984,33 @@ 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: 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 + - name: environment_template_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. + description: The ID of the reusable environment template. requestBody: content: application/json: schema: - $ref: '#/components/schemas/CreateSessionEventsParams' + $ref: '#/components/schemas/UpdateEnvironmentTemplateParams' responses: - '202': - description: The events were accepted. + '200': + description: The updated environment template. + content: + application/json: + schema: + $ref: '#/components/schemas/EnvironmentTemplateResource' '400': description: The request was invalid. content: @@ -32949,19 +33024,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: @@ -32978,54 +33053,28 @@ 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: 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 + - 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. + description: The ID of the reusable environment template. responses: '200': - description: A page of session items. + description: The deleted environment template. content: application/json: schema: - $ref: '#/components/schemas/SessionItemListResource' + $ref: '#/components/schemas/DeletedEnvironmentTemplateResource' '400': description: The request was invalid. content: @@ -33039,19 +33088,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: @@ -33068,22 +33117,14 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/traces: + /agents/sessions: 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: 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 - schema: - type: string - minLength: 0 - maxLength: 1048576 - description: The ID of the session. - name: limit in: query required: false @@ -33109,14 +33150,22 @@ paths: minLength: 0 maxLength: 1048576 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: Only return sessions whose root agent has this ID. Omit to return sessions for all agents. responses: '200': - description: A page of published session traces. + description: A page of sessions. content: application/json: schema: - $ref: '#/components/schemas/SessionTraceListResource' - description: A page of published session traces. + $ref: '#/components/schemas/SessionListResource' + description: A paginated list of sessions. '400': description: The request was invalid. content: @@ -33159,11 +33208,83 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /agents/sessions/{session_id}/turns: + 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: 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: 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: @@ -33175,39 +33296,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 turns. + description: The requested session. content: application/json: schema: - $ref: '#/components/schemas/SessionTurnListResource' - description: A page of turns from an agent session or subagent. + $ref: '#/components/schemas/SessionResource' '400': description: The request was invalid. content: @@ -33250,11 +33345,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). + 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). tags: - Agents parameters: @@ -33265,22 +33359,19 @@ paths: type: string minLength: 0 maxLength: 1048576 - 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. + description: The ID of the session. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAgentSessionParams' responses: '200': - description: The requested turn. + description: The updated session. content: application/json: schema: - $ref: '#/components/schemas/TurnResource' + $ref: '#/components/schemas/SessionResource' '400': description: The request was invalid. content: @@ -33323,11 +33414,10 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /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). + 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: @@ -33338,47 +33428,14 @@ paths: type: string minLength: 0 maxLength: 1048576 - 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. + description: The ID of the session. responses: '200': - description: A page of session turn items. + description: The deleted session. content: application/json: schema: - $ref: '#/components/schemas/SessionItemListResource' + $ref: '#/components/schemas/DeletedSessionResource' '400': description: The request was invalid. content: @@ -33421,14 +33478,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /vaults: + /agents/sessions/{session_id}/artifacts: 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: 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: - - 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 @@ -33454,38 +33519,24 @@ 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 + - name: environment_id 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. + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: Restrict the listing to artifacts produced by this environment. responses: '200': - description: A page of vaults. + description: A page of durable session artifacts. content: application/json: schema: - $ref: '#/components/schemas/VaultListResource' - description: A page of vaults. + $ref: '#/components/schemas/SessionArtifactListResource' + description: A page of durable artifacts published by a session. '400': description: The request was invalid. content: @@ -33499,19 +33550,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: @@ -33528,24 +33579,37 @@ 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}/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). 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 that owns the artifact. + - name: artifact_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The immutable session artifact ID. responses: - '201': - description: The created vault. + '200': + description: The requested session artifact. content: application/json: schema: - $ref: '#/components/schemas/VaultResource' + $ref: '#/components/schemas/SessionArtifactResource' '400': description: The request was invalid. content: @@ -33559,19 +33623,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: @@ -33588,29 +33652,36 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /vaults/{vault_id}: - 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). + 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: - - 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 artifact. + - name: artifact_id + in: path + required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The immutable session artifact ID. responses: '200': - description: The requested vault. + description: The deleted session artifact. content: application/json: schema: - $ref: '#/components/schemas/VaultResource' + $ref: '#/components/schemas/DeletedSessionArtifactResource' '400': description: The request was invalid. content: @@ -33624,19 +33695,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: @@ -33653,36 +33724,38 @@ 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}/artifacts/{artifact_id}/content: + 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). 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 artifact. + - name: artifact_id + in: path required: true + schema: + type: string + minLength: 0 + maxLength: 1048576 + description: The immutable session artifact ID. responses: '200': - description: The updated vault. + description: The immutable artifact contents. content: - application/json: + application/octet-stream: schema: - $ref: '#/components/schemas/VaultResource' + type: string + format: binary '400': description: The request was invalid. content: @@ -33696,19 +33769,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: @@ -33725,28 +33798,105 @@ 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}/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: - - 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. responses: '200': - description: The deleted vault. + 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/DeletedVaultResource' + $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: @@ -33760,19 +33910,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: @@ -33789,22 +33939,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /vaults/{vault_id}/credentials: + /agents/sessions/{session_id}/items: 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: 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: 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 @@ -33830,38 +33980,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 vault credentials. + description: A page of session items. content: application/json: schema: - $ref: '#/components/schemas/VaultCredentialListResource' - description: A page of credentials in a vault. + $ref: '#/components/schemas/SessionItemListResource' '400': description: The request was invalid. content: @@ -33875,19 +34000,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: @@ -33904,33 +34029,55 @@ paths: 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). + /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 + - 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/CreateVaultCredentialParams' + 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 credential without secret values. + '200': + description: A page of published session traces. content: application/json: schema: - $ref: '#/components/schemas/VaultCredentialResource' + $ref: '#/components/schemas/SessionTraceListResource' + description: A page of published session traces. '400': description: The request was invalid. content: @@ -33944,19 +34091,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: @@ -33973,37 +34120,55 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /vaults/{vault_id}/credentials/{credential_id}: + /agents/sessions/{session_id}/turns: 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: 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. - - name: credential_id - in: path - required: true + 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: The ID of the vault credential. + description: Return resources after this resource ID in the selected order. responses: '200': - description: The requested vault credential without secret values. + description: A page of session turns. content: application/json: schema: - $ref: '#/components/schemas/VaultCredentialResource' + $ref: '#/components/schemas/SessionTurnListResource' + description: A page of turns from an agent session or subagent. '400': description: The request was invalid. content: @@ -34017,19 +34182,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: @@ -34046,42 +34211,37 @@ paths: 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). + /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. - - name: credential_id + 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 vault credential. - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/RotateVaultCredentialParams' - required: true + description: The ID of the turn. responses: '200': - description: The updated vault credential without secret values. + description: The requested turn. content: application/json: schema: - $ref: '#/components/schemas/VaultCredentialResource' + $ref: '#/components/schemas/TurnResource' '400': description: The request was invalid. content: @@ -34095,19 +34255,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: @@ -34124,36 +34284,62 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - delete: - operationId: deleteVaultCredential - summary: Delete a vault credential - description: Deletes a vault credential. 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. - - name: credential_id + 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 vault credential. + 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 credential. + description: A page of session turn items. content: application/json: schema: - $ref: '#/components/schemas/DeletedVaultCredentialResource' + $ref: '#/components/schemas/SessionItemListResource' '400': description: The request was invalid. content: @@ -34167,19 +34353,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: @@ -34196,344 +34382,1121 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse-2' - /webhook_endpoints: + /vaults: get: - summary: List Webhook Endpoints - description: Returns webhook endpoints for the authenticated project in newest-first order. - operationId: ListWebhookEndpoints + 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: limit in: query - description: Maximum number of webhook endpoints to return. Defaults to 20. 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 - description: ID of the last webhook endpoint from the previous page. required: false schema: - anyOf: - - example: whe_123 + 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 - - type: 'null' + 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: Success + description: A page of vaults. content: application/json: schema: - $ref: '#/components/schemas/WebhookEndpointListResource' + $ref: '#/components/schemas/VaultListResource' + description: A page of vaults. '400': - description: The request parameters are invalid. + description: The request was invalid. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $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 pagination cursor does not identify a webhook endpoint in the authenticated project. + description: The requested vault or credential was not found. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' - x-oaiMeta: - beta: true + $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: - summary: Create Webhook Endpoint - description: Creates a webhook endpoint for the authenticated project. - operationId: CreateWebhookEndpoint - parameters: [] + 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 requestBody: content: application/json: schema: - $ref: '#/components/schemas/PublicCreateEndpointBody' + $ref: '#/components/schemas/CreateVaultParams' responses: - '200': - description: Success + '201': + description: The created vault. content: application/json: schema: - $ref: '#/components/schemas/WebhookEndpointWithSecretResource' + $ref: '#/components/schemas/VaultResource' '400': - description: The webhook endpoint parameters are invalid or the endpoint cannot be created with the requested URL or event types. + description: The request was invalid. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' - x-oaiMeta: - beta: true - /webhook_endpoints/{webhook_endpoint_id}: + $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}: get: - summary: Retrieve Webhook Endpoint - description: Retrieves a webhook endpoint for the authenticated project. - operationId: RetrieveWebhookEndpoint + 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: - - name: webhook_endpoint_id + - name: vault_id in: path - description: The ID of the webhook endpoint to retrieve. required: true schema: - example: whe_123 type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the vault. responses: '200': - description: Success + description: The requested vault. content: application/json: schema: - $ref: '#/components/schemas/WebhookEndpointBody' + $ref: '#/components/schemas/VaultResource' '400': - description: The request parameters are invalid. + description: The request was invalid. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $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 webhook endpoint was not found in the authenticated project. + description: The requested vault or credential was not found. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' - x-oaiMeta: - beta: true + $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: - summary: Update Webhook Endpoint - description: Updates a webhook endpoint for the authenticated project. - operationId: UpdateWebhookEndpoint + 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: - - name: webhook_endpoint_id + - name: vault_id in: path - description: The ID of the webhook endpoint to update. required: true schema: - example: whe_123 type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the vault. requestBody: content: application/json: schema: - $ref: '#/components/schemas/PublicUpdateEndpointBody' + $ref: '#/components/schemas/UpdateVaultParams' + example: + name: Research vault + required: true responses: '200': - description: Success + description: The updated vault. content: application/json: schema: - $ref: '#/components/schemas/WebhookEndpointBody' + $ref: '#/components/schemas/VaultResource' '400': - description: The webhook endpoint parameters are invalid or the requested URL or event types are not permitted. + description: The request was invalid. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $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 webhook endpoint was not found in the authenticated project. + description: The requested vault or credential was not found. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' - x-oaiMeta: - beta: true + $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: - summary: Delete Webhook Endpoint - description: Deletes a webhook endpoint for the authenticated project. - operationId: DeleteWebhookEndpoint + 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: webhook_endpoint_id + - name: vault_id in: path - description: The ID of the webhook endpoint to delete. required: true schema: - example: whe_123 type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the vault. responses: '200': - description: Success + description: The deleted vault. content: application/json: schema: - $ref: '#/components/schemas/DeletedWebhookEndpointResource' + $ref: '#/components/schemas/DeletedVaultResource' '400': - description: The request parameters are invalid. + description: The request was invalid. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $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 webhook endpoint was not found in the authenticated project. + description: The requested vault or credential was not found. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' - x-oaiMeta: - beta: true - /webhook_endpoints/{webhook_endpoint_id}/rotate_secret: - post: - summary: Rotate Webhook Endpoint Signing Secret - description: Rotates the signing secret for a webhook endpoint in the authenticated project. - operationId: RotateWebhookEndpointSigningSecret + $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: webhook_endpoint_id + - name: vault_id in: path - description: The ID of the webhook endpoint whose signing secret will be rotated. required: true schema: - example: whe_123 type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PublicRotateSecretBody' + 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: Success + description: A page of vault credentials. content: application/json: schema: - $ref: '#/components/schemas/WebhookEndpointWithSecretResource' + $ref: '#/components/schemas/VaultCredentialListResource' + description: A page of credentials in a vault. '400': - description: The request parameters are invalid. + description: The request was invalid. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $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 webhook endpoint was not found in the authenticated project. + description: The requested vault or credential was not found. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' - x-oaiMeta: - beta: true - /webhook_endpoints/{webhook_endpoint_id}/test: + $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: - summary: Test Webhook Endpoint - description: Sends a sample event to a webhook endpoint for the authenticated project. - operationId: TestWebhookEndpoint + 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: webhook_endpoint_id + - name: vault_id in: path - description: The ID of the webhook endpoint to test. required: true schema: - example: whe_123 type: string + minLength: 0 + maxLength: 1048576 + description: The ID of the vault. requestBody: content: application/json: schema: - $ref: '#/components/schemas/PublicTestEndpointBody' + $ref: '#/components/schemas/CreateVaultCredentialParams' responses: - '200': - description: Success + '201': + description: The created vault credential without secret values. content: application/json: schema: - $ref: '#/components/schemas/WebhookEndpointTestResultResource' + $ref: '#/components/schemas/VaultCredentialResource' '400': - description: The request parameters are invalid. + description: The request was invalid. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' - '404': - description: The webhook endpoint was not found in the authenticated project. + $ref: '#/components/schemas/ErrorResponse-2' + '401': + description: Authentication or project context was missing. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' - '500': - description: The sample event could not be sent to the webhook endpoint. + $ref: '#/components/schemas/ErrorResponse-2' + '403': + description: The API key lacks the required management permission. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' - x-oaiMeta: - beta: true - /webhook_event_types: - get: - summary: List Webhook Event Types - description: Returns webhook event types visible to the authenticated project. - operationId: ListWebhookEventTypes - parameters: [] - responses: - '200': - description: Success + $ref: '#/components/schemas/ErrorResponse-2' + '404': + description: The requested vault or credential was not found. content: application/json: schema: - $ref: '#/components/schemas/WebhookEventTypeListResource' - '401': - description: The request does not contain authentication credentials. - headers: - WWW-Authenticate: - description: The bearer authentication challenge returned by the service. + $ref: '#/components/schemas/ErrorResponse-2' + '409': + description: The request conflicted with the current vault state. + content: + application/json: schema: - type: string - example: Bearer realm="OpenAI API" + $ref: '#/components/schemas/ErrorResponse-2' + '500': + description: An internal error occurred. content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' - x-oaiMeta: - beta: true - /responses?beta=true: - post: - operationId: beta_createResponse + $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: - - Responses - summary: Create a model response - description: | - Creates a model response. Provide [text](https://developers.openai.com/api/docs/guides/text) or - [image](https://developers.openai.com/api/docs/guides/images-vision) inputs to generate [text](https://developers.openai.com/api/docs/guides/text) - or [JSON](https://developers.openai.com/api/docs/guides/structured-outputs) outputs. Have the model call - your own [custom code](https://developers.openai.com/api/docs/guides/function-calling) or use built-in - [tools](https://developers.openai.com/api/docs/guides/tools) like [web search](https://developers.openai.com/api/docs/guides/tools-web-search) - or [file search](https://developers.openai.com/api/docs/guides/tools-file-search) to use your own data - as input for the model's response. - requestBody: + - Vaults + parameters: + - name: vault_id + in: path required: true - content: - application/json: - schema: - $ref: '#/components/schemas/BetaCreateResponse' + 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: OK + description: The requested vault credential without secret values. content: application/json: schema: - $ref: '#/components/schemas/BetaResponse' - text/event-stream: - schema: - $ref: '#/components/schemas/BetaResponseStreamEvent' + $ref: '#/components/schemas/VaultCredentialResource' '400': - description: Invalid response request or incompatible request parameters. + description: The request was invalid. content: application/json: schema: - $ref: '#/components/schemas/BetaErrorResponse' + $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 model or a referenced resource was not found or is unavailable to this caller. + description: The requested vault or credential was not found. content: application/json: schema: - $ref: '#/components/schemas/BetaErrorResponse' - '429': - $ref: '#/components/responses/InferenceRateLimited' + $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': - $ref: '#/components/responses/InferenceServiceUnavailable' - x-oaiMeta: - group: responses - path: create - examples: - - title: Text input - request: - curl: | + 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 + maxLength: 1048576 + description: The ID of the vault credential. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RotateVaultCredentialParams' + example: + metadata: {} + required: true + responses: + '200': + description: The updated 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' + delete: + operationId: deleteVaultCredential + summary: Delete a vault credential + description: Deletes a vault credential. 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 deleted vault credential. + content: + application/json: + schema: + $ref: '#/components/schemas/DeletedVaultCredentialResource' + '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' + /webhook_endpoints: + get: + summary: List Webhook Endpoints + description: Returns webhook endpoints for the authenticated project in newest-first order. + operationId: ListWebhookEndpoints + parameters: + - name: limit + in: query + description: Maximum number of webhook endpoints to return. Defaults to 20. + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + - name: after + in: query + description: ID of the last webhook endpoint from the previous page. + required: false + schema: + anyOf: + - example: whe_123 + type: string + - type: 'null' + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookEndpointListResource' + '400': + description: The request parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The pagination cursor does not identify a webhook endpoint in the authenticated project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + x-oaiMeta: + beta: true + post: + summary: Create Webhook Endpoint + description: Creates a webhook endpoint for the authenticated project. + operationId: CreateWebhookEndpoint + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PublicCreateEndpointBody' + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookEndpointWithSecretResource' + '400': + description: The webhook endpoint parameters are invalid or the endpoint cannot be created with the requested URL or event types. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + x-oaiMeta: + beta: true + /webhook_endpoints/{webhook_endpoint_id}: + get: + summary: Retrieve Webhook Endpoint + description: Retrieves a webhook endpoint for the authenticated project. + operationId: RetrieveWebhookEndpoint + parameters: + - name: webhook_endpoint_id + in: path + description: The ID of the webhook endpoint to retrieve. + required: true + schema: + example: whe_123 + type: string + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookEndpointBody' + '400': + description: The request parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The webhook endpoint was not found in the authenticated project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + x-oaiMeta: + beta: true + post: + summary: Update Webhook Endpoint + description: Updates a webhook endpoint for the authenticated project. + operationId: UpdateWebhookEndpoint + parameters: + - name: webhook_endpoint_id + in: path + description: The ID of the webhook endpoint to update. + required: true + schema: + example: whe_123 + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PublicUpdateEndpointBody' + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookEndpointBody' + '400': + description: The webhook endpoint parameters are invalid or the requested URL or event types are not permitted. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The webhook endpoint was not found in the authenticated project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + x-oaiMeta: + beta: true + delete: + summary: Delete Webhook Endpoint + description: Deletes a webhook endpoint for the authenticated project. + operationId: DeleteWebhookEndpoint + parameters: + - name: webhook_endpoint_id + in: path + description: The ID of the webhook endpoint to delete. + required: true + schema: + example: whe_123 + type: string + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/DeletedWebhookEndpointResource' + '400': + description: The request parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The webhook endpoint was not found in the authenticated project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + x-oaiMeta: + beta: true + /webhook_endpoints/{webhook_endpoint_id}/rotate_secret: + post: + summary: Rotate Webhook Endpoint Signing Secret + description: Rotates the signing secret for a webhook endpoint in the authenticated project. + operationId: RotateWebhookEndpointSigningSecret + parameters: + - name: webhook_endpoint_id + in: path + description: The ID of the webhook endpoint whose signing secret will be rotated. + required: true + schema: + example: whe_123 + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PublicRotateSecretBody' + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookEndpointWithSecretResource' + '400': + description: The request parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The webhook endpoint was not found in the authenticated project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + x-oaiMeta: + beta: true + /webhook_endpoints/{webhook_endpoint_id}/test: + post: + summary: Test Webhook Endpoint + description: Sends a sample event to a webhook endpoint for the authenticated project. + operationId: TestWebhookEndpoint + parameters: + - name: webhook_endpoint_id + in: path + description: The ID of the webhook endpoint to test. + required: true + schema: + example: whe_123 + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PublicTestEndpointBody' + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookEndpointTestResultResource' + '400': + description: The request parameters are invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '404': + description: The webhook endpoint was not found in the authenticated project. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: The sample event could not be sent to the webhook endpoint. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + x-oaiMeta: + beta: true + /webhook_event_types: + get: + summary: List Webhook Event Types + description: Returns webhook event types visible to the authenticated project. + operationId: ListWebhookEventTypes + parameters: [] + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookEventTypeListResource' + '401': + description: The request does not contain authentication credentials. + headers: + WWW-Authenticate: + description: The bearer authentication challenge returned by the service. + schema: + type: string + example: Bearer realm="OpenAI API" + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + x-oaiMeta: + beta: true + /responses?beta=true: + post: + operationId: beta_createResponse + tags: + - Responses + summary: Create a model response + description: | + Creates a model response. Provide [text](https://developers.openai.com/api/docs/guides/text) or + [image](https://developers.openai.com/api/docs/guides/images-vision) inputs to generate [text](https://developers.openai.com/api/docs/guides/text) + or [JSON](https://developers.openai.com/api/docs/guides/structured-outputs) outputs. Have the model call + your own [custom code](https://developers.openai.com/api/docs/guides/function-calling) or use built-in + [tools](https://developers.openai.com/api/docs/guides/tools) like [web search](https://developers.openai.com/api/docs/guides/tools-web-search) + or [file search](https://developers.openai.com/api/docs/guides/tools-file-search) to use your own data + as input for the model's response. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/BetaCreateResponse' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/BetaResponse' + text/event-stream: + schema: + $ref: '#/components/schemas/BetaResponseStreamEvent' + '400': + description: Invalid response request or incompatible request parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/BetaErrorResponse' + '404': + description: The requested model or a referenced resource was not found or is unavailable to this caller. + content: + application/json: + schema: + $ref: '#/components/schemas/BetaErrorResponse' + '429': + $ref: '#/components/responses/InferenceRateLimited' + '503': + $ref: '#/components/responses/InferenceServiceUnavailable' + x-oaiMeta: + group: responses + path: create + examples: + - title: Text input + request: + curl: | curl https://api.openai.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ @@ -35809,6 +36772,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: @@ -37385,6 +38351,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 @@ -41361,7 +42336,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: @@ -41740,6 +42716,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 @@ -43195,11 +44177,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' @@ -43234,13 +44223,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 @@ -43422,11 +44404,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 @@ -43434,6 +44411,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: @@ -45104,6 +46086,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 @@ -45654,11 +46675,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 @@ -45708,13 +46736,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 @@ -48954,6 +49975,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: | @@ -49010,11 +50036,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 @@ -49143,6 +50164,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: | @@ -49199,11 +50225,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 @@ -49496,6 +50517,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 @@ -49539,11 +50565,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: @@ -49967,6 +50988,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: @@ -50469,6 +51493,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: @@ -50480,8 +51506,6 @@ components: default: live x-stainless-const: true description: The session type. Always `live`. - triggers: - $ref: '#/components/schemas/triggers' required: - model - type @@ -50637,14 +51661,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 @@ -51842,9 +52866,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: @@ -52775,6 +53804,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: @@ -58567,7 +59599,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' @@ -58789,7 +59821,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 @@ -60927,8 +61959,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: | @@ -64037,6 +65071,7 @@ components: schema: $ref: '#/components/schemas/ResponseFormatJsonSchemaSchema' x-openai-ruby-json-schema-input: true + x-openai-go-public-type: any strict: anyOf: - type: boolean @@ -66131,6 +67166,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' @@ -70165,6 +71201,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. @@ -70234,11 +71275,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 @@ -71588,6 +72624,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: | @@ -71693,6 +72758,9 @@ components: - type - url - pattern + x-stainless-naming: + go: + type_name: ResponseFunctionWebSearchActionFind WebSearchActionOpenPage: type: object title: Open page action @@ -71914,6 +72982,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: @@ -73617,6 +74688,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 @@ -73841,6 +74918,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 @@ -77247,6 +78330,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 @@ -77985,6 +79073,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 @@ -77999,6 +79092,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. @@ -78009,6 +79226,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 @@ -78335,6 +79593,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 @@ -78495,6 +79758,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 @@ -78922,6 +80186,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 @@ -79154,6 +80419,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 @@ -79245,11 +80515,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 @@ -81876,6 +83141,150 @@ components: - type additionalProperties: false description: An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported. + DecisionInputJson: + type: object + properties: + type: + type: string + enum: + - input_json + default: input_json + x-stainless-const: true + data: + anyOf: + - type: object + additionalProperties: + anyOf: + - {} + - type: 'null' + propertyNames: + type: string + minLength: 0 + minProperties: 0 + - type: array + items: + type: object + additionalProperties: + anyOf: + - {} + - type: 'null' + propertyNames: + type: string + minLength: 0 + minProperties: 0 + minItems: 0 + required: + - type + - data + additionalProperties: false + description: A JSON object or an array of objects rendered as text. Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON. + DecisionInputContentParts: + type: array + items: + x-oai-discriminator-values: + - input_text + - input_image + - input_json + discriminator: + propertyName: type + mapping: + input_text: '#/components/schemas/DecisionInputText' + input_image: '#/components/schemas/DecisionInputImage' + input_json: '#/components/schemas/DecisionInputJson' + anyOf: + - $ref: '#/components/schemas/DecisionInputText' + - $ref: '#/components/schemas/DecisionInputImage' + - $ref: '#/components/schemas/DecisionInputJson' + minItems: 0 + maxItems: 16384 + DecisionInputContent: + description: A text string or an ordered list of text, image, and JSON parts. + anyOf: + - type: string + minLength: 0 + maxLength: 10485760 + - $ref: '#/components/schemas/DecisionInputContentParts' + title: Parts + DecisionInputUserMessage: + type: object + properties: + role: + type: string + enum: + - user + default: user + x-stainless-const: true + content: + $ref: '#/components/schemas/DecisionInputContent' + type: + type: string + enum: + - message + default: message + x-stainless-const: true + required: + - role + - content + additionalProperties: false + description: A user message containing input text, images, or JSON. + DecisionInputDeveloperContentParts: + type: array + items: + $ref: '#/components/schemas/DecisionInputText' + minItems: 0 + maxItems: 16384 + DecisionInputDeveloperContent: + description: A text string or an ordered list of input text parts. + anyOf: + - type: string + minLength: 0 + maxLength: 10485760 + - $ref: '#/components/schemas/DecisionInputDeveloperContentParts' + title: Parts + DecisionInputDeveloperMessage: + type: object + properties: + role: + type: string + enum: + - developer + default: developer + x-stainless-const: true + content: + $ref: '#/components/schemas/DecisionInputDeveloperContent' + type: + type: string + enum: + - message + default: message + x-stainless-const: true + required: + - role + - content + additionalProperties: false + description: A developer message containing input text. + DecisionInputSystemMessage: + type: object + properties: + role: + type: string + enum: + - system + default: system + x-stainless-const: true + content: + $ref: '#/components/schemas/DecisionInputDeveloperContent' + type: + type: string + enum: + - message + default: message + x-stainless-const: true + required: + - role + - content + additionalProperties: false + description: A system message containing input text. DecisionInputOutputText: type: object properties: @@ -81910,38 +83319,62 @@ components: - type - refusal additionalProperties: false - DecisionInputContentParts: + DecisionInputAssistantContentParts: type: array items: x-oai-discriminator-values: - - input_text - - input_image - - input_json + - output_text + - refusal discriminator: propertyName: type mapping: - input_text: '#/components/schemas/DecisionInputText' - input_image: '#/components/schemas/DecisionInputImage' - input_json: '#/components/schemas/DecisionInputJson' + output_text: '#/components/schemas/DecisionInputOutputText' + refusal: '#/components/schemas/DecisionInputRefusal' anyOf: - - $ref: '#/components/schemas/DecisionInputText' - - $ref: '#/components/schemas/DecisionInputImage' - - $ref: '#/components/schemas/DecisionInputJson' + - $ref: '#/components/schemas/DecisionInputOutputText' + - $ref: '#/components/schemas/DecisionInputRefusal' minItems: 0 maxItems: 16384 - DecisionInputContent: - description: A text string or an ordered list of text, image, and JSON parts. + DecisionInputAssistantContent: + description: A text string or an ordered list of output text and refusal parts. anyOf: - type: string minLength: 0 maxLength: 10485760 - - $ref: '#/components/schemas/DecisionInputContentParts' + - $ref: '#/components/schemas/DecisionInputAssistantContentParts' title: Parts MessagePhaseParam: type: string enum: - commentary - final_answer + DecisionInputAssistantMessage: + type: object + properties: + role: + type: string + enum: + - assistant + default: assistant + x-stainless-const: true + content: + $ref: '#/components/schemas/DecisionInputAssistantContent' + phase: + anyOf: + - $ref: '#/components/schemas/MessagePhaseParam' + - type: 'null' + description: The phase of an assistant message. + type: + type: string + enum: + - message + default: message + x-stainless-const: true + required: + - role + - content + additionalProperties: false + description: An assistant message containing output text or refusals. DecisionInputMessage: type: object discriminator: @@ -82172,6 +83605,65 @@ components: - $ref: '#/components/schemas/DecisionInputCustomToolCallOutput' minItems: 0 maxItems: 131072 + DecisionQuestionInputText: + type: object + properties: + type: + type: string + enum: + - input_text + default: input_text + x-stainless-const: true + text: + type: string + minLength: 0 + maxLength: 10485760 + required: + - type + - text + additionalProperties: false + DecisionQuestionInputImage: + type: object + properties: + image_url: + type: string + minLength: 0 + maxLength: 1073741824 + pattern: ^(data:|https?://) + description: A base64-encoded image in a data URL or a publicly accessible HTTP(S) image URL. + detail: + anyOf: + - $ref: '#/components/schemas/ImageDetailParam' + - type: 'null' + description: The image detail level, using the selected model's image profile. Defaults to auto. + default: auto + type: + type: string + enum: + - input_image + default: input_image + x-stainless-const: true + required: + - image_url + - type + additionalProperties: false + description: An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported. + DecisionQuestionInputPart: + description: A text, image, or JSON content part in a question instruction. + discriminator: + propertyName: type + mapping: + input_text: '#/components/schemas/DecisionQuestionInputText' + input_image: '#/components/schemas/DecisionQuestionInputImage' + input_json: '#/components/schemas/DecisionInputJson' + x-oai-discriminator-values: + - input_text + - input_image + - input_json + anyOf: + - $ref: '#/components/schemas/DecisionQuestionInputText' + - $ref: '#/components/schemas/DecisionQuestionInputImage' + - $ref: '#/components/schemas/DecisionInputJson' QuestionParamPredicate: type: object properties: @@ -82375,6 +83867,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. @@ -82629,406 +84122,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 + country: + type: + - string + - 'null' minLength: 0 - description: The error type. - code: - type: string + description: The two-letter ISO country code, such as `US`. + region: + type: + - string + - 'null' minLength: 0 - description: A machine-readable error code. - message: - type: string + description: The region or state name. + city: + type: + - string + - 'null' minLength: 0 - description: A human-readable error message. - param: + description: The city name. + timezone: type: - string - 'null' minLength: 0 - description: The request parameter that caused the error, or null for a request-wide error. - required: - - type - - code - - message - - param - additionalProperties: false - description: Details about an API error. - ErrorResponse-2: - type: object - properties: - error: - $ref: '#/components/schemas/ErrorBodyResource' - description: The error returned by the API. + description: The IANA timezone, such as `America/Los_Angeles`. required: - - error + - country + - region + - city + - timezone additionalProperties: false - description: An API error response. - EnvironmentPackagesParam: + description: Approximate user location used to localize web search results. + AgentToolResourceWebSearch: type: object properties: - python: + 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 - maxLength: 1048576 minItems: 0 - maxItems: 16384 - description: Python packages to install. Defaults to an empty list. - system: - type: - - array + 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 + - mode + - context_size + - allowed_domains + - location + additionalProperties: false + description: Web search. + AgentToolResourceComputerUse: + type: object + properties: + 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: + - type + - include_screenshots + additionalProperties: false + description: Browser use in an OpenAI-hosted session. + AgentToolResourceAutomations: + 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. + 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: + - 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: System packages to install. Defaults to an empty list. + 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: - 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 @@ -83039,54 +84708,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: @@ -83098,62 +84749,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: @@ -83165,39 +84775,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: @@ -83209,36 +84812,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: @@ -83250,21 +84846,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: @@ -83274,36 +84868,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: @@ -83313,45 +84906,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 @@ -83359,4418 +84945,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: - 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. + 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: 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: - openai_hosted: '#/components/schemas/CreateEnvironmentParamOpenaiHosted' - x-oai-discriminator-values: - - openai_hosted - anyOf: - - $ref: '#/components/schemas/CreateEnvironmentParamOpenaiHosted' - CreateAgentEnvironmentParams: + description: Hosted environment selection with confidential setup commands and variables omitted. + AutomationEnvironmentResourceSelfHosted: type: object properties: - environment: - $ref: '#/components/schemas/CreateEnvironmentParam' - description: The required hosting type and its configuration. - vault_ids: + 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: - - array + - string - 'null' + minLength: 0 + description: An existing registration, or null to create a session-owned environment. + workspace_directory: + type: string + minLength: 0 + description: The absolute project directory in the environment. + capability_directories: + type: array 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. + maxItems: 2000 + description: Directories that expose capabilities to the agent. required: - - environment + - type + - environment_id + - workspace_directory + - capability_directories 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: + AutomationEnvironmentResource: + description: Environment selection saved before an invocation creates its session. + discriminator: + propertyName: type + mapping: + 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/AutomationEnvironmentResourceNone' + - $ref: '#/components/schemas/AutomationEnvironmentResourceOpenaiHosted' + - $ref: '#/components/schemas/AutomationEnvironmentResourceSelfHosted' + InputContentResourceInputText: type: object properties: - object: + type: type: string enum: - - agent.environment.file - default: agent.environment.file + - input_text + default: input_text 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: + description: The type of the object. Always `input_text`. + text: 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. + description: The text supplied to the agent. required: - - object - - data - - next - - has_more + - type + - text 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: + description: Text input recorded in a session item. + InputContentResourceInputImage: type: object properties: type: type: string enum: - - output_text - default: output_text + - input_image + default: input_image x-stainless-const: true - description: The content type. Always `output_text`. - text: + description: The type of the object. Always `input_image`. + image_url: type: string minLength: 0 - description: The text produced by the agent. + description: The URL of the image supplied to the agent, which may be a base64-encoded data URL. required: - type - - text + - image_url additionalProperties: false - description: A text content part produced by the agent. - EncryptedContentResource: + description: Image input recorded in a session item. + InputContentResource: + description: User-provided content recorded in a session item. + discriminator: + propertyName: type + mapping: + input_text: '#/components/schemas/InputContentResourceInputText' + input_image: '#/components/schemas/InputContentResourceInputImage' + x-oai-discriminator-values: + - input_text + - input_image + anyOf: + - $ref: '#/components/schemas/InputContentResourceInputText' + - $ref: '#/components/schemas/InputContentResourceInputImage' + InputMessageResource-2: type: object properties: type: type: string enum: - - encrypted_content - default: encrypted_content + - message + default: message x-stainless-const: true - description: The content type. Always `encrypted_content`. - encrypted_content: + description: The type of the input item. Always `message`. + role: type: string - minLength: 0 - description: The encrypted content payload. + 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 - - encrypted_content + - role + - content additionalProperties: false - description: Encrypted content exchanged between agents. - AgentContentResource: - description: A plaintext or encrypted content part exchanged between agents. - discriminator: - propertyName: type - mapping: - output_text: '#/components/schemas/OutputTextResource' - encrypted_content: '#/components/schemas/EncryptedContentResource' - x-oai-discriminator-values: - - output_text - - encrypted_content - 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: + description: A user message recorded in a session. + AutomationTargetResourceNewSession: type: object properties: - 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: type: string - minLength: 0 - description: The ID of the session that owns the subagent. - name: + 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: - type: - type: string - 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 to the agent, which may be a base64-encoded data URL. + error: + $ref: '#/components/schemas/ErrorBodyResource' + description: The error returned by the API. required: - - type - - image_url + - error additionalProperties: false - description: Image input recorded in a session item. - InputContentResource: - description: User-provided content recorded in a session item. - discriminator: - propertyName: type - mapping: - input_text: '#/components/schemas/InputContentResourceInputText' - input_image: '#/components/schemas/InputContentResourceInputImage' - 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. - anyOf: - - type: string - minLength: 0 - - type: array - items: - $ref: '#/components/schemas/InputContentResource' - minItems: 0 - maxItems: 2000 - FunctionCallOutputItemResource: + 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: - 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: + effort: anyOf: - - $ref: '#/components/schemas/FunctionCallOutputResource' + - $ref: '#/components/schemas/ReasoningEffortParam' - type: 'null' - description: The function result, if the call succeeded. - error: - type: - - string - - 'null' - minLength: 0 - description: The error message, if the call failed. - required: - - id - - turn_id - - type - - call_id - - status - - output - - error + 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: The result supplied for a function call. - AgentMessageItemResource: + description: Reasoning configuration for the agent. + TextFormatParamText: 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 + - text + default: text x-stainless-const: true - 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: - $ref: '#/components/schemas/AgentContentResource' - minItems: 0 - maxItems: 2000 - description: The content exchanged between the agents. + description: The type of the object. Always `text`. required: - - id - - turn_id - type - - sender_agent_id - - recipient_agent_id - - content additionalProperties: false - description: A message exchanged between agent threads. - McpCallItemResource: + description: Generates ordinary text without a structured-output constraint. + TextFormatParamJsonSchema: type: object properties: type: type: string enum: - - mcp_call - default: mcp_call + - json_schema + default: json_schema 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: + 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 + - schema + additionalProperties: false + description: Constrains generated text to a JSON Schema. + TextFormatParam: + description: The output format for generated text. + discriminator: + propertyName: type + mapping: + text: '#/components/schemas/TextFormatParamText' + json_schema: '#/components/schemas/TextFormatParamJsonSchema' + x-oai-discriminator-values: + - text + - json_schema + anyOf: + - $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: + format: anyOf: - - {} + - $ref: '#/components/schemas/TextFormatParam' - type: 'null' - description: The output returned by the MCP tool, if any. - error: + description: 'The output format. Omission uses ordinary text (`{"type": "text"}`).' + verbosity: anyOf: - - {} + - $ref: '#/components/schemas/VerbosityParam' - type: 'null' - description: The error returned by the MCP tool, if any. + 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: - - type - - id - - turn_id - - server_label - - name - - arguments - - status - - output - - error + - enabled additionalProperties: false - description: A call to a tool on an MCP server. - ComputerScreenshotResource: + description: Explicit configuration for creating and coordinating subagents. + x-openai-go-legacy-bool-fields: + - enabled + AgentToolConfigParamFunction: type: object properties: type: type: string enum: - - computer_screenshot - default: computer_screenshot + - function + default: function x-stainless-const: true - description: The content type. Always `computer_screenshot`. - image_url: + description: The type of the object. Always `function`. + name: type: string minLength: 0 - description: The complete JPEG image as a base64 data URL. + 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 - - image_url + - name + - description + - parameters additionalProperties: false - description: A browser screenshot emitted by the model during computer use. - ComputerUseCallItemResource: + description: A function defined by the application. + AgentToolConfigParamToolSearch: type: object properties: type: type: string enum: - - computer_use_call - default: computer_use_call + - tool_search + default: tool_search 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: - type: string - minLength: 0 - description: The ID of the turn that contains this item. - title: - 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. + description: The type of the object. Always `tool_search`. required: - type - - id - - turn_id - - title - - status - - output additionalProperties: false - description: One execution of the platform-provided computer-use capability. - BrowserAuthenticationFieldResource: + description: Discovers deferred function tools and loads them into the model context. + AgentToolConfigParamProgrammaticToolCalling: 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: + 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 this control requires a nonempty value. + default: true + description: Whether tools can be called from model-generated code. Defaults to `true`. required: - - id - - label - type - - required additionalProperties: false - description: A control in a registered browser-login form. - BrowserAuthenticationOptionResource: + description: Enables calling tools from model-generated code. + McpTransportConfigParamHttp: type: object properties: - id: + type: type: string - minLength: 0 - description: The option ID to submit as selected_option. - label: + enum: + - http + default: http + x-stainless-const: true + description: The type of the object. Always `http`. + server_url: type: string minLength: 0 - description: The method label to display. - field_ids: - type: array - items: + 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' + additionalProperties: type: string minLength: 0 - minItems: 0 - maxItems: 2000 - description: IDs from the registered fields that this method accepts. + maxLength: 1048576 + propertyNames: + type: string + minLength: 1 + maxLength: 256 + minProperties: 0 + maxProperties: 1024 + description: Additional HTTP headers sent to the MCP server. required: - - id - - label - - field_ids + - type + - server_url additionalProperties: false - description: A sign-in method and the fields that belong to it. - BrowserAuthenticationHistoryRequestKindResourceBrowserAuthentication: + description: Connects to an MCP server over HTTP. + McpTransportConfigParamStdio: type: object properties: type: type: string enum: - - browser_authentication - default: browser_authentication + - stdio + default: stdio x-stainless-const: true - description: The type of the object. Always `browser_authentication`. - reason: - type: - - string - - 'null' + description: The type of the object. Always `stdio`. + command: + type: string minLength: 0 - description: Why the agent needs the user to sign in. - credential_origin: + maxLength: 1048576 + description: The command used to start the MCP server. + args: 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' + type: string + minLength: 0 + maxLength: 1048576 minItems: 0 - maxItems: 2000 - description: Controls to render. All submitted values are sensitive. - options: - type: array + maxItems: 16384 + 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' 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: type: string - minLength: 0 - request_id: + enum: + - mcp + default: mcp + x-stainless-const: true + description: The type of the object. Always `mcp`. + server_label: type: string minLength: 0 - request: - $ref: '#/components/schemas/BrowserAuthenticationHistoryRequestKindResource' - id: - type: string + maxLength: 1048576 + description: A label used to identify the MCP server in tool calls. + credential_id: + type: + - string + - 'null' 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. + 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: - type: string - minLength: 0 - description: The ID of the tool call item. - turn_id: + description: The type of the object. Always `inline`. + data: 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: + maxLength: 6990508 + description: The standard-base64-encoded file contents. + path: type: string - minLength: 0 - description: The ID of the agent that requested the subagent. - content: - type: array - items: - $ref: '#/components/schemas/AgentContentResource' - minItems: 0 - maxItems: 2000 - description: The task given to the spawned agent. - model: - type: - - string - - 'null' - minLength: 0 - description: The model requested for the spawned agent. - reasoning_effort: - type: - - string - - 'null' - minLength: 0 - description: The reasoning effort requested for the spawned agent. + minLength: 1 + maxLength: 4096 + description: The absolute destination path inside `/workspace`. required: - type - - id - - turn_id - - status - - agent_id - - content - - model - - reasoning_effort + - data + - path additionalProperties: false - description: A request to spawn a subagent. - SendSubagentInputCallItemResource: + 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 enum: - - send_subagent_input_call - default: send_subagent_input_call + - openai_hosted + default: openai_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: + 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: + 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_id: type: string - minLength: 0 - description: The ID of the agent sending the input. - recipient_agent_id: + 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 ID of the agent receiving the input. - content: - type: array - items: - $ref: '#/components/schemas/AgentContentResource' - minItems: 0 - maxItems: 2000 - description: The input sent to the receiving 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 - - sender_agent_id - - recipient_agent_id - - content additionalProperties: false - description: A request to send input to another agent. - ResumeSubagentCallItemResource: + 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: - - resume_subagent_call - default: resume_subagent_call + - self_hosted + default: self_hosted 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 `self_hosted`. + 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. + workspace_directory: type: string minLength: 0 - description: The ID of the agent to resume. + maxLength: 1048576 + description: Absolute project directory inside the self-hosted environment. required: - type - - id - - turn_id - - status - - sender_agent_id - - recipient_agent_id + - workspace_directory additionalProperties: false - description: A request to resume a subagent. - WaitForSubagentsCallItemResource: + 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: - - wait_for_subagents_call - default: wait_for_subagents_call + - input_text + default: input_text 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: - 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 `input_text`. + text: 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. + maxLength: 1048576 + description: The text sent to the model. required: - type - - id - - turn_id - - status - - sender_agent_id - - recipient_agent_ids + - text additionalProperties: false - description: A request to wait for one or more subagents. - CloseSubagentCallItemResource: + description: Text input to the model. + InputContentParamInputImage: type: object properties: type: type: string enum: - - close_subagent_call - default: close_subagent_call + - input_image + default: input_image x-stainless-const: true - x-enumDescriptions: - - The current public item type. - description: The item type. Always `close_subagent_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: - type: string - minLength: 0 - description: The ID of the agent requesting the close. - recipient_agent_id: - type: string - minLength: 0 - description: The ID of the agent to close. + maxLength: 1048576 + description: The URL of the image sent to the model. required: - type - - id - - turn_id - - status - - sender_agent_id - - recipient_agent_id + - image_url additionalProperties: false - description: A request to close a subagent. - SessionTurnItemResource: - description: An item associated with a session turn. + description: Image input to the model. + InputContentParam: + description: Content included in an input message. 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' + input_text: '#/components/schemas/InputContentParamInputText' + input_image: '#/components/schemas/InputContentParamInputImage' 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 + - input_text + - input_image 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/InputContentParamInputText' + - $ref: '#/components/schemas/InputContentParamInputImage' + InputMessageParam: type: object properties: - object: + type: type: string enum: - - list - default: list + - message + default: message x-stainless-const: true - description: The object type, which is always `list`. - data: + 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/SessionTurnItemResource' + $ref: '#/components/schemas/InputContentParam' minItems: 0 - maxItems: 2000 - description: The resources returned in this page, in the requested sort order. - first_id: + 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 + 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: - - string + - array - 'null' - minLength: 0 - description: The ID of the first resource in `data`, or `null` if the page is empty. - last_id: + items: + type: string + minLength: 0 + maxLength: 1048576 + minItems: 0 + maxItems: 16384 + description: The IDs of vaults made available to each new session. + metadata: type: - - string + - object - '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. + 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: - - object - - data - - first_id - - last_id - - has_more + - type + - environment + - input 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: + description: Create a session for each invocation. + AutomationTargetParamExistingSession: type: object properties: - code: - $ref: '#/components/schemas/SessionTurnErrorCodeResource' - description: A stable, machine-readable failure category. - message: + type: + type: string + enum: + - existing_session + default: existing_session + x-stainless-const: true + description: The type of the object. Always `existing_session`. + session_id: type: string minLength: 0 - description: A customer-safe explanation of the failure. + maxLength: 1048576 + description: The session receiving each invocation. + instructions: + type: string + minLength: 0 + maxLength: 1048576 + description: Instructions delivered as an automation notification. required: - - code - - message + - type + - session_id + - instructions additionalProperties: false - description: A customer-safe error describing why a session request failed. - InputTokensDetailsResource-2: + 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: - cached_tokens: - type: integer - format: int64 - description: The number of input tokens retrieved from the prompt cache. + type: + type: string + enum: + - periodic + default: periodic + x-stainless-const: true + description: The type of the object. Always `periodic`. + 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' + 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: - - cached_tokens + - type + - name + - target + - expression + - timezone additionalProperties: false - description: A breakdown of input token usage for a session or turn. - OutputTokensDetailsResource-2: + CreateAutomationParamsOnce: type: object properties: - reasoning_tokens: + 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: The number of output tokens used for reasoning. + description: A future Unix timestamp in seconds. required: - - reasoning_tokens + - type + - name + - target + - run_at additionalProperties: false - description: A breakdown of output token usage for a session or turn. - TokenUsageResource: + CreateAutomationParams: + description: Creates an automation without invoking it immediately. + discriminator: + propertyName: type + mapping: + periodic: '#/components/schemas/CreateAutomationParamsPeriodic' + once: '#/components/schemas/CreateAutomationParamsOnce' + x-oai-discriminator-values: + - periodic + - once + anyOf: + - $ref: '#/components/schemas/CreateAutomationParamsPeriodic' + - $ref: '#/components/schemas/CreateAutomationParamsOnce' + UpdateAutomationParams: 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: + 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: 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 + description: A future Unix timestamp in seconds; accepted only before a one-time scheduled invocation exists. additionalProperties: false - description: Recorded token usage for a session or turn. Usage is best effort and may change. - TurnResource: + description: Updates configuration; timing fields must match the stored automation type. + DeletedAutomationResource: type: object properties: id: type: string minLength: 0 - description: The ID of the turn. + description: The deleted automation ID. object: - $ref: '#/components/schemas/TurnObjectResource' - description: The object type. Always `agent.session.turn`. - session_id: + type: string + enum: + - agent.automation.deleted + default: agent.automation.deleted + x-stainless-const: true + description: Always `agent.automation.deleted`. + deleted: + type: boolean + description: Always true. + required: + - id + - object + - deleted + additionalProperties: false + 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 + - completed + - failed + - skipped + AutomationInvocationErrorResource: + type: object + properties: + code: type: string minLength: 0 - description: The ID of the session that owns the turn. - agent_id: + description: A machine-readable error code. + message: type: string minLength: 0 - description: The ID of the agent that ran the turn. - subagent_id: - type: - - string - - 'null' + description: A public explanation of the delivery failure. + required: + - code + - message + additionalProperties: false + AutomationInvocationResource: + type: object + properties: + id: + type: string 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 invocation ID. + object: + type: string + 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 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: - type: string - minLength: 0 - maxLength: 1048576 - description: The name of the function. - description: + description: The type of the object. Always `input_text`. + text: 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`. + description: The text supplied by the user. required: - type - - name - - description - - parameters + - text additionalProperties: false - description: A function defined by the application. - PersistedAgentToolConfigParamToolSearch: + description: Text supplied by the user. + MessageContentResourceInputImage: type: object properties: type: type: string enum: - - tool_search - default: tool_search + - input_image + default: input_image x-stainless-const: true - description: The type of the object. Always `tool_search`. - required: + 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 + - image_url additionalProperties: false - description: Discovers deferred function tools and loads them into the model context. - PersistedAgentToolConfigParamProgrammaticToolCalling: + description: An image supplied by the user. + MessageContentResourceOutputText: type: object properties: type: type: string enum: - - programmatic_tool_calling - default: programmatic_tool_calling + - output_text + default: output_text 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 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: Enables calling tools from model-generated code. - PersistedMcpTransportConfigParamHttp: + 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: - - http - default: http + - message + default: message 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: + description: The item type. Always `message`. + id: type: - - object + - string - '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. + 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 - - server_url + - id + - turn_id + - role + - content + - status + - phase additionalProperties: false - description: Connects to an MCP server over HTTP. - PersistedMcpTransportConfigParamStdio: + description: A user or assistant message recorded in a session. + SummaryTextResource: type: object properties: type: type: string enum: - - stdio - default: stdio + - summary_text + default: summary_text x-stainless-const: true - 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' - items: - type: string - minLength: 0 - maxLength: 1048576 - minItems: 0 - maxItems: 16384 - description: Arguments passed to the MCP server command. - cwd: + description: The content type. Always `summary_text`. + text: type: string minLength: 0 - maxLength: 1048576 - 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. + description: The reasoning summary text. required: - type - - command - - cwd + - text 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: - 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. - PersistedAgentToolConfigParamMcp: + description: A reasoning summary content part. + ReasoningItemResource: type: object properties: type: type: string enum: - - mcp - default: mcp + - reasoning + default: reasoning x-stainless-const: true - description: The type of the object. Always `mcp`. - server_label: + description: The item type. Always `reasoning`. + 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 reasoning 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' + 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: 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: + maxItems: 2000 + description: The reasoning summaries produced by the agent. + status: anyOf: - - $ref: '#/components/schemas/McpConnectionOriginParam' + - $ref: '#/components/schemas/OutputItemStatusResource' - type: 'null' - description: Selects where outbound MCP HTTP connections originate. + description: The status of the reasoning item. required: - type - - server_label - - transport + - id + - turn_id + - summary + - status additionalProperties: false - description: Tools provided by a remote MCP server without stored credentials. - WebSearchModeParam: + description: A reasoning item produced by the agent. + FunctionCallStatusResource: type: string enum: - - disabled - - cached - - live + - in_progress + - completed + - failed + - incomplete 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: + - 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: - country: - type: - - string - - 'null' + type: + type: string + enum: + - function_call + default: function_call + x-stainless-const: true + description: The item type. Always `function_call`. + 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 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. + call_id: + type: string minLength: 0 - maxLength: 1048576 - description: The city name. - timezone: - type: - - string - - 'null' + description: The ID used to submit the function result. + name: + type: string minLength: 0 - maxLength: 1048576 - description: The IANA timezone, such as `America/Los_Angeles`. + 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 + - id + - turn_id + - call_id + - name + - arguments + - status additionalProperties: false - description: Approximate user location used to localize web search results. - PersistedAgentToolConfigParamWebSearch: + 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: + 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: - - web_search - default: web_search + - function_call_output + default: function_call_output 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: + 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: anyOf: - - $ref: '#/components/schemas/WebSearchContextSizeParam' + - $ref: '#/components/schemas/FunctionCallOutputResource' - type: 'null' - description: The amount of search context made available to the model. Defaults to `medium`. - allowed_domains: + description: The function result, if the call succeeded. + error: type: - - array + - string - '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. + minLength: 0 + description: The error message, if the call failed. required: + - id + - turn_id - type + - call_id + - status + - output + - error additionalProperties: false - description: Web search. - PersistedAgentToolConfigParamComputerUse: + 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: - - computer_use - default: computer_use + - agent_message + default: agent_message 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`. + 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: + $ref: '#/components/schemas/AgentContentResource' + minItems: 0 + maxItems: 2000 + description: The content exchanged between the agents. required: + - id + - turn_id - type + - sender_agent_id + - recipient_agent_id + - content 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: + description: A message exchanged between agent threads. + McpCallItemResource: 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' + type: + type: string + enum: + - mcp_call + default: mcp_call + x-stainless-const: true + 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. + description: The search query, when a single query was used. + queries: + type: + - array + - 'null' + items: + type: string + minLength: 0 + minItems: 0 + maxItems: 2000 + description: The search queries, when multiple queries were used. required: - type - - path - - size_bytes + - query + - queries 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: + description: A search query or group of search queries. + WebSearchActionResourceOpenPage: type: object properties: - id: - type: string - minLength: 0 - description: The ID of the reusable environment template. - name: - type: - - string - - '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. - required: - - id - - name - - object - - created_at - - updated_at - - packages - - network - - capability_directories - - skills - - plugins - - files - additionalProperties: false - description: Reusable configuration that provisions a fresh OpenAI-hosted environment for each session. - EnvironmentTemplateListResource: - 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: + 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: - - 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. + minLength: 0 + description: The ID of the agent requesting the interrupt. + recipient_agent_id: + type: string + minLength: 0 + description: The ID of the agent to interrupt. required: - type - - enabled + - id + - turn_id + - status + - sender_agent_id + - recipient_agent_id additionalProperties: false - description: Enables calling tools from model-generated code. - McpTransportResourceHttp: + description: A request to interrupt a subagent's current turn. The subagent remains available. + CreateSubagentCallItemResource: type: object properties: type: type: string enum: - - http - default: http + - create_subagent_call + default: create_subagent_call x-stainless-const: true - description: The type of the object. Always `http`. - server_url: + x-enumDescriptions: + - The current public item type. + description: The item type. Always `create_subagent_call`. + id: type: string minLength: 0 - description: The URL of the MCP server. + 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. + agent_id: + type: string + minLength: 0 + description: The ID of the agent that requested the subagent. + content: + type: array + items: + $ref: '#/components/schemas/AgentContentResource' + minItems: 0 + maxItems: 2000 + description: The task given to the spawned agent. + model: + type: + - string + - 'null' + minLength: 0 + description: The model requested for the spawned agent. + reasoning_effort: + type: + - string + - 'null' + minLength: 0 + description: The reasoning effort requested for the spawned agent. required: - type - - server_url + - id + - turn_id + - status + - agent_id + - content + - model + - reasoning_effort additionalProperties: false - description: Connects to an MCP server over HTTP. - McpTransportResourceStdio: + description: A request to spawn a subagent. + SendSubagentInputCallItemResource: type: object properties: type: type: string enum: - - stdio - default: stdio + - send_subagent_input_call + default: send_subagent_input_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 `send_subagent_input_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. + 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: Environment variable names inherited from the execution environment. + description: The input sent to the receiving agent. required: - type - - command - - args - - cwd - - env_vars + - id + - turn_id + - status + - sender_agent_id + - recipient_agent_id + - content 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: + description: A request to send input to another agent. + ResumeSubagentCallItemResource: type: object properties: type: type: string enum: - - mcp - default: mcp + - resume_subagent_call + default: resume_subagent_call x-stainless-const: true - description: The type of the object. Always `mcp`. - server_label: + x-enumDescriptions: + - The current public item type. + description: The item type. Always `resume_subagent_call`. + id: type: string minLength: 0 - description: A label used to identify the MCP server in tool calls. - credential_id: - type: - - string - - 'null' + description: The ID of the tool call item. + turn_id: + type: string 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: - type: - - array - - '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. + 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: + type: string + minLength: 0 + description: The ID of the agent to resume. required: - type - - server_label - - credential_id - - transport - - request_metadata - - allowed_tools - - required - - connection_origin + - id + - turn_id + - status + - sender_agent_id + - recipient_agent_id additionalProperties: false - description: Tools provided by a remote MCP server. - AgentToolResourceWebSearch: + description: A request to resume a subagent. + WaitForSubagentsCallItemResource: type: object properties: type: type: string enum: - - web_search - default: web_search + - wait_for_subagents_call + default: wait_for_subagents_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 `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: 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 IDs of the agents to wait for. required: - type - - mode - - context_size - - allowed_domains - - location + - id + - turn_id + - status + - sender_agent_id + - recipient_agent_ids additionalProperties: false - description: Web search. - AgentToolResourceComputerUse: + description: A request to wait for one or more subagents. + CloseSubagentCallItemResource: type: object properties: type: type: string enum: - - computer_use - default: computer_use + - close_subagent_call + default: close_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. + x-enumDescriptions: + - The current public item type. + description: The item type. Always `close_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 close. + recipient_agent_id: + type: string + minLength: 0 + description: The ID of the agent to close. required: - type - - include_screenshots + - id + - turn_id + - status + - sender_agent_id + - recipient_agent_id additionalProperties: false - description: Browser use in an OpenAI-hosted session. - AgentToolResource: - description: A tool available to the agent. + description: A request to close a subagent. + SessionTurnItemResource: + description: An item associated with a session turn. 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' + 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: - - function - - programmatic_tool_calling - - mcp - - web_search - - computer_use + - 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/AgentToolResourceFunction' - - $ref: '#/components/schemas/AgentToolResourceProgrammaticToolCalling' - - $ref: '#/components/schemas/AgentToolResourceMcp' - - $ref: '#/components/schemas/AgentToolResourceWebSearch' - - $ref: '#/components/schemas/AgentToolResourceComputerUse' - SessionAgentResource: + - $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: - id: + 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/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 agent. - name: + 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 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 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: 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 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: - - id - - name - - model - - reasoning - - text - - service_tier - - instructions - - tools - - multi_agent + - object + - data + - first_id + - last_id + - has_more additionalProperties: false - description: The effective agent configuration for a session. - EnvironmentResourceNone: + 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: - type: + code: + $ref: '#/components/schemas/SessionTurnErrorCodeResource' + description: A stable, machine-readable failure category. + message: type: string - enum: - - none - default: none - x-stainless-const: true - description: The type of the object. Always `none`. + minLength: 0 + description: A customer-safe explanation of the failure. required: - - type + - code + - message 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 customer-safe error describing why a session request failed. + InputTokensDetailsResource-2: type: object properties: - type: - type: string - enum: - - openai_hosted - default: openai_hosted - x-stainless-const: true - description: The type of the object. Always `openai_hosted`. - 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. + cached_tokens: + type: integer + format: int64 + description: The number of input tokens retrieved from the prompt cache. required: - - type - - id - - packages - - network - - capability_directories - - skills - - plugins - - files + - cached_tokens additionalProperties: false - description: An environment hosted by OpenAI. - EnvironmentResourceSelfHosted: + description: A breakdown of input token usage for a session or turn. + OutputTokensDetailsResource-2: 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: - type: string - minLength: 0 - description: Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - id: - type: string - minLength: 0 - description: The public ID of the environment. - workspace_directory: - 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. + reasoning_tokens: + type: integer + format: int64 + description: The number of output tokens used for reasoning. required: - - type - - remote_url - - id - - workspace_directory - - capability_directories + - reasoning_tokens additionalProperties: false - 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: + 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: - 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. + description: The ID of the turn. object: + $ref: '#/components/schemas/TurnObjectResource' + description: The object type. Always `agent.session.turn`. + session_id: type: string - enum: - - agent.session - default: agent.session - x-stainless-const: true - description: The object type. Always `agent.session`. + 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, when the session was created. - last_active_at: - type: integer + 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 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. + description: The Unix timestamp, in seconds, when the turn started. + completed_at: type: - - string + - integer - '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. + 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: @@ -87783,7 +89132,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. @@ -87810,22 +89159,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: @@ -87838,35 +89172,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: @@ -87880,7 +89210,7 @@ components: - type additionalProperties: false description: Discovers deferred function tools and loads them into the model context. - AgentToolConfigParamProgrammaticToolCalling: + PersistedAgentToolResourceProgrammaticToolCalling: type: object properties: type: @@ -87892,13 +89222,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: @@ -87911,36 +89241,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: @@ -87953,70 +89271,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. - discriminator: + 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: @@ -88029,29 +89326,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: @@ -88060,26 +89351,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: @@ -88090,14 +89382,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: @@ -88106,20 +89394,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: @@ -88131,23 +89422,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 @@ -88155,117 +89461,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' @@ -88279,101 +89695,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' @@ -88383,134 +89726,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 @@ -88526,602 +89943,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: - 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: + model: type: string minLength: 0 - description: The unique ID of the event. - session_id: - type: string + 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 - description: The ID of the session associated with the event. - turn_id: + 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 - description: The ID of the turn associated with the event, when applicable. - item_id: + 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 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: + description: The ID of the deleted agent. + object: type: string - minLength: 0 - description: The complete reasoning summary text. + 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: - - type - - event_id - - session_id - - turn_id - - item_id - - output_index - - summary_index - - text + - id + - object + - deleted additionalProperties: false - description: Emitted when a reasoning summary content part is complete. - SessionErrorResource: + description: A deleted reusable agent. + EnvironmentTemplateResource: type: object properties: - type: + id: type: string minLength: 0 - description: The error type. - code: + description: The ID of the reusable environment template. + name: type: - string - 'null' minLength: 0 - description: The machine-readable error code, if any. - message: + description: An optional human-readable display name for the template. + object: type: string - minLength: 0 - description: A customer-safe explanation of the error. - param: - type: - - string - - 'null' - minLength: 0 - description: The request parameter associated with the error, if any. + 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. required: - - type - - code - - message - - param + - id + - name + - object + - created_at + - updated_at + - packages + - network + - capability_directories + - skills + - plugins + - files additionalProperties: false - description: An error payload with the same public fields as Responses API streaming errors. - SessionEventError: + description: Reusable configuration that provisions a fresh OpenAI-hosted environment for each session. + EnvironmentTemplateListResource: type: object properties: - type: + object: type: string enum: - - error - default: error + - list + default: list x-stainless-const: true - description: The type of the object. Always `error`. - event_id: - type: string + 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 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. - error: - $ref: '#/components/schemas/SessionErrorResource' - description: The error that occurred. + 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 - - event_id - - session_id - - error + - object + - data + - first_id + - last_id + - has_more 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: A page of Agents API resources, with IDs for retrieving additional pages. + CreateEnvironmentTemplateParams: 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 + 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: An error reported while preparing a session environment. - SessionEnvironmentStateResource: + description: Parameters for creating a reusable, project-scoped OpenAI-hosted environment template. + UpdateEnvironmentTemplateParams: + type: object + properties: + 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: 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. - required: - - type - - event_id - - session_id - - turn_id - - item_id - - output_index - - delta + 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: + - 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 @@ -89131,36 +91006,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 @@ -89175,128 +91066,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 @@ -89321,17 +91329,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 @@ -89356,17 +91364,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 @@ -89391,17 +91399,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 @@ -89415,196 +91423,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 @@ -89614,39 +91565,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 @@ -89656,51 +91598,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 @@ -89710,51 +91637,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 @@ -89764,52 +91676,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 @@ -89824,47 +91720,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 @@ -89879,46 +91856,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 @@ -89933,56 +91891,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 @@ -89997,454 +91961,916 @@ 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 - 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: - 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 + - environment additionalProperties: false - description: Reasoning effort for subsequent turns. The reasoning summary stays unchanged. - UpdateSessionAgentParam: + description: Emitted when a session environment fails. + SessionEventAgentSessionSubagentCreated: type: object properties: - model: + 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 - 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 + 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: Model settings that can change after session creation. - UpdateAgentSessionParams: + description: Emitted when a subagent is created. + SessionEventAgentSessionSubagentActive: 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.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: Fields to update on an existing session. - DeletedSessionResource: + description: Emitted when a closed subagent successfully resumes. + SessionEventAgentSessionSubagentClosed: + type: object + properties: + 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: 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 - 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: + description: Emitted when an output text content part is complete. + SessionEventAgentSessionTurnReasoningSummaryPartAdded: type: object properties: type: type: string enum: - - browser_origin_access - default: browser_origin_access + - agent.session.turn.reasoning_summary_part.added + default: agent.session.turn.reasoning_summary_part.added x-stainless-const: true - decision: - $ref: '#/components/schemas/BrowserOriginAccessDecisionParam' - description: Whether to allow, deny, or cancel the requested origin access. - required: - - type - - decision - additionalProperties: false + 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: + type: string + enum: + - browser_origin_access + default: browser_origin_access + x-stainless-const: true + decision: + $ref: '#/components/schemas/BrowserOriginAccessDecisionParam' + description: Whether to allow, deny, or cancel the requested origin access. + required: + - type + - decision + additionalProperties: false ComputerUseApprovalResponseParam: x-oai-discriminator-values: - browser_authentication @@ -92163,6 +94589,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 @@ -92193,18 +94689,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: @@ -92259,6 +94755,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 @@ -92557,6 +95085,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: @@ -92736,6 +95447,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 @@ -92755,8 +95468,6 @@ components: type: string enum: - active - triggers: - $ref: '#/components/schemas/LiveSessionCreateParams/properties/triggers' required: - model - id @@ -93365,6 +96076,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: @@ -93604,6 +96548,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: @@ -96232,6 +99179,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 @@ -98083,6 +101036,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 @@ -99620,6 +102579,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: @@ -103258,6 +106220,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 @@ -106630,6 +109593,7 @@ components: - $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' @@ -106667,954 +109631,74 @@ components: - $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: + SessionSpendControlResource: 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' + 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: - - type - - event_type - - decisions + - limit + - consumed 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: + description: Session-wide spending control, present only when a limit is configured. + SessionSpendControlParam: 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 + limit: + type: + - integer + - 'null' + format: int64 + minimum: 1 + maximum: 4503599627370495 + description: Positive USD cents, or null to remove the limit. required: - - questions - - model - LiveDecisionsDelegationParam-2: + - limit + additionalProperties: false + description: Sets the session-wide limit without changing recorded spend. + DecisionPromptCacheBreakpoint: type: object properties: - type: - default: decisions - x-stainless-const: true + mode: 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 + - explicit + default: explicit 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' + description: The breakpoint mode. Always `explicit`. required: - - type - - event_type - - decisions + - mode 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: + 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. + OAuthErrorCode: + anyOf: + - enum: + - invalid_grant + - invalid_subject_token + - type: string + AutomationMetadataParam: 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 - 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 - 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 - 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 - DecisionPromptCacheBreakpoint: - type: object - properties: - mode: - type: string - enum: - - explicit - default: explicit - x-stainless-const: true - description: The breakpoint mode. Always `explicit`. - required: - - mode - 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. - DecisionInputJson: - type: object - properties: - type: - type: string - enum: - - input_json - default: input_json - x-stainless-const: true - data: - anyOf: - - type: object - additionalProperties: - anyOf: - - {} - - type: 'null' - propertyNames: - type: string - minLength: 0 - minProperties: 0 - - type: array - items: - type: object - additionalProperties: - anyOf: - - {} - - type: 'null' - propertyNames: - type: string - minLength: 0 - minProperties: 0 - minItems: 0 - required: - - type - - data - additionalProperties: false - description: A JSON object or an array of objects rendered as text. Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON. - DecisionQuestionInputPart: - description: A text, image, or JSON content part in a question instruction. - discriminator: - propertyName: type - mapping: - input_text: '#/components/schemas/DecisionQuestionInputText' - input_image: '#/components/schemas/DecisionQuestionInputImage' - input_json: '#/components/schemas/DecisionInputJson' - x-oai-discriminator-values: - - input_text - - input_image - - input_json - anyOf: - - $ref: '#/components/schemas/DecisionQuestionInputText' - - $ref: '#/components/schemas/DecisionQuestionInputImage' - - $ref: '#/components/schemas/DecisionInputJson' - DecisionQuestionInputText: - type: object - properties: - type: - type: string - enum: - - input_text - default: input_text - x-stainless-const: true - text: - type: string - minLength: 0 - maxLength: 10485760 - required: - - type - - text - additionalProperties: false - DecisionQuestionInputImage: - type: object - properties: - image_url: - type: string - minLength: 0 - maxLength: 1073741824 - pattern: ^(data:|https?://) - description: A base64-encoded image in a data URL or a publicly accessible HTTP(S) image URL. - detail: - anyOf: - - $ref: '#/components/schemas/ImageDetailParam' - - type: 'null' - description: The image detail level, using the selected model's image profile. Defaults to auto. - default: auto - type: - type: string - enum: - - input_image - default: input_image - x-stainless-const: true - required: - - image_url - - type - additionalProperties: false - description: An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported. - DecisionInputUserMessage: - type: object - properties: - role: - type: string - enum: - - user - default: user - x-stainless-const: true - content: - $ref: '#/components/schemas/DecisionInputContent' - type: - type: string - enum: - - message - default: message - x-stainless-const: true - required: - - role - - content - additionalProperties: false - description: A user message containing input text, images, or JSON. - DecisionInputDeveloperMessage: - type: object - properties: - role: - type: string - enum: - - developer - default: developer - x-stainless-const: true - content: - $ref: '#/components/schemas/DecisionInputDeveloperContent' - type: - type: string - enum: - - message - default: message - x-stainless-const: true - required: - - role - - content - additionalProperties: false - description: A developer message containing input text. - DecisionInputSystemMessage: - type: object - properties: - role: - type: string - enum: - - system - default: system - x-stainless-const: true - content: - $ref: '#/components/schemas/DecisionInputDeveloperContent' - type: - type: string - enum: - - message - default: message - x-stainless-const: true - required: - - role - - content - additionalProperties: false - description: A system message containing input text. - DecisionInputAssistantMessage: - type: object - properties: - role: - type: string - enum: - - assistant - default: assistant - x-stainless-const: true - content: - $ref: '#/components/schemas/DecisionInputAssistantContent' - phase: - anyOf: - - $ref: '#/components/schemas/MessagePhaseParam' - - type: 'null' - description: The phase of an assistant message. - type: - type: string - enum: - - message - default: message - x-stainless-const: true - required: - - role - - content - additionalProperties: false - description: An assistant message containing output text or refusals. - DecisionInputDeveloperContent: - description: A text string or an ordered list of input text parts. - anyOf: - - type: string - minLength: 0 - maxLength: 10485760 - - $ref: '#/components/schemas/DecisionInputDeveloperContentParts' - title: Parts - DecisionInputAssistantContent: - description: A text string or an ordered list of output text and refusal parts. - anyOf: - - type: string + additionalProperties: + type: string minLength: 0 - maxLength: 10485760 - - $ref: '#/components/schemas/DecisionInputAssistantContentParts' - title: Parts - DecisionInputDeveloperContentParts: - type: array - items: - $ref: '#/components/schemas/DecisionInputText' - minItems: 0 - maxItems: 16384 - DecisionInputAssistantContentParts: - type: array - items: - x-oai-discriminator-values: - - output_text - - refusal - discriminator: - propertyName: type - mapping: - output_text: '#/components/schemas/DecisionInputOutputText' - refusal: '#/components/schemas/DecisionInputRefusal' - anyOf: - - $ref: '#/components/schemas/DecisionInputOutputText' - - $ref: '#/components/schemas/DecisionInputRefusal' - minItems: 0 - maxItems: 16384 - OAuthErrorCode: - anyOf: - - enum: - - invalid_grant - - invalid_subject_token - - type: string + maxLength: 512 + propertyNames: + type: string + minLength: 1 + maxLength: 64 + minProperties: 0 + maxProperties: 16 ResponseSteerInputContent: discriminator: propertyName: type diff --git a/scripts/castiron/CUSTOM_CODE.md b/scripts/castiron/CUSTOM_CODE.md index 1809ea4788..50b102fd27 100644 --- a/scripts/castiron/CUSTOM_CODE.md +++ b/scripts/castiron/CUSTOM_CODE.md @@ -122,6 +122,11 @@ Next uses separate `Castiron next / budget-only change` and two tracks cannot overwrite each other's authorization. The policy version is fixed by next's protected base; advancing main does not silently change it. Changing the reviewed pin changes next's own base and rebuilds its merge queue. +Review invalidation reads the effective checker's inert `PIN_REVIEW_POLICY` +capability marker at that exact revision. Legacy or unknown versions retain +human review for every pin edit; only the recognized effective-policy contract +allows non-increasing forward pin changes to use ordinary review. No checker +code is executed by the invalidation handler. The effective policy is read from the selected authenticated main commit. The next base selects that version; a candidate never selects its own executing @@ -210,7 +215,9 @@ base, never the candidate. Pin-only updates and initial pin adoption use ordinar CODEOWNERS and required reviews when the pin does not roll back to an older main checker, the effective pinned budget stays the same or decreases, and its schema, strictness and ratchet mode stay unchanged. Initial adoption compares checker age -with authenticated bootstrap main; later updates compare with the prior pin. A +and effective policy with authenticated bootstrap main, not the unpinned target's +local policy fields; later updates compare with the current protected +target pin and effective policy, even for stale PRs. A checker rollback, an effective pinned-budget increase or mode transition, a local numeric budget increase, or Go ratchet activation still requires an exact-head human approving review from a repository owner, member, or collaborator. Bot reviews, stale reviews and dismissed @@ -277,3 +284,5 @@ handler as their replacement. A failed invalidation or rerun must be investigate missing reporter runs remain pending until the normal trusted run is requested. Install and validate the review signal on the protected target before activating next policy checks, including actual PR and queue revocation after dismissal. + +The trusted selector also checks this exact active-checker contract before granting a pin-only review exemption. Legacy or unrecognized contracts retain the required exact-head review in the selection receipt, so the final publisher revalidates it even without a review-change event. diff --git a/scripts/castiron/custom_code_policy.py b/scripts/castiron/custom_code_policy.py index f4e8ad99bd..59314c434c 100755 --- a/scripts/castiron/custom_code_policy.py +++ b/scripts/castiron/custom_code_policy.py @@ -30,6 +30,8 @@ POLICY = ".castiron-ratchet.json" NEXT_POLICY_VERSION = 1 +# Inert capability marker read by trusted review invalidation at this exact revision. +PIN_REVIEW_POLICY = "effective-policy-v1" SELECTION_RECEIPT_VERSION = 1 @@ -133,6 +135,18 @@ def next_policy_sha(repo: Path, repository: str, base: str, authenticated_main: return cast(str, policy) +def supports_effective_pin_review(repo: Path, revision: str) -> bool: + """Read the effective checker's inert contract; never execute its source.""" + revision = report.require_sha(revision) + path = "scripts/castiron/custom_code_policy.py" + entry = report.git(repo, "ls-tree", revision, "--", path).split() + if len(entry) != 4 or entry[0] not in (b"100644", b"100755") or entry[1] != b"blob": + return False + source = report.git(repo, "show", f"{revision}:{path}") + declarations = re.findall(rb"^PIN_REVIEW_POLICY = .*$", source, re.MULTILINE) + return declarations == [b'PIN_REVIEW_POLICY = "effective-policy-v1"'] + + class HumanReviewRules(TypedDict): version: int associations: list[str] @@ -156,7 +170,7 @@ def has_human_approval(reviews: list[dict[str, Any]], author: str, head: str) -> """Versioned review predicate; publisher consumes these same trusted rules.""" latest: dict[str, dict[str, Any]] = {} for review in reviews: - if review["state"] != "PENDING": + if review["state"] != "PENDING" and review.get("user") is not None: login = review["user"]["login"] if login not in latest or review["id"] > latest[login]["id"]: latest[login] = review @@ -207,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, @@ -272,43 +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) - ) - previous = ( - read_policy( - repo, next_policy_sha(repo, repository, candidate_base, authenticated_main) - ) - if "next_policy" in candidate_base_policy - else candidate_base_policy - ) - # Bootstrap executes authenticated main; initial adoption must not silently - # replace it with older checker code, even when policy fields match. - previous_checker = ( - candidate_base_policy["next_policy"]["main_sha"] - if "next_policy" in candidate_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 = ( - 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 { @@ -497,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) @@ -509,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 dc9106c378..f572c33c2d 100644 --- a/scripts/castiron/fixtures/github_publisher.cjs +++ b/scripts/castiron/fixtures/github_publisher.cjs @@ -8,7 +8,9 @@ const github = { actions: { getWorkflowRun: async ({ run_id }) => { if (data.run_errors?.[run_id]) - throw Object.assign(new Error('Workflow run lookup failed'), { status: data.run_errors[run_id] }); + throw Object.assign(new Error('Workflow run lookup failed'), { + status: data.run_errors[run_id], + }); return { data: data.runs_by_id?.[run_id] || data.run }; }, getWorkflow: async ({ workflow_id }) => ({ @@ -37,8 +39,8 @@ const github = { object: { sha: ref.startsWith('pull/') ? data.merge_sha - : ref === 'heads/main' && data.main_sha - ? data.main_sha + : ref === 'heads/main' && (data.main_sha_sequence?.length || data.main_sha) + ? data.main_sha_sequence?.shift() || data.main_sha : data.current.base.sha, }, }, @@ -46,6 +48,11 @@ const github = { }, repos: { 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 ||= {}; @@ -107,12 +114,34 @@ const github = { throw new Error(`Unexpected GitHub lookup: ${method}`); }, }; +const exec = { + getExecOutput: async (command, args) => { + if ( + command !== 'python3' || + args[0] !== '-I' || + args[1] !== 'scripts/castiron/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'); + } + 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 ?? 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 6e37e91568..8ba5d4c672 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": "2f75276742e4b8b007e29d6ae7bc098a23bd5ef5809ecb328c0e91bf0fb7d9aa" + "sha256": "db521f2e39d1c39ad2edacedc9903954471308e660e6df5b4ba8ca7615e5a5a8" }, ".github/workflows/castiron-custom-code.yml": { "mode": "100644", @@ -11,11 +11,11 @@ }, "api.md": { "mode": "100644", - "sha256": "f58148943cc440a8f82d8b78a88ce875a4826cf9ce68c9c8894af806337cb66e" + "sha256": "b095fd916ad7f8388af0f336a1f5a210eba3ffcba8beb69ef576e8b76abc7773" }, "scripts/castiron/CUSTOM_CODE.md": { "mode": "100644", - "sha256": "c80c8e834f55f3cfbf690f6bffb70d7b0a10317261a407b46686d810e07f6a61" + "sha256": "8464fb28964ae0f7bec38ae7ba8107e97287d4118657a3017a2712e753d4c608" }, "scripts/castiron/README.md": { "mode": "100644", @@ -27,7 +27,7 @@ }, "scripts/castiron/custom_code_policy.py": { "mode": "100755", - "sha256": "f2d21cf2f66b1907ea177930270b6f161951b67af59bc34724f62743d6561a67" + "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": "062eb3da63eb0a25cf8de21e9aa0025afb1322eaf4ae59d5d6b3515b3dabda4b" + "sha256": "3f77c368ed668bb6ddcde1f2e806e3f307d64cb68cc45fe4c4968adfe1f7c0fe" }, "scripts/castiron/ruff.toml": { "mode": "100644", @@ -55,16 +55,20 @@ }, "scripts/castiron/test_custom_code_policy.py": { "mode": "100644", - "sha256": "eb49e1d2f55ea369010c1ea1e074d822de687abf439bdc8b4c2c29e7ce38f4db" + "sha256": "a9b4dcabec71c66e1e280fd54f46f78eea9bc664f8dca500f5da418e27114602" }, "scripts/castiron/test_custom_code_publication.py": { "mode": "100644", - "sha256": "38d723f458225eb2d4745aca4044f6e4283f10b2a9d3a5257349b04ecd1c8c75" + "sha256": "0e7628d6906153029fea156273094a3d0b17846abd0894a91ab0833241bfdf31" }, "scripts/castiron/test_custom_code_report.py": { "mode": "100644", "sha256": "f4d90fd38b17aac59096488391b65ef9da5493d2049d4c038d5926a960257ca7" }, + "scripts/castiron/test_custom_code_review_revocation.py": { + "mode": "100644", + "sha256": "2ad322e7e7b2cbd425f6647edc1cde98d4354b989dfb0b61f326030292e9c460" + }, "src/openai/__init__.py": { "mode": "100644", "sha256": "a410d257a94f2c4f6cd0951a178131e8d883e21a69ef6bea245271db215ba196" @@ -279,7 +283,7 @@ }, "src/openai/resources/audio/voices.py": { "mode": "100644", - "sha256": "85243d3a08489a2bd66c58d317190e867e8441d1ccf9ceebe9adb81e2e3be919" + "sha256": "da2533258e202da4969be1843a50bfcdc0a637dbbc6c75194f96d2e90d955150" }, "src/openai/resources/batches.py": { "mode": "100644", @@ -291,11 +295,23 @@ }, "src/openai/resources/beta/agents/__init__.py": { "mode": "100644", - "sha256": "123c391d0b82ae321cbc1790c1ff2fc9e89eda731833a1298346d0e3f8b231d9" + "sha256": "e569c61815e1ee18c4fc57e7d26b34223ed964a0324bb679e1599985e190bf5a" }, "src/openai/resources/beta/agents/agents.py": { "mode": "100644", - "sha256": "19d76c005be84ce26327df8a3cd5dce4b1865f8642ba66a2c982da8cfe8abb53" + "sha256": "bf71aadeaf938d143a5965256e219237fe4bfc61162f401744c37cb1c9996a50" + }, + "src/openai/resources/beta/agents/automations/__init__.py": { + "mode": "100644", + "sha256": "8ce937ef0abfc7763a31f949b6f8b697a63a538af93eff39beffc3a3da167539" + }, + "src/openai/resources/beta/agents/automations/automations.py": { + "mode": "100644", + "sha256": "12667bf711a724fe02cb5afb5e70247bd13288d13dbc98f3fe4dc63ec67252ef" + }, + "src/openai/resources/beta/agents/automations/invocations.py": { + "mode": "100644", + "sha256": "9244fad74ffce90ef67b7904690ff7289bc1a53889957cfa0f5a2cb9e75b652f" }, "src/openai/resources/beta/agents/environments/__init__.py": { "mode": "100644", @@ -1463,7 +1479,7 @@ }, "src/openai/types/audio/__init__.py": { "mode": "100644", - "sha256": "e468dcb2033e714b0c5bef0275902c9d6621bed5e93e50b44bce1ef0d2eee7ad" + "sha256": "420636426adc04451ff9afa515741a0cdf62a5a03db78c38ace66a5fd192d77f" }, "src/openai/types/audio/speech_create_params.py": { "mode": "100644", @@ -1573,6 +1589,10 @@ "mode": "100644", "sha256": "4ac1fa687ed2615dbcf1a16324b56bb2e85e13d7d901f00b47987defed0e59d3" }, + "src/openai/types/audio/voice_deleted.py": { + "mode": "100644", + "sha256": "27147936aea24eee30b50374421299dc26c656a90ff95c075c0cc62c7897514b" + }, "src/openai/types/audio_model.py": { "mode": "100644", "sha256": "10c4c46d91afc4b2f8d1a5843464bc4cce44d7dbee472978c60999e438a3dd4b" @@ -1903,11 +1923,11 @@ }, "src/openai/types/beta/agent_tool.py": { "mode": "100644", - "sha256": "d22019b34f5df60a33d4195c3aec543ca8f049f6314c803393eea184e587c2b5" + "sha256": "ed568481e6de6956b9deccfbb7cce718bba3cfbab6270851602886141af5230c" }, "src/openai/types/beta/agent_tool_param.py": { "mode": "100644", - "sha256": "aed679880e57a5695c3abd2586f3e8fdc2b65549a6822651b0717bccd68b6ab0" + "sha256": "50116fba12372f68fc831149fafc3896e5b0be3f8f12bc72cc539ead14be34b3" }, "src/openai/types/beta/agent_update_params.py": { "mode": "100644", @@ -1923,7 +1943,67 @@ }, "src/openai/types/beta/agents/__init__.py": { "mode": "100644", - "sha256": "4aa9d94d93b1ad4271b80df290602c399617b7aaca1a6c8900158c5de56c7c19" + "sha256": "b67d5c4e10eb60f3b20cd18df8b715563116130e0bcdc27729524803c1929167" + }, + "src/openai/types/beta/agents/automation.py": { + "mode": "100644", + "sha256": "edcce96fe1c6630a60a3cb7dc37af0d02a0bdf019c463a58747e62434500c6e6" + }, + "src/openai/types/beta/agents/automation_agent_config.py": { + "mode": "100644", + "sha256": "e3c97c93d0db0e76a7d407b62f65c4cf284825494bcf1d0d96653305e994781b" + }, + "src/openai/types/beta/agents/automation_create_params.py": { + "mode": "100644", + "sha256": "5dd8f64b7943d9d1e4ae65df62e10ad909346454c463588b1968e767a4bb6200" + }, + "src/openai/types/beta/agents/automation_created_by.py": { + "mode": "100644", + "sha256": "f23a06548c19fd173be99d8a0da73b22a9c622139a19c0ab6543f2a09ddac913" + }, + "src/openai/types/beta/agents/automation_deleted.py": { + "mode": "100644", + "sha256": "87230b565c9dc45c42e6c0de37ea0766acdecbcdc64cb13f670f2a3622cb1e29" + }, + "src/openai/types/beta/agents/automation_environment.py": { + "mode": "100644", + "sha256": "ebdb84cac2846835eb13aa09aed2845826460965a3b46c355c2751eb089385d3" + }, + "src/openai/types/beta/agents/automation_list_params.py": { + "mode": "100644", + "sha256": "e1ae3f3da0fa9fa4431f5d851b7e6383e253e3100fb1fa2f3fb7fb33297f94ab" + }, + "src/openai/types/beta/agents/automation_metadata_param.py": { + "mode": "100644", + "sha256": "34a8ea39010150e8f4eddf70b9c9c34fbac10a00f8775553dfb4a7ac6a4de405" + }, + "src/openai/types/beta/agents/automation_target.py": { + "mode": "100644", + "sha256": "1297dccb4b8d7e6538aa12ccdf7e2e6cd31c4e1b96d524d843203e1e6b78f75d" + }, + "src/openai/types/beta/agents/automation_target_param.py": { + "mode": "100644", + "sha256": "aad9dcc0ce6817c9ff825e0c718fa046e2f06966e5e77d2fa4d60faa23a389e4" + }, + "src/openai/types/beta/agents/automation_update_params.py": { + "mode": "100644", + "sha256": "35081349926baa822f87855ab84c4417881ff74b178852bb0c6ddea5b21d6728" + }, + "src/openai/types/beta/agents/automations/__init__.py": { + "mode": "100644", + "sha256": "a3996a8766d44ec626412dc575740c4de8e639a912fa3eb1d8ea312797230565" + }, + "src/openai/types/beta/agents/automations/automation_invocation.py": { + "mode": "100644", + "sha256": "e37d31a77350a83cfacf1abad551bab70b9fac092164f4c4004b8b4cc7b46368" + }, + "src/openai/types/beta/agents/automations/automation_invocation_source.py": { + "mode": "100644", + "sha256": "e6e39cde3a3ac98102a910ba8c981bdd0d098bf0944907f51273661db5ba61e5" + }, + "src/openai/types/beta/agents/automations/invocation_list_params.py": { + "mode": "100644", + "sha256": "e7235ed843f1f3b21b26369628d2eb95a35059c20b2f0637eeda22323657d1ae" }, "src/openai/types/beta/agents/environment_create_params.py": { "mode": "100644", @@ -1973,6 +2053,14 @@ "mode": "100644", "sha256": "6bf1e5694ad8be2cf17549f965ac593502144419d052a8314499d80e75f47d9f" }, + "src/openai/types/beta/agents/one_time_automation.py": { + "mode": "100644", + "sha256": "7da7ad20e1b8d925bf4d0133d6bff9f5a9e917efd9a11f7d652428dfd7fb0873" + }, + "src/openai/types/beta/agents/periodic_automation.py": { + "mode": "100644", + "sha256": "ac26a7b3578e3b890ec8a2263a303934b016e1f7044d6d29e9f7c23b3271b335" + }, "src/openai/types/beta/agents/session_create_params.py": { "mode": "100644", "sha256": "70fe10d2ef44268bad65a58f96ae70e4150f1092c885bf78f28e3ddb99df5af1" @@ -2715,35 +2803,35 @@ }, "src/openai/types/beta/beta_response_input_file.py": { "mode": "100644", - "sha256": "c2c9c8d40df3ebfbd9078157b4452a3842bd8ae87b1dce788b6f67329e1936da" + "sha256": "678fff6dcb76fdd4b958c86e9e0a1009244283e3688f4d5c43184fd8103f7dbe" }, "src/openai/types/beta/beta_response_input_file_content.py": { "mode": "100644", - "sha256": "8abcdf4a2ea67c89c3e11df6c4df7497fe003a2f66568ceee1a7a069739337c1" + "sha256": "a26937c4678dbf2e03f15317a9bbe2e9729ec21c67cb23ad1ca13421b5206c82" }, "src/openai/types/beta/beta_response_input_file_content_param.py": { "mode": "100644", - "sha256": "1f18c52d754bcfe9bf11e8785ae60781af1088764eeb3c3ca4743b3e11dff3cf" + "sha256": "e9ee5b6fa0598dfc6923e4db2008dbd93e0ef0e12c7a3486fcce188ac606b26f" }, "src/openai/types/beta/beta_response_input_file_param.py": { "mode": "100644", - "sha256": "49a56202c24785fe88fc7b8e3ce9f84fd95cba06f128077469aba32948288325" + "sha256": "9e0ff392f9355d35455db9fc8d7b3c87cc0cefa5c241eefdb28a66f4668aaef7" }, "src/openai/types/beta/beta_response_input_image.py": { "mode": "100644", - "sha256": "ce05149eea0d7acb40bb773d91e1c743fb6bb7fb0bf2ad658960aab210f2a565" + "sha256": "3792174e56f06280aa1159a76da5ba81ae7bc06e95a49538a49eb35a3153c17d" }, "src/openai/types/beta/beta_response_input_image_content.py": { "mode": "100644", - "sha256": "897fc69b1eae099efcd103ed6d34bc65c2765f23e828ac8f0e6e603e86ea41e9" + "sha256": "897f719ce596f4c34e1ef02235a6734ed94bda418c53ae21f035d3e5964b4cdc" }, "src/openai/types/beta/beta_response_input_image_content_param.py": { "mode": "100644", - "sha256": "71bbf3abea8466bf4a64ab940dfa3274c393b61b1d3944939ab645649264e351" + "sha256": "29fd94be12976fbb72fea7db17008d4f1a06dc8e88bfe8c55dac4c4018eb167b" }, "src/openai/types/beta/beta_response_input_image_param.py": { "mode": "100644", - "sha256": "55343bd638ddad039b73cc2ccd17704fed3e5366e3f7421920ceaf514b05c80b" + "sha256": "4862b3cc063af9d90e7dc67579b84ae21087bf46bd18faeb481d65ba23b29a9e" }, "src/openai/types/beta/beta_response_input_item.py": { "mode": "100644", @@ -2771,23 +2859,23 @@ }, "src/openai/types/beta/beta_response_input_text.py": { "mode": "100644", - "sha256": "15182941ec3e77ed9bdfe36b4e02580f0635c0bae8f238359a034b9e378d7bff" + "sha256": "da753d1f3e2618ad969342bb5c20ddf515aa7481f8f81bc351a2b674812b3aa1" }, "src/openai/types/beta/beta_response_input_text_content.py": { "mode": "100644", - "sha256": "b5612d0d3b4b278fb8241557bf3c0dd4effa2c5f5bd8f3a435e427110e1c03d2" + "sha256": "05fafd48cdbe85f06a942e6f3c5f211e5694bb3c4047dc7d6e53850907b5bacb" }, "src/openai/types/beta/beta_response_input_text_content_param.py": { "mode": "100644", - "sha256": "46c712a687cdc21cc542cd61981f484ad5c15bd816c1afdb2187e4d7fa74b9ee" + "sha256": "147fd5668879a2195d8bd570f33bac43db1f3959f5baa67172bb8e832b6d99c2" }, "src/openai/types/beta/beta_response_input_text_param.py": { "mode": "100644", - "sha256": "0defb6d937d50bd69d44de40730a43dc19cdca3ff01b61c99a879c5dab55b124" + "sha256": "4db28c3ef3960793c5a874009fa43f2d27afb4b10aff154ebf1160e4f7eef4e1" }, "src/openai/types/beta/beta_response_item.py": { "mode": "100644", - "sha256": "42d18b72f1d5ebfc20d2600ec529a651dd7775279111c2cca40c3e0204de397f" + "sha256": "a36f81a50941233bd7f65e323c8fadefe24a309d2f2697ef103382d9d456ca3f" }, "src/openai/types/beta/beta_response_local_environment.py": { "mode": "100644", @@ -2827,7 +2915,7 @@ }, "src/openai/types/beta/beta_response_output_item.py": { "mode": "100644", - "sha256": "f26a25c55e3ba8d71fd8e6159ca60adc3ffd911e1ccd6c3562bad80190192827" + "sha256": "f785f2680a96e7e2b262c8d653e02c84f59a96cbcb6721edcf1ac258d10e4095" }, "src/openai/types/beta/beta_response_output_item_added_event.py": { "mode": "100644", @@ -3359,11 +3447,11 @@ }, "src/openai/types/beta/persisted_agent_tool.py": { "mode": "100644", - "sha256": "e5e5366709bc38fafc00c715c8439584fc0cef798b628cda99aa9fb3a8b5b703" + "sha256": "337c62e5505ccc43656dad66d619b0a0be532181c8f598e7ccf047b9e6ed8824" }, "src/openai/types/beta/persisted_agent_tool_param.py": { "mode": "100644", - "sha256": "99ea26437bc4cdddcae3c137eb7fd8b50526e2560ed6a60a1e4d24a4d99277d2" + "sha256": "d9e83ab1f8347f4acc525746b1e2c0bc42cbcf64742976dea0983cc419e8fe74" }, "src/openai/types/beta/persisted_mcp_transport.py": { "mode": "100644", @@ -3751,19 +3839,19 @@ }, "src/openai/types/chat/chat_completion_content_part_image.py": { "mode": "100644", - "sha256": "57f18f29c768c4d5ea45155eebbea8dadb0f04e46671f915f3e5c5319a9a86aa" + "sha256": "37c32f3ac96d0bd3b7bfb7c6fd5cb24ca8834f123962b8d3775c692f0c790b87" }, "src/openai/types/chat/chat_completion_content_part_image_param.py": { "mode": "100644", - "sha256": "52044063b5abf48378835ac428bafffb3c4514601d2dcfe4fffed2d4b8e0cc59" + "sha256": "a4d2f746c6d3939a4f450f51c275cfde4eba8c9f523a5ffa4a488c9f82a711a3" }, "src/openai/types/chat/chat_completion_content_part_input_audio_param.py": { "mode": "100644", - "sha256": "66fa0ab2c663d9f504248119ade71f158edd7f3f4b00fdb74c9ab6b02baf514e" + "sha256": "5d4db7a70e814268c78d580a43adf765ec31da8fde1e872592837f9baf203280" }, "src/openai/types/chat/chat_completion_content_part_param.py": { "mode": "100644", - "sha256": "626f25b3143dcd4fde8e2629d4670d33ca9de8776bdb919aeff93efe6bafe050" + "sha256": "4334661b0c4b913af698bd17a2004ad8cdf008549222f10e23f87cb84e89dd30" }, "src/openai/types/chat/chat_completion_content_part_refusal_param.py": { "mode": "100644", @@ -3771,11 +3859,11 @@ }, "src/openai/types/chat/chat_completion_content_part_text.py": { "mode": "100644", - "sha256": "b6da63ccd495749261123d6ae4eb152656376dff1d768b6b1df3304abd56ab7d" + "sha256": "0e0cac98dd112de540a08bdb288ed8b7ac8a0a3908bb738bc97ec5a5bcea484f" }, "src/openai/types/chat/chat_completion_content_part_text_param.py": { "mode": "100644", - "sha256": "06d1709d217212d5efb1030c53ae0b52fe3401be1d739fb0177bc04b08565a81" + "sha256": "05dfba4e59c1792d84107bf31a58d4670205ca2757415fab9da081f0dadb286b" }, "src/openai/types/chat/chat_completion_custom_tool_param.py": { "mode": "100644", @@ -3999,7 +4087,7 @@ }, "src/openai/types/conversations/computer_screenshot_content.py": { "mode": "100644", - "sha256": "d1a9f29bf8d477d5332751899e0b34bb87137c76556c7c96b6bd41131e644caf" + "sha256": "e2130cbb329d466c958e8f3c8b79a2c98aa0843a0bd430d4b9968a01705ea67d" }, "src/openai/types/conversations/conversation.py": { "mode": "100644", @@ -4563,11 +4651,11 @@ }, "src/openai/types/live/client_delegation.py": { "mode": "100644", - "sha256": "e6efc29ad4f4ecb765a7432c6c5ce38de42e3c900867e0301488f67be58d3a40" + "sha256": "dc4b69870eebfd3d61d882842bc9da52747830348e8fc08e620241a3eeb76fc5" }, "src/openai/types/live/client_delegation_param.py": { "mode": "100644", - "sha256": "80f40a1a9db172d10481bc3c8fe57469bc589418d8c34a0197a1de31fbb74b94" + "sha256": "3857ba5c18270f43297dd03659a30968bc9e2cac9e1a9538865ee463b135d81c" }, "src/openai/types/live/client_event.py": { "mode": "100644", @@ -4703,11 +4791,11 @@ }, "src/openai/types/live/fork_session_config.py": { "mode": "100644", - "sha256": "77ecc7dea50455238f1ff8e21d833807cc53916982822cb32ad0fba0e47edd7e" + "sha256": "6ae76980c417e0fc0c340f2fc495d7c2e2ac41f066b7269d8e1d5a1e93b60f19" }, "src/openai/types/live/fork_session_config_param.py": { "mode": "100644", - "sha256": "171df324e999c35d977b0339f65c133891ac6c8604825fe4012dfa3306167033" + "sha256": "5775736aa35cf48e932db023944e0287ce2a2f180eda9c86c49a7c0f4c8f699e" }, "src/openai/types/live/fork_session_start_event.py": { "mode": "100644", @@ -4795,11 +4883,11 @@ }, "src/openai/types/live/media_session_config_param.py": { "mode": "100644", - "sha256": "981b98d38fae3ac96192f13cd9dc51c23857d8e5e1a3c71a61e07eceed0c8380" + "sha256": "b4fa9ca230634515061076183d049fc2a46611a8ad80127b5c30212a2a56d92c" }, "src/openai/types/live/media_session_fork_config_param.py": { "mode": "100644", - "sha256": "8e4e32b83e685932d618540770b8103ec203e79da743be799a6d60d90ceab92a" + "sha256": "efbc8b8435669eb74baedc0eb336915e72739ebf3791fd4b9cc50b216d31f065" }, "src/openai/types/live/output_audio_delta_event.py": { "mode": "100644", @@ -4875,7 +4963,7 @@ }, "src/openai/types/live/session_accept_params.py": { "mode": "100644", - "sha256": "84c6b9c3da675384127d34168acb54041676efbbfa9e673a5b469b9a7311e0cc" + "sha256": "fd82bf7d2963e62e7d4b6ca55684a02e38536d0a8132083a52a9e7f12bd2afc9" }, "src/openai/types/live/session_close_event.py": { "mode": "100644", @@ -4891,11 +4979,11 @@ }, "src/openai/types/live/session_config.py": { "mode": "100644", - "sha256": "e633afa348c21659c1abad1d2b814c45bb39011fb81e1210c077c728383cf91e" + "sha256": "6f66f8e598ff0eb74298e4a8bec02b256ec78c38bed26340d3efd641204a36c3" }, "src/openai/types/live/session_config_param.py": { "mode": "100644", - "sha256": "8b771028ec4eb6d41d1d8d4be43a433d43c3e5c3860e007c87714bc7a6a7e684" + "sha256": "22be34dd4de2443b6646140b46a8c46f13491c088bebc6868903c532bd2ec45e" }, "src/openai/types/live/session_fork_params.py": { "mode": "100644", @@ -4915,7 +5003,7 @@ }, "src/openai/types/live/session_resource.py": { "mode": "100644", - "sha256": "e19523ff71354c760432de799797ffba7cac29e3d4acd018c19a6a5d3445dbc6" + "sha256": "09b77ba564f7563a2a8ed6ffbab6a2796234edd0446cc2930b6f9498d10d6b94" }, "src/openai/types/live/session_start_event.py": { "mode": "100644", @@ -4931,11 +5019,11 @@ }, "src/openai/types/live/session_update_config.py": { "mode": "100644", - "sha256": "b56b6c950f603b2dc15a15de4602e3454dd8b5db3f67b0968e7a9e1ba977d79e" + "sha256": "419d10729d53e237668181fbb2be89f338669386f0f8c2622dae91d42b264fde" }, "src/openai/types/live/session_update_config_param.py": { "mode": "100644", - "sha256": "17aa1877ba81991936e856f5a97274ebecd69e7127fc725098acbdd410899306" + "sha256": "40112ebfa9d803c228909d5ba934be04c5e6d990b5930b1d74bffb720c56563b" }, "src/openai/types/live/session_update_event.py": { "mode": "100644", @@ -5099,7 +5187,7 @@ }, "src/openai/types/realtime/conversation_item_input_audio_transcription_delta_event.py": { "mode": "100644", - "sha256": "cc0ebd7e315fd30a64e9df0ff1e8940fc06d2d3d0fdf887dba749759d4d418f9" + "sha256": "e0e955bb2d08d25f9217a2b3f48b2ac0a20328af2ac1765bfb94f616de9c1e7f" }, "src/openai/types/realtime/conversation_item_input_audio_transcription_failed_event.py": { "mode": "100644", @@ -5311,7 +5399,7 @@ }, "src/openai/types/realtime/realtime_error_event.py": { "mode": "100644", - "sha256": "7bfb5d08c6e790a4edb5b85a4cb765f34faa7e43e4992ba6a7691fe579749f3c" + "sha256": "3caef26e78cca8e07685e5c40b8f12f7cc3416f473407eb254b6c7a38b6b52fe" }, "src/openai/types/realtime/realtime_function_tool.py": { "mode": "100644", @@ -6259,35 +6347,35 @@ }, "src/openai/types/responses/response_input_file.py": { "mode": "100644", - "sha256": "31d416a5c703bff6cf7c472710b47280605a120e1f82596eae8ca1384e458ee0" + "sha256": "08367864bff957fa4a8b020acee507981a9dc2280efe19b7fb7eb2287959f6a4" }, "src/openai/types/responses/response_input_file_content.py": { "mode": "100644", - "sha256": "c54c2ca5ab211759d1b7d4b2c04fac7559f20112724472a7b9cf9b7557dcf43d" + "sha256": "a3bd4748c31fa004957efbd251821f670179f33265c4de609934c336fd1adb5f" }, "src/openai/types/responses/response_input_file_content_param.py": { "mode": "100644", - "sha256": "321623a15e3baee5220420886d66103d88647d152f71addf30062f7f19451188" + "sha256": "1b3cb6af87357124adfc1e19ad82e19a87a54058c7726414e9c26b7a3955690f" }, "src/openai/types/responses/response_input_file_param.py": { "mode": "100644", - "sha256": "081641494f64cfe21fb1377d6e7654e83be1ee7fbea547cb3f24b762f318f550" + "sha256": "dc7af160ae8ca96c77aebf92f01fb3e5db77de39d9deb767d0f69a792837a73f" }, "src/openai/types/responses/response_input_image.py": { "mode": "100644", - "sha256": "174c919fd66a287d80f81ddcbcac4294a98f1110485bb6b5b0e670b537f85e7f" + "sha256": "4852c46a52e5128aed6ddb96e2cbda86b8ca5b9235f632ee60668f0f67908df6" }, "src/openai/types/responses/response_input_image_content.py": { "mode": "100644", - "sha256": "20af7a823f02f018e9971ff007c72f9f6d496803536755c6aaa516a95304bf07" + "sha256": "79d7a845bae7ab4f7d33d2b5aafcc175cc36f05d0fa97613c80dc6c65a7f351c" }, "src/openai/types/responses/response_input_image_content_param.py": { "mode": "100644", - "sha256": "947aa18fc02f5d240881d94bfbd427d86e030ef4c0a3d4b1dcd8aa78f4fe2764" + "sha256": "3c9402108cf4ef22f7550b4cc023dc9f03ad36841b966b28534d050ce71654e0" }, "src/openai/types/responses/response_input_image_param.py": { "mode": "100644", - "sha256": "bade76829f77e4c95b9017b18c28b1eb0843aaf4124edf40ce13adf05ca31909" + "sha256": "db2fd3ca33fad4186fadd2c636f0509aa0c768f98d55590bf017a44fdaeaf908" }, "src/openai/types/responses/response_input_item.py": { "mode": "100644", @@ -6315,19 +6403,19 @@ }, "src/openai/types/responses/response_input_text.py": { "mode": "100644", - "sha256": "cf7cb6d30b9e1a88afd9c523abe8415a46210dd1962ba50216fcb8172f1bff7d" + "sha256": "5e8250a26a4fa696b5dd63f4e990ab89f3370d2c88f1df898e386eea98070434" }, "src/openai/types/responses/response_input_text_content.py": { "mode": "100644", - "sha256": "d74f1319d3e691e23b4696593bc39b152fb769490d1a7b504ca5c89cf5facf26" + "sha256": "45acd1cafcdeef42d581af4156c7577f69629fe9393bbaf4d2340ecce516d682" }, "src/openai/types/responses/response_input_text_content_param.py": { "mode": "100644", - "sha256": "c0119604950bc7975274782f171d483e59a406b38af781ac42b5dcf2971c0d57" + "sha256": "852bb7535307b24de02778f46b20c8a2a9727ce165c3a171ed42f03ac94a9072" }, "src/openai/types/responses/response_input_text_param.py": { "mode": "100644", - "sha256": "b95504039a977c0647f8d426be2194e1e7229cdbec9f0e7065b334f7ad4338ca" + "sha256": "67d2d5fb278f9fe1f8ed0c8f4201477f23de5a6c681465f81d4471d5c752fc8d" }, "src/openai/types/responses/response_item.py": { "mode": "100644", @@ -6755,7 +6843,7 @@ }, "src/openai/types/shared/decision_input_json.py": { "mode": "100644", - "sha256": "161cecb4ba9d08ee9c4890609360b596901f4913eaf5464876b60236fa0cbb99" + "sha256": "7e494030f2dc9fe1bd372c8789956110e35db226707dfceba20843efa8951450" }, "src/openai/types/shared/decision_question_input_image.py": { "mode": "100644", @@ -7475,7 +7563,7 @@ }, "tests/api_resources/audio/test_voices.py": { "mode": "100644", - "sha256": "5d9074a59cc739f26b38a4b6c3716d03bdd1ef369ecc9e734d82d8d8e2512e2f" + "sha256": "1d8aa916e39242bbff3d461bf9254aa943cdf4cb3e9b0098a2226973edffe4e9" }, "tests/api_resources/beta/__init__.py": { "mode": "100644", @@ -7485,6 +7573,14 @@ "mode": "100644", "sha256": "0ee742b76cb44e9e0eb921dca08a89091274455a50e995ba2769688f10a097de" }, + "tests/api_resources/beta/agents/automations/__init__.py": { + "mode": "100644", + "sha256": "0ee742b76cb44e9e0eb921dca08a89091274455a50e995ba2769688f10a097de" + }, + "tests/api_resources/beta/agents/automations/test_invocations.py": { + "mode": "100644", + "sha256": "f375bf7bbc7ad74f271f2ff499dc1ec6644c47352b566b9020d6dd2aea0bc1ba" + }, "tests/api_resources/beta/agents/environments/__init__.py": { "mode": "100644", "sha256": "0ee742b76cb44e9e0eb921dca08a89091274455a50e995ba2769688f10a097de" @@ -7553,6 +7649,10 @@ "mode": "100644", "sha256": "d8a8341ac03b5dec9f1ebd22574b6f44b0b42088368cecaae559dd06d7261362" }, + "tests/api_resources/beta/agents/test_automations.py": { + "mode": "100644", + "sha256": "37b24f5906be1a5b0b7479fc13d78befdf10ea262658cb7de10c29dec86e4f96" + }, "tests/api_resources/beta/agents/test_environments.py": { "mode": "100644", "sha256": "529f48933850ff09980fbd8a8ec6c9bef538efa5bffa71660e14421693df02fa" @@ -7731,7 +7831,7 @@ }, "tests/api_resources/live/test_sessions.py": { "mode": "100644", - "sha256": "2610c853c6b96655b18b54b770c11843a774b4d1f8dbd5eeb9f9672e158040e8" + "sha256": "c8e24169a91d24699b65c4b927afac7dc436cab20acea02d0368721cd7692005" }, "tests/api_resources/live/test_sideband.py": { "mode": "100644", @@ -7847,7 +7947,7 @@ }, "tests/api_resources/test_live.py": { "mode": "100644", - "sha256": "a770d729eb27749e1ee1aa62c51cd37e2fc995a95540bcfa1e579efde492072d" + "sha256": "6fa5e16d2004c3dbb9b9aa8b6c62bf10ce1d0ddc000de4cf1a5f7e8835695c7f" }, "tests/api_resources/test_models.py": { "mode": "100644", diff --git a/scripts/castiron/test_custom_code_policy.py b/scripts/castiron/test_custom_code_policy.py index be49c70665..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 @@ -29,6 +30,9 @@ def setUp(self) -> None: # pyright: ignore[reportImplicitOverride] checker = self.repo / "scripts/castiron/custom_code_budget.py" checker.parent.mkdir(parents=True) checker.write_text("NEXT_POLICY_VERSION = 1\n") + checker.with_name("custom_code_policy.py").write_text( + 'PIN_REVIEW_POLICY = "effective-policy-v1"\n' + ) self.main = self.commit("main policy") self.git("update-ref", "refs/remotes/origin/main", self.main) self.pin = {"repository": REPO, "main_sha": self.main} @@ -38,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)) @@ -374,6 +424,20 @@ def test_bootstrap_budget_increase_keeps_human_proof_for_pr_and_queue(self) -> N result = self.select(base=self.main, pull_heads=heads) self.assertEqual(result["policy_reviews"], [{"number": 3, "head_sha": self.head}]) + def test_authorless_review_does_not_block_valid_approval(self) -> None: + self.git("checkout", "-q", "--detach", self.base) + policy = selector.read_policy(self.repo, self.base) + self.write_policy( + {**policy, "max_custom_patch_lines": policy["max_custom_patch_lines"] + 1} + ) + self.head = self.commit("increase budget") + reviews = [self.approved(id=9, user=None), self.approved()] + with mock.patch.object(selector.report, "api", side_effect=self.review_api(reviews)): + self.assertEqual( + self.select()["policy_reviews"], + [{"number": 3, "head_sha": self.head}], + ) + def test_budget_increase_without_pin_change_requires_human(self) -> None: self.git("checkout", "-q", "--detach", self.base) policy = selector.read_policy(self.repo, self.base) @@ -461,12 +525,13 @@ def test_pin_effective_policy_review_for_pr_and_queue(self) -> None: self.head = self.commit("request pin without changing local budget") for heads in (None, [self.head]): with self.subTest(proposed=proposed, bootstrap=bootstrap, heads=heads): + needs_proof = requires_human and not bootstrap with mock.patch.object( selector, "require_human_policy_review", side_effect=ValueError("human review missing"), ) as review: - if requires_human: + if needs_proof: with self.assertRaisesRegex(ValueError, "human"): self.select(base=base, main=newer, pull_heads=heads) review.assert_called_once_with(REPO, self.head) @@ -474,7 +539,7 @@ def test_pin_effective_policy_review_for_pr_and_queue(self) -> None: result = self.select(base=base, main=newer, pull_heads=heads) review.assert_not_called() self.assertEqual(result["policy_reviews"], []) - if requires_human: + if needs_proof: with mock.patch.object( selector.report, "api", @@ -485,6 +550,48 @@ def test_pin_effective_policy_review_for_pr_and_queue(self) -> None: result["policy_reviews"], [{"number": 3, "head_sha": self.head}] ) + def test_legacy_checker_pin_review_receipt_for_pr_and_queue(self) -> None: + declarations = ( + None, + 'PIN_REVIEW_POLICY = "unknown"\n', + 'PIN_REVIEW_POLICY = "effective-policy-v1"\n' * 2, + ) + for declaration in declarations: + self.git("checkout", "-q", "--detach", self.main) + checker = self.repo / "scripts/castiron/custom_code_policy.py" + if declaration is None: + checker.unlink() + else: + checker.write_text(declaration) + legacy = self.commit("legacy review contract") + checker.write_text('PIN_REVIEW_POLICY = "effective-policy-v1"\n') + newer = self.commit("modern review contract") + self.git("update-ref", "refs/remotes/origin/main", newer) + self.git("checkout", "-q", "--detach", legacy) + self.write_policy( + {**self.policy, "next_policy": {"repository": REPO, "main_sha": legacy}} + ) + base = self.commit("protected legacy checker") + self.write_policy( + {**self.policy, "next_policy": {"repository": REPO, "main_sha": newer}} + ) + self.head = self.commit("forward same-budget pin") + for heads in (None, [self.head]): + with self.subTest(declaration=declaration, heads=heads): + with ( + mock.patch.object(selector.report, "api", side_effect=self.review_api([])), + self.assertRaisesRegex(ValueError, "human"), + ): + self.select(base=base, main=newer, pull_heads=heads) + with mock.patch.object( + selector.report, "api", side_effect=self.review_api([self.approved()]) + ): + result = self.select(base=base, main=newer, pull_heads=heads) + self.assertEqual(result["policy_sha"], legacy) + self.assertEqual( + result["policy_reviews"], [{"number": 3, "head_sha": self.head}] + ) + def test_rollback_pin_keeps_human_proof_for_pr_and_queue(self) -> None: self.git("checkout", "-q", "--detach", self.main) (self.repo / "checker-fix.txt").write_text("reviewed checker fix") @@ -508,6 +615,59 @@ def test_rollback_pin_keeps_human_proof_for_pr_and_queue(self) -> None: self.assertEqual(result["policy_sha"], newer) self.assertEqual(result["policy_reviews"], [{"number": 3, "head_sha": self.head}]) + def test_stale_pin_compares_current_protected_policy_for_pr_and_queue(self) -> None: + for protected_policy in ( + self.policy, + {**self.policy, "max_custom_patch_lines": 3999}, + {"schema_version": 2, "max_custom_patch_lines": 0, "generated_files": "strict"}, + ): + self.git("checkout", "-q", "--detach", self.main) + (self.repo / "checker-fix.txt").write_text("intermediate checker") + intermediate = self.commit("intermediate main checker") + self.write_policy(protected_policy) + (self.repo / "checker-fix.txt").write_text("protected checker") + current = self.commit("current main checker") + (self.repo / "checker-fix.txt").write_text("forward checker") + forward = self.commit("forward main checker") + self.git("update-ref", "refs/remotes/origin/main", forward) + self.git("checkout", "-q", "--detach", self.base) + self.write_policy( + {**self.policy, "next_policy": {"repository": REPO, "main_sha": current}} + ) + protected_base = self.commit("advance protected next pin") + for proposed in (intermediate, current, forward): + self.git("checkout", "-q", "--detach", self.base) + self.write_policy( + {**self.policy, "next_policy": {"repository": REPO, "main_sha": proposed}} + ) + self.head = self.commit("stale policy-only PR") + for heads in (None, [self.head]): + with self.subTest(policy=protected_policy, proposed=proposed, heads=heads): + with mock.patch.object( + selector.report, "api", side_effect=self.review_api([]) + ): + if proposed == intermediate: + with self.assertRaisesRegex(ValueError, "human"): + self.select(base=protected_base, main=forward, pull_heads=heads) + else: + result = self.select( + base=protected_base, main=forward, pull_heads=heads + ) + self.assertEqual(result["policy_reviews"], []) + with mock.patch.object( + selector.report, "api", side_effect=self.review_api([self.approved()]) + ): + result = self.select( + base=protected_base, main=forward, pull_heads=heads + ) + self.assertEqual(result["policy_sha"], current) + self.assertEqual( + result["policy_reviews"], + [{"number": 3, "head_sha": self.head}] + if proposed == intermediate + else [], + ) + def test_initial_older_pin_keeps_human_proof_for_pr_and_queue(self) -> None: self.git("checkout", "-q", "--detach", self.main) (self.repo / "checker-fix.txt").write_text("reviewed bootstrap checker fix") @@ -539,6 +699,40 @@ def test_initial_older_pin_keeps_human_proof_for_pr_and_queue(self) -> None: [{"number": 3, "head_sha": self.head}] if pin_sha == self.main else [], ) + def test_bootstrap_uses_active_main_policy_for_pr_and_queue(self) -> None: + self.git("checkout", "-q", "--detach", self.main) + self.write_policy( + {"schema_version": 2, "max_custom_patch_lines": 0, "generated_files": "strict"} + ) + current = self.commit("main activates strict zero policy") + self.git("update-ref", "refs/remotes/origin/main", current) + for proposed in (self.main, current): + self.git("checkout", "-q", "--detach", self.main) + self.write_policy( + {**self.policy, "next_policy": {"repository": REPO, "main_sha": proposed}} + ) + self.head = self.commit("initial pin with unchanged legacy local ceiling") + for heads in (None, [self.head]): + with self.subTest(proposed=proposed, heads=heads): + with mock.patch.object(selector.report, "api", side_effect=self.review_api([])): + if proposed == self.main: + with self.assertRaisesRegex(ValueError, "human"): + self.select(base=self.main, main=current, pull_heads=heads) + else: + result = self.select(base=self.main, main=current, pull_heads=heads) + self.assertEqual(result["policy_reviews"], []) + self.assertEqual(result["policy_sha"], current) + with mock.patch.object( + selector.report, "api", side_effect=self.review_api([self.approved()]) + ): + result = self.select(base=self.main, main=current, pull_heads=heads) + self.assertTrue(result["bootstrap"]) + self.assertEqual(result["policy_sha"], current) + self.assertEqual( + result["policy_reviews"], + [{"number": 3, "head_sha": self.head}] if proposed == self.main else [], + ) + def test_incapable_policy_is_not_executed(self) -> None: self.git("checkout", "-q", "--detach", self.main) (self.repo / "scripts/castiron/custom_code_budget.py").write_text( diff --git a/scripts/castiron/test_custom_code_publication.py b/scripts/castiron/test_custom_code_publication.py index 817f137548..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,486 +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, - "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_merge_sha_signal_requires_exact_live_merge_and_parents(self) -> None: - payload = self.payload() - payload["run"]["head_sha"] = payload["context"]["payload"]["workflow_run"]["head_sha"] = ( - "e" * 40 - ) - payload["merge_sha"] = "e" * 40 - payload["merge_commit"] = {"parents": [{"sha": "b" * 40}, {"sha": "a" * 40}]} - self.assertEqual(len(self.invoke(payload)), 6) - payload["merge_commit"]["parents"].reverse() - self.assertEqual(self.invoke(payload), []) - - 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..5170e6f2af --- /dev/null +++ b/scripts/castiron/test_custom_code_review_revocation.py @@ -0,0 +1,596 @@ +# 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 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.assertIn("ref: ${{ github.workflow_sha }}", revoke) + self.assertIn("persist-credentials: false", revoke) + self.assertNotIn("ref: ${{ github.event", revoke) + self.assertIn("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/openai/resources/audio/voices.py b/src/openai/resources/audio/voices.py index 48165f6769..48107c06af 100644 --- a/src/openai/resources/audio/voices.py +++ b/src/openai/resources/audio/voices.py @@ -10,13 +10,14 @@ from ... import _legacy_response from ..._files import deepcopy_with_paths from ..._types import Body, Omit, Query, Headers, NotGiven, FileTypes, omit, not_given -from ..._utils import extract_files, required_args, maybe_transform, async_maybe_transform +from ..._utils import extract_files, path_template, required_args, maybe_transform, async_maybe_transform from ..._compat import cached_property from ..._resource import SyncAPIResource, AsyncAPIResource from ..._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper from ...types.audio import voice_create_params from ..._base_client import make_request_options from ...types.audio.voice import Voice +from ...types.audio.voice_deleted import VoiceDeleted __all__ = ["Voices", "AsyncVoices"] @@ -192,6 +193,50 @@ def create( cast_to=Voice, ) + def delete( + self, + voice_id: str, + *, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> VoiceDeleted: + """ + 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. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not voice_id: + raise ValueError(f"Expected a non-empty value for `voice_id` but received {voice_id!r}") + return self._delete( + path_template("/audio/voices/{voice_id}", voice_id=voice_id), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=VoiceDeleted, + ) + class AsyncVoices(AsyncAPIResource): """Turn audio into text or text into audio.""" @@ -364,6 +409,50 @@ async def create( cast_to=Voice, ) + async def delete( + self, + voice_id: str, + *, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> VoiceDeleted: + """ + 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. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not voice_id: + raise ValueError(f"Expected a non-empty value for `voice_id` but received {voice_id!r}") + return await self._delete( + path_template("/audio/voices/{voice_id}", voice_id=voice_id), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=VoiceDeleted, + ) + class VoicesWithRawResponse: def __init__(self, voices: Voices) -> None: @@ -372,6 +461,9 @@ def __init__(self, voices: Voices) -> None: self.create = _legacy_response.to_raw_response_wrapper( voices.create, ) + self.delete = _legacy_response.to_raw_response_wrapper( + voices.delete, + ) class AsyncVoicesWithRawResponse: @@ -381,6 +473,9 @@ def __init__(self, voices: AsyncVoices) -> None: self.create = _legacy_response.async_to_raw_response_wrapper( voices.create, ) + self.delete = _legacy_response.async_to_raw_response_wrapper( + voices.delete, + ) class VoicesWithStreamingResponse: @@ -390,6 +485,9 @@ def __init__(self, voices: Voices) -> None: self.create = to_streamed_response_wrapper( voices.create, ) + self.delete = to_streamed_response_wrapper( + voices.delete, + ) class AsyncVoicesWithStreamingResponse: @@ -399,3 +497,6 @@ def __init__(self, voices: AsyncVoices) -> None: self.create = async_to_streamed_response_wrapper( voices.create, ) + self.delete = async_to_streamed_response_wrapper( + voices.delete, + ) diff --git a/src/openai/resources/beta/agents/__init__.py b/src/openai/resources/beta/agents/__init__.py index dc5ca3d8f6..dea64063d3 100644 --- a/src/openai/resources/beta/agents/__init__.py +++ b/src/openai/resources/beta/agents/__init__.py @@ -27,6 +27,14 @@ SessionsWithStreamingResponse as SessionsWithStreamingResponse, AsyncSessionsWithStreamingResponse as AsyncSessionsWithStreamingResponse, ) + from .automations import ( + Automations as Automations, + AsyncAutomations as AsyncAutomations, + AutomationsWithRawResponse as AutomationsWithRawResponse, + AsyncAutomationsWithRawResponse as AsyncAutomationsWithRawResponse, + AutomationsWithStreamingResponse as AutomationsWithStreamingResponse, + AsyncAutomationsWithStreamingResponse as AsyncAutomationsWithStreamingResponse, + ) from .environments import ( Environments as Environments, AsyncEnvironments as AsyncEnvironments, @@ -38,6 +46,12 @@ else: _EXPORTS = { + "Automations": (".automations", "Automations"), + "AsyncAutomations": (".automations", "AsyncAutomations"), + "AutomationsWithRawResponse": (".automations", "AutomationsWithRawResponse"), + "AsyncAutomationsWithRawResponse": (".automations", "AsyncAutomationsWithRawResponse"), + "AutomationsWithStreamingResponse": (".automations", "AutomationsWithStreamingResponse"), + "AsyncAutomationsWithStreamingResponse": (".automations", "AsyncAutomationsWithStreamingResponse"), "Environments": (".environments", "Environments"), "AsyncEnvironments": (".environments", "AsyncEnvironments"), "EnvironmentsWithRawResponse": (".environments", "EnvironmentsWithRawResponse"), @@ -65,6 +79,7 @@ } _SUBMODULES = { "agents", + "automations", "environments", "sessions", "vaults", @@ -88,6 +103,12 @@ def __dir__() -> list[str]: __all__ = [ + "Automations", + "AsyncAutomations", + "AutomationsWithRawResponse", + "AsyncAutomationsWithRawResponse", + "AutomationsWithStreamingResponse", + "AsyncAutomationsWithStreamingResponse", "Environments", "AsyncEnvironments", "EnvironmentsWithRawResponse", diff --git a/src/openai/resources/beta/agents/agents.py b/src/openai/resources/beta/agents/agents.py index 6069be1b90..d2e18676ca 100644 --- a/src/openai/resources/beta/agents/agents.py +++ b/src/openai/resources/beta/agents/agents.py @@ -33,6 +33,14 @@ AsyncSessionsWithStreamingResponse, ) from ....types.beta.agent import Agent +from .automations.automations import ( + Automations, + AsyncAutomations, + AutomationsWithRawResponse, + AsyncAutomationsWithRawResponse, + AutomationsWithStreamingResponse, + AsyncAutomationsWithStreamingResponse, +) from .environments.environments import ( Environments, AsyncEnvironments, @@ -51,6 +59,10 @@ class Agents(SyncAPIResource): + @cached_property + def automations(self) -> Automations: + return Automations(self._client) + @cached_property def environments(self) -> Environments: return Environments(self._client) @@ -405,6 +417,10 @@ def delete( class AsyncAgents(AsyncAPIResource): + @cached_property + def automations(self) -> AsyncAutomations: + return AsyncAutomations(self._client) + @cached_property def environments(self) -> AsyncEnvironments: return AsyncEnvironments(self._client) @@ -778,6 +794,10 @@ def __init__(self, agents: Agents) -> None: agents.delete, ) + @cached_property + def automations(self) -> AutomationsWithRawResponse: + return AutomationsWithRawResponse(self._agents.automations) + @cached_property def environments(self) -> EnvironmentsWithRawResponse: return EnvironmentsWithRawResponse(self._agents.environments) @@ -811,6 +831,10 @@ def __init__(self, agents: AsyncAgents) -> None: agents.delete, ) + @cached_property + def automations(self) -> AsyncAutomationsWithRawResponse: + return AsyncAutomationsWithRawResponse(self._agents.automations) + @cached_property def environments(self) -> AsyncEnvironmentsWithRawResponse: return AsyncEnvironmentsWithRawResponse(self._agents.environments) @@ -844,6 +868,10 @@ def __init__(self, agents: Agents) -> None: agents.delete, ) + @cached_property + def automations(self) -> AutomationsWithStreamingResponse: + return AutomationsWithStreamingResponse(self._agents.automations) + @cached_property def environments(self) -> EnvironmentsWithStreamingResponse: return EnvironmentsWithStreamingResponse(self._agents.environments) @@ -877,6 +905,10 @@ def __init__(self, agents: AsyncAgents) -> None: agents.delete, ) + @cached_property + def automations(self) -> AsyncAutomationsWithStreamingResponse: + return AsyncAutomationsWithStreamingResponse(self._agents.automations) + @cached_property def environments(self) -> AsyncEnvironmentsWithStreamingResponse: return AsyncEnvironmentsWithStreamingResponse(self._agents.environments) diff --git a/src/openai/resources/beta/agents/automations/__init__.py b/src/openai/resources/beta/agents/automations/__init__.py new file mode 100644 index 0000000000..3a2c76a3be --- /dev/null +++ b/src/openai/resources/beta/agents/automations/__init__.py @@ -0,0 +1,73 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +import typing as _t + +if _t.TYPE_CHECKING: + from .automations import ( + Automations as Automations, + AsyncAutomations as AsyncAutomations, + AutomationsWithRawResponse as AutomationsWithRawResponse, + AsyncAutomationsWithRawResponse as AsyncAutomationsWithRawResponse, + AutomationsWithStreamingResponse as AutomationsWithStreamingResponse, + AsyncAutomationsWithStreamingResponse as AsyncAutomationsWithStreamingResponse, + ) + from .invocations import ( + Invocations as Invocations, + AsyncInvocations as AsyncInvocations, + InvocationsWithRawResponse as InvocationsWithRawResponse, + AsyncInvocationsWithRawResponse as AsyncInvocationsWithRawResponse, + InvocationsWithStreamingResponse as InvocationsWithStreamingResponse, + AsyncInvocationsWithStreamingResponse as AsyncInvocationsWithStreamingResponse, + ) + +else: + _EXPORTS = { + "Invocations": (".invocations", "Invocations"), + "AsyncInvocations": (".invocations", "AsyncInvocations"), + "InvocationsWithRawResponse": (".invocations", "InvocationsWithRawResponse"), + "AsyncInvocationsWithRawResponse": (".invocations", "AsyncInvocationsWithRawResponse"), + "InvocationsWithStreamingResponse": (".invocations", "InvocationsWithStreamingResponse"), + "AsyncInvocationsWithStreamingResponse": (".invocations", "AsyncInvocationsWithStreamingResponse"), + "Automations": (".automations", "Automations"), + "AsyncAutomations": (".automations", "AsyncAutomations"), + "AutomationsWithRawResponse": (".automations", "AutomationsWithRawResponse"), + "AsyncAutomationsWithRawResponse": (".automations", "AsyncAutomationsWithRawResponse"), + "AutomationsWithStreamingResponse": (".automations", "AutomationsWithStreamingResponse"), + "AsyncAutomationsWithStreamingResponse": (".automations", "AsyncAutomationsWithStreamingResponse"), + } + _SUBMODULES = { + "automations", + "invocations", + } + + def __getattr__(name: str) -> _t.Any: + import importlib + + if name in _EXPORTS: + module_name, symbol_name = _EXPORTS[name] + value = getattr(importlib.import_module(module_name, __name__), symbol_name) + elif name in _SUBMODULES: + value = importlib.import_module(f".{name}", __name__) + else: + raise AttributeError(f"module {__name__!r} has no attribute {name!r}") + globals()[name] = value + return value + + def __dir__() -> list[str]: + return sorted(set(globals()) | set(_EXPORTS) | _SUBMODULES) + + +__all__ = [ + "Invocations", + "AsyncInvocations", + "InvocationsWithRawResponse", + "AsyncInvocationsWithRawResponse", + "InvocationsWithStreamingResponse", + "AsyncInvocationsWithStreamingResponse", + "Automations", + "AsyncAutomations", + "AutomationsWithRawResponse", + "AsyncAutomationsWithRawResponse", + "AutomationsWithStreamingResponse", + "AsyncAutomationsWithStreamingResponse", +] diff --git a/src/openai/resources/beta/agents/automations/automations.py b/src/openai/resources/beta/agents/automations/automations.py new file mode 100644 index 0000000000..2b6f4db4ae --- /dev/null +++ b/src/openai/resources/beta/agents/automations/automations.py @@ -0,0 +1,1044 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Any, Dict, cast +from typing_extensions import Literal, overload + +import httpx2 + +from ..... import _legacy_response +from ....._types import Body, Omit, Query, Headers, NotGiven, omit, not_given +from ....._utils import path_template, required_args, maybe_transform, async_maybe_transform +from ....._compat import cached_property +from .invocations import ( + Invocations, + AsyncInvocations, + InvocationsWithRawResponse, + AsyncInvocationsWithRawResponse, + InvocationsWithStreamingResponse, + AsyncInvocationsWithStreamingResponse, +) +from ....._resource import SyncAPIResource, AsyncAPIResource +from ....._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper +from .....pagination import SyncCursorPage, AsyncCursorPage +from ....._base_client import AsyncPaginator, make_request_options +from .....types.beta.agents import ( + automation_list_params, + automation_create_params, + automation_update_params, +) +from .....types.beta.agents.automation import Automation +from .....types.beta.agents.automation_deleted import AutomationDeleted +from .....types.beta.agents.automation_target_param import AutomationTargetParam +from .....types.beta.agents.automation_metadata_param import AutomationMetadataParam + +__all__ = ["Automations", "AsyncAutomations"] + + +class Automations(SyncAPIResource): + @cached_property + def invocations(self) -> Invocations: + return Invocations(self._client) + + @cached_property + def with_raw_response(self) -> AutomationsWithRawResponse: + """ + This property can be used as a prefix for any HTTP method call to return + the raw response object instead of the parsed content. + + For more information, see https://www.github.com/openai/openai-python#accessing-raw-response-data-eg-headers + """ + return AutomationsWithRawResponse(self) + + @cached_property + def with_streaming_response(self) -> AutomationsWithStreamingResponse: + """ + An alternative to `.with_raw_response` that doesn't eagerly read the response body. + + For more information, see https://www.github.com/openai/openai-python#with_streaming_response + """ + return AutomationsWithStreamingResponse(self) + + @overload + def create( + self, + *, + expression: str, + name: str, + target: AutomationTargetParam, + timezone: str, + type: Literal["periodic"], + metadata: AutomationMetadataParam | Omit = omit, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + """ + Saves an active automation without invoking it immediately. + + Args: + expression: A standard five-field cron expression defining scheduled occurrences. + + name: A human-readable name for the automation. + + target: The session an automation invocation targets. + + timezone: The IANA timezone used to interpret the cron expression. + + type: The type of the object. Always `periodic`. + + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + ... + + @overload + def create( + self, + *, + name: str, + run_at: int, + target: AutomationTargetParam, + type: Literal["once"], + metadata: AutomationMetadataParam | Omit = omit, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + """ + Saves an active automation without invoking it immediately. + + Args: + name: A human-readable name for the automation. + + run_at: A future Unix timestamp in seconds. + + target: The session an automation invocation targets. + + type: The type of the object. Always `once`. + + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + ... + + @required_args(["expression", "name", "target", "timezone", "type"], ["name", "run_at", "target", "type"]) + def create( + self, + *, + expression: str | Omit = omit, + name: str, + target: AutomationTargetParam, + timezone: str | Omit = omit, + type: Literal["periodic"] | Literal["once"], + metadata: AutomationMetadataParam | Omit = omit, + run_at: int | Omit = omit, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return cast( + Automation, + self._post( + "/agents/automations", + body=maybe_transform( + { + "expression": expression, + "name": name, + "target": target, + "timezone": timezone, + "type": type, + "metadata": metadata, + "run_at": run_at, + }, + automation_create_params.AutomationCreateParams, + ), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=cast(Any, Automation), # Union types cannot be passed in as arguments in the type system + ), + ) + + def retrieve( + self, + automation_id: str, + *, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + """ + Retrieves a project-owned automation. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return cast( + Automation, + self._get( + path_template("/agents/automations/{automation_id}", automation_id=automation_id), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=cast(Any, Automation), # Union types cannot be passed in as arguments in the type system + ), + ) + + def update( + self, + automation_id: str, + *, + expression: str | Omit = omit, + metadata: Dict[str, str] | Omit = omit, + name: str | Omit = omit, + run_at: int | Omit = omit, + target: AutomationTargetParam | Omit = omit, + timezone: str | Omit = omit, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + """ + Updates supplied fields; target and metadata replace the whole field. + + Args: + expression: Only accepted for periodic automations. + + metadata: Replaces all metadata; omit to leave unchanged. + + run_at: A future Unix timestamp in seconds; accepted only before a one-time scheduled + invocation exists. + + target: Replaces the complete target, retaining its type and any creator session. + + timezone: Only accepted for periodic automations. + + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return cast( + Automation, + self._post( + path_template("/agents/automations/{automation_id}", automation_id=automation_id), + body=maybe_transform( + { + "expression": expression, + "metadata": metadata, + "name": name, + "run_at": run_at, + "target": target, + "timezone": timezone, + }, + automation_update_params.AutomationUpdateParams, + ), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=cast(Any, Automation), # Union types cannot be passed in as arguments in the type system + ), + ) + + def list( + self, + *, + after: str | Omit = omit, + limit: int | Omit = omit, + order: Literal["asc", "desc"] | Omit = omit, + session_id: str | Omit = omit, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> SyncCursorPage[Automation]: + """ + Lists project-owned automations, optionally filtered by target session. + + Args: + after: Return resources after this resource ID in the selected order. + + limit: The maximum number of resources to return, between 1 and 100. Defaults to 20. + + order: The order in which resources are returned. Defaults to `desc`. + + - `asc` - Returns resources in ascending order. + - `desc` - Returns resources in descending order. + + session_id: Matches existing-session targets, including agent-created automations. + + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return self._get_api_list( + "/agents/automations", + page=SyncCursorPage[Automation], + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + query=maybe_transform( + { + "after": after, + "limit": limit, + "order": order, + "session_id": session_id, + }, + automation_list_params.AutomationListParams, + ), + security={"bearer_auth": True}, + ), + model=cast(Any, Automation), # Union types cannot be passed in as arguments in the type system + ) + + def delete( + self, + automation_id: str, + *, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> AutomationDeleted: + """ + Deletes the automation and prevents future invocations without deleting its + target session. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return self._delete( + path_template("/agents/automations/{automation_id}", automation_id=automation_id), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=AutomationDeleted, + ) + + def pause( + self, + automation_id: str, + *, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + """ + Pauses future scheduled delivery without stopping an active session. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return cast( + Automation, + self._post( + path_template("/agents/automations/{automation_id}/pause", automation_id=automation_id), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=cast(Any, Automation), # Union types cannot be passed in as arguments in the type system + ), + ) + + def resume( + self, + automation_id: str, + *, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + """ + Resumes scheduled delivery; one-time automations without a pending invocation + require a future run_at. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return cast( + Automation, + self._post( + path_template("/agents/automations/{automation_id}/resume", automation_id=automation_id), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=cast(Any, Automation), # Union types cannot be passed in as arguments in the type system + ), + ) + + +class AsyncAutomations(AsyncAPIResource): + @cached_property + def invocations(self) -> AsyncInvocations: + return AsyncInvocations(self._client) + + @cached_property + def with_raw_response(self) -> AsyncAutomationsWithRawResponse: + """ + This property can be used as a prefix for any HTTP method call to return + the raw response object instead of the parsed content. + + For more information, see https://www.github.com/openai/openai-python#accessing-raw-response-data-eg-headers + """ + return AsyncAutomationsWithRawResponse(self) + + @cached_property + def with_streaming_response(self) -> AsyncAutomationsWithStreamingResponse: + """ + An alternative to `.with_raw_response` that doesn't eagerly read the response body. + + For more information, see https://www.github.com/openai/openai-python#with_streaming_response + """ + return AsyncAutomationsWithStreamingResponse(self) + + @overload + async def create( + self, + *, + expression: str, + name: str, + target: AutomationTargetParam, + timezone: str, + type: Literal["periodic"], + metadata: AutomationMetadataParam | Omit = omit, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + """ + Saves an active automation without invoking it immediately. + + Args: + expression: A standard five-field cron expression defining scheduled occurrences. + + name: A human-readable name for the automation. + + target: The session an automation invocation targets. + + timezone: The IANA timezone used to interpret the cron expression. + + type: The type of the object. Always `periodic`. + + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + ... + + @overload + async def create( + self, + *, + name: str, + run_at: int, + target: AutomationTargetParam, + type: Literal["once"], + metadata: AutomationMetadataParam | Omit = omit, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + """ + Saves an active automation without invoking it immediately. + + Args: + name: A human-readable name for the automation. + + run_at: A future Unix timestamp in seconds. + + target: The session an automation invocation targets. + + type: The type of the object. Always `once`. + + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + ... + + @required_args(["expression", "name", "target", "timezone", "type"], ["name", "run_at", "target", "type"]) + async def create( + self, + *, + expression: str | Omit = omit, + name: str, + target: AutomationTargetParam, + timezone: str | Omit = omit, + type: Literal["periodic"] | Literal["once"], + metadata: AutomationMetadataParam | Omit = omit, + run_at: int | Omit = omit, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return cast( + Automation, + await self._post( + "/agents/automations", + body=await async_maybe_transform( + { + "expression": expression, + "name": name, + "target": target, + "timezone": timezone, + "type": type, + "metadata": metadata, + "run_at": run_at, + }, + automation_create_params.AutomationCreateParams, + ), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=cast(Any, Automation), # Union types cannot be passed in as arguments in the type system + ), + ) + + async def retrieve( + self, + automation_id: str, + *, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + """ + Retrieves a project-owned automation. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return cast( + Automation, + await self._get( + path_template("/agents/automations/{automation_id}", automation_id=automation_id), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=cast(Any, Automation), # Union types cannot be passed in as arguments in the type system + ), + ) + + async def update( + self, + automation_id: str, + *, + expression: str | Omit = omit, + metadata: Dict[str, str] | Omit = omit, + name: str | Omit = omit, + run_at: int | Omit = omit, + target: AutomationTargetParam | Omit = omit, + timezone: str | Omit = omit, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + """ + Updates supplied fields; target and metadata replace the whole field. + + Args: + expression: Only accepted for periodic automations. + + metadata: Replaces all metadata; omit to leave unchanged. + + run_at: A future Unix timestamp in seconds; accepted only before a one-time scheduled + invocation exists. + + target: Replaces the complete target, retaining its type and any creator session. + + timezone: Only accepted for periodic automations. + + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return cast( + Automation, + await self._post( + path_template("/agents/automations/{automation_id}", automation_id=automation_id), + body=await async_maybe_transform( + { + "expression": expression, + "metadata": metadata, + "name": name, + "run_at": run_at, + "target": target, + "timezone": timezone, + }, + automation_update_params.AutomationUpdateParams, + ), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=cast(Any, Automation), # Union types cannot be passed in as arguments in the type system + ), + ) + + def list( + self, + *, + after: str | Omit = omit, + limit: int | Omit = omit, + order: Literal["asc", "desc"] | Omit = omit, + session_id: str | Omit = omit, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> AsyncPaginator[Automation, AsyncCursorPage[Automation]]: + """ + Lists project-owned automations, optionally filtered by target session. + + Args: + after: Return resources after this resource ID in the selected order. + + limit: The maximum number of resources to return, between 1 and 100. Defaults to 20. + + order: The order in which resources are returned. Defaults to `desc`. + + - `asc` - Returns resources in ascending order. + - `desc` - Returns resources in descending order. + + session_id: Matches existing-session targets, including agent-created automations. + + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return self._get_api_list( + "/agents/automations", + page=AsyncCursorPage[Automation], + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + query=maybe_transform( + { + "after": after, + "limit": limit, + "order": order, + "session_id": session_id, + }, + automation_list_params.AutomationListParams, + ), + security={"bearer_auth": True}, + ), + model=cast(Any, Automation), # Union types cannot be passed in as arguments in the type system + ) + + async def delete( + self, + automation_id: str, + *, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> AutomationDeleted: + """ + Deletes the automation and prevents future invocations without deleting its + target session. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return await self._delete( + path_template("/agents/automations/{automation_id}", automation_id=automation_id), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=AutomationDeleted, + ) + + async def pause( + self, + automation_id: str, + *, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + """ + Pauses future scheduled delivery without stopping an active session. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return cast( + Automation, + await self._post( + path_template("/agents/automations/{automation_id}/pause", automation_id=automation_id), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=cast(Any, Automation), # Union types cannot be passed in as arguments in the type system + ), + ) + + async def resume( + self, + automation_id: str, + *, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> Automation: + """ + Resumes scheduled delivery; one-time automations without a pending invocation + require a future run_at. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return cast( + Automation, + await self._post( + path_template("/agents/automations/{automation_id}/resume", automation_id=automation_id), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=cast(Any, Automation), # Union types cannot be passed in as arguments in the type system + ), + ) + + +class AutomationsWithRawResponse: + def __init__(self, automations: Automations) -> None: + self._automations = automations + + self.create = _legacy_response.to_raw_response_wrapper( + automations.create, + ) + self.retrieve = _legacy_response.to_raw_response_wrapper( + automations.retrieve, + ) + self.update = _legacy_response.to_raw_response_wrapper( + automations.update, + ) + self.list = _legacy_response.to_raw_response_wrapper( + automations.list, + ) + self.delete = _legacy_response.to_raw_response_wrapper( + automations.delete, + ) + self.pause = _legacy_response.to_raw_response_wrapper( + automations.pause, + ) + self.resume = _legacy_response.to_raw_response_wrapper( + automations.resume, + ) + + @cached_property + def invocations(self) -> InvocationsWithRawResponse: + return InvocationsWithRawResponse(self._automations.invocations) + + +class AsyncAutomationsWithRawResponse: + def __init__(self, automations: AsyncAutomations) -> None: + self._automations = automations + + self.create = _legacy_response.async_to_raw_response_wrapper( + automations.create, + ) + self.retrieve = _legacy_response.async_to_raw_response_wrapper( + automations.retrieve, + ) + self.update = _legacy_response.async_to_raw_response_wrapper( + automations.update, + ) + self.list = _legacy_response.async_to_raw_response_wrapper( + automations.list, + ) + self.delete = _legacy_response.async_to_raw_response_wrapper( + automations.delete, + ) + self.pause = _legacy_response.async_to_raw_response_wrapper( + automations.pause, + ) + self.resume = _legacy_response.async_to_raw_response_wrapper( + automations.resume, + ) + + @cached_property + def invocations(self) -> AsyncInvocationsWithRawResponse: + return AsyncInvocationsWithRawResponse(self._automations.invocations) + + +class AutomationsWithStreamingResponse: + def __init__(self, automations: Automations) -> None: + self._automations = automations + + self.create = to_streamed_response_wrapper( + automations.create, + ) + self.retrieve = to_streamed_response_wrapper( + automations.retrieve, + ) + self.update = to_streamed_response_wrapper( + automations.update, + ) + self.list = to_streamed_response_wrapper( + automations.list, + ) + self.delete = to_streamed_response_wrapper( + automations.delete, + ) + self.pause = to_streamed_response_wrapper( + automations.pause, + ) + self.resume = to_streamed_response_wrapper( + automations.resume, + ) + + @cached_property + def invocations(self) -> InvocationsWithStreamingResponse: + return InvocationsWithStreamingResponse(self._automations.invocations) + + +class AsyncAutomationsWithStreamingResponse: + def __init__(self, automations: AsyncAutomations) -> None: + self._automations = automations + + self.create = async_to_streamed_response_wrapper( + automations.create, + ) + self.retrieve = async_to_streamed_response_wrapper( + automations.retrieve, + ) + self.update = async_to_streamed_response_wrapper( + automations.update, + ) + self.list = async_to_streamed_response_wrapper( + automations.list, + ) + self.delete = async_to_streamed_response_wrapper( + automations.delete, + ) + self.pause = async_to_streamed_response_wrapper( + automations.pause, + ) + self.resume = async_to_streamed_response_wrapper( + automations.resume, + ) + + @cached_property + def invocations(self) -> AsyncInvocationsWithStreamingResponse: + return AsyncInvocationsWithStreamingResponse(self._automations.invocations) diff --git a/src/openai/resources/beta/agents/automations/invocations.py b/src/openai/resources/beta/agents/automations/invocations.py new file mode 100644 index 0000000000..0c0f3021a5 --- /dev/null +++ b/src/openai/resources/beta/agents/automations/invocations.py @@ -0,0 +1,406 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal + +import httpx2 + +from ..... import _legacy_response +from ....._types import Body, Omit, Query, Headers, NotGiven, omit, not_given +from ....._utils import path_template, maybe_transform +from ....._compat import cached_property +from ....._resource import SyncAPIResource, AsyncAPIResource +from ....._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper +from .....pagination import SyncCursorPage, AsyncCursorPage +from ....._base_client import AsyncPaginator, make_request_options +from .....types.beta.agents.automations import invocation_list_params +from .....types.beta.agents.automations.automation_invocation import AutomationInvocation + +__all__ = ["Invocations", "AsyncInvocations"] + + +class Invocations(SyncAPIResource): + @cached_property + def with_raw_response(self) -> InvocationsWithRawResponse: + """ + This property can be used as a prefix for any HTTP method call to return + the raw response object instead of the parsed content. + + For more information, see https://www.github.com/openai/openai-python#accessing-raw-response-data-eg-headers + """ + return InvocationsWithRawResponse(self) + + @cached_property + def with_streaming_response(self) -> InvocationsWithStreamingResponse: + """ + An alternative to `.with_raw_response` that doesn't eagerly read the response body. + + For more information, see https://www.github.com/openai/openai-python#with_streaming_response + """ + return InvocationsWithStreamingResponse(self) + + def create( + self, + automation_id: str, + *, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> AutomationInvocation: + """ + Queues a manual delivery without changing the saved schedule. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return self._post( + path_template("/agents/automations/{automation_id}/invocations", automation_id=automation_id), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=AutomationInvocation, + ) + + def retrieve( + self, + invocation_id: str, + *, + automation_id: str, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> AutomationInvocation: + """ + Retrieves a delivery record for a project-owned automation. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + if not invocation_id: + raise ValueError(f"Expected a non-empty value for `invocation_id` but received {invocation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return self._get( + path_template( + "/agents/automations/{automation_id}/invocations/{invocation_id}", + automation_id=automation_id, + invocation_id=invocation_id, + ), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=AutomationInvocation, + ) + + def list( + self, + automation_id: str, + *, + after: str | Omit = omit, + limit: int | Omit = omit, + order: Literal["asc", "desc"] | Omit = omit, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> SyncCursorPage[AutomationInvocation]: + """ + Lists delivery records for a project-owned automation. + + Args: + after: Return resources after this resource ID in the selected order. + + limit: The maximum number of resources to return, between 1 and 100. Defaults to 20. + + order: The order in which resources are returned. Defaults to `desc`. + + - `asc` - Returns resources in ascending order. + - `desc` - Returns resources in descending order. + + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return self._get_api_list( + path_template("/agents/automations/{automation_id}/invocations", automation_id=automation_id), + page=SyncCursorPage[AutomationInvocation], + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + query=maybe_transform( + { + "after": after, + "limit": limit, + "order": order, + }, + invocation_list_params.InvocationListParams, + ), + security={"bearer_auth": True}, + ), + model=AutomationInvocation, + ) + + +class AsyncInvocations(AsyncAPIResource): + @cached_property + def with_raw_response(self) -> AsyncInvocationsWithRawResponse: + """ + This property can be used as a prefix for any HTTP method call to return + the raw response object instead of the parsed content. + + For more information, see https://www.github.com/openai/openai-python#accessing-raw-response-data-eg-headers + """ + return AsyncInvocationsWithRawResponse(self) + + @cached_property + def with_streaming_response(self) -> AsyncInvocationsWithStreamingResponse: + """ + An alternative to `.with_raw_response` that doesn't eagerly read the response body. + + For more information, see https://www.github.com/openai/openai-python#with_streaming_response + """ + return AsyncInvocationsWithStreamingResponse(self) + + async def create( + self, + automation_id: str, + *, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> AutomationInvocation: + """ + Queues a manual delivery without changing the saved schedule. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return await self._post( + path_template("/agents/automations/{automation_id}/invocations", automation_id=automation_id), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=AutomationInvocation, + ) + + async def retrieve( + self, + invocation_id: str, + *, + automation_id: str, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> AutomationInvocation: + """ + Retrieves a delivery record for a project-owned automation. + + Args: + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + if not invocation_id: + raise ValueError(f"Expected a non-empty value for `invocation_id` but received {invocation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return await self._get( + path_template( + "/agents/automations/{automation_id}/invocations/{invocation_id}", + automation_id=automation_id, + invocation_id=invocation_id, + ), + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + security={"bearer_auth": True}, + ), + cast_to=AutomationInvocation, + ) + + def list( + self, + automation_id: str, + *, + after: str | Omit = omit, + limit: int | Omit = omit, + order: Literal["asc", "desc"] | Omit = omit, + # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. + # The extra values given here take precedence over values defined on the client or passed to this method. + extra_headers: Headers | None = None, + extra_query: Query | None = None, + extra_body: Body | None = None, + timeout: float | httpx2.Timeout | None | NotGiven = not_given, + ) -> AsyncPaginator[AutomationInvocation, AsyncCursorPage[AutomationInvocation]]: + """ + Lists delivery records for a project-owned automation. + + Args: + after: Return resources after this resource ID in the selected order. + + limit: The maximum number of resources to return, between 1 and 100. Defaults to 20. + + order: The order in which resources are returned. Defaults to `desc`. + + - `asc` - Returns resources in ascending order. + - `desc` - Returns resources in descending order. + + extra_headers: Send extra headers + + extra_query: Add additional query parameters to the request + + extra_body: Add additional JSON properties to the request + + timeout: Override the client-level default timeout for this request, in seconds + """ + if not automation_id: + raise ValueError(f"Expected a non-empty value for `automation_id` but received {automation_id!r}") + extra_headers = {"OpenAI-Beta": "agents=v1", **(extra_headers or {})} + return self._get_api_list( + path_template("/agents/automations/{automation_id}/invocations", automation_id=automation_id), + page=AsyncCursorPage[AutomationInvocation], + options=make_request_options( + extra_headers=extra_headers, + extra_query=extra_query, + extra_body=extra_body, + timeout=timeout, + query=maybe_transform( + { + "after": after, + "limit": limit, + "order": order, + }, + invocation_list_params.InvocationListParams, + ), + security={"bearer_auth": True}, + ), + model=AutomationInvocation, + ) + + +class InvocationsWithRawResponse: + def __init__(self, invocations: Invocations) -> None: + self._invocations = invocations + + self.create = _legacy_response.to_raw_response_wrapper( + invocations.create, + ) + self.retrieve = _legacy_response.to_raw_response_wrapper( + invocations.retrieve, + ) + self.list = _legacy_response.to_raw_response_wrapper( + invocations.list, + ) + + +class AsyncInvocationsWithRawResponse: + def __init__(self, invocations: AsyncInvocations) -> None: + self._invocations = invocations + + self.create = _legacy_response.async_to_raw_response_wrapper( + invocations.create, + ) + self.retrieve = _legacy_response.async_to_raw_response_wrapper( + invocations.retrieve, + ) + self.list = _legacy_response.async_to_raw_response_wrapper( + invocations.list, + ) + + +class InvocationsWithStreamingResponse: + def __init__(self, invocations: Invocations) -> None: + self._invocations = invocations + + self.create = to_streamed_response_wrapper( + invocations.create, + ) + self.retrieve = to_streamed_response_wrapper( + invocations.retrieve, + ) + self.list = to_streamed_response_wrapper( + invocations.list, + ) + + +class AsyncInvocationsWithStreamingResponse: + def __init__(self, invocations: AsyncInvocations) -> None: + self._invocations = invocations + + self.create = async_to_streamed_response_wrapper( + invocations.create, + ) + self.retrieve = async_to_streamed_response_wrapper( + invocations.retrieve, + ) + self.list = async_to_streamed_response_wrapper( + invocations.list, + ) diff --git a/src/openai/types/audio/__init__.py b/src/openai/types/audio/__init__.py index 2326a03140..d42a1193f8 100644 --- a/src/openai/types/audio/__init__.py +++ b/src/openai/types/audio/__init__.py @@ -7,6 +7,7 @@ from .speech_model import SpeechModel as SpeechModel from .transcription import Transcription as Transcription from .voice_consent import VoiceConsent as VoiceConsent +from .voice_deleted import VoiceDeleted as VoiceDeleted from .transcription_word import TranscriptionWord as TranscriptionWord from .translation_verbose import TranslationVerbose as TranslationVerbose from .voice_create_params import VoiceCreateParams as VoiceCreateParams diff --git a/src/openai/types/audio/voice_deleted.py b/src/openai/types/audio/voice_deleted.py new file mode 100644 index 0000000000..29bb54b98c --- /dev/null +++ b/src/openai/types/audio/voice_deleted.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["VoiceDeleted"] + + +class VoiceDeleted(BaseModel): + id: str + """The voice identifier.""" + + deleted: bool + """Whether the voice was deleted.""" + + object: Literal["audio.voice.deleted"] + """The object type, which is always `audio.voice.deleted`.""" diff --git a/src/openai/types/beta/agent_tool.py b/src/openai/types/beta/agent_tool.py index ff4aa6bd2e..6588ac8c8a 100644 --- a/src/openai/types/beta/agent_tool.py +++ b/src/openai/types/beta/agent_tool.py @@ -15,6 +15,7 @@ "AgentToolResourceWebSearch", "AgentToolResourceWebSearchLocation", "AgentToolResourceComputerUse", + "AgentToolResourceAutomations", ] @@ -123,6 +124,13 @@ class AgentToolResourceComputerUse(BaseModel): """The type of the object. Always `computer_use`.""" +class AgentToolResourceAutomations(BaseModel): + """Lets the agent manage its own scheduled wakeups.""" + + type: Literal["automations"] + """The type of the object. Always `automations`.""" + + AgentTool: TypeAlias = Annotated[ Union[ AgentToolResourceFunction, @@ -130,6 +138,7 @@ class AgentToolResourceComputerUse(BaseModel): AgentToolResourceMcp, AgentToolResourceWebSearch, AgentToolResourceComputerUse, + AgentToolResourceAutomations, ], PropertyInfo(discriminator="type"), ] diff --git a/src/openai/types/beta/agent_tool_param.py b/src/openai/types/beta/agent_tool_param.py index 5246817c9f..e8fb85c647 100644 --- a/src/openai/types/beta/agent_tool_param.py +++ b/src/openai/types/beta/agent_tool_param.py @@ -17,6 +17,7 @@ "AgentToolConfigParamWebSearch", "AgentToolConfigParamWebSearchLocation", "AgentToolConfigParamComputerUse", + "AgentToolConfigParamAutomations", ] @@ -150,6 +151,13 @@ class AgentToolConfigParamComputerUse(TypedDict, total=False): """Whether computer tool outputs include screenshots. Defaults to `false`.""" +class AgentToolConfigParamAutomations(TypedDict, total=False): + """Lets the agent manage its own scheduled wakeups.""" + + type: Required[Literal["automations"]] + """The type of the object. Always `automations`.""" + + AgentToolParam: TypeAlias = Union[ AgentToolConfigParamFunction, AgentToolConfigParamToolSearch, @@ -157,4 +165,5 @@ class AgentToolConfigParamComputerUse(TypedDict, total=False): AgentToolConfigParamMcp, AgentToolConfigParamWebSearch, AgentToolConfigParamComputerUse, + AgentToolConfigParamAutomations, ] diff --git a/src/openai/types/beta/agents/__init__.py b/src/openai/types/beta/agents/__init__.py index b0ddbdbed2..500bbbceb1 100644 --- a/src/openai/types/beta/agents/__init__.py +++ b/src/openai/types/beta/agents/__init__.py @@ -3,15 +3,28 @@ from __future__ import annotations from .vault import Vault as Vault +from .automation import Automation as Automation from .vault_status import VaultStatus as VaultStatus from .vault_deleted import VaultDeleted as VaultDeleted from .environment_info import EnvironmentInfo as EnvironmentInfo +from .automation_target import AutomationTarget as AutomationTarget from .vault_list_params import VaultListParams as VaultListParams +from .automation_deleted import AutomationDeleted as AutomationDeleted +from .one_time_automation import OneTimeAutomation as OneTimeAutomation +from .periodic_automation import PeriodicAutomation as PeriodicAutomation from .session_list_params import SessionListParams as SessionListParams from .vault_create_params import VaultCreateParams as VaultCreateParams from .vault_update_params import VaultUpdateParams as VaultUpdateParams +from .automation_created_by import AutomationCreatedBy as AutomationCreatedBy from .session_create_params import SessionCreateParams as SessionCreateParams from .session_update_params import SessionUpdateParams as SessionUpdateParams +from .automation_environment import AutomationEnvironment as AutomationEnvironment +from .automation_list_params import AutomationListParams as AutomationListParams +from .automation_agent_config import AutomationAgentConfig as AutomationAgentConfig +from .automation_target_param import AutomationTargetParam as AutomationTargetParam from .environment_list_params import EnvironmentListParams as EnvironmentListParams +from .automation_create_params import AutomationCreateParams as AutomationCreateParams +from .automation_update_params import AutomationUpdateParams as AutomationUpdateParams +from .automation_metadata_param import AutomationMetadataParam as AutomationMetadataParam from .environment_create_params import EnvironmentCreateParams as EnvironmentCreateParams from .vault_status_filter_param import VaultStatusFilterParam as VaultStatusFilterParam diff --git a/src/openai/types/beta/agents/automation.py b/src/openai/types/beta/agents/automation.py new file mode 100644 index 0000000000..6a3678176b --- /dev/null +++ b/src/openai/types/beta/agents/automation.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Annotated, TypeAlias + +from ...._utils import PropertyInfo +from .one_time_automation import OneTimeAutomation +from .periodic_automation import PeriodicAutomation + +__all__ = ["Automation"] + +Automation: TypeAlias = Annotated[Union[PeriodicAutomation, OneTimeAutomation], PropertyInfo(discriminator="type")] diff --git a/src/openai/types/beta/agents/automation_agent_config.py b/src/openai/types/beta/agents/automation_agent_config.py new file mode 100644 index 0000000000..498324c859 --- /dev/null +++ b/src/openai/types/beta/agents/automation_agent_config.py @@ -0,0 +1,37 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ...._models import BaseModel +from ..agent_text import AgentText +from ..agent_tool import AgentTool +from ..agent_reasoning import AgentReasoning +from ..multi_agent_config import MultiAgentConfig + +__all__ = ["AutomationAgentConfig"] + + +class AutomationAgentConfig(BaseModel): + """Inline agent configuration without a generated session-local identity.""" + + instructions: Optional[str] = None + """Custom instructions, or null when absent.""" + + model: str + """The requested model name.""" + + multi_agent: MultiAgentConfig + """The configuration for creating and coordinating subagents.""" + + reasoning: AgentReasoning + """The configured reasoning policy.""" + + service_tier: Literal["auto", "default", "flex", "priority", "fast", "ultrafast"] + """The configured service-tier policy.""" + + text: AgentText + """The configured output format and verbosity.""" + + tools: List[AgentTool] + """Configured tools, excluding confidential credentials.""" diff --git a/src/openai/types/beta/agents/automation_create_params.py b/src/openai/types/beta/agents/automation_create_params.py new file mode 100644 index 0000000000..4b3ab7e848 --- /dev/null +++ b/src/openai/types/beta/agents/automation_create_params.py @@ -0,0 +1,40 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from .automation_target_param import AutomationTargetParam +from .automation_metadata_param import AutomationMetadataParam + +__all__ = ["AutomationCreateParams", "CreateAutomationParamsPeriodic", "CreateAutomationParamsOnce"] + + +class CreateAutomationParamsPeriodic(TypedDict, total=False): + expression: Required[str] + + name: Required[str] + + target: Required[AutomationTargetParam] + + timezone: Required[str] + + type: Required[Literal["periodic"]] + + metadata: AutomationMetadataParam + + +class CreateAutomationParamsOnce(TypedDict, total=False): + name: Required[str] + + run_at: Required[int] + + target: Required[AutomationTargetParam] + + type: Required[Literal["once"]] + + metadata: AutomationMetadataParam + + +AutomationCreateParams: TypeAlias = Union[CreateAutomationParamsPeriodic, CreateAutomationParamsOnce] diff --git a/src/openai/types/beta/agents/automation_created_by.py b/src/openai/types/beta/agents/automation_created_by.py new file mode 100644 index 0000000000..3c5c11a224 --- /dev/null +++ b/src/openai/types/beta/agents/automation_created_by.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal, Annotated, TypeAlias + +from ...._utils import PropertyInfo +from ...._models import BaseModel + +__all__ = ["AutomationCreatedBy", "AutomationCreatedByResourceDeveloper", "AutomationCreatedByResourceAgent"] + + +class AutomationCreatedByResourceDeveloper(BaseModel): + type: Literal["developer"] + """The type of the object. Always `developer`.""" + + +class AutomationCreatedByResourceAgent(BaseModel): + session_id: str + """The creator session, which is also the automation's target.""" + + tool_call_id: str + """The tool call that created the automation.""" + + type: Literal["agent"] + """The type of the object. Always `agent`.""" + + +AutomationCreatedBy: TypeAlias = Annotated[ + Union[AutomationCreatedByResourceDeveloper, AutomationCreatedByResourceAgent], PropertyInfo(discriminator="type") +] diff --git a/src/openai/types/beta/agents/automation_deleted.py b/src/openai/types/beta/agents/automation_deleted.py new file mode 100644 index 0000000000..cc9d826c42 --- /dev/null +++ b/src/openai/types/beta/agents/automation_deleted.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ...._models import BaseModel + +__all__ = ["AutomationDeleted"] + + +class AutomationDeleted(BaseModel): + id: str + """The deleted automation ID.""" + + deleted: bool + """Always true.""" + + object: Literal["agent.automation.deleted"] + """Always `agent.automation.deleted`.""" diff --git a/src/openai/types/beta/agents/automation_environment.py b/src/openai/types/beta/agents/automation_environment.py new file mode 100644 index 0000000000..553bbeca91 --- /dev/null +++ b/src/openai/types/beta/agents/automation_environment.py @@ -0,0 +1,197 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ...._utils import PropertyInfo +from ...._models import BaseModel +from ..hosted_plugin import HostedPlugin + +__all__ = [ + "AutomationEnvironment", + "AutomationEnvironmentResourceNone", + "AutomationEnvironmentResourceOpenAIHosted", + "AutomationEnvironmentResourceOpenAIHostedDesktop", + "AutomationEnvironmentResourceOpenaiHostedFile", + "AutomationEnvironmentResourceOpenAIHostedFileHostedTemplateFileResourceFileID", + "AutomationEnvironmentResourceOpenAIHostedFileHostedTemplateFileResourceInline", + "AutomationEnvironmentResourceOpenAIHostedNetwork", + "AutomationEnvironmentResourceOpenAIHostedPackages", + "AutomationEnvironmentResourceOpenaiHostedSkill", + "AutomationEnvironmentResourceOpenAIHostedSkillHostedTemplateSkillResourceSkillReference", + "AutomationEnvironmentResourceOpenAIHostedSkillHostedTemplateSkillResourceInline", + "AutomationEnvironmentResourceSelfHosted", +] + + +class AutomationEnvironmentResourceNone(BaseModel): + type: Literal["none"] + """The type of the object. Always `none`.""" + + +class AutomationEnvironmentResourceOpenAIHostedDesktop(BaseModel): + """Desktop overrides, or null to inherit the template or creation default.""" + + enabled: bool + """Whether the environment provisions a desktop and browser proxy.""" + + +class AutomationEnvironmentResourceOpenAIHostedFileHostedTemplateFileResourceFileID(BaseModel): + """A project-scoped Files API reference resolved separately for each session.""" + + file_id: str + """The ID of the uploaded file.""" + + path: str + """The file's absolute path inside the environment.""" + + type: Literal["file_id"] + """The type of the object. Always `file_id`.""" + + +class AutomationEnvironmentResourceOpenAIHostedFileHostedTemplateFileResourceInline(BaseModel): + """Metadata for confidential inline file contents.""" + + path: str + """The file's absolute path inside the environment.""" + + size_bytes: int + """The decoded size of the inline file in bytes.""" + + type: Literal["inline"] + """The type of the object. Always `inline`.""" + + +AutomationEnvironmentResourceOpenaiHostedFile: TypeAlias = Annotated[ + Union[ + AutomationEnvironmentResourceOpenAIHostedFileHostedTemplateFileResourceFileID, + AutomationEnvironmentResourceOpenAIHostedFileHostedTemplateFileResourceInline, + ], + PropertyInfo(discriminator="type"), +] + + +class AutomationEnvironmentResourceOpenAIHostedNetwork(BaseModel): + """Network overrides, or null to inherit the template or creation default.""" + + access: Literal["enabled", "disabled", "restricted"] + """The environment's network access mode. + + - `enabled` - Allows unrestricted network access. + - `disabled` - Disables network access. + - `restricted` - Applies the configured domain restrictions. + """ + + allowed_domains: List[str] + """Domains the environment may access when network access is restricted.""" + + +class AutomationEnvironmentResourceOpenAIHostedPackages(BaseModel): + """Package overrides, or null to inherit the template or creation default.""" + + npm: List[str] + """npm packages installed globally in the environment.""" + + python: List[str] + """Python packages installed in the environment.""" + + system: List[str] + """System packages installed in the environment.""" + + +class AutomationEnvironmentResourceOpenAIHostedSkillHostedTemplateSkillResourceSkillReference(BaseModel): + """A skill resolved afresh from the Skills API whenever a session starts.""" + + skill_id: str + """The referenced skill ID.""" + + type: Literal["skill_reference"] + """The type of the object. Always `skill_reference`.""" + + version: Optional[str] = None + """The requested version selector, including `latest`.""" + + +class AutomationEnvironmentResourceOpenAIHostedSkillHostedTemplateSkillResourceInline(BaseModel): + """Safe metadata for an inline skill archive.""" + + description: str + """The skill description declared in `SKILL.md`.""" + + name: str + """The skill name declared in `SKILL.md`.""" + + type: Literal["inline"] + """The type of the object. Always `inline`.""" + + +AutomationEnvironmentResourceOpenaiHostedSkill: TypeAlias = Annotated[ + Union[ + AutomationEnvironmentResourceOpenAIHostedSkillHostedTemplateSkillResourceSkillReference, + AutomationEnvironmentResourceOpenAIHostedSkillHostedTemplateSkillResourceInline, + ], + PropertyInfo(discriminator="type"), +] + + +class AutomationEnvironmentResourceOpenAIHosted(BaseModel): + """ + Hosted environment selection with confidential setup commands and variables omitted. + """ + + capability_directories: Optional[List[str]] = None + """Directory overrides, or null to inherit the template or creation default.""" + + container_size: Optional[Literal["small", "medium", "large"]] = None + """The configured container size, or null to use the creation default.""" + + desktop: Optional[AutomationEnvironmentResourceOpenAIHostedDesktop] = None + """Desktop overrides, or null to inherit the template or creation default.""" + + environment_id: Optional[str] = None + """An existing environment reference, or null when provisioning a new environment.""" + + environment_template_id: Optional[str] = None + """A template reference, or null when no template is selected.""" + + files: Optional[List[AutomationEnvironmentResourceOpenaiHostedFile]] = None + """File overrides, excluding contents, or null to inherit.""" + + network: Optional[AutomationEnvironmentResourceOpenAIHostedNetwork] = None + """Network overrides, or null to inherit the template or creation default.""" + + packages: Optional[AutomationEnvironmentResourceOpenAIHostedPackages] = None + """Package overrides, or null to inherit the template or creation default.""" + + plugins: Optional[List[HostedPlugin]] = None + """Plugin overrides, excluding archive contents, or null to inherit.""" + + skills: Optional[List[AutomationEnvironmentResourceOpenaiHostedSkill]] = None + """Skill overrides, excluding archive contents, or null to inherit.""" + + type: Literal["openai_hosted"] + """The type of the object. Always `openai_hosted`.""" + + +class AutomationEnvironmentResourceSelfHosted(BaseModel): + capability_directories: List[str] + """Directories that expose capabilities to the agent.""" + + environment_id: Optional[str] = None + """An existing registration, or null to create a session-owned environment.""" + + type: Literal["self_hosted"] + """The type of the object. Always `self_hosted`.""" + + workspace_directory: str + """The absolute project directory in the environment.""" + + +AutomationEnvironment: TypeAlias = Annotated[ + Union[ + AutomationEnvironmentResourceNone, + AutomationEnvironmentResourceOpenAIHosted, + AutomationEnvironmentResourceSelfHosted, + ], + PropertyInfo(discriminator="type"), +] diff --git a/src/openai/types/beta/agents/automation_list_params.py b/src/openai/types/beta/agents/automation_list_params.py new file mode 100644 index 0000000000..b7077fbef8 --- /dev/null +++ b/src/openai/types/beta/agents/automation_list_params.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypedDict + +__all__ = ["AutomationListParams"] + + +class AutomationListParams(TypedDict, total=False): + after: str + """Return resources after this resource ID in the selected order.""" + + limit: int + """The maximum number of resources to return, between 1 and 100. Defaults to 20.""" + + order: Literal["asc", "desc"] + """The order in which resources are returned. Defaults to `desc`. + + - `asc` - Returns resources in ascending order. + - `desc` - Returns resources in descending order. + """ + + session_id: str + """Matches existing-session targets, including agent-created automations.""" diff --git a/src/openai/types/beta/agents/automation_metadata_param.py b/src/openai/types/beta/agents/automation_metadata_param.py new file mode 100644 index 0000000000..0120649b37 --- /dev/null +++ b/src/openai/types/beta/agents/automation_metadata_param.py @@ -0,0 +1,10 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict +from typing_extensions import TypeAlias + +__all__ = ["AutomationMetadataParam"] + +AutomationMetadataParam: TypeAlias = Dict[str, str] diff --git a/src/openai/types/beta/agents/automation_target.py b/src/openai/types/beta/agents/automation_target.py new file mode 100644 index 0000000000..37d10f3926 --- /dev/null +++ b/src/openai/types/beta/agents/automation_target.py @@ -0,0 +1,70 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ...._utils import PropertyInfo +from ...._models import BaseModel +from ..input_content import InputContent +from .automation_environment import AutomationEnvironment +from .automation_agent_config import AutomationAgentConfig + +__all__ = [ + "AutomationTarget", + "AutomationTargetResourceNewSession", + "AutomationTargetResourceNewSessionInput", + "AutomationTargetResourceExistingSession", +] + + +class AutomationTargetResourceNewSessionInput(BaseModel): + """A user message recorded in a session.""" + + content: List[InputContent] + """The content of the message.""" + + role: Literal["user"] + """The role of the message author. Always `user`.""" + + type: Literal["message"] + """The type of the input item. Always `message`.""" + + +class AutomationTargetResourceNewSession(BaseModel): + agent: Optional[AutomationAgentConfig] = None + """The inline agent configuration, or null when agent_id is configured.""" + + agent_id: Optional[str] = None + """The saved agent reference, or null when an inline agent is configured.""" + + environment: AutomationEnvironment + """Configuration or references used to select the execution environment.""" + + input: List[AutomationTargetResourceNewSessionInput] + """Initial input delivered to each new session.""" + + metadata: Dict[str, str] + """Metadata attached to each new session.""" + + type: Literal["new_session"] + """The type of the object. Always `new_session`.""" + + vault_ids: List[str] + """Vaults made available to each new session.""" + + +class AutomationTargetResourceExistingSession(BaseModel): + instructions: str + """Saved instructions delivered as an automation notification.""" + + session_id: str + """The session receiving each invocation.""" + + type: Literal["existing_session"] + """The type of the object. Always `existing_session`.""" + + +AutomationTarget: TypeAlias = Annotated[ + Union[AutomationTargetResourceNewSession, AutomationTargetResourceExistingSession], + PropertyInfo(discriminator="type"), +] diff --git a/src/openai/types/beta/agents/automation_target_param.py b/src/openai/types/beta/agents/automation_target_param.py new file mode 100644 index 0000000000..88e810691a --- /dev/null +++ b/src/openai/types/beta/agents/automation_target_param.py @@ -0,0 +1,106 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Iterable, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from ...._types import SequenceNotStr +from ..agent_text_param import AgentTextParam +from ..agent_tool_param import AgentToolParam +from ..environment_param import EnvironmentParam +from ..agent_reasoning_param import AgentReasoningParam +from ..multi_agent_config_param import MultiAgentConfigParam +from ..agent_session_input_message_param import AgentSessionInputMessageParam + +__all__ = [ + "AutomationTargetParam", + "AutomationTargetParamNewSession", + "AutomationTargetParamNewSessionAgent", + "AutomationTargetParamExistingSession", +] + + +class AutomationTargetParamNewSessionAgent(TypedDict, total=False): + """Inline agent configuration. Provide exactly one of agent and agent_id.""" + + instructions: Optional[str] + """Additional instructions appended to the agent's default base instructions. + + Omit to leave unchanged. + """ + + model: str + """The model to use for the agent. The requested model name is preserved.""" + + multi_agent: Optional[MultiAgentConfigParam] + """Configuration for creating and coordinating subagents.""" + + reasoning: Optional[AgentReasoningParam] + """Configuration for model reasoning. + + Omit to keep the current settings; pass `null` to reset to the model's default + effort. + """ + + service_tier: Optional[Literal["auto", "default", "flex", "priority", "fast", "ultrafast"]] + """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. + """ + + text: Optional[AgentTextParam] + """Configuration for text generated by the agent.""" + + tools: Optional[Iterable[AgentToolParam]] + """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. + """ + + +class AutomationTargetParamNewSession(TypedDict, total=False): + """Create a session for each invocation.""" + + environment: Required[EnvironmentParam] + """The execution environment for each new session.""" + + input: Required[Iterable[AgentSessionInputMessageParam]] + """Initial user messages submitted with each new session.""" + + type: Required[Literal["new_session"]] + """The type of the object. Always `new_session`.""" + + agent: AutomationTargetParamNewSessionAgent + """Inline agent configuration. Provide exactly one of agent and agent_id.""" + + agent_id: str + """A saved agent ID. Provide exactly one of agent and agent_id.""" + + metadata: Optional[Dict[str, str]] + """Metadata attached to each new session.""" + + vault_ids: Optional[SequenceNotStr[str]] + """The IDs of vaults made available to each new session.""" + + +class AutomationTargetParamExistingSession(TypedDict, total=False): + """Deliver instructions to an existing session.""" + + instructions: Required[str] + """Instructions delivered as an automation notification.""" + + session_id: Required[str] + """The session receiving each invocation.""" + + type: Required[Literal["existing_session"]] + """The type of the object. Always `existing_session`.""" + + +AutomationTargetParam: TypeAlias = Union[AutomationTargetParamNewSession, AutomationTargetParamExistingSession] diff --git a/src/openai/types/beta/agents/automation_update_params.py b/src/openai/types/beta/agents/automation_update_params.py new file mode 100644 index 0000000000..8b8c732a6a --- /dev/null +++ b/src/openai/types/beta/agents/automation_update_params.py @@ -0,0 +1,32 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict +from typing_extensions import TypedDict + +from .automation_target_param import AutomationTargetParam + +__all__ = ["AutomationUpdateParams"] + + +class AutomationUpdateParams(TypedDict, total=False): + expression: str + """Only accepted for periodic automations.""" + + metadata: Dict[str, str] + """Replaces all metadata; omit to leave unchanged.""" + + name: str + + run_at: int + """ + A future Unix timestamp in seconds; accepted only before a one-time scheduled + invocation exists. + """ + + target: AutomationTargetParam + """Replaces the complete target, retaining its type and any creator session.""" + + timezone: str + """Only accepted for periodic automations.""" diff --git a/src/openai/types/beta/agents/automations/__init__.py b/src/openai/types/beta/agents/automations/__init__.py new file mode 100644 index 0000000000..597235a76e --- /dev/null +++ b/src/openai/types/beta/agents/automations/__init__.py @@ -0,0 +1,7 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .automation_invocation import AutomationInvocation as AutomationInvocation +from .invocation_list_params import InvocationListParams as InvocationListParams +from .automation_invocation_source import AutomationInvocationSource as AutomationInvocationSource diff --git a/src/openai/types/beta/agents/automations/automation_invocation.py b/src/openai/types/beta/agents/automations/automation_invocation.py new file mode 100644 index 0000000000..48ffc1a132 --- /dev/null +++ b/src/openai/types/beta/agents/automations/automation_invocation.py @@ -0,0 +1,55 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ....._models import BaseModel +from .automation_invocation_source import AutomationInvocationSource + +__all__ = ["AutomationInvocation", "Error"] + + +class Error(BaseModel): + """The permanent delivery failure, or null when no failure occurred.""" + + code: str + """A machine-readable error code.""" + + message: str + """A public explanation of the delivery failure.""" + + +class AutomationInvocation(BaseModel): + """One attempted delivery by an automation.""" + + id: str + """The invocation ID.""" + + automation_id: str + """The automation that owns the invocation.""" + + created_at: int + """The creation time as a Unix timestamp in seconds.""" + + error: Optional[Error] = None + """The permanent delivery failure, or null when no failure occurred.""" + + object: Literal["agent.automation.invocation"] + """Always `agent.automation.invocation`.""" + + scheduled_at: Optional[int] = None + """ + The intended occurrence as a Unix timestamp in seconds, or null for manual runs. + """ + + session_id: Optional[str] = None + """The target or newly created session ID, or null before one is available.""" + + skip_reason: Optional[Literal["pending_delivery"]] = None + """Why an occurrence was skipped, or null when it was not skipped.""" + + source: AutomationInvocationSource + """Whether the invocation was manual or scheduled.""" + + status: Literal["queued", "completed", "failed", "skipped"] + """Delivery status; completed does not mean the agent's work has finished.""" diff --git a/src/openai/types/beta/agents/automations/automation_invocation_source.py b/src/openai/types/beta/agents/automations/automation_invocation_source.py new file mode 100644 index 0000000000..d0e3738d95 --- /dev/null +++ b/src/openai/types/beta/agents/automations/automation_invocation_source.py @@ -0,0 +1,33 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal, Annotated, TypeAlias + +from ....._utils import PropertyInfo +from ....._models import BaseModel +from ..automation import Automation + +__all__ = [ + "AutomationInvocationSource", + "AutomationInvocationSourceResourceManual", + "AutomationInvocationSourceResourceAutomation", +] + + +class AutomationInvocationSourceResourceManual(BaseModel): + type: Literal["manual"] + """The type of the object. Always `manual`.""" + + +class AutomationInvocationSourceResourceAutomation(BaseModel): + automation: Automation + """The automation snapshot for this occurrence, excluding confidential values.""" + + type: Literal["automation"] + """The type of the object. Always `automation`.""" + + +AutomationInvocationSource: TypeAlias = Annotated[ + Union[AutomationInvocationSourceResourceManual, AutomationInvocationSourceResourceAutomation], + PropertyInfo(discriminator="type"), +] diff --git a/src/openai/types/beta/agents/automations/invocation_list_params.py b/src/openai/types/beta/agents/automations/invocation_list_params.py new file mode 100644 index 0000000000..a318dbf070 --- /dev/null +++ b/src/openai/types/beta/agents/automations/invocation_list_params.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypedDict + +__all__ = ["InvocationListParams"] + + +class InvocationListParams(TypedDict, total=False): + after: str + """Return resources after this resource ID in the selected order.""" + + limit: int + """The maximum number of resources to return, between 1 and 100. Defaults to 20.""" + + order: Literal["asc", "desc"] + """The order in which resources are returned. Defaults to `desc`. + + - `asc` - Returns resources in ascending order. + - `desc` - Returns resources in descending order. + """ diff --git a/src/openai/types/beta/agents/one_time_automation.py b/src/openai/types/beta/agents/one_time_automation.py new file mode 100644 index 0000000000..b2184a3935 --- /dev/null +++ b/src/openai/types/beta/agents/one_time_automation.py @@ -0,0 +1,44 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from typing import Dict +from typing_extensions import Literal + +from ...._models import BaseModel +from .automation_target import AutomationTarget +from .automation_created_by import AutomationCreatedBy + +__all__ = ["OneTimeAutomation"] + + +class OneTimeAutomation(BaseModel): + """Fields shared by periodic and one-time automations.""" + + id: str + """The automation ID.""" + + created_at: int + """The creation time as a Unix timestamp in seconds.""" + + created_by: AutomationCreatedBy + """Service-recorded provenance; callers cannot supply this field.""" + + metadata: Dict[str, str] + """Custom string key-value pairs attached to the automation.""" + + name: str + """The automation's display name.""" + + object: Literal["agent.automation"] + """Always `agent.automation`.""" + + run_at: int + """The Unix timestamp, in seconds, of the scheduled occurrence.""" + + status: Literal["active", "paused", "completed"] + """Completion means the schedule has finished, not the agent's work.""" + + target: AutomationTarget + """The session configuration or existing session receiving invocations.""" + + type: Literal["once"] + """The type of the object. Always `once`.""" diff --git a/src/openai/types/beta/agents/periodic_automation.py b/src/openai/types/beta/agents/periodic_automation.py new file mode 100644 index 0000000000..1a46a7abb3 --- /dev/null +++ b/src/openai/types/beta/agents/periodic_automation.py @@ -0,0 +1,47 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from typing import Dict +from typing_extensions import Literal + +from ...._models import BaseModel +from .automation_target import AutomationTarget +from .automation_created_by import AutomationCreatedBy + +__all__ = ["PeriodicAutomation"] + + +class PeriodicAutomation(BaseModel): + """Fields shared by periodic and one-time automations.""" + + id: str + """The automation ID.""" + + created_at: int + """The creation time as a Unix timestamp in seconds.""" + + created_by: AutomationCreatedBy + """Service-recorded provenance; callers cannot supply this field.""" + + expression: str + """The cron expression determining scheduled occurrences.""" + + metadata: Dict[str, str] + """Custom string key-value pairs attached to the automation.""" + + name: str + """The automation's display name.""" + + object: Literal["agent.automation"] + """Always `agent.automation`.""" + + status: Literal["active", "paused"] + """Whether scheduled delivery is active or paused.""" + + target: AutomationTarget + """The session configuration or existing session receiving invocations.""" + + timezone: str + """The timezone used to interpret the expression.""" + + type: Literal["periodic"] + """The type of the object. Always `periodic`.""" diff --git a/src/openai/types/beta/beta_response_input_file.py b/src/openai/types/beta/beta_response_input_file.py index 37661b60d5..55084bb2a4 100644 --- a/src/openai/types/beta/beta_response_input_file.py +++ b/src/openai/types/beta/beta_response_input_file.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class BetaResponseInputFile(BaseModel): """A file input to the model.""" diff --git a/src/openai/types/beta/beta_response_input_file_content.py b/src/openai/types/beta/beta_response_input_file_content.py index 5f2f96dd96..3e816bca7a 100644 --- a/src/openai/types/beta/beta_response_input_file_content.py +++ b/src/openai/types/beta/beta_response_input_file_content.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class BetaResponseInputFileContent(BaseModel): """A file input to the model.""" diff --git a/src/openai/types/beta/beta_response_input_file_content_param.py b/src/openai/types/beta/beta_response_input_file_content_param.py index ccc9a7426a..33b8c7c5b1 100644 --- a/src/openai/types/beta/beta_response_input_file_content_param.py +++ b/src/openai/types/beta/beta_response_input_file_content_param.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class BetaResponseInputFileContentParam(TypedDict, total=False): """A file input to the model.""" diff --git a/src/openai/types/beta/beta_response_input_file_param.py b/src/openai/types/beta/beta_response_input_file_param.py index 12d226ed36..034f26d03f 100644 --- a/src/openai/types/beta/beta_response_input_file_param.py +++ b/src/openai/types/beta/beta_response_input_file_param.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class BetaResponseInputFileParam(TypedDict, total=False): """A file input to the model.""" diff --git a/src/openai/types/beta/beta_response_input_image.py b/src/openai/types/beta/beta_response_input_image.py index 81da7d63f4..70b6f32b65 100644 --- a/src/openai/types/beta/beta_response_input_image.py +++ b/src/openai/types/beta/beta_response_input_image.py @@ -18,6 +18,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class BetaResponseInputImage(BaseModel): """An image input to the model. diff --git a/src/openai/types/beta/beta_response_input_image_content.py b/src/openai/types/beta/beta_response_input_image_content.py index 532c65d14f..ae4631afe6 100644 --- a/src/openai/types/beta/beta_response_input_image_content.py +++ b/src/openai/types/beta/beta_response_input_image_content.py @@ -18,6 +18,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class BetaResponseInputImageContent(BaseModel): """An image input to the model. diff --git a/src/openai/types/beta/beta_response_input_image_content_param.py b/src/openai/types/beta/beta_response_input_image_content_param.py index 03e343c788..bd0a5c78f3 100644 --- a/src/openai/types/beta/beta_response_input_image_content_param.py +++ b/src/openai/types/beta/beta_response_input_image_content_param.py @@ -19,6 +19,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class BetaResponseInputImageContentParam(TypedDict, total=False): """An image input to the model. diff --git a/src/openai/types/beta/beta_response_input_image_param.py b/src/openai/types/beta/beta_response_input_image_param.py index cabe60f743..97ba647010 100644 --- a/src/openai/types/beta/beta_response_input_image_param.py +++ b/src/openai/types/beta/beta_response_input_image_param.py @@ -19,6 +19,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class BetaResponseInputImageParam(TypedDict, total=False): """An image input to the model. diff --git a/src/openai/types/beta/beta_response_input_text.py b/src/openai/types/beta/beta_response_input_text.py index 51b1a5eeef..8c97d83d41 100644 --- a/src/openai/types/beta/beta_response_input_text.py +++ b/src/openai/types/beta/beta_response_input_text.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class BetaResponseInputText(BaseModel): """A text input to the model.""" diff --git a/src/openai/types/beta/beta_response_input_text_content.py b/src/openai/types/beta/beta_response_input_text_content.py index 9b8e5a65d6..d29d388a44 100644 --- a/src/openai/types/beta/beta_response_input_text_content.py +++ b/src/openai/types/beta/beta_response_input_text_content.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class BetaResponseInputTextContent(BaseModel): """A text input to the model.""" diff --git a/src/openai/types/beta/beta_response_input_text_content_param.py b/src/openai/types/beta/beta_response_input_text_content_param.py index b1003c3892..dad7072a9a 100644 --- a/src/openai/types/beta/beta_response_input_text_content_param.py +++ b/src/openai/types/beta/beta_response_input_text_content_param.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class BetaResponseInputTextContentParam(TypedDict, total=False): """A text input to the model.""" diff --git a/src/openai/types/beta/beta_response_input_text_param.py b/src/openai/types/beta/beta_response_input_text_param.py index e9ceb8830c..071ca2268e 100644 --- a/src/openai/types/beta/beta_response_input_text_param.py +++ b/src/openai/types/beta/beta_response_input_text_param.py @@ -16,6 +16,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class BetaResponseInputTextParam(TypedDict, total=False): """A text input to the model.""" diff --git a/src/openai/types/beta/beta_response_item.py b/src/openai/types/beta/beta_response_item.py index 6a9e3049c2..cbdf9a622f 100644 --- a/src/openai/types/beta/beta_response_item.py +++ b/src/openai/types/beta/beta_response_item.py @@ -113,6 +113,9 @@ class AgentMessageContentComputerScreenshotPromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class AgentMessageContentComputerScreenshot(BaseModel): """A screenshot of a computer.""" diff --git a/src/openai/types/beta/beta_response_output_item.py b/src/openai/types/beta/beta_response_output_item.py index 025d72f2fb..d1d7211481 100644 --- a/src/openai/types/beta/beta_response_output_item.py +++ b/src/openai/types/beta/beta_response_output_item.py @@ -111,6 +111,9 @@ class AgentMessageContentComputerScreenshotPromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class AgentMessageContentComputerScreenshot(BaseModel): """A screenshot of a computer.""" diff --git a/src/openai/types/beta/persisted_agent_tool.py b/src/openai/types/beta/persisted_agent_tool.py index 422445d8b5..136ee6a24f 100644 --- a/src/openai/types/beta/persisted_agent_tool.py +++ b/src/openai/types/beta/persisted_agent_tool.py @@ -16,6 +16,7 @@ "PersistedAgentToolResourceWebSearch", "PersistedAgentToolResourceWebSearchLocation", "PersistedAgentToolResourceComputerUse", + "PersistedAgentToolResourceAutomations", ] @@ -128,6 +129,13 @@ class PersistedAgentToolResourceComputerUse(BaseModel): """The type of the object. Always `computer_use`.""" +class PersistedAgentToolResourceAutomations(BaseModel): + """Lets the agent manage its own scheduled wakeups.""" + + type: Literal["automations"] + """The type of the object. Always `automations`.""" + + PersistedAgentTool: TypeAlias = Annotated[ Union[ PersistedAgentToolResourceFunction, @@ -136,6 +144,7 @@ class PersistedAgentToolResourceComputerUse(BaseModel): PersistedAgentToolResourceMcp, PersistedAgentToolResourceWebSearch, PersistedAgentToolResourceComputerUse, + PersistedAgentToolResourceAutomations, ], PropertyInfo(discriminator="type"), ] diff --git a/src/openai/types/beta/persisted_agent_tool_param.py b/src/openai/types/beta/persisted_agent_tool_param.py index b61830bf73..2e49b46e4f 100644 --- a/src/openai/types/beta/persisted_agent_tool_param.py +++ b/src/openai/types/beta/persisted_agent_tool_param.py @@ -17,6 +17,7 @@ "PersistedAgentToolConfigParamWebSearch", "PersistedAgentToolConfigParamWebSearchLocation", "PersistedAgentToolConfigParamComputerUse", + "PersistedAgentToolConfigParamAutomations", ] @@ -147,6 +148,13 @@ class PersistedAgentToolConfigParamComputerUse(TypedDict, total=False): """Whether computer tool outputs include screenshots. Defaults to `false`.""" +class PersistedAgentToolConfigParamAutomations(TypedDict, total=False): + """Lets the agent manage its own scheduled wakeups.""" + + type: Required[Literal["automations"]] + """The type of the object. Always `automations`.""" + + PersistedAgentToolParam: TypeAlias = Union[ PersistedAgentToolConfigParamFunction, PersistedAgentToolConfigParamToolSearch, @@ -154,4 +162,5 @@ class PersistedAgentToolConfigParamComputerUse(TypedDict, total=False): PersistedAgentToolConfigParamMcp, PersistedAgentToolConfigParamWebSearch, PersistedAgentToolConfigParamComputerUse, + PersistedAgentToolConfigParamAutomations, ] diff --git a/src/openai/types/chat/chat_completion_content_part_image.py b/src/openai/types/chat/chat_completion_content_part_image.py index 20951fc3ad..82e553d845 100644 --- a/src/openai/types/chat/chat_completion_content_part_image.py +++ b/src/openai/types/chat/chat_completion_content_part_image.py @@ -29,6 +29,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ChatCompletionContentPartImage(BaseModel): """ diff --git a/src/openai/types/chat/chat_completion_content_part_image_param.py b/src/openai/types/chat/chat_completion_content_part_image_param.py index 067cd7a14b..a8e8e7276b 100644 --- a/src/openai/types/chat/chat_completion_content_part_image_param.py +++ b/src/openai/types/chat/chat_completion_content_part_image_param.py @@ -28,6 +28,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ChatCompletionContentPartImageParam(TypedDict, total=False): """ diff --git a/src/openai/types/chat/chat_completion_content_part_input_audio_param.py b/src/openai/types/chat/chat_completion_content_part_input_audio_param.py index e14bf35115..0f3076e1f6 100644 --- a/src/openai/types/chat/chat_completion_content_part_input_audio_param.py +++ b/src/openai/types/chat/chat_completion_content_part_input_audio_param.py @@ -24,6 +24,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ChatCompletionContentPartInputAudioParam(TypedDict, total=False): """ diff --git a/src/openai/types/chat/chat_completion_content_part_param.py b/src/openai/types/chat/chat_completion_content_part_param.py index cc34b7cb5e..192794e88c 100644 --- a/src/openai/types/chat/chat_completion_content_part_param.py +++ b/src/openai/types/chat/chat_completion_content_part_param.py @@ -35,6 +35,9 @@ class FilePromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class File(TypedDict, total=False): """ diff --git a/src/openai/types/chat/chat_completion_content_part_text.py b/src/openai/types/chat/chat_completion_content_part_text.py index 590b95aea1..ffd2ffecfc 100644 --- a/src/openai/types/chat/chat_completion_content_part_text.py +++ b/src/openai/types/chat/chat_completion_content_part_text.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ChatCompletionContentPartText(BaseModel): """Learn about [text inputs](https://developers.openai.com/api/docs/guides/text).""" diff --git a/src/openai/types/chat/chat_completion_content_part_text_param.py b/src/openai/types/chat/chat_completion_content_part_text_param.py index adee12ec16..2c3e8321fb 100644 --- a/src/openai/types/chat/chat_completion_content_part_text_param.py +++ b/src/openai/types/chat/chat_completion_content_part_text_param.py @@ -16,6 +16,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ChatCompletionContentPartTextParam(TypedDict, total=False): """Learn about [text inputs](https://developers.openai.com/api/docs/guides/text).""" diff --git a/src/openai/types/conversations/computer_screenshot_content.py b/src/openai/types/conversations/computer_screenshot_content.py index b2fc076c44..75afcec376 100644 --- a/src/openai/types/conversations/computer_screenshot_content.py +++ b/src/openai/types/conversations/computer_screenshot_content.py @@ -18,6 +18,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ComputerScreenshotContent(BaseModel): """A screenshot of a computer.""" diff --git a/src/openai/types/live/client_delegation.py b/src/openai/types/live/client_delegation.py index 6826f18f07..a3a6e20c7c 100644 --- a/src/openai/types/live/client_delegation.py +++ b/src/openai/types/live/client_delegation.py @@ -1,5 +1,6 @@ # File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. +from typing import Optional from typing_extensions import Literal from ..._models import BaseModel @@ -15,3 +16,13 @@ class ClientDelegation(BaseModel): type: Literal["client"] """The delegation owner. Always `client` for tasks handled by your application.""" + + acknowledgement_delay_ms: Optional[int] = None + """ + 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. + """ diff --git a/src/openai/types/live/client_delegation_param.py b/src/openai/types/live/client_delegation_param.py index 018c8add78..bd919967a2 100644 --- a/src/openai/types/live/client_delegation_param.py +++ b/src/openai/types/live/client_delegation_param.py @@ -15,3 +15,13 @@ class ClientDelegationParam(TypedDict, total=False): type: Required[Literal["client"]] """The delegation owner. Always `client` for tasks handled by your application.""" + + acknowledgement_delay_ms: int + """ + 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. + """ diff --git a/src/openai/types/live/fork_session_config.py b/src/openai/types/live/fork_session_config.py index 4529bdfc3b..be59cfa035 100644 --- a/src/openai/types/live/fork_session_config.py +++ b/src/openai/types/live/fork_session_config.py @@ -36,6 +36,16 @@ class Delegation(BaseModel): Always `responses` for tasks handled by the Responses API. """ + acknowledgement_delay_ms: Optional[int] = None + """ + 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. + """ + responses: Optional[ResponsesDelegationUpdateConfig] = None """Responses backend settings to update. diff --git a/src/openai/types/live/fork_session_config_param.py b/src/openai/types/live/fork_session_config_param.py index 089748640e..bfc73e3e54 100644 --- a/src/openai/types/live/fork_session_config_param.py +++ b/src/openai/types/live/fork_session_config_param.py @@ -36,6 +36,16 @@ class Delegation(TypedDict, total=False): Always `responses` for tasks handled by the Responses API. """ + acknowledgement_delay_ms: int + """ + 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. + """ + responses: ResponsesDelegationUpdateConfigParam """Responses backend settings to update. diff --git a/src/openai/types/live/media_session_config_param.py b/src/openai/types/live/media_session_config_param.py index 221037a655..4c1dbf3899 100644 --- a/src/openai/types/live/media_session_config_param.py +++ b/src/openai/types/live/media_session_config_param.py @@ -68,12 +68,31 @@ class DelegationResponses(TypedDict, total=False): Always `responses` for tasks handled by the Responses API. """ + acknowledgement_delay_ms: int + """ + 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. + """ + class DelegationDecisions(TypedDict, total=False): decisions: Required[DecisionsDelegationConfigParam] type: Required[Literal["decisions"]] + acknowledgement_delay_ms: int + """ + 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. + """ + Delegation: TypeAlias = Union[ClientDelegationParam, DelegationResponses, DelegationDecisions] diff --git a/src/openai/types/live/media_session_fork_config_param.py b/src/openai/types/live/media_session_fork_config_param.py index 3bc95297f3..874e9b3327 100644 --- a/src/openai/types/live/media_session_fork_config_param.py +++ b/src/openai/types/live/media_session_fork_config_param.py @@ -21,6 +21,16 @@ class Delegation(TypedDict, total=False): Always `responses` for tasks handled by the Responses API. """ + acknowledgement_delay_ms: int + """ + 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. + """ + responses: ResponsesDelegationUpdateConfigParam """Responses backend settings to update. diff --git a/src/openai/types/live/session_accept_params.py b/src/openai/types/live/session_accept_params.py index 31cfa363d2..e024b92f71 100644 --- a/src/openai/types/live/session_accept_params.py +++ b/src/openai/types/live/session_accept_params.py @@ -77,12 +77,31 @@ class SessionDelegationResponses(TypedDict, total=False): Always `responses` for tasks handled by the Responses API. """ + acknowledgement_delay_ms: int + """ + 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. + """ + class SessionDelegationDecisions(TypedDict, total=False): decisions: Required[DecisionsDelegationConfigParam] type: Required[Literal["decisions"]] + acknowledgement_delay_ms: int + """ + 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. + """ + SessionDelegation: TypeAlias = Union[ClientDelegationParam, SessionDelegationResponses, SessionDelegationDecisions] diff --git a/src/openai/types/live/session_config.py b/src/openai/types/live/session_config.py index 5725586def..41cbfbc16e 100644 --- a/src/openai/types/live/session_config.py +++ b/src/openai/types/live/session_config.py @@ -69,12 +69,31 @@ class DelegationResponses(BaseModel): Always `responses` for tasks handled by the Responses API. """ + acknowledgement_delay_ms: Optional[int] = None + """ + 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. + """ + class DelegationDecisions(BaseModel): decisions: DecisionsDelegationConfig type: Literal["decisions"] + acknowledgement_delay_ms: Optional[int] = None + """ + 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. + """ + Delegation: TypeAlias = Annotated[ Union[ClientDelegation, DelegationResponses, DelegationDecisions, None], PropertyInfo(discriminator="type") diff --git a/src/openai/types/live/session_config_param.py b/src/openai/types/live/session_config_param.py index f62a83e4bc..7f1887c71e 100644 --- a/src/openai/types/live/session_config_param.py +++ b/src/openai/types/live/session_config_param.py @@ -69,12 +69,31 @@ class DelegationResponses(TypedDict, total=False): Always `responses` for tasks handled by the Responses API. """ + acknowledgement_delay_ms: int + """ + 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. + """ + class DelegationDecisions(TypedDict, total=False): decisions: Required[DecisionsDelegationConfigParam] type: Required[Literal["decisions"]] + acknowledgement_delay_ms: int + """ + 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. + """ + Delegation: TypeAlias = Union[ClientDelegationParam, DelegationResponses, DelegationDecisions] diff --git a/src/openai/types/live/session_resource.py b/src/openai/types/live/session_resource.py index 3f5f494c22..0f8d85df72 100644 --- a/src/openai/types/live/session_resource.py +++ b/src/openai/types/live/session_resource.py @@ -69,12 +69,31 @@ class DelegationResponses(BaseModel): Always `responses` for tasks handled by the Responses API. """ + acknowledgement_delay_ms: Optional[int] = None + """ + 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. + """ + class DelegationDecisions(BaseModel): decisions: DecisionsDelegationConfig type: Literal["decisions"] + acknowledgement_delay_ms: Optional[int] = None + """ + 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. + """ + Delegation: TypeAlias = Annotated[ Union[ClientDelegation, DelegationResponses, DelegationDecisions, None], PropertyInfo(discriminator="type") diff --git a/src/openai/types/live/session_update_config.py b/src/openai/types/live/session_update_config.py index eb6e586547..c89eb7c593 100644 --- a/src/openai/types/live/session_update_config.py +++ b/src/openai/types/live/session_update_config.py @@ -24,6 +24,16 @@ class DelegationResponses(BaseModel): Always `responses` for tasks handled by the Responses API. """ + acknowledgement_delay_ms: Optional[int] = None + """ + 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. + """ + responses: Optional[ResponsesDelegationUpdateConfig] = None """Responses backend settings to update. @@ -34,6 +44,16 @@ class DelegationResponses(BaseModel): class DelegationDecisions(BaseModel): type: Literal["decisions"] + acknowledgement_delay_ms: Optional[int] = None + """ + 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. + """ + decisions: Optional[DecisionsDelegationUpdateConfig] = None diff --git a/src/openai/types/live/session_update_config_param.py b/src/openai/types/live/session_update_config_param.py index 7f32c98a9e..686e7b8ef2 100644 --- a/src/openai/types/live/session_update_config_param.py +++ b/src/openai/types/live/session_update_config_param.py @@ -24,6 +24,16 @@ class DelegationResponses(TypedDict, total=False): Always `responses` for tasks handled by the Responses API. """ + acknowledgement_delay_ms: int + """ + 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. + """ + responses: ResponsesDelegationUpdateConfigParam """Responses backend settings to update. @@ -34,6 +44,16 @@ class DelegationResponses(TypedDict, total=False): class DelegationDecisions(TypedDict, total=False): type: Required[Literal["decisions"]] + acknowledgement_delay_ms: int + """ + 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. + """ + decisions: DecisionsDelegationUpdateConfigParam diff --git a/src/openai/types/realtime/conversation_item_input_audio_transcription_delta_event.py b/src/openai/types/realtime/conversation_item_input_audio_transcription_delta_event.py index 73d15e2271..6e528de19d 100644 --- a/src/openai/types/realtime/conversation_item_input_audio_transcription_delta_event.py +++ b/src/openai/types/realtime/conversation_item_input_audio_transcription_delta_event.py @@ -32,7 +32,7 @@ class ConversationItemInputAudioTranscriptionDeltaEvent(BaseModel): logprobs: Optional[List[LogProbProperties]] = None """The log probabilities of the transcription. - These can be enabled by configurating the session with + 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 diff --git a/src/openai/types/realtime/realtime_error_event.py b/src/openai/types/realtime/realtime_error_event.py index e9b6933df1..1cd8636d0b 100644 --- a/src/openai/types/realtime/realtime_error_event.py +++ b/src/openai/types/realtime/realtime_error_event.py @@ -12,7 +12,7 @@ class RealtimeErrorEvent(BaseModel): """ 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. """ error: RealtimeError diff --git a/src/openai/types/responses/response_input_file.py b/src/openai/types/responses/response_input_file.py index 6337f4e0f1..549419339e 100644 --- a/src/openai/types/responses/response_input_file.py +++ b/src/openai/types/responses/response_input_file.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ResponseInputFile(BaseModel): """A file input to the model.""" diff --git a/src/openai/types/responses/response_input_file_content.py b/src/openai/types/responses/response_input_file_content.py index 685d751626..1c83786a1f 100644 --- a/src/openai/types/responses/response_input_file_content.py +++ b/src/openai/types/responses/response_input_file_content.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ResponseInputFileContent(BaseModel): """A file input to the model.""" diff --git a/src/openai/types/responses/response_input_file_content_param.py b/src/openai/types/responses/response_input_file_content_param.py index 07c7f9ffe7..b85f301cfe 100644 --- a/src/openai/types/responses/response_input_file_content_param.py +++ b/src/openai/types/responses/response_input_file_content_param.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ResponseInputFileContentParam(TypedDict, total=False): """A file input to the model.""" diff --git a/src/openai/types/responses/response_input_file_param.py b/src/openai/types/responses/response_input_file_param.py index a78fe28623..6e9afcd84a 100644 --- a/src/openai/types/responses/response_input_file_param.py +++ b/src/openai/types/responses/response_input_file_param.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ResponseInputFileParam(TypedDict, total=False): """A file input to the model.""" diff --git a/src/openai/types/responses/response_input_image.py b/src/openai/types/responses/response_input_image.py index 8efb56f76f..364459bffc 100644 --- a/src/openai/types/responses/response_input_image.py +++ b/src/openai/types/responses/response_input_image.py @@ -18,6 +18,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ResponseInputImage(BaseModel): """An image input to the model. diff --git a/src/openai/types/responses/response_input_image_content.py b/src/openai/types/responses/response_input_image_content.py index 999a9dfe9f..1b89fa5c10 100644 --- a/src/openai/types/responses/response_input_image_content.py +++ b/src/openai/types/responses/response_input_image_content.py @@ -18,6 +18,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ResponseInputImageContent(BaseModel): """An image input to the model. diff --git a/src/openai/types/responses/response_input_image_content_param.py b/src/openai/types/responses/response_input_image_content_param.py index a045fc579b..fed5dcb614 100644 --- a/src/openai/types/responses/response_input_image_content_param.py +++ b/src/openai/types/responses/response_input_image_content_param.py @@ -19,6 +19,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ResponseInputImageContentParam(TypedDict, total=False): """An image input to the model. diff --git a/src/openai/types/responses/response_input_image_param.py b/src/openai/types/responses/response_input_image_param.py index dc99692124..018d1272ba 100644 --- a/src/openai/types/responses/response_input_image_param.py +++ b/src/openai/types/responses/response_input_image_param.py @@ -19,6 +19,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ResponseInputImageParam(TypedDict, total=False): """An image input to the model. diff --git a/src/openai/types/responses/response_input_text.py b/src/openai/types/responses/response_input_text.py index 028f506ee1..f7fbe38680 100644 --- a/src/openai/types/responses/response_input_text.py +++ b/src/openai/types/responses/response_input_text.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ResponseInputText(BaseModel): """A text input to the model.""" diff --git a/src/openai/types/responses/response_input_text_content.py b/src/openai/types/responses/response_input_text_content.py index 354b92d891..393e894f38 100644 --- a/src/openai/types/responses/response_input_text_content.py +++ b/src/openai/types/responses/response_input_text_content.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(BaseModel): mode: Literal["explicit"] """The breakpoint mode. Always `explicit`.""" + ttl: Optional[Literal["30m", "12h"]] = None + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ResponseInputTextContent(BaseModel): """A text input to the model.""" diff --git a/src/openai/types/responses/response_input_text_content_param.py b/src/openai/types/responses/response_input_text_content_param.py index 3044469711..71622e7777 100644 --- a/src/openai/types/responses/response_input_text_content_param.py +++ b/src/openai/types/responses/response_input_text_content_param.py @@ -17,6 +17,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ResponseInputTextContentParam(TypedDict, total=False): """A text input to the model.""" diff --git a/src/openai/types/responses/response_input_text_param.py b/src/openai/types/responses/response_input_text_param.py index 494be064d0..b15de2e89a 100644 --- a/src/openai/types/responses/response_input_text_param.py +++ b/src/openai/types/responses/response_input_text_param.py @@ -16,6 +16,9 @@ class PromptCacheBreakpoint(TypedDict, total=False): mode: Required[Literal["explicit"]] """The breakpoint mode. Always `explicit`.""" + ttl: Literal["30m", "12h"] + """The minimum lifetime of this cache breakpoint. Defaults to the request TTL.""" + class ResponseInputTextParam(TypedDict, total=False): """A text input to the model.""" diff --git a/src/openai/types/shared/decision_input_json.py b/src/openai/types/shared/decision_input_json.py index 10cc2f67a2..87e999e7ff 100644 --- a/src/openai/types/shared/decision_input_json.py +++ b/src/openai/types/shared/decision_input_json.py @@ -14,6 +14,6 @@ class DecisionInputJSON(BaseModel): Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON. """ - data: Union[Dict[str, Optional[object]], List[Dict[str, Optional[object]]]] + data: Union[List[Dict[str, Optional[object]]], Dict[str, Optional[object]]] type: Literal["input_json"] diff --git a/tests/api_resources/audio/test_voices.py b/tests/api_resources/audio/test_voices.py index 996c723434..1e60fd830f 100644 --- a/tests/api_resources/audio/test_voices.py +++ b/tests/api_resources/audio/test_voices.py @@ -9,7 +9,10 @@ from openai import OpenAI, AsyncOpenAI from tests.utils import assert_matches_type -from openai.types.audio import Voice +from openai.types.audio import ( + Voice, + VoiceDeleted, +) base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010") @@ -112,6 +115,44 @@ def test_streaming_response_create_overload_2(self, client: OpenAI) -> None: assert cast(Any, response.is_closed) is True + @parametrize + def test_method_delete(self, client: OpenAI) -> None: + voice = client.audio.voices.delete( + "voice_id", + ) + assert_matches_type(VoiceDeleted, voice, path=["response"]) + + @parametrize + def test_raw_response_delete(self, client: OpenAI) -> None: + response = client.audio.voices.with_raw_response.delete( + "voice_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + voice = response.parse() + assert_matches_type(VoiceDeleted, voice, path=["response"]) + + @parametrize + def test_streaming_response_delete(self, client: OpenAI) -> None: + with client.audio.voices.with_streaming_response.delete( + "voice_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + voice = response.parse() + assert_matches_type(VoiceDeleted, voice, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + def test_path_params_delete(self, client: OpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `voice_id` but received ''"): + client.audio.voices.with_raw_response.delete( + "", + ) + class TestAsyncVoices: parametrize = pytest.mark.parametrize( @@ -212,3 +253,41 @@ async def test_streaming_response_create_overload_2(self, async_client: AsyncOpe assert_matches_type(Voice, voice, path=["response"]) assert cast(Any, response.is_closed) is True + + @parametrize + async def test_method_delete(self, async_client: AsyncOpenAI) -> None: + voice = await async_client.audio.voices.delete( + "voice_id", + ) + assert_matches_type(VoiceDeleted, voice, path=["response"]) + + @parametrize + async def test_raw_response_delete(self, async_client: AsyncOpenAI) -> None: + response = await async_client.audio.voices.with_raw_response.delete( + "voice_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + voice = response.parse() + assert_matches_type(VoiceDeleted, voice, path=["response"]) + + @parametrize + async def test_streaming_response_delete(self, async_client: AsyncOpenAI) -> None: + async with async_client.audio.voices.with_streaming_response.delete( + "voice_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + voice = await response.parse() + assert_matches_type(VoiceDeleted, voice, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + async def test_path_params_delete(self, async_client: AsyncOpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `voice_id` but received ''"): + await async_client.audio.voices.with_raw_response.delete( + "", + ) diff --git a/tests/api_resources/beta/agents/automations/__init__.py b/tests/api_resources/beta/agents/automations/__init__.py new file mode 100644 index 0000000000..d7a8b19970 --- /dev/null +++ b/tests/api_resources/beta/agents/automations/__init__.py @@ -0,0 +1 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. diff --git a/tests/api_resources/beta/agents/automations/test_invocations.py b/tests/api_resources/beta/agents/automations/test_invocations.py new file mode 100644 index 0000000000..aa5ecc9438 --- /dev/null +++ b/tests/api_resources/beta/agents/automations/test_invocations.py @@ -0,0 +1,293 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +import os +from typing import Any, cast + +import pytest + +from openai import OpenAI, AsyncOpenAI +from tests.utils import assert_matches_type +from openai.pagination import SyncCursorPage, AsyncCursorPage +from openai.types.beta.agents.automations import AutomationInvocation + +base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010") + + +class TestInvocations: + parametrize = pytest.mark.parametrize("client", [False, True], indirect=True, ids=["loose", "strict"]) + + @parametrize + def test_method_create(self, client: OpenAI) -> None: + invocation = client.beta.agents.automations.invocations.create( + "automation_id", + ) + assert_matches_type(AutomationInvocation, invocation, path=["response"]) + + @parametrize + def test_raw_response_create(self, client: OpenAI) -> None: + response = client.beta.agents.automations.invocations.with_raw_response.create( + "automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + invocation = response.parse() + assert_matches_type(AutomationInvocation, invocation, path=["response"]) + + @parametrize + def test_streaming_response_create(self, client: OpenAI) -> None: + with client.beta.agents.automations.invocations.with_streaming_response.create( + "automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + invocation = response.parse() + assert_matches_type(AutomationInvocation, invocation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + def test_path_params_create(self, client: OpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + client.beta.agents.automations.invocations.with_raw_response.create( + "", + ) + + @parametrize + def test_method_retrieve(self, client: OpenAI) -> None: + invocation = client.beta.agents.automations.invocations.retrieve( + invocation_id="invocation_id", + automation_id="automation_id", + ) + assert_matches_type(AutomationInvocation, invocation, path=["response"]) + + @parametrize + def test_raw_response_retrieve(self, client: OpenAI) -> None: + response = client.beta.agents.automations.invocations.with_raw_response.retrieve( + invocation_id="invocation_id", + automation_id="automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + invocation = response.parse() + assert_matches_type(AutomationInvocation, invocation, path=["response"]) + + @parametrize + def test_streaming_response_retrieve(self, client: OpenAI) -> None: + with client.beta.agents.automations.invocations.with_streaming_response.retrieve( + invocation_id="invocation_id", + automation_id="automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + invocation = response.parse() + assert_matches_type(AutomationInvocation, invocation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + def test_path_params_retrieve(self, client: OpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + client.beta.agents.automations.invocations.with_raw_response.retrieve( + invocation_id="invocation_id", + automation_id="", + ) + + with pytest.raises(ValueError, match=r"Expected a non-empty value for `invocation_id` but received ''"): + client.beta.agents.automations.invocations.with_raw_response.retrieve( + invocation_id="", + automation_id="automation_id", + ) + + @parametrize + def test_method_list(self, client: OpenAI) -> None: + invocation = client.beta.agents.automations.invocations.list( + automation_id="automation_id", + ) + assert_matches_type(SyncCursorPage[AutomationInvocation], invocation, path=["response"]) + + @parametrize + def test_method_list_with_all_params(self, client: OpenAI) -> None: + invocation = client.beta.agents.automations.invocations.list( + automation_id="automation_id", + after="after", + limit=1, + order="asc", + ) + assert_matches_type(SyncCursorPage[AutomationInvocation], invocation, path=["response"]) + + @parametrize + def test_raw_response_list(self, client: OpenAI) -> None: + response = client.beta.agents.automations.invocations.with_raw_response.list( + automation_id="automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + invocation = response.parse() + assert_matches_type(SyncCursorPage[AutomationInvocation], invocation, path=["response"]) + + @parametrize + def test_streaming_response_list(self, client: OpenAI) -> None: + with client.beta.agents.automations.invocations.with_streaming_response.list( + automation_id="automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + invocation = response.parse() + assert_matches_type(SyncCursorPage[AutomationInvocation], invocation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + def test_path_params_list(self, client: OpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + client.beta.agents.automations.invocations.with_raw_response.list( + automation_id="", + ) + + +class TestAsyncInvocations: + parametrize = pytest.mark.parametrize( + "async_client", [False, True, {"http_client": "aiohttp"}], indirect=True, ids=["loose", "strict", "aiohttp"] + ) + + @parametrize + async def test_method_create(self, async_client: AsyncOpenAI) -> None: + invocation = await async_client.beta.agents.automations.invocations.create( + "automation_id", + ) + assert_matches_type(AutomationInvocation, invocation, path=["response"]) + + @parametrize + async def test_raw_response_create(self, async_client: AsyncOpenAI) -> None: + response = await async_client.beta.agents.automations.invocations.with_raw_response.create( + "automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + invocation = response.parse() + assert_matches_type(AutomationInvocation, invocation, path=["response"]) + + @parametrize + async def test_streaming_response_create(self, async_client: AsyncOpenAI) -> None: + async with async_client.beta.agents.automations.invocations.with_streaming_response.create( + "automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + invocation = await response.parse() + assert_matches_type(AutomationInvocation, invocation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + async def test_path_params_create(self, async_client: AsyncOpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + await async_client.beta.agents.automations.invocations.with_raw_response.create( + "", + ) + + @parametrize + async def test_method_retrieve(self, async_client: AsyncOpenAI) -> None: + invocation = await async_client.beta.agents.automations.invocations.retrieve( + invocation_id="invocation_id", + automation_id="automation_id", + ) + assert_matches_type(AutomationInvocation, invocation, path=["response"]) + + @parametrize + async def test_raw_response_retrieve(self, async_client: AsyncOpenAI) -> None: + response = await async_client.beta.agents.automations.invocations.with_raw_response.retrieve( + invocation_id="invocation_id", + automation_id="automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + invocation = response.parse() + assert_matches_type(AutomationInvocation, invocation, path=["response"]) + + @parametrize + async def test_streaming_response_retrieve(self, async_client: AsyncOpenAI) -> None: + async with async_client.beta.agents.automations.invocations.with_streaming_response.retrieve( + invocation_id="invocation_id", + automation_id="automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + invocation = await response.parse() + assert_matches_type(AutomationInvocation, invocation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + async def test_path_params_retrieve(self, async_client: AsyncOpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + await async_client.beta.agents.automations.invocations.with_raw_response.retrieve( + invocation_id="invocation_id", + automation_id="", + ) + + with pytest.raises(ValueError, match=r"Expected a non-empty value for `invocation_id` but received ''"): + await async_client.beta.agents.automations.invocations.with_raw_response.retrieve( + invocation_id="", + automation_id="automation_id", + ) + + @parametrize + async def test_method_list(self, async_client: AsyncOpenAI) -> None: + invocation = await async_client.beta.agents.automations.invocations.list( + automation_id="automation_id", + ) + assert_matches_type(AsyncCursorPage[AutomationInvocation], invocation, path=["response"]) + + @parametrize + async def test_method_list_with_all_params(self, async_client: AsyncOpenAI) -> None: + invocation = await async_client.beta.agents.automations.invocations.list( + automation_id="automation_id", + after="after", + limit=1, + order="asc", + ) + assert_matches_type(AsyncCursorPage[AutomationInvocation], invocation, path=["response"]) + + @parametrize + async def test_raw_response_list(self, async_client: AsyncOpenAI) -> None: + response = await async_client.beta.agents.automations.invocations.with_raw_response.list( + automation_id="automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + invocation = response.parse() + assert_matches_type(AsyncCursorPage[AutomationInvocation], invocation, path=["response"]) + + @parametrize + async def test_streaming_response_list(self, async_client: AsyncOpenAI) -> None: + async with async_client.beta.agents.automations.invocations.with_streaming_response.list( + automation_id="automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + invocation = await response.parse() + assert_matches_type(AsyncCursorPage[AutomationInvocation], invocation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + async def test_path_params_list(self, async_client: AsyncOpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + await async_client.beta.agents.automations.invocations.with_raw_response.list( + automation_id="", + ) diff --git a/tests/api_resources/beta/agents/test_automations.py b/tests/api_resources/beta/agents/test_automations.py new file mode 100644 index 0000000000..b716535612 --- /dev/null +++ b/tests/api_resources/beta/agents/test_automations.py @@ -0,0 +1,1028 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +import os +from typing import Any, cast + +import pytest + +from openai import OpenAI, AsyncOpenAI +from tests.utils import assert_matches_type +from openai.pagination import SyncCursorPage, AsyncCursorPage +from openai.types.beta.agents import ( + Automation, + AutomationDeleted, +) + +base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010") + + +class TestAutomations: + parametrize = pytest.mark.parametrize("client", [False, True], indirect=True, ids=["loose", "strict"]) + + @parametrize + def test_method_create_overload_1(self, client: OpenAI) -> None: + automation = 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", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_method_create_with_all_params_overload_1(self, client: OpenAI) -> None: + automation = 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", + metadata={}, + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_raw_response_create_overload_1(self, client: OpenAI) -> None: + response = client.beta.agents.automations.with_raw_response.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", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_streaming_response_create_overload_1(self, client: OpenAI) -> None: + with client.beta.agents.automations.with_streaming_response.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", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + def test_method_create_overload_2(self, client: OpenAI) -> None: + automation = client.beta.agents.automations.create( + name="x", + run_at=1, + target={ + "environment": {"type": "none"}, + "input": [ + { + "content": [ + { + "text": "text", + "type": "input_text", + } + ], + "role": "user", + } + ], + "type": "new_session", + }, + type="once", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_method_create_with_all_params_overload_2(self, client: OpenAI) -> None: + automation = client.beta.agents.automations.create( + name="x", + run_at=1, + target={ + "environment": {"type": "none"}, + "input": [ + { + "content": [ + { + "text": "text", + "type": "input_text", + } + ], + "role": "user", + } + ], + "type": "new_session", + }, + type="once", + metadata={}, + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_raw_response_create_overload_2(self, client: OpenAI) -> None: + response = client.beta.agents.automations.with_raw_response.create( + name="x", + run_at=1, + target={ + "environment": {"type": "none"}, + "input": [ + { + "content": [ + { + "text": "text", + "type": "input_text", + } + ], + "role": "user", + } + ], + "type": "new_session", + }, + type="once", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_streaming_response_create_overload_2(self, client: OpenAI) -> None: + with client.beta.agents.automations.with_streaming_response.create( + name="x", + run_at=1, + target={ + "environment": {"type": "none"}, + "input": [ + { + "content": [ + { + "text": "text", + "type": "input_text", + } + ], + "role": "user", + } + ], + "type": "new_session", + }, + type="once", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + def test_method_retrieve(self, client: OpenAI) -> None: + automation = client.beta.agents.automations.retrieve( + "automation_id", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_raw_response_retrieve(self, client: OpenAI) -> None: + response = client.beta.agents.automations.with_raw_response.retrieve( + "automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_streaming_response_retrieve(self, client: OpenAI) -> None: + with client.beta.agents.automations.with_streaming_response.retrieve( + "automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + def test_path_params_retrieve(self, client: OpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + client.beta.agents.automations.with_raw_response.retrieve( + "", + ) + + @parametrize + def test_method_update(self, client: OpenAI) -> None: + automation = client.beta.agents.automations.update( + automation_id="automation_id", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_method_update_with_all_params(self, client: OpenAI) -> None: + automation = client.beta.agents.automations.update( + automation_id="automation_id", + expression="x", + metadata={"foo": "string"}, + name="x", + run_at=0, + 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", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_raw_response_update(self, client: OpenAI) -> None: + response = client.beta.agents.automations.with_raw_response.update( + automation_id="automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_streaming_response_update(self, client: OpenAI) -> None: + with client.beta.agents.automations.with_streaming_response.update( + automation_id="automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + def test_path_params_update(self, client: OpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + client.beta.agents.automations.with_raw_response.update( + automation_id="", + ) + + @parametrize + def test_method_list(self, client: OpenAI) -> None: + automation = client.beta.agents.automations.list() + assert_matches_type(SyncCursorPage[Automation], automation, path=["response"]) + + @parametrize + def test_method_list_with_all_params(self, client: OpenAI) -> None: + automation = client.beta.agents.automations.list( + after="after", + limit=1, + order="asc", + session_id="session_id", + ) + assert_matches_type(SyncCursorPage[Automation], automation, path=["response"]) + + @parametrize + def test_raw_response_list(self, client: OpenAI) -> None: + response = client.beta.agents.automations.with_raw_response.list() + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(SyncCursorPage[Automation], automation, path=["response"]) + + @parametrize + def test_streaming_response_list(self, client: OpenAI) -> None: + with client.beta.agents.automations.with_streaming_response.list() as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = response.parse() + assert_matches_type(SyncCursorPage[Automation], automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + def test_method_delete(self, client: OpenAI) -> None: + automation = client.beta.agents.automations.delete( + "automation_id", + ) + assert_matches_type(AutomationDeleted, automation, path=["response"]) + + @parametrize + def test_raw_response_delete(self, client: OpenAI) -> None: + response = client.beta.agents.automations.with_raw_response.delete( + "automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(AutomationDeleted, automation, path=["response"]) + + @parametrize + def test_streaming_response_delete(self, client: OpenAI) -> None: + with client.beta.agents.automations.with_streaming_response.delete( + "automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = response.parse() + assert_matches_type(AutomationDeleted, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + def test_path_params_delete(self, client: OpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + client.beta.agents.automations.with_raw_response.delete( + "", + ) + + @parametrize + def test_method_pause(self, client: OpenAI) -> None: + automation = client.beta.agents.automations.pause( + "automation_id", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_raw_response_pause(self, client: OpenAI) -> None: + response = client.beta.agents.automations.with_raw_response.pause( + "automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_streaming_response_pause(self, client: OpenAI) -> None: + with client.beta.agents.automations.with_streaming_response.pause( + "automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + def test_path_params_pause(self, client: OpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + client.beta.agents.automations.with_raw_response.pause( + "", + ) + + @parametrize + def test_method_resume(self, client: OpenAI) -> None: + automation = client.beta.agents.automations.resume( + "automation_id", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_raw_response_resume(self, client: OpenAI) -> None: + response = client.beta.agents.automations.with_raw_response.resume( + "automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + def test_streaming_response_resume(self, client: OpenAI) -> None: + with client.beta.agents.automations.with_streaming_response.resume( + "automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + def test_path_params_resume(self, client: OpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + client.beta.agents.automations.with_raw_response.resume( + "", + ) + + +class TestAsyncAutomations: + parametrize = pytest.mark.parametrize( + "async_client", [False, True, {"http_client": "aiohttp"}], indirect=True, ids=["loose", "strict", "aiohttp"] + ) + + @parametrize + async def test_method_create_overload_1(self, async_client: AsyncOpenAI) -> None: + automation = await async_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", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_method_create_with_all_params_overload_1(self, async_client: AsyncOpenAI) -> None: + automation = await async_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", + metadata={}, + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_raw_response_create_overload_1(self, async_client: AsyncOpenAI) -> None: + response = await async_client.beta.agents.automations.with_raw_response.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", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_streaming_response_create_overload_1(self, async_client: AsyncOpenAI) -> None: + async with async_client.beta.agents.automations.with_streaming_response.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", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = await response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + async def test_method_create_overload_2(self, async_client: AsyncOpenAI) -> None: + automation = await async_client.beta.agents.automations.create( + name="x", + run_at=1, + target={ + "environment": {"type": "none"}, + "input": [ + { + "content": [ + { + "text": "text", + "type": "input_text", + } + ], + "role": "user", + } + ], + "type": "new_session", + }, + type="once", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_method_create_with_all_params_overload_2(self, async_client: AsyncOpenAI) -> None: + automation = await async_client.beta.agents.automations.create( + name="x", + run_at=1, + target={ + "environment": {"type": "none"}, + "input": [ + { + "content": [ + { + "text": "text", + "type": "input_text", + } + ], + "role": "user", + } + ], + "type": "new_session", + }, + type="once", + metadata={}, + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_raw_response_create_overload_2(self, async_client: AsyncOpenAI) -> None: + response = await async_client.beta.agents.automations.with_raw_response.create( + name="x", + run_at=1, + target={ + "environment": {"type": "none"}, + "input": [ + { + "content": [ + { + "text": "text", + "type": "input_text", + } + ], + "role": "user", + } + ], + "type": "new_session", + }, + type="once", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_streaming_response_create_overload_2(self, async_client: AsyncOpenAI) -> None: + async with async_client.beta.agents.automations.with_streaming_response.create( + name="x", + run_at=1, + target={ + "environment": {"type": "none"}, + "input": [ + { + "content": [ + { + "text": "text", + "type": "input_text", + } + ], + "role": "user", + } + ], + "type": "new_session", + }, + type="once", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = await response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + async def test_method_retrieve(self, async_client: AsyncOpenAI) -> None: + automation = await async_client.beta.agents.automations.retrieve( + "automation_id", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_raw_response_retrieve(self, async_client: AsyncOpenAI) -> None: + response = await async_client.beta.agents.automations.with_raw_response.retrieve( + "automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_streaming_response_retrieve(self, async_client: AsyncOpenAI) -> None: + async with async_client.beta.agents.automations.with_streaming_response.retrieve( + "automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = await response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + async def test_path_params_retrieve(self, async_client: AsyncOpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + await async_client.beta.agents.automations.with_raw_response.retrieve( + "", + ) + + @parametrize + async def test_method_update(self, async_client: AsyncOpenAI) -> None: + automation = await async_client.beta.agents.automations.update( + automation_id="automation_id", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_method_update_with_all_params(self, async_client: AsyncOpenAI) -> None: + automation = await async_client.beta.agents.automations.update( + automation_id="automation_id", + expression="x", + metadata={"foo": "string"}, + name="x", + run_at=0, + 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", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_raw_response_update(self, async_client: AsyncOpenAI) -> None: + response = await async_client.beta.agents.automations.with_raw_response.update( + automation_id="automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_streaming_response_update(self, async_client: AsyncOpenAI) -> None: + async with async_client.beta.agents.automations.with_streaming_response.update( + automation_id="automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = await response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + async def test_path_params_update(self, async_client: AsyncOpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + await async_client.beta.agents.automations.with_raw_response.update( + automation_id="", + ) + + @parametrize + async def test_method_list(self, async_client: AsyncOpenAI) -> None: + automation = await async_client.beta.agents.automations.list() + assert_matches_type(AsyncCursorPage[Automation], automation, path=["response"]) + + @parametrize + async def test_method_list_with_all_params(self, async_client: AsyncOpenAI) -> None: + automation = await async_client.beta.agents.automations.list( + after="after", + limit=1, + order="asc", + session_id="session_id", + ) + assert_matches_type(AsyncCursorPage[Automation], automation, path=["response"]) + + @parametrize + async def test_raw_response_list(self, async_client: AsyncOpenAI) -> None: + response = await async_client.beta.agents.automations.with_raw_response.list() + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(AsyncCursorPage[Automation], automation, path=["response"]) + + @parametrize + async def test_streaming_response_list(self, async_client: AsyncOpenAI) -> None: + async with async_client.beta.agents.automations.with_streaming_response.list() as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = await response.parse() + assert_matches_type(AsyncCursorPage[Automation], automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + async def test_method_delete(self, async_client: AsyncOpenAI) -> None: + automation = await async_client.beta.agents.automations.delete( + "automation_id", + ) + assert_matches_type(AutomationDeleted, automation, path=["response"]) + + @parametrize + async def test_raw_response_delete(self, async_client: AsyncOpenAI) -> None: + response = await async_client.beta.agents.automations.with_raw_response.delete( + "automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(AutomationDeleted, automation, path=["response"]) + + @parametrize + async def test_streaming_response_delete(self, async_client: AsyncOpenAI) -> None: + async with async_client.beta.agents.automations.with_streaming_response.delete( + "automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = await response.parse() + assert_matches_type(AutomationDeleted, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + async def test_path_params_delete(self, async_client: AsyncOpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + await async_client.beta.agents.automations.with_raw_response.delete( + "", + ) + + @parametrize + async def test_method_pause(self, async_client: AsyncOpenAI) -> None: + automation = await async_client.beta.agents.automations.pause( + "automation_id", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_raw_response_pause(self, async_client: AsyncOpenAI) -> None: + response = await async_client.beta.agents.automations.with_raw_response.pause( + "automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_streaming_response_pause(self, async_client: AsyncOpenAI) -> None: + async with async_client.beta.agents.automations.with_streaming_response.pause( + "automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = await response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + async def test_path_params_pause(self, async_client: AsyncOpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + await async_client.beta.agents.automations.with_raw_response.pause( + "", + ) + + @parametrize + async def test_method_resume(self, async_client: AsyncOpenAI) -> None: + automation = await async_client.beta.agents.automations.resume( + "automation_id", + ) + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_raw_response_resume(self, async_client: AsyncOpenAI) -> None: + response = await async_client.beta.agents.automations.with_raw_response.resume( + "automation_id", + ) + + assert response.is_closed is True + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + automation = response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + @parametrize + async def test_streaming_response_resume(self, async_client: AsyncOpenAI) -> None: + async with async_client.beta.agents.automations.with_streaming_response.resume( + "automation_id", + ) as response: + assert not response.is_closed + assert response.http_request.headers.get("X-Stainless-Lang") == "python" + + automation = await response.parse() + assert_matches_type(Automation, automation, path=["response"]) + + assert cast(Any, response.is_closed) is True + + @parametrize + async def test_path_params_resume(self, async_client: AsyncOpenAI) -> None: + with pytest.raises(ValueError, match=r"Expected a non-empty value for `automation_id` but received ''"): + await async_client.beta.agents.automations.with_raw_response.resume( + "", + ) diff --git a/tests/api_resources/live/test_sessions.py b/tests/api_resources/live/test_sessions.py index 15e1ea293d..dfe67c5b67 100644 --- a/tests/api_resources/live/test_sessions.py +++ b/tests/api_resources/live/test_sessions.py @@ -43,7 +43,10 @@ def test_method_accept_with_all_params(self, client: OpenAI) -> None: "model": "x", "type": "live", "audio": {"output": {"voice": "alloy"}}, - "delegation": {"type": "client"}, + "delegation": { + "type": "client", + "acknowledgement_delay_ms": 0, + }, "input": [ { "content": [ @@ -197,6 +200,7 @@ def test_method_fork_with_all_params(self, client: OpenAI) -> None: }, "delegation": { "type": "responses", + "acknowledgement_delay_ms": 0, "responses": { "instructions": "instructions", "max_output_tokens": 16, @@ -415,7 +419,10 @@ async def test_method_accept_with_all_params(self, async_client: AsyncOpenAI) -> "model": "x", "type": "live", "audio": {"output": {"voice": "alloy"}}, - "delegation": {"type": "client"}, + "delegation": { + "type": "client", + "acknowledgement_delay_ms": 0, + }, "input": [ { "content": [ @@ -571,6 +578,7 @@ async def test_method_fork_with_all_params(self, async_client: AsyncOpenAI) -> N }, "delegation": { "type": "responses", + "acknowledgement_delay_ms": 0, "responses": { "instructions": "instructions", "max_output_tokens": 16, diff --git a/tests/api_resources/test_live.py b/tests/api_resources/test_live.py index 53bb484b00..9d315f9051 100644 --- a/tests/api_resources/test_live.py +++ b/tests/api_resources/test_live.py @@ -40,7 +40,10 @@ def test_method_create_with_all_params(self, client: OpenAI) -> None: "allowed_server_events": "all", } }, - "delegation": {"type": "client"}, + "delegation": { + "type": "client", + "acknowledgement_delay_ms": 0, + }, "input": [ { "content": [ @@ -141,7 +144,10 @@ async def test_method_create_with_all_params(self, async_client: AsyncOpenAI) -> "allowed_server_events": "all", } }, - "delegation": {"type": "client"}, + "delegation": { + "type": "client", + "acknowledgement_delay_ms": 0, + }, "input": [ { "content": [