feat(api): add agent context compaction settings

.castiron.stats.yml

@@ -1,7 +1,7 @@
 schema_version: 1
-generation_id: 27aedac3-d226-45f3-9b03-cdbc31e26c4a
-openapi_spec_hash: 6e0c0f870093ed93cda3b6c04057dff1
-openapi_transformed_spec_hash: 6dca3c69339704dc304046890bab23a2
+generation_id: 093e3a9d-ca04-4b14-b524-cdefc6807fe1
+openapi_spec_hash: df8d45213a6894a955338882c36a1d86
+openapi_transformed_spec_hash: 050a1c6e01247b5af767e740b8494686
 config_hash: 8a684aec06907ff8ced7809753e16225
-codegen_sha: a437bfc5da2d18f1d2cf8b2e0dabf33cbce30762
-codegen_hash: 7c728907f3820a04cdb65380930c806a947d51378d79412f730f857ec317f0bf
+codegen_sha: 514ca4482332258ac041a8d62a18c51ad31627e3
+codegen_hash: 319a11170cf75d4fb01e168ed07a00b7eecc51b23d5912ff6d9d8552968d127d

api_reference/openapi.transformed.yml

@@ -85063,6 +85063,9 @@ components:
         multi_agent:
           $ref: '#/components/schemas/MultiAgentConfigResource'
           description: The configuration for creating and coordinating subagents.
+        compaction:
+          $ref: '#/components/schemas/CompactionResource'
+          description: The effective context compaction settings.
       required:
       - model
       - reasoning
@@ -86500,6 +86503,11 @@ components:
           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.
+        compaction:
+          anyOf:
+          - $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.
       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:
@@ -89969,6 +89977,9 @@ components:
         multi_agent:
           $ref: '#/components/schemas/MultiAgentConfigResource'
           description: The resolved configuration for creating and coordinating subagents.
+        compaction:
+          $ref: '#/components/schemas/CompactionResource'
+          description: The effective context compaction settings.
       required:
       - id
       - object
@@ -90423,6 +90434,11 @@ components:
           - $ref: '#/components/schemas/MultiAgentConfigCurrentParam'
           - type: 'null'
           description: Configuration for creating and coordinating subagents. Subagent tools are disabled by default.
+        compaction:
+          anyOf:
+          - $ref: '#/components/schemas/CompactionParam'
+          - type: 'null'
+          description: Context compaction settings. Omission or null enables background compaction.
       required:
       - model
       additionalProperties: false
@@ -90493,6 +90509,11 @@ components:
           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.
+        compaction:
+          anyOf:
+          - $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.
       additionalProperties: false
       description: Fields to replace on an existing reusable agent.
     DeletedAgentResource:
@@ -91075,6 +91096,9 @@ components:
         multi_agent:
           $ref: '#/components/schemas/MultiAgentConfigResource'
           description: Configuration for creating and coordinating subagents.
+        compaction:
+          $ref: '#/components/schemas/CompactionResource'
+          description: The effective context compaction settings.
       required:
       - id
       - name
@@ -111061,6 +111085,26 @@ components:
           type: transport.dtmf.sent
           event_id: event_dtmf_2
           event: '#'
+    CompactionParam:
+      type: object
+      properties:
+        async:
+          type:
+          - boolean
+          - 'null'
+          description: Whether to compact context in the background. Omission or null defaults to true. Set to false to use blocking compaction. Background compaction may increase token usage.
+      additionalProperties: false
+      description: Settings for compacting the agent's context.
+    CompactionResource:
+      type: object
+      properties:
+        async:
+          type: boolean
+          description: Whether context is compacted in the background. Defaults to true.
+      required:
+      - async
+      additionalProperties: false
+      description: The effective settings for compacting the agent's context.
     SessionSpendControlResource:
       type: object
       properties:

scripts/castiron/generated-files.json

@@ -239,7 +239,7 @@
     },
     "src/openai/resources/beta/agents/agents.py": {
       "mode": "100644",
-      "sha256": "bf71aadeaf938d143a5965256e219237fe4bfc61162f401744c37cb1c9996a50"
+      "sha256": "fa3b51beeff5b5c0cf3454aa34b13b72301fdf7420996f9e71974700f6b8bcbd"
     },
     "src/openai/resources/beta/agents/automations/__init__.py": {
       "mode": "100644",
@@ -1591,7 +1591,7 @@
     },
     "src/openai/types/beta/agent.py": {
       "mode": "100644",
-      "sha256": "49592e550206fd1fc615f3cb4ec1a9678185ece70059de6b6074b967a35b4d8c"
+      "sha256": "39c20eb4aae2c8a5bd650ef29331f4a9c6a859ae9cbb674e9ddb62e2f85a13c8"
     },
     "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": "77d29008724620d464e53153004c4cfb91f350d0814b6c84635005004ca6fc25"
