Python: Support prompt cache breakpoints for GPT-5.6 models in OpenAI clients

[Mordris]

Motivation & Context

GPT-5.6 models support explicit prompt cache breakpoints, and cache writes are billed on these models, so controlling where a prefix is cached now matters for cost. Today the clients silently drop a prompt_cache_breakpoint set through Content.additional_properties, and prompt_cache_options is not part of the typed chat options, so neither knob is usable from the framework.

Description & Review Guide

• What are the major changes?

  • A prompt_cache_options field on OpenAIChatOptions and OpenAIChatCompletionOptions, typed with the openai SDK's own PromptCacheOptions params type for each API. _prepare_options already forwards options generically, so no extra plumbing was needed.
  • A shared _attach_prompt_cache_breakpoint helper (private to the two chat clients) copies prompt_cache_breakpoint from Content.additional_properties onto the outgoing part, following the existing detail/file_id/filename pattern. It is applied to the blocks each API accepts: input_text/input_image/input_file for the Responses client, and text/image/audio/file parts for the Chat Completions client.
  • A client_prompt_caching.py sample (per review feedback) demonstrating both knobs with the visible cached-token count.
  • Chat Completions: _prepare_content_for_openai gets an explicit text case (text previously fell through to the to_dict fallback), and text parts that carry a breakpoint keep list-form content, because the plain-string flattening cannot hold one. The same applies to system/developer messages. Without a breakpoint, the existing string forms are preserved unchanged.

• What is the impact of these changes?

  • Opt-in only. Requests without the new option/metadata are unchanged; unit tests pin the exact part shapes for that case.
  • Verified against the live API: with mode: "explicit" (which disables the implicit breakpoint), a repeated ~1.6k-token prefix reports cached_tokens ≈ 3100 on the second call across gpt-5.6-luna, gpt-5.6-sol and gpt-5.6-terra on the Responses API, and on gpt-5.6-luna via Chat Completions; the same setup without a breakpoint reports 0. Older models are unaffected; opting in on one surfaces the API's own 400 (prompt_cache_breakpoint is not supported on this model).
  • The SDK's PromptCacheOptions types were introduced in openai 2.45.0, so the package floor moves from 2.25.0 to 2.45.0 in this PR.

• What do you want reviewers to focus on?

  • Whether additional_properties is the surface you want for the per-part breakpoint, or if you'd rather have a first-class field on Content (happy to rework it).
  • The list-vs-string content decision for Chat Completions text parts that carry a breakpoint.

Related Issue

Fixes #7157

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

Pull request overview

This PR adds Python OpenAI client support for GPT‑5.6 prompt caching controls by (a) exposing request-level prompt_cache_options in the typed options and (b) forwarding per-part prompt_cache_breakpoint metadata from Content.additional_properties into the outgoing request payloads, while preserving existing message-shape behavior when no breakpoint is present.

Changes:

• Introduces PromptCacheOptions and a shared attach_prompt_cache_breakpoint(...) helper in _shared.py.
• Adds prompt_cache_options to both Responses (OpenAIChatOptions) and Chat Completions (OpenAIChatCompletionOptions) typed option sets.
• Updates Chat Completions content/message preparation to keep list-form text parts when a breakpoint is present, and adds unit tests covering breakpoint propagation and options passthrough.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
python/packages/openai/agent_framework_openai/_shared.py	Adds a typed PromptCacheOptions shape and a helper to copy prompt_cache_breakpoint from Content.additional_properties into outgoing parts.
python/packages/openai/agent_framework_openai/_chat_completion_client.py	Plumbs breakpoint copying into Chat Completions parts and adjusts string-vs-list flattening so breakpoints are not lost.
python/packages/openai/agent_framework_openai/_chat_client.py	Plumbs breakpoint copying into Responses API parts and adds typed support for prompt_cache_options.
python/packages/openai/tests/openai/test_openai_chat_completion_client.py	Adds unit tests ensuring breakpoints are preserved (list-form) and prompt_cache_options passes through.
python/packages/openai/tests/openai/test_openai_chat_client.py	Adds unit tests ensuring breakpoint propagation for Responses parts and prompt_cache_options passthrough.

[Mordris]

@Mordris please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.

@microsoft-github-policy-service agree [company="{your company}"]

Options:

• (default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

@microsoft-github-policy-service agree

• (when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.

@microsoft-github-policy-service agree company="Microsoft"

Contributor License Agreement

@microsoft-github-policy-service agree

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/openai/agent_framework_openai
_chat_client.py	1279	123	90%	315, 328, 678–682, 690–693, 699–703, 753–760, 762–764, 771–773, 831, 839, 862, 980, 1079, 1138, 1140, 1142, 1144, 1210, 1224, 1304, 1314, 1319, 1362, 1473–1474, 1489, 1726, 1731–1732, 1815, 1825, 1852, 1858, 1868, 1874, 1879, 1885, 1890–1891, 1971, 2015, 2018–2021, 2035, 2037, 2045–2046, 2058, 2100, 2165, 2182, 2185, 2212–2214, 2253, 2270, 2273, 2335, 2342, 2366–2367, 2402, 2440–2441, 2459–2460, 2503, 2630–2631, 2649, 2732–2740, 2770, 2915, 2930, 2979–2982, 2992–2994, 3021–3023, 3033–3034, 3040, 3055, 3177–3178
_chat_completion_client.py	382	18	95%	449, 545–546, 550, 791, 793, 798, 801, 904, 906, 923, 944, 952, 976, 989, 1022, 1045, 1366
_shared.py	166	16	90%	257, 276–278, 290, 300, 312, 318, 340, 344, 378–379, 398, 417–418, 420
TOTAL	44614	5211	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9057	33 💤	0 ❌	0 🔥	2m 28s ⏱️

[eavanvalkenburg]

would be good to have a sample for this as well

[Mordris]

Added a sample: samples/02-agents/providers/openai/client_prompt_caching.py (plus a row in the folder README). It marks a stable prefix with prompt_cache_breakpoint under prompt_cache_options: {"mode": "explicit"} and prints cache_read_input_token_count per turn so the cache read is visible. Verified against gpt-5.6-luna: first turn writes (0 cached), the next one reads 1964 cached input tokens.