github-featured/microsoft--agent-framework

Files

T

Yunus Emre Gültepe 61802723ff Python: Support prompt cache breakpoints for GPT-5.6 models in OpenAI clients (#7163 )

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

Add request-level prompt_cache_options to OpenAIChatOptions and
OpenAIChatCompletionOptions, and forward a per-part prompt_cache_breakpoint
from Content.additional_properties onto the content blocks each API supports.
Text parts that carry a breakpoint keep typed list content, since the
plain-string form cannot hold one; without a breakpoint the existing string
forms are unchanged.

* Clarify system-message content-shape comment

* Address review: SDK prompt cache types, private helper, add sample

Replace the custom PromptCacheOptions TypedDict with the openai SDK's own
types for each API, which raises the openai floor to 2.45.0 where those
types were introduced. Make the breakpoint helper private to the two chat
clients. Add a prompt caching sample with a README entry, and unquote the
helper's Content annotation so the pyupgrade hook passes.

* Guard the prompt cache options import for older openai versions

The SDK's PromptCacheOptions types only exist in openai 2.45.0 and
later, so each client falls back to a local mirror when the import
fails and the dependency floor stays at 2.25.0. A TYPE_CHECKING-only
import is not enough because the options classes are introspected with
get_type_hints() at runtime. Verified against openai 2.25.0: the
package imports, the fallback resolves, and part-level breakpoints
still work; sending the option itself requires 2.45.0, which the field
docstrings now note.

* Make the old-openai fallback for PromptCacheOptions deliberately empty

Assigning None instead, as suggested in review, trips pyright's
reportInvalidTypeForm on the field annotation (the symbol becomes
type | None after the try/except). An empty TypedDict gives the same
effect for users on older openai versions: any content they put in
prompt_cache_options is flagged by their type checker, since the
option cannot be sent on those versions anyway, while
get_type_hints() on the options classes keeps working at runtime.

* Guard prompt_cache_options at runtime instead of via an empty fallback type

The empty-TypedDict fallback flagged valid `prompt_cache_options` usage under
pyright on every openai version — including this PR's own
`client_prompt_caching.py` sample (`poe check -S`) — because pyright resolves the
try/except symbol to the fallback shape regardless of the installed openai, while
mypy/ty resolve the failed import to `Any` and never warn. So a type-only "warn on
old openai" signal is not achievable cleanly across type checkers.

Restore the faithful fallback (mirrors the SDK's `mode`/`ttl` shape) so the option
type-checks identically on every supported openai version, and add a runtime guard:
setting `prompt_cache_options` on openai < 2.45 now raises a clear
ChatClientInvalidRequestException instead of forwarding an unusable option to the
SDK. This keeps the option non-silent for all users regardless of type checker,
without forcing an openai upgrade. Adds tests covering the guard for both clients.

* Gate system/developer breakpoint shape on a real mapping value

The system/developer branch switched to list-form content whenever
prompt_cache_breakpoint was set to any non-None value, but the option is
only attached when the value is a mapping. A malformed value (e.g. a
string) therefore changed the message shape without adding a breakpoint.
Decide the shape from the built part instead, matching the user-role path.

2026-07-22 21:43:19 +00:00

4.5 KiB

Raw Permalink Blame History

OpenAI Provider Samples

This folder contains OpenAI provider samples for the generic clients in agent_framework.openai.

Chat Completions API samples (`OpenAIChatCompletionClient`)

File	Description
`chat_completion_client_basic.py`	Basic non-streaming and streaming chat completion sample with an explicit `gpt-5.4-nano` model and API key.
`chat_completion_client_with_explicit_settings.py`	Chat completion sample with explicit model and API key settings.
`chat_completion_client_with_function_tools.py`	Function tools with agent-level and run-level patterns.
`chat_completion_client_with_local_mcp.py`	Local MCP integration with the chat completions client.
`chat_completion_client_with_runtime_json_schema.py`	Runtime JSON schema output with the chat completions client.
`chat_completion_client_with_session.py`	Session management with the chat completions client.
`chat_completion_client_with_web_search.py`	Web search with the chat completions client.

Responses API samples (`OpenAIChatClient`)

File	Description
`client_basic.py`	Basic non-streaming and streaming responses sample with an explicit `gpt-5.4-nano` model and API key.
`client_image_analysis.py`	Analyze images with the responses client.
`client_image_generation.py`	Generate images from text prompts.
`client_prompt_caching.py`	Explicit prompt cache breakpoints and `prompt_cache_options` on GPT-5.6 models.
`client_reasoning.py`	Reasoning-focused sample for models such as `gpt-5`.
`client_streaming_image_generation.py`	Streaming image generation sample.
`client_verbosity.py`	GPT-5 `verbosity` option (`low`/`medium`/`high`) with default and per-call overrides.
`client_with_agent_as_tool.py`	Agent-as-tool orchestration pattern.
`client_with_code_interpreter.py`	Code interpreter sample.
`client_with_code_interpreter_files.py`	Code interpreter sample with uploaded files.
`client_with_explicit_settings.py`	Responses client with explicit model and API key settings.
`client_with_file_search.py`	Hosted file search sample.
`client_with_function_tools.py`	Function tools with agent-level and run-level patterns.
`client_with_hosted_mcp.py`	Hosted MCP tools and approval workflows.
`client_with_local_mcp.py`	Local MCP integration with the responses client.
`client_with_local_shell.py`	Local shell tool sample.
`client_with_runtime_json_schema.py`	Runtime JSON schema output with the responses client.
`client_with_session.py`	Session management with the responses client.
`client_with_shell.py`	Hosted shell tool sample.
`client_with_structured_output.py`	Structured output with Pydantic models.
`client_with_web_search.py`	Web search with the responses client.

Environment Variables

Set these before running the OpenAI provider samples:

OPENAI_API_KEY
OPENAI_MODEL

Optionally, you can also set:

OPENAI_ORG_ID
OPENAI_BASE_URL

If your shell also contains AZURE_OPENAI_* variables, these samples still stay on OpenAI as long as OPENAI_API_KEY is present. To force Azure routing with the generic clients, pass an explicit Azure input such as credential, azure_endpoint, or api_version, or use the Azure provider samples.

Optional Dependencies

Some samples need extra packages:

client_image_generation.py and client_streaming_image_generation.py use Pillow for image display.
MCP samples require the relevant MCP server/tooling you configure locally.

4.5 KiB Raw Permalink Blame History