From fddeb8f895c5fdf3db04a3c128b4663fb7d0fbf6 Mon Sep 17 00:00:00 2001 From: markstuart-oai <323302876+markstuart-oai@users.noreply.github.com> Date: Fri, 30 Oct 2026 23:47:42 +0000 Subject: [PATCH] feat(api): add agent session review and tool settings Castiron-Promotion-ID: v1:30dc74db4b358fa53c2b4527c9808beb0f65d0b24885047ea615133c2343c8b7 --- .castiron.stats.yml | 10 ++--- api_reference/openapi.transformed.yml | 39 +++++++++++++++++-- scripts/castiron/generated-files.json | 10 ++--- .../beta/agents/sessions/sessions.py | 36 +++++++++++++++-- src/openai/types/beta/agent_session.py | 7 ++++ .../beta/agents/session_create_params.py | 8 ++++ .../beta/agents/session_update_params.py | 26 +++++++++++-- .../beta/agents/test_sessions.py | 24 ++++++++++++ 8 files changed, 140 insertions(+), 20 deletions(-) diff --git a/.castiron.stats.yml b/.castiron.stats.yml index 9368af3714..50c57a64d0 100644 --- a/.castiron.stats.yml +++ b/.castiron.stats.yml @@ -1,7 +1,7 @@ schema_version: 1 -generation_id: 287e1fa6-451c-4f5f-9a80-498c77a0bd65 -openapi_spec_hash: 17689beb6a2da96f6cf9e5ac1e758a99 -openapi_transformed_spec_hash: 75a7f7b19910025d8f8f8aa1556d9b69 +generation_id: 92191688-2814-4240-a392-408609958bf7 +openapi_spec_hash: c3c2cc244c107fdd6e624a7b961015a9 +openapi_transformed_spec_hash: 5b121d4b6cca6573c41db323a7399527 config_hash: b707b209c892562880c415693d111ad6 -codegen_sha: b79c2ec277007e5a097e73a710864b77338da840 -codegen_hash: 7acc6ff9d93bbfd3be9e38f79d6b509bfd063f80cdd751f997b86e000327b9ae +codegen_sha: 877cf0eac8dabd1578d463ff47f140c493bd4d1a +codegen_hash: 78d280346819510f8ed577aad3d2df4df8dab155df63a48d6ae06e50a98111aa diff --git a/api_reference/openapi.transformed.yml b/api_reference/openapi.transformed.yml index 1b228fd734..157bf377f5 100644 --- a/api_reference/openapi.transformed.yml +++ b/api_reference/openapi.transformed.yml @@ -33545,7 +33545,7 @@ paths: 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). + description: Updates session tools, 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: @@ -92393,6 +92393,9 @@ components: - $ref: '#/components/schemas/TokenUsageResource' - type: 'null' description: Best-effort token usage for the session, or null if unknown. Recorded usage may change. + review: + $ref: '#/components/schemas/SessionReviewResource' + description: Review applied to eligible actions in this session. Omitted when review is none and automatic review is not enabled. Omission means none. spend_control: $ref: '#/components/schemas/SessionSpendControlResource' description: Configured spending limit and best-effort consumption, in USD cents. Unlimited sessions omit this object. @@ -92511,6 +92514,9 @@ components: type: boolean default: false description: Whether to stream session events as server-sent events. Defaults to `false`. + review: + $ref: '#/components/schemas/SessionReviewParam' + description: Action review mode. Omit to use none. spend_control: anyOf: - $ref: '#/components/schemas/SessionSpendControlParam' @@ -94121,14 +94127,23 @@ components: - type: 'null' description: Omit to keep the current tier. Null resets it to auto. x-openai-go-optional-enum: true + tools: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/AgentToolConfigParam' + minItems: 0 + maxItems: 16384 + description: Replaces the session tools. Functions and MCP servers change on the next model call. Built-in tools change by the next turn. Omit to keep the current tools, or pass null or an empty array to clear them. additionalProperties: false - description: Model settings that can change after session creation. + description: Agent 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. + description: Agent settings to update on this session. Omitted fields stay unchanged. metadata: type: - object @@ -94144,6 +94159,9 @@ components: 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. + review: + $ref: '#/components/schemas/SessionReviewParam' + description: Default action review for new root turns. Existing turns and their subagents keep their review mode. spend_control: anyOf: - $ref: '#/components/schemas/SessionSpendControlParam' @@ -111902,6 +111920,21 @@ components: - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' discriminator: propertyName: type + SessionReviewParam: + type: string + enum: + - none + - auto_review + x-enumDescriptions: + - Keep the existing execution behavior without automatic action review. + - Review eligible actions automatically. Deny manual approval fallbacks. + description: Review applied to eligible actions in a session. + SessionReviewResource: + type: string + enum: + - none + - auto_review + description: The configured action review mode. SessionSpendControlResource: type: object properties: diff --git a/scripts/castiron/generated-files.json b/scripts/castiron/generated-files.json index f0d145120c..d1eb8b59d3 100644 --- a/scripts/castiron/generated-files.json +++ b/scripts/castiron/generated-files.json @@ -287,7 +287,7 @@ }, "src/openai/resources/beta/agents/sessions/sessions.py": { "mode": "100644", - "sha256": "d1719b767d0b16e9eba1c405a66e9c11874da30a6ba2fa873603d1e6a9f6f7e2" + "sha256": "264c1c83bc479591e9b70166208a4384e7266c7176a3fea7971f1d876ef54294" }, "src/openai/resources/beta/agents/sessions/subagents/__init__.py": { "mode": "100644", @@ -1703,7 +1703,7 @@ }, "src/openai/types/beta/agent_session.py": { "mode": "100644", - "sha256": "4dbf44628416d12c8cdf46a6a73e293239736ca23dfb096e39850d68ffe5daa6" + "sha256": "c3563e065a7d80a1ee1676d31cd4b835a2363a691db2ac778f8a0c13f265e37b" }, "src/openai/types/beta/agent_session_assistant_message.py": { "mode": "100644", @@ -2019,7 +2019,7 @@ }, "src/openai/types/beta/agents/session_create_params.py": { "mode": "100644", - "sha256": "d4566c2d07b1a1469e929763fa12e626cb1dbeae6dedfd00648f8220b4af8581" + "sha256": "89d1618c6a0a6ef4791ee9376bbd8fdd512b8f0c259eb551c0c27281cbf61170" }, "src/openai/types/beta/agents/session_list_params.py": { "mode": "100644", @@ -2027,7 +2027,7 @@ }, "src/openai/types/beta/agents/session_update_params.py": { "mode": "100644", - "sha256": "de3b4a42dfa9591dc07086c3ac888502c8dd0d3c7e77c82969a10a116dcee18e" + "sha256": "595ab57453c5678034088224417b1946dc37f4dd11e28c7f6df49d75d7dd3dd0" }, "src/openai/types/beta/agents/sessions/__init__.py": { "mode": "100644", @@ -7715,7 +7715,7 @@ }, "tests/api_resources/beta/agents/test_sessions.py": { "mode": "100644", - "sha256": "8cfecc54a8e76b3714fa35298725eb6b315750fe5a2b112fff6185e14df8f831" + "sha256": "3c3b516e8fb4271b93de010045026578ca1f38ba0310491cb6d1a60e61d5de23" }, "tests/api_resources/beta/agents/test_vaults.py": { "mode": "100644", diff --git a/src/openai/resources/beta/agents/sessions/sessions.py b/src/openai/resources/beta/agents/sessions/sessions.py index c38a5d5142..126e37a2c6 100644 --- a/src/openai/resources/beta/agents/sessions/sessions.py +++ b/src/openai/resources/beta/agents/sessions/sessions.py @@ -164,6 +164,7 @@ def create( agent_id: str | Omit = omit, input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit, metadata: Optional[Dict[str, str]] | Omit = omit, + review: Literal["none", "auto_review"] | Omit = omit, spend_control: Optional[session_create_params.SpendControl] | Omit = omit, stream: Literal[False] | Omit = omit, vault_ids: Optional[SequenceNotStr[str]] | Omit = omit, @@ -185,6 +186,7 @@ def create( agent_id: str | Omit = omit, input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit, metadata: Optional[Dict[str, str]] | Omit = omit, + review: Literal["none", "auto_review"] | Omit = omit, spend_control: Optional[session_create_params.SpendControl] | Omit = omit, vault_ids: Optional[SequenceNotStr[str]] | Omit = omit, extra_headers: Headers | None = None, @@ -205,6 +207,7 @@ def create( agent_id: str | Omit = omit, input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit, metadata: Optional[Dict[str, str]] | Omit = omit, + review: Literal["none", "auto_review"] | Omit = omit, spend_control: Optional[session_create_params.SpendControl] | Omit = omit, vault_ids: Optional[SequenceNotStr[str]] | Omit = omit, extra_headers: Headers | None = None, @@ -224,6 +227,7 @@ def create( agent_id: str | Omit = omit, input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit, metadata: Optional[Dict[str, str]] | Omit = omit, + review: Literal["none", "auto_review"] | Omit = omit, spend_control: Optional[session_create_params.SpendControl] | Omit = omit, stream: Literal[False] | Literal[True] | Omit = omit, vault_ids: Optional[SequenceNotStr[str]] | Omit = omit, @@ -242,6 +246,7 @@ def create( "agent_id": agent_id, "input": input, "metadata": metadata, + "review": review, "spend_control": spend_control, "vault_ids": vault_ids, }, @@ -318,6 +323,7 @@ def update( *, agent: session_update_params.Agent | Omit = omit, metadata: Optional[Dict[str, str]] | Omit = omit, + review: Literal["none", "auto_review"] | Omit = omit, spend_control: Optional[session_update_params.SpendControl] | 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. @@ -326,19 +332,26 @@ def update( extra_body: Body | None = None, timeout: float | httpx2.Timeout | None | NotGiven = not_given, ) -> AgentSession: - """Updates session metadata, model, reasoning effort, or service tier. + """Updates session tools, 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). Args: - agent: Model settings for subsequent turns. Omitted fields stay unchanged. + agent: Agent settings to update on this session. Omitted fields stay unchanged. metadata: 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. + review: Default action review for new root turns. Existing turns and their subagents + keep their review mode. + + - `none` - Keep the existing execution behavior without automatic action review. + - `auto_review` - Review eligible actions automatically. Deny manual approval + fallbacks. + spend_control: Omit to retain the limit; null or a null limit removes it without resetting spend. @@ -359,6 +372,7 @@ def update( { "agent": agent, "metadata": metadata, + "review": review, "spend_control": spend_control, }, session_update_params.SessionUpdateParams, @@ -573,6 +587,7 @@ async def create( agent_id: str | Omit = omit, input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit, metadata: Optional[Dict[str, str]] | Omit = omit, + review: Literal["none", "auto_review"] | Omit = omit, spend_control: Optional[session_create_params.SpendControl] | Omit = omit, stream: Literal[False] | Omit = omit, vault_ids: Optional[SequenceNotStr[str]] | Omit = omit, @@ -594,6 +609,7 @@ async def create( agent_id: str | Omit = omit, input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit, metadata: Optional[Dict[str, str]] | Omit = omit, + review: Literal["none", "auto_review"] | Omit = omit, spend_control: Optional[session_create_params.SpendControl] | Omit = omit, vault_ids: Optional[SequenceNotStr[str]] | Omit = omit, extra_headers: Headers | None = None, @@ -614,6 +630,7 @@ async def create( agent_id: str | Omit = omit, input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit, metadata: Optional[Dict[str, str]] | Omit = omit, + review: Literal["none", "auto_review"] | Omit = omit, spend_control: Optional[session_create_params.SpendControl] | Omit = omit, vault_ids: Optional[SequenceNotStr[str]] | Omit = omit, extra_headers: Headers | None = None, @@ -633,6 +650,7 @@ async def create( agent_id: str | Omit = omit, input: Union[str, Iterable[AgentSessionInputMessageParam], None] | Omit = omit, metadata: Optional[Dict[str, str]] | Omit = omit, + review: Literal["none", "auto_review"] | Omit = omit, spend_control: Optional[session_create_params.SpendControl] | Omit = omit, stream: Literal[False] | Literal[True] | Omit = omit, vault_ids: Optional[SequenceNotStr[str]] | Omit = omit, @@ -651,6 +669,7 @@ async def create( "agent_id": agent_id, "input": input, "metadata": metadata, + "review": review, "spend_control": spend_control, "vault_ids": vault_ids, }, @@ -727,6 +746,7 @@ async def update( *, agent: session_update_params.Agent | Omit = omit, metadata: Optional[Dict[str, str]] | Omit = omit, + review: Literal["none", "auto_review"] | Omit = omit, spend_control: Optional[session_update_params.SpendControl] | 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. @@ -735,19 +755,26 @@ async def update( extra_body: Body | None = None, timeout: float | httpx2.Timeout | None | NotGiven = not_given, ) -> AgentSession: - """Updates session metadata, model, reasoning effort, or service tier. + """Updates session tools, 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). Args: - agent: Model settings for subsequent turns. Omitted fields stay unchanged. + agent: Agent settings to update on this session. Omitted fields stay unchanged. metadata: 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. + review: Default action review for new root turns. Existing turns and their subagents + keep their review mode. + + - `none` - Keep the existing execution behavior without automatic action review. + - `auto_review` - Review eligible actions automatically. Deny manual approval + fallbacks. + spend_control: Omit to retain the limit; null or a null limit removes it without resetting spend. @@ -768,6 +795,7 @@ async def update( { "agent": agent, "metadata": metadata, + "review": review, "spend_control": spend_control, }, session_update_params.SessionUpdateParams, diff --git a/src/openai/types/beta/agent_session.py b/src/openai/types/beta/agent_session.py index 28d4c76aa6..70ea0abd52 100644 --- a/src/openai/types/beta/agent_session.py +++ b/src/openai/types/beta/agent_session.py @@ -287,6 +287,13 @@ class AgentSession(BaseModel): vault_ids: List[str] """The IDs of vaults made available to the session.""" + review: Optional[Literal["none", "auto_review"]] = None + """Review applied to eligible actions in this session. + + Omitted when review is none and automatic review is not enabled. Omission means + none. + """ + spend_control: Optional[SpendControl] = None """Configured spending limit and best-effort consumption, in USD cents. diff --git a/src/openai/types/beta/agents/session_create_params.py b/src/openai/types/beta/agents/session_create_params.py index 5896261f9e..60fac9e66d 100644 --- a/src/openai/types/beta/agents/session_create_params.py +++ b/src/openai/types/beta/agents/session_create_params.py @@ -57,6 +57,14 @@ class SessionCreateParamsBase(TypedDict, total=False): characters. Omission or null defaults to an empty map. """ + review: Literal["none", "auto_review"] + """Action review mode. Omit to use none. + + - `none` - Keep the existing execution behavior without automatic action review. + - `auto_review` - Review eligible actions automatically. Deny manual approval + fallbacks. + """ + spend_control: Optional[SpendControl] """Optional spending limit in USD cents. diff --git a/src/openai/types/beta/agents/session_update_params.py b/src/openai/types/beta/agents/session_update_params.py index 2f1edd924c..843382c9d5 100644 --- a/src/openai/types/beta/agents/session_update_params.py +++ b/src/openai/types/beta/agents/session_update_params.py @@ -2,15 +2,17 @@ from __future__ import annotations -from typing import Dict, Optional +from typing import Dict, Iterable, Optional from typing_extensions import Literal, Required, TypedDict +from ..agent_tool_param import AgentToolParam + __all__ = ["SessionUpdateParams", "Agent", "AgentReasoning", "SpendControl"] class SessionUpdateParams(TypedDict, total=False): agent: Agent - """Model settings for subsequent turns. Omitted fields stay unchanged.""" + """Agent settings to update on this session. Omitted fields stay unchanged.""" metadata: Optional[Dict[str, str]] """Replaces all metadata. @@ -19,6 +21,16 @@ class SessionUpdateParams(TypedDict, total=False): key-value pairs, with keys up to 64 and values up to 512 characters. """ + review: Literal["none", "auto_review"] + """Default action review for new root turns. + + Existing turns and their subagents keep their review mode. + + - `none` - Keep the existing execution behavior without automatic action review. + - `auto_review` - Review eligible actions automatically. Deny manual approval + fallbacks. + """ + spend_control: Optional[SpendControl] """ Omit to retain the limit; null or a null limit removes it without resetting @@ -34,7 +46,7 @@ class AgentReasoning(TypedDict, total=False): class Agent(TypedDict, total=False): - """Model settings for subsequent turns. Omitted fields stay unchanged.""" + """Agent settings to update on this session. Omitted fields stay unchanged.""" model: str """The model for subsequent turns. Omit to keep the current model.""" @@ -53,6 +65,14 @@ class Agent(TypedDict, total=False): - `ultrafast` - Uses the ultrafast service tier. """ + tools: Optional[Iterable[AgentToolParam]] + """Replaces the session tools. + + Functions and MCP servers change on the next model call. Built-in tools change + by the next turn. Omit to keep the current tools, or pass null or an empty array + to clear them. + """ + class SpendControl(TypedDict, total=False): """ diff --git a/tests/api_resources/beta/agents/test_sessions.py b/tests/api_resources/beta/agents/test_sessions.py index fd4e595eb0..226201ee6a 100644 --- a/tests/api_resources/beta/agents/test_sessions.py +++ b/tests/api_resources/beta/agents/test_sessions.py @@ -60,6 +60,7 @@ def test_method_create_with_all_params_overload_1(self, client: OpenAI) -> None: agent_id="agent_id", input="x", metadata={"foo": "string"}, + review="none", spend_control={"limit": 1}, stream=False, vault_ids=["string"], @@ -134,6 +135,7 @@ def test_method_create_with_all_params_overload_2(self, client: OpenAI) -> None: agent_id="agent_id", input="x", metadata={"foo": "string"}, + review="none", spend_control={"limit": 1}, vault_ids=["string"], ) @@ -219,8 +221,18 @@ def test_method_update_with_all_params(self, client: OpenAI) -> None: "model": "model", "reasoning": {"effort": "none"}, "service_tier": "auto", + "tools": [ + { + "description": "description", + "name": "name", + "parameters": {"foo": "bar"}, + "type": "function", + "defer_loading": True, + } + ], }, metadata={"foo": "string"}, + review="none", spend_control={"limit": 1}, ) assert_matches_type(AgentSession, session, path=["response"]) @@ -378,6 +390,7 @@ async def test_method_create_with_all_params_overload_1(self, async_client: Asyn agent_id="agent_id", input="x", metadata={"foo": "string"}, + review="none", spend_control={"limit": 1}, stream=False, vault_ids=["string"], @@ -452,6 +465,7 @@ async def test_method_create_with_all_params_overload_2(self, async_client: Asyn agent_id="agent_id", input="x", metadata={"foo": "string"}, + review="none", spend_control={"limit": 1}, vault_ids=["string"], ) @@ -537,8 +551,18 @@ async def test_method_update_with_all_params(self, async_client: AsyncOpenAI) -> "model": "model", "reasoning": {"effort": "none"}, "service_tier": "auto", + "tools": [ + { + "description": "description", + "name": "name", + "parameters": {"foo": "bar"}, + "type": "function", + "defer_loading": True, + } + ], }, metadata={"foo": "string"}, + review="none", spend_control={"limit": 1}, ) assert_matches_type(AgentSession, session, path=["response"])