Python: Support GPT-5 verbosity option and restore Foundry agent_reference (#5619)

* Python: Support GPT-5 verbosity option and restore Foundry agent_reference

Adds verbosity as a typed Literal["low","medium","high"] field on
OpenAIChatOptions (Responses API) and OpenAIChatCompletionOptions (Chat
Completions API), set in the same way as the existing reasoning options.
For the Responses API, top-level verbosity is translated to the nested
text.verbosity shape the OpenAI service expects. The same field flows
through to FoundryChatClient via the existing FoundryChatOptions alias.

Also fixes #5582: PR #5447 removed the agent_reference injection from
RawFoundryAgentChatClient._prepare_options, so first-turn calls against
a Foundry Prompt Agent went out without model and without agent_reference
and were rejected by the Responses API with "Missing required parameter:
'model'". Restores the injection on the non-preview path
(allow_preview=False) and adds a guard test that asserts the preview
path does not inject agent_reference, since the preview SDK injects it
via project_client.get_openai_client(agent_name=...).

Closes #5516
Closes #5582

* Python: Address Copilot review on PR #5619

- Foundry verbosity sample docstring: replace the misleading "set deployment
  name on model=" instruction with the actual env-var pattern the sample relies
  on (FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL).
- _build_agent_reference docstring: clarify the helper is used for both
  Prompt Agents and HostedAgents on the non-preview path.
- Add a Responses API test that locks in the documented precedence rule:
  when both top-level verbosity and text["verbosity"] are supplied, the
  top-level value wins.

* Python: Drop redundant Foundry verbosity sample and list OpenAI sample in README

- Remove samples/02-agents/providers/foundry/foundry_chat_client_verbosity.py
  per review feedback. The verbosity functionality is identical across the
  OpenAI and Foundry clients (FoundryChatOptions is an alias of
  OpenAIChatOptions), so a single sample on the OpenAI side is sufficient.
- Add the new client_verbosity.py entry to the OpenAI samples README.

python/samples/02-agents/providers/openai/README.md

@@ -24,6 +24,7 @@ This folder contains OpenAI provider samples for the generic clients in
 | [`client_image_generation.py`](client_image_generation.py) | Generate images from text prompts. |
 | [`client_reasoning.py`](client_reasoning.py) | Reasoning-focused sample for models such as `gpt-5`. |
 | [`client_streaming_image_generation.py`](client_streaming_image_generation.py) | Streaming image generation sample. |
+| [`client_verbosity.py`](client_verbosity.py) | GPT-5 `verbosity` option (`low`/`medium`/`high`) with default and per-call overrides. |
 | [`client_with_agent_as_tool.py`](client_with_agent_as_tool.py) | Agent-as-tool orchestration pattern. |
 | [`client_with_code_interpreter.py`](client_with_code_interpreter.py) | Code interpreter sample. |
 | [`client_with_code_interpreter_files.py`](client_with_code_interpreter_files.py) | Code interpreter sample with uploaded files. |

python/samples/02-agents/providers/openai/client_verbosity.py

@@ -0,0 +1,73 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Literal
+
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatClient, OpenAIChatOptions
+from dotenv import load_dotenv
+
+Verbosity = Literal["low", "medium", "high"]
+
+load_dotenv()
+
+"""
+OpenAI Chat Client Verbosity Example
+
+Demonstrates the GPT-5 ``verbosity`` parameter on the Responses API. ``verbosity``
+controls how concise or detailed the model's natural-language output is and accepts
+``"low"``, ``"medium"``, or ``"high"``.
+
+The framework exposes ``verbosity`` as a top-level option on ``OpenAIChatOptions``
+(parallel to ``reasoning``) and translates it to ``text.verbosity`` when calling the
+Responses API.
+"""
+
+
+PROMPT = "Explain in your own words what photosynthesis is and why it matters."
+
+
+async def run_with_verbosity(level: Verbosity) -> None:
+    """Run the same prompt with a different verbosity setting and print the output length."""
+    agent = Agent(
+        client=OpenAIChatClient[OpenAIChatOptions](model="gpt-5"),
+        name=f"Explainer-{level}",
+        instructions="You are a friendly science explainer.",
+        default_options={"verbosity": level},
+    )
+
+    print(f"\033[92m=== verbosity={level!r} ===\033[0m")
+    response = await agent.run(PROMPT)
+    text = response.text or ""
+    print(text)
+    print(f"\n[chars: {len(text)}]\n")
+
+
+async def run_per_call_override() -> None:
+    """Show that verbosity can be overridden per ``run`` call."""
+    agent = Agent(
+        client=OpenAIChatClient[OpenAIChatOptions](model="gpt-5"),
+        name="Explainer-default",
+        instructions="You are a friendly science explainer.",
+        default_options={"verbosity": "high"},
+    )
+
+    print("\033[92m=== per-call override: verbosity='low' ===\033[0m")
+    response = await agent.run(PROMPT, options={"verbosity": "low"})
+    text = response.text or ""
+    print(text)
+    print(f"\n[chars: {len(text)}]\n")
+
+
+async def main() -> None:
+    print("\033[92m=== OpenAI Chat Client Verbosity Example ===\033[0m\n")
+
+    levels: tuple[Verbosity, ...] = ("low", "medium", "high")
+    for level in levels:
+        await run_with_verbosity(level)
+
+    await run_per_call_override()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())