+      "sha256": "e43e1e4d33b6e9764aa070c25bc15809a035ffb1ddfadc4680e33020f260f36b"
     },
     "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": "ed9a72c49bf1dcdf0b875f323ceb257eb772ac0a290c3d595a436998cc79ed75"
+      "sha256": "942e581fb98626566ae555e27262d1c6a7b772201e3385695ed1462ed317866a"
     },
     "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": "e9ec42a357a53780f81361f20080a7ee6762b461d243289511637bc67b76eaa4"
+      "sha256": "5677862d355898407a4bc29cca2ad56e4ba93df1525f4805a76df029f348cef3"
     },
     "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": "e3c97c93d0db0e76a7d407b62f65c4cf284825494bcf1d0d96653305e994781b"
+      "sha256": "41776af1d179879d851f2c766558473bd3f6c4a56bf77bc9182bb081395811ad"
     },
     "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": "aad9dcc0ce6817c9ff825e0c718fa046e2f06966e5e77d2fa4d60faa23a389e4"
+      "sha256": "d850b41c5e0ba1e23715816ff6d078a7680ea085d26d4a23c74ef892daa85ec3"
     },
     "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": "70fe10d2ef44268bad65a58f96ae70e4150f1092c885bf78f28e3ddb99df5af1"
+      "sha256": "8507384a202b0b572799f1afb0ac44fbce25e1787a3c3b87b9fc270b8a135633"
     },
     "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": "37b24f5906be1a5b0b7479fc13d78befdf10ea262658cb7de10c29dec86e4f96"
