Add prompt_cache_retention to ModelSettings (#2095)

Author: ihower

src/agents/model_settings.py

@@ -116,6 +116,12 @@ class ModelSettings:
     For Responses API: automatically enabled when not specified.
     For Chat Completions API: disabled when not specified."""
 
+    prompt_cache_retention: Literal["in_memory", "24h"] | None = None
+    """The retention policy for the prompt cache. Set to `24h` to enable extended
+    prompt caching, which keeps cached prefixes active for longer, up to a maximum
+    of 24 hours.
+    [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention)."""
+
     include_usage: bool | None = None
     """Whether to include usage chunk.
     Only available for Chat Completions API."""

src/agents/models/openai_chatcompletions.py

@@ -308,6 +308,7 @@ async def _fetch_response(
             reasoning_effort=self._non_null_or_omit(reasoning_effort),
             verbosity=self._non_null_or_omit(model_settings.verbosity),
             top_logprobs=self._non_null_or_omit(model_settings.top_logprobs),
+            prompt_cache_retention=self._non_null_or_omit(model_settings.prompt_cache_retention),
             extra_headers=self._merge_headers(model_settings),
             extra_query=model_settings.extra_query,
             extra_body=model_settings.extra_body,

src/agents/models/openai_responses.py

@@ -326,6 +326,7 @@ async def _fetch_response(
             extra_body=model_settings.extra_body,
             text=response_format,
             store=self._non_null_or_omit(model_settings.store),
+            prompt_cache_retention=self._non_null_or_omit(model_settings.prompt_cache_retention),
             reasoning=self._non_null_or_omit(model_settings.reasoning),
             metadata=self._non_null_or_omit(model_settings.metadata),
             **extra_args,

tests/model_settings/test_serialization.py

@@ -56,6 +56,7 @@ def test_all_fields_serialization() -> None:
         reasoning=Reasoning(),
         metadata={"foo": "bar"},
         store=False,
+        prompt_cache_retention="24h",
         include_usage=False,
         response_include=["reasoning.encrypted_content"],
         top_logprobs=1,