feat(api): add experimental agent time awareness (#4211)

## Summary

Adds optional time-awareness settings for agents and sessions.

## Changes

- Set experimental.time_awareness when creating or updating agents and
configuring sessions.
- Read effective experimental settings in agent and session responses.
- Document that experimental updates merge by key and preserve omitted
settings.

Author: jbeckwith-oai

.castiron.stats.yml

@@ -1,7 +1,7 @@
 schema_version: 1
-generation_id: ca0448a4-c5bb-4dae-b9a8-ce0695616efc
-openapi_spec_hash: 8ca9f63bc016670f3fd9c8265f106c33
-openapi_transformed_spec_hash: 2cb5f40bd6fd564475d5b6ef285c9858
+generation_id: edefdf16-46c7-4f93-94a6-10028a087b3e
+openapi_spec_hash: 0c25fc15ac5b26e2054196d579cc67a0
+openapi_transformed_spec_hash: 651cea16581547a33af56bd631894a03
 config_hash: 8a684aec06907ff8ced7809753e16225
-codegen_sha: 52a6c414b9565e2a8a3f89f87a4df1a5b20deaea
-codegen_hash: 6171d1d87772171c445edcacc04ee274f4d10497fe9da70810d5c778ab57c394
+codegen_sha: a1dd47dd01ce07be1ecbc39e2f66f2156d89c6f3
+codegen_hash: 2c7827fd0ccd38edcd80a97839ae5c10cf89f8da20ea468d4b20c41468607b81

api_reference/openapi.transformed.yml

@@ -85071,6 +85071,9 @@ components:
         compaction:
           $ref: '#/components/schemas/CompactionResource'
           description: The effective context compaction settings.
+        experimental:
+          $ref: '#/components/schemas/ExperimentalConfigResource'
+          description: The effective experimental settings for the agent.
       required:
       - model
       - reasoning
@@ -86513,8 +86516,12 @@ components:
           - $ref: '#/components/schemas/CompactionParam'
           - type: 'null'
           description: Context compaction settings. Omit to keep the current settings. A supplied object replaces the settings; null or an empty object enables background compaction.
+        experimental:
+          $ref: '#/components/schemas/ExperimentalConfigOverridesParam'
+          default: {}
+          description: Experimental settings to merge by key. Omitted settings keep their current values.
       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.
+      description: Agent configuration for a session. Omitted fields inherit from `agent_id` when supplied. Supplied objects and arrays replace the whole field, except experimental settings, which merge by key. Null resets nullable fields.
     EnvironmentParamNone:
       type: object
       properties:
@@ -89985,6 +89992,9 @@ components:
         compaction:
           $ref: '#/components/schemas/CompactionResource'
           description: The effective context compaction settings.
+        experimental:
+          $ref: '#/components/schemas/ExperimentalConfigResource'
+          description: The effective experimental settings for the agent.
       required:
       - id
       - object
@@ -90444,6 +90454,11 @@ components:
           - $ref: '#/components/schemas/CompactionParam'
           - type: 'null'
           description: Context compaction settings. Omission or null enables background compaction.
+        experimental:
+          $ref: '#/components/schemas/ExperimentalConfigParam'
+          default:
+            time_awareness: false
+          description: Experimental agent settings. All experimental features default to disabled.
       required:
       - model
       additionalProperties: false
@@ -90519,6 +90534,10 @@ components:
           - $ref: '#/components/schemas/CompactionParam'
           - type: 'null'
           description: Context compaction settings. Omit to keep the current settings. A supplied object replaces the settings; null or an empty object enables background compaction.
+        experimental:
+          $ref: '#/components/schemas/ExperimentalConfigOverridesParam'
+          default: {}
+          description: Experimental settings to merge by key. Omitted settings keep their current values.
       additionalProperties: false
       description: Fields to replace on an existing reusable agent.
     DeletedAgentResource:
@@ -91104,6 +91123,9 @@ components:
         compaction:
           $ref: '#/components/schemas/CompactionResource'
           description: The effective context compaction settings.
+        experimental:
+          $ref: '#/components/schemas/ExperimentalConfigResource'
+          description: The effective experimental settings for the agent.
       required:
       - id
       - name
@@ -111114,6 +111136,33 @@ components:
       type: string
       format: binary
       description: A transparent PNG overlaid on the first image to guide the edit. Must match that image's dimensions after orientation and contain transparent pixels. Supports GPT Image 2.5 and 2.6. Cannot be combined with mask.
+    ExperimentalConfigOverridesParam:
+      type: object
+      properties:
+        time_awareness:
+          type: boolean
+          description: Whether to give the model periodic current-time reminders. Omit to keep the current setting.
+      additionalProperties: false
+      description: Experimental settings to update. Omitted settings keep their current values.
+    ExperimentalConfigParam:
+      type: object
+      properties:
+        time_awareness:
+          type: boolean
+          default: false
+          description: Whether to give the model periodic current-time reminders. Defaults to false.
+      additionalProperties: false
+      description: Experimental agent settings. These features may change.
+    ExperimentalConfigResource:
+      type: object
+      properties:
+        time_awareness:
+          type: boolean
+          description: Whether the model receives periodic current-time reminders.
+      required:
+      - time_awareness
+      additionalProperties: false
+      description: The effective experimental settings for an agent.
     SessionSpendControlResource:
       type: object
       properties:

scripts/castiron/generated-files.json

@@ -239,7 +239,7 @@
     },
     "src/openai/resources/beta/agents/agents.py": {
       "mode": "100644",
-      "sha256": "fa3b51beeff5b5c0cf3454aa34b13b72301fdf7420996f9e71974700f6b8bcbd"
+      "sha256": "1ee66922d98bdaeecb4b464f7f288d2b4e3fd42e15f20d07e37e10ea45edfbc4"
     },
     "src/openai/resources/beta/agents/automations/__init__.py": {
       "mode": "100644",
@@ -1591,7 +1591,7 @@
     },
     "src/openai/types/beta/agent.py": {
       "mode": "100644",
-      "sha256": "39c20eb4aae2c8a5bd650ef29331f4a9c6a859ae9cbb674e9ddb62e2f85a13c8"
+      "sha256": "770de49d96ab880e0679a72a0358113ae9c4e7ff85bc50d215598d1a09066c71"
     },
     "src/openai/types/beta/agent_browser_authentication_cancel_param.py": {
       "mode": "100644",
@@ -1631,7 +1631,7 @@
     },
     "src/openai/types/beta/agent_create_params.py": {
       "mode": "100644",
-      "sha256": "e43e1e4d33b6e9764aa070c25bc15809a035ffb1ddfadc4680e33020f260f36b"
+      "sha256": "7e113690e45eca7d31a40c042a27a89a597fca373c39bafd8bb75f68c93f282b"
     },
     "src/openai/types/beta/agent_create_subagent_call_item.py": {
       "mode": "100644",
@@ -1703,7 +1703,7 @@
     },
     "src/openai/types/beta/agent_session.py": {
       "mode": "100644",
-      "sha256": "942e581fb98626566ae555e27262d1c6a7b772201e3385695ed1462ed317866a"
+      "sha256": "4dbf44628416d12c8cdf46a6a73e293239736ca23dfb096e39850d68ffe5daa6"
     },
     "src/openai/types/beta/agent_session_assistant_message.py": {
       "mode": "100644",
@@ -1887,7 +1887,7 @@
     },
     "src/openai/types/beta/agent_update_params.py": {
       "mode": "100644",
-      "sha256": "5677862d355898407a4bc29cca2ad56e4ba93df1525f4805a76df029f348cef3"
+      "sha256": "6bc4493187bd7c9ce15ce7cfa3efce0264fec0c4149e0dc4e94264b248b94a36"
     },
     "src/openai/types/beta/agent_wait_for_subagents_call_item.py": {
       "mode": "100644",
@@ -1907,7 +1907,7 @@
     },
     "src/openai/types/beta/agents/automation_agent_config.py": {
       "mode": "100644",
-      "sha256": "41776af1d179879d851f2c766558473bd3f6c4a56bf77bc9182bb081395811ad"
+      "sha256": "bcc57f2186654a8d6ae3126678cbb72953588aacda537e0d1ce62f706e5cca41"
     },
     "src/openai/types/beta/agents/automation_create_params.py": {
       "mode": "100644",
@@ -1939,7 +1939,7 @@
     },
     "src/openai/types/beta/agents/automation_target_param.py": {
       "mode": "100644",
-      "sha256": "d850b41c5e0ba1e23715816ff6d078a7680ea085d26d4a23c74ef892daa85ec3"
+      "sha256": "2347708ca2624bc3ee7ae4e7209cbe6d2d35a6e1933b4251317ca287dadc5306"
     },
     "src/openai/types/beta/agents/automation_update_params.py": {
       "mode": "100644",
@@ -2019,7 +2019,7 @@
     },
     "src/openai/types/beta/agents/session_create_params.py": {
       "mode": "100644",
-      "sha256": "8507384a202b0b572799f1afb0ac44fbce25e1787a3c3b87b9fc270b8a135633"
+      "sha256": "d4566c2d07b1a1469e929763fa12e626cb1dbeae6dedfd00648f8220b4af8581"
     },
     "src/openai/types/beta/agents/session_list_params.py": {
       "mode": "100644",
@@ -7707,15 +7707,15 @@
     },
     "tests/api_resources/beta/agents/test_automations.py": {
       "mode": "100644",
-      "sha256": "80f3bd3acb28dfda5849f9d32c7d37bcaeaa5bab9e7aa6bca05df648030c410c"
+      "sha256": "34501f413c83a2ccd9aa494eb59f5c0ae1ba21fa14619dd2bc41571ad8a6422a"
     },
     "tests/api_resources/beta/agents/test_environments.py": {
       "mode": "100644",
       "sha256": "529f48933850ff09980fbd8a8ec6c9bef538efa5bffa71660e14421693df02fa"
     },
     "tests/api_resources/beta/agents/test_sessions.py": {
       "mode": "100644",
-      "sha256": "55353ee6b6a4b2e8349b20cac41b7223e3bee28ec6bb6b60411d9e0cb8dc3ed8"
+      "sha256": "8cfecc54a8e76b3714fa35298725eb6b315750fe5a2b112fff6185e14df8f831"
     },
     "tests/api_resources/beta/agents/test_vaults.py": {
       "mode": "100644",
@@ -7755,7 +7755,7 @@
     },
     "tests/api_resources/beta/test_agents.py": {
       "mode": "100644",
-      "sha256": "ad2a5d7d46d65caab580ad00c4840dc598504fc50bbf20cc9558c5f2713ca335"
+      "sha256": "6216ae37c6ea996da62e4916570840ed549aeb86603b607d61078b4b30c87d15"
     },
     "tests/api_resources/beta/test_assistants.py": {
       "mode": "100644",

src/openai/resources/beta/agents/agents.py

@@ -99,6 +99,7 @@ def create(
         *,
         model: str,
         compaction: Optional[agent_create_params.Compaction] | Omit = omit,
+        experimental: agent_create_params.Experimental | Omit = omit,
         instructions: Optional[str] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
         multi_agent: Optional[MultiAgentConfigParam] | Omit = omit,
@@ -124,6 +125,8 @@ def create(
 
           compaction: Context compaction settings. Omission or null enables background compaction.
 
+          experimental: Experimental agent settings. All experimental features default to disabled.
+
           instructions: Additional instructions appended to the agent's default base instructions. Omit
               or set to null to add no custom instructions.
 
@@ -168,6 +171,7 @@ def create(
                     "model": model,
                     "service_tier": service_tier,
                     "compaction": compaction,
+                    "experimental": experimental,
                     "instructions": instructions,
                     "metadata": metadata,
                     "multi_agent": multi_agent,
@@ -233,6 +237,7 @@ def update(
         agent_id: str,
         *,
         compaction: Optional[agent_update_params.Compaction] | Omit = omit,
+        experimental: agent_update_params.Experimental | Omit = omit,
         instructions: Optional[str] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
         model: str | Omit = omit,
@@ -259,6 +264,9 @@ def update(
               object replaces the settings; null or an empty object enables background
               compaction.
 
+          experimental: Experimental settings to merge by key. Omitted settings keep their current
+              values.
+
           instructions: Additional instructions appended to the agent's default base instructions. Omit
               to leave unchanged.
 
@@ -307,6 +315,7 @@ def update(
                     "model": model,
                     "service_tier": service_tier,
                     "compaction": compaction,
+                    "experimental": experimental,
                     "instructions": instructions,
                     "metadata": metadata,
                     "multi_agent": multi_agent,
@@ -467,6 +476,7 @@ async def create(
         *,
         model: str,
         compaction: Optional[agent_create_params.Compaction] | Omit = omit,
+        experimental: agent_create_params.Experimental | Omit = omit,
         instructions: Optional[str] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
         multi_agent: Optional[MultiAgentConfigParam] | Omit = omit,
@@ -492,6 +502,8 @@ async def create(
 
           compaction: Context compaction settings. Omission or null enables background compaction.
 
+          experimental: Experimental agent settings. All experimental features default to disabled.
+
           instructions: Additional instructions appended to the agent's default base instructions. Omit
               or set to null to add no custom instructions.
 
@@ -536,6 +548,7 @@ async def create(
                     "model": model,
                     "service_tier": service_tier,
                     "compaction": compaction,
+                    "experimental": experimental,
                     "instructions": instructions,
                     "metadata": metadata,
                     "multi_agent": multi_agent,
@@ -601,6 +614,7 @@ async def update(
         agent_id: str,
         *,
         compaction: Optional[agent_update_params.Compaction] | Omit = omit,
+        experimental: agent_update_params.Experimental | Omit = omit,
         instructions: Optional[str] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
         model: str | Omit = omit,
@@ -627,6 +641,9 @@ async def update(
               object replaces the settings; null or an empty object enables background
               compaction.
 
+          experimental: Experimental settings to merge by key. Omitted settings keep their current
+              values.
+
           instructions: Additional instructions appended to the agent's default base instructions. Omit
               to leave unchanged.
 
@@ -675,6 +692,7 @@ async def update(
                     "model": model,
                     "service_tier": service_tier,
                     "compaction": compaction,
+                    "experimental": experimental,
                     "instructions": instructions,
                     "metadata": metadata,
                     "multi_agent": multi_agent,

src/openai/types/beta/agent.py

@@ -11,7 +11,7 @@
 from .multi_agent_config import MultiAgentConfig
 from .persisted_agent_tool import PersistedAgentTool
 
-__all__ = ["Agent", "Compaction"]
+__all__ = ["Agent", "Compaction", "Experimental"]
 
 
 class Compaction(BaseModel):
@@ -21,6 +21,13 @@ class Compaction(BaseModel):
     """Whether context is compacted in the background. Defaults to true."""
 
 
+class Experimental(BaseModel):
+    """The effective experimental settings for the agent."""
+
+    time_awareness: bool
+    """Whether the model receives periodic current-time reminders."""
+
+
 class Agent(BaseModel):
     """A reusable agent scoped to the caller's project."""
 
@@ -68,3 +75,6 @@ class Agent(BaseModel):
 
     compaction: Optional[Compaction] = None
     """The effective context compaction settings."""
+
+    experimental: Optional[Experimental] = None
+    """The effective experimental settings for the agent."""

src/openai/types/beta/agent_create_params.py

@@ -11,7 +11,7 @@
 from .multi_agent_config_param import MultiAgentConfigParam
 from .persisted_agent_tool_param import PersistedAgentToolParam
 
-__all__ = ["AgentCreateParams", "Compaction"]
+__all__ = ["AgentCreateParams", "Compaction", "Experimental"]
 
 
 class AgentCreateParams(TypedDict, total=False):
@@ -21,6 +21,9 @@ class AgentCreateParams(TypedDict, total=False):
     compaction: Optional[Compaction]
     """Context compaction settings. Omission or null enables background compaction."""
 
+    experimental: Experimental
+    """Experimental agent settings. All experimental features default to disabled."""
+
     instructions: Optional[str]
     """Additional instructions appended to the agent's default base instructions.
 
@@ -79,3 +82,10 @@ class Compaction(TypedDict, total=False):
     Omission or null defaults to true. Set to false to use blocking compaction.
     Background compaction may increase token usage.
     """
+
+
+class Experimental(TypedDict, total=False):
+    """Experimental agent settings. All experimental features default to disabled."""
+
+    time_awareness: bool
+    """Whether to give the model periodic current-time reminders. Defaults to false."""