+      "sha256": "80f3bd3acb28dfda5849f9d32c7d37bcaeaa5bab9e7aa6bca05df648030c410c"
     },
     "tests/api_resources/beta/agents/test_environments.py": {
       "mode": "100644",
       "sha256": "529f48933850ff09980fbd8a8ec6c9bef538efa5bffa71660e14421693df02fa"
     },
     "tests/api_resources/beta/agents/test_sessions.py": {
       "mode": "100644",
-      "sha256": "42d73e43adfc9dff9ac4b0742dc16e6d97f9f67b2a83da62304193da0cf48077"
+      "sha256": "55353ee6b6a4b2e8349b20cac41b7223e3bee28ec6bb6b60411d9e0cb8dc3ed8"
     },
     "tests/api_resources/beta/agents/test_vaults.py": {
       "mode": "100644",
@@ -7755,7 +7755,7 @@
     },
     "tests/api_resources/beta/test_agents.py": {
       "mode": "100644",
-      "sha256": "c46bb6c136bd81420c9038ded41cc1cff3600332f60377587fefefb52824d9b6"
+      "sha256": "ad2a5d7d46d65caab580ad00c4840dc598504fc50bbf20cc9558c5f2713ca335"
     },
     "tests/api_resources/beta/test_assistants.py": {
       "mode": "100644",

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

@@ -98,6 +98,7 @@ def create(
         self,
         *,
         model: str,
+        compaction: Optional[agent_create_params.Compaction] | Omit = omit,
         instructions: Optional[str] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
         multi_agent: Optional[MultiAgentConfigParam] | Omit = omit,
@@ -121,6 +122,8 @@ def create(
         Args:
           model: The model to use for the agent. The requested model name is preserved.
 
+          compaction: Context compaction settings. Omission or null enables background compaction.
+
           instructions: Additional instructions appended to the agent's default base instructions. Omit
               or set to null to add no custom instructions.
 
@@ -164,6 +167,7 @@ def create(
                 {
                     "model": model,
                     "service_tier": service_tier,
+                    "compaction": compaction,
                     "instructions": instructions,
                     "metadata": metadata,
                     "multi_agent": multi_agent,
@@ -228,6 +232,7 @@ def update(
         self,
         agent_id: str,
         *,
+        compaction: Optional[agent_update_params.Compaction] | Omit = omit,
         instructions: Optional[str] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
         model: str | Omit = omit,
@@ -250,6 +255,10 @@ def update(
         [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).
 
         Args:
+          compaction: Context compaction settings. Omit to keep the current settings. A supplied
+              object replaces the settings; null or an empty object enables background
+              compaction.
+
           instructions: Additional instructions appended to the agent's default base instructions. Omit
               to leave unchanged.
 
@@ -297,6 +306,7 @@ def update(
                 {
                     "model": model,
                     "service_tier": service_tier,
+                    "compaction": compaction,
                     "instructions": instructions,
                     "metadata": metadata,
                     "multi_agent": multi_agent,
@@ -456,6 +466,7 @@ async def create(
         self,
         *,
         model: str,
+        compaction: Optional[agent_create_params.Compaction] | Omit = omit,
         instructions: Optional[str] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
         multi_agent: Optional[MultiAgentConfigParam] | Omit = omit,
@@ -479,6 +490,8 @@ async def create(
         Args:
           model: The model to use for the agent. The requested model name is preserved.
 
+          compaction: Context compaction settings. Omission or null enables background compaction.
+
           instructions: Additional instructions appended to the agent's default base instructions. Omit
               or set to null to add no custom instructions.
 
@@ -522,6 +535,7 @@ async def create(
                 {
                     "model": model,
                     "service_tier": service_tier,
+                    "compaction": compaction,
                     "instructions": instructions,
                     "metadata": metadata,
                     "multi_agent": multi_agent,
@@ -586,6 +600,7 @@ async def update(
         self,
         agent_id: str,
         *,
+        compaction: Optional[agent_update_params.Compaction] | Omit = omit,
         instructions: Optional[str] | Omit = omit,
         metadata: Optional[Dict[str, str]] | Omit = omit,
         model: str | Omit = omit,
@@ -608,6 +623,10 @@ async def update(
         [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).
 
         Args:
+          compaction: Context compaction settings. Omit to keep the current settings. A supplied
+              object replaces the settings; null or an empty object enables background
+              compaction.
+
           instructions: Additional instructions appended to the agent's default base instructions. Omit
               to leave unchanged.
 
@@ -655,6 +674,7 @@ async def update(
                 {
                     "model": model,
                     "service_tier": service_tier,
+                    "compaction": compaction,
                     "instructions": instructions,
                     "metadata": metadata,
                     "multi_agent": multi_agent,

src/openai/types/beta/agent.py

@@ -3,13 +3,22 @@
 from typing import Dict, List, Optional
 from typing_extensions import Literal
 
+from pydantic import Field as FieldInfo
+
 from ..._models import BaseModel
 from .agent_text import AgentText
 from .agent_reasoning import AgentReasoning
 from .multi_agent_config import MultiAgentConfig
 from .persisted_agent_tool import PersistedAgentTool
 
-__all__ = ["Agent"]
+__all__ = ["Agent", "Compaction"]
+
+
+class Compaction(BaseModel):
+    """The effective context compaction settings."""
+
+    async_: bool = FieldInfo(alias="async")
+    """Whether context is compacted in the background. Defaults to true."""
 
 
 class Agent(BaseModel):
@@ -56,3 +65,6 @@ class Agent(BaseModel):
 
     updated_at: int
     """The Unix timestamp, in seconds, when the agent was last updated."""
+
+    compaction: Optional[Compaction] = None
+    """The effective context compaction settings."""

src/openai/types/beta/agent_create_params.py

@@ -3,20 +3,24 @@
 from __future__ import annotations
 
 from typing import Dict, Iterable, Optional
-from typing_extensions import Literal, Required, TypedDict
+from typing_extensions import Literal, Required, Annotated, TypedDict
 
+from ..._utils import PropertyInfo
 from .agent_text_param import AgentTextParam
 from .agent_reasoning_param import AgentReasoningParam
 from .multi_agent_config_param import MultiAgentConfigParam
 from .persisted_agent_tool_param import PersistedAgentToolParam
 
-__all__ = ["AgentCreateParams"]
+__all__ = ["AgentCreateParams", "Compaction"]
 
 
 class AgentCreateParams(TypedDict, total=False):
     model: Required[str]
     """The model to use for the agent. The requested model name is preserved."""
 
+    compaction: Optional[Compaction]
+    """Context compaction settings. Omission or null enables background compaction."""
+
     instructions: Optional[str]
     """Additional instructions appended to the agent's default base instructions.
 
@@ -64,3 +68,14 @@ class AgentCreateParams(TypedDict, total=False):
     Defaults to an empty list. The tool list must fit within 3 MiB (3,145,728 bytes)
     of compact UTF-8 JSON.
     """
+
+
+class Compaction(TypedDict, total=False):
+    """Context compaction settings. Omission or null enables background compaction."""
+
+    async_: Annotated[Optional[bool], PropertyInfo(alias="async")]
+    """Whether to compact context in the background.
+
+    Omission or null defaults to true. Set to false to use blocking compaction.
+    Background compaction may increase token usage.
+    """