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/packages/foundry/agent_framework_foundry/_agent.py

@@ -135,6 +135,18 @@ def _uses_foundry_agent_session(conversation_id: Any) -> bool:
     )
 
 
+def _build_agent_reference(agent_name: str, agent_version: str | None) -> dict[str, str]:
+    """Build the Responses API ``agent_reference`` payload for non-preview Foundry agent calls.
+
+    Used for both Prompt Agents and HostedAgents on the ``allow_preview=False`` code path —
+    the preview branch instead injects identity via ``project_client.get_openai_client(agent_name=...)``.
+    """
+    ref: dict[str, str] = {"name": agent_name, "type": "agent_reference"}
+    if agent_version:
+        ref["version"] = agent_version
+    return ref
+
+
 class RawFoundryAgentChatClient(  # type: ignore[misc]
     RawOpenAIChatClient[FoundryAgentOptionsT],
     Generic[FoundryAgentOptionsT],
@@ -342,6 +354,12 @@ class RawFoundryAgentChatClient(  # type: ignore[misc]
             run_options.pop("previous_response_id", None)
             run_options.pop("conversation", None)
             extra_body["agent_session_id"] = conversation_id
+        # Non-preview Prompt/Hosted Agent calls need agent_reference in the request body to
+        # tell the Responses API which Foundry agent (and version) is in use, since ``model``
+        # is stripped below. The preview path injects the reference via the OpenAI client kwarg
+        # ``agent_name`` instead, so skip there. See issue #5582.
+        if not self.allow_preview:
+            extra_body.setdefault("agent_reference", _build_agent_reference(self.agent_name, self.agent_version))
         if extra_body:
             run_options["extra_body"] = extra_body
 

python/packages/foundry/tests/foundry/test_foundry_agent.py

@@ -196,7 +196,10 @@ async def test_raw_foundry_agent_chat_client_prepare_options_accepts_function_to
             options={"tools": [my_func]},
         )
 
-    assert result == {}
+    # agent_reference is required so the Responses API can resolve model server-side; see #5582.
+    assert result == {
+        "extra_body": {"agent_reference": {"name": "test-agent", "type": "agent_reference"}},
+    }
 
 
 async def test_raw_foundry_agent_chat_client_prepare_options_strips_client_side_fields() -> None:
@@ -236,7 +239,128 @@ async def test_raw_foundry_agent_chat_client_prepare_options_strips_client_side_
     assert "tools" not in result
     assert "tool_choice" not in result
     assert "parallel_tool_calls" not in result
-    assert result == {}
+    # agent_reference is required so the Responses API can resolve model server-side; see #5582.
+    assert result == {
+        "extra_body": {"agent_reference": {"name": "test-agent", "type": "agent_reference"}},
+    }
+
+
+async def test_raw_foundry_agent_chat_client_prepare_options_injects_agent_reference_first_turn() -> None:
+    """First-turn (no conversation_id) Prompt Agent calls must carry agent_reference in extra_body.
+
+    Regression test for https://github.com/microsoft/agent-framework/issues/5582 — without this
+    the Responses API rejects with "Missing required parameter: 'model'", because both ``model``
+    and ``agent_reference`` are absent from the request body.
+    """
+
+    mock_project = MagicMock()
+    mock_project.get_openai_client.return_value = MagicMock()
+
+    client = RawFoundryAgentChatClient(
+        project_client=mock_project,
+        agent_name="test-agent",
+        agent_version="2",
+    )
+
+    with patch(
+        "agent_framework_openai._chat_client.RawOpenAIChatClient._prepare_options",
+        new_callable=AsyncMock,
+        return_value={"model": "gpt-4.1"},
+    ):
+        result = await client._prepare_options(
+            messages=[Message(role="user", contents="hi")],
+            options={},
+        )
+
+    assert "model" not in result
+    assert result["extra_body"] == {
+        "agent_reference": {"name": "test-agent", "type": "agent_reference", "version": "2"},
+    }
+
+
+async def test_raw_foundry_agent_chat_client_prepare_options_agent_reference_omits_version_when_unset() -> None:
+    """When agent_version is unset, agent_reference should omit the version key entirely."""
+
+    mock_project = MagicMock()
+    mock_project.get_openai_client.return_value = MagicMock()
+
+    client = RawFoundryAgentChatClient(
+        project_client=mock_project,
+        agent_name="hosted-agent",
+    )
+
+    with patch(
+        "agent_framework_openai._chat_client.RawOpenAIChatClient._prepare_options",
+        new_callable=AsyncMock,
+        return_value={"model": "gpt-4.1"},
+    ):
+        result = await client._prepare_options(
+            messages=[Message(role="user", contents="hi")],
+            options={},
+        )
+
+    assert result["extra_body"] == {
+        "agent_reference": {"name": "hosted-agent", "type": "agent_reference"},
+    }
+
+
+async def test_raw_foundry_agent_chat_client_prepare_options_skips_agent_reference_when_allow_preview() -> None:
+    """Hosted-agent (allow_preview=True) requests must NOT add agent_reference in the body.
+
+    The preview path injects the agent identity via ``project_client.get_openai_client(agent_name=...)``
+    at the SDK wrapper level. Adding it again in extra_body would either duplicate or conflict
+    with the wrapper's injection. Keep this gate aligned with the constructor branch in
+    ``RawFoundryAgentChatClient.__init__``.
+    """
+
+    mock_project = MagicMock()
+    mock_project.get_openai_client.return_value = MagicMock()
+
+    client = RawFoundryAgentChatClient(
+        project_client=mock_project,
+        agent_name="hosted-agent",
+        agent_version="3",
+        allow_preview=True,
+    )
+
+    with patch(
+        "agent_framework_openai._chat_client.RawOpenAIChatClient._prepare_options",
+        new_callable=AsyncMock,
+        return_value={"model": "gpt-4.1"},
+    ):
+        result = await client._prepare_options(
+            messages=[Message(role="user", contents="hi")],
+            options={},
+        )
+
+    assert "model" not in result
+    # No extra_body at all is the cleanest signal — agent_reference must not be injected here.
+    assert "extra_body" not in result
+
+
+async def test_raw_foundry_agent_chat_client_prepare_options_respects_caller_agent_reference() -> None:
+    """A caller-supplied extra_body['agent_reference'] should not be overwritten."""
+
+    mock_project = MagicMock()
+    mock_project.get_openai_client.return_value = MagicMock()
+
+    client = RawFoundryAgentChatClient(
+        project_client=mock_project,
+        agent_name="default-agent",
+    )
+
+    caller_reference = {"name": "override-agent", "type": "agent_reference", "version": "5"}
+    with patch(
+        "agent_framework_openai._chat_client.RawOpenAIChatClient._prepare_options",
+        new_callable=AsyncMock,
+        return_value={"model": "gpt-4.1", "extra_body": {"agent_reference": caller_reference}},
+    ):
+        result = await client._prepare_options(
+            messages=[Message(role="user", contents="hi")],
+            options={"extra_body": {"agent_reference": caller_reference}},
+        )
+
+    assert result["extra_body"]["agent_reference"] == caller_reference
 
 
 async def test_raw_foundry_agent_chat_client_prepare_options_maps_agent_session_id_to_extra_body() -> None:
@@ -267,6 +391,7 @@ async def test_raw_foundry_agent_chat_client_prepare_options_maps_agent_session_
     assert result["extra_body"] == {
         "custom": "value",
         "agent_session_id": "agent-session-123",
+        "agent_reference": {"name": "test-agent", "type": "agent_reference"},
     }
     assert "previous_response_id" not in result
     assert "conversation" not in result

python/packages/openai/agent_framework_openai/_chat_client.py

@@ -204,6 +204,11 @@ class OpenAIChatOptions(ChatOptions[ResponseFormatT], Generic[ResponseFormatT],
     """Configuration for reasoning models (gpt-5, o-series).
     See: https://platform.openai.com/docs/guides/reasoning"""
 
+    verbosity: Literal["low", "medium", "high"]
+    """Output verbosity for GPT-5 family models. Lower values yield shorter responses.
+    Translated to ``text.verbosity`` when sent to the Responses API.
+    See: https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_new_params_and_tools#1-verbosity-parameter"""
+
     safety_identifier: str
     """A stable identifier for detecting policy violations.
     Recommend hashing username/email to avoid sending identifying info."""
@@ -1322,6 +1327,11 @@ class RawOpenAIChatClient(  # type: ignore[misc]
         response_format, text_config = self._prepare_response_and_text_format(
             response_format=response_format, text_config=text_config
         )
+        # The Responses API nests verbosity under ``text.verbosity``; surface it as a
+        # top-level option for parity with ``reasoning`` and translate here.
+        if (verbosity := run_options.pop("verbosity", None)) is not None:
+            text_config = dict(text_config) if text_config else {}
+            text_config["verbosity"] = verbosity
         if text_config:
             run_options["text"] = text_config
         if response_format:

python/packages/openai/agent_framework_openai/_chat_completion_client.py

@@ -145,6 +145,9 @@ class OpenAIChatCompletionOptions(ChatOptions[ResponseModelT], Generic[ResponseM
     logprobs: bool
     top_logprobs: int
     prediction: Prediction
+    verbosity: Literal["low", "medium", "high"]
+    """Output verbosity for GPT-5 family models. Lower values yield shorter responses.
+    See: https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_new_params_and_tools#1-verbosity-parameter"""
 
 
 OpenAIChatCompletionOptionsT = TypeVar(

python/packages/openai/tests/openai/test_openai_chat_client.py

@@ -343,6 +343,76 @@ async def test_get_response_with_all_parameters() -> None:
     assert run_options["input"][1]["content"][0]["text"] == "Test message"
 
 
+def test_openai_chat_options_declares_verbosity_field() -> None:
+    """OpenAIChatOptions declares verbosity as a typed Literal field."""
+    from typing import get_args, get_type_hints
+
+    from agent_framework_openai import OpenAIChatOptions
+
+    annotations = get_type_hints(OpenAIChatOptions)
+    assert "verbosity" in annotations
+    assert {"low", "medium", "high"} <= set(get_args(annotations["verbosity"]))
+
+
+async def test_verbosity_option_translates_to_text_field() -> None:
+    """Top-level verbosity is translated to text.verbosity for the Responses API."""
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+    _, run_options, _ = await client._prepare_request(
+        messages=[Message(role="user", contents=["Test message"])],
+        options={"verbosity": "low"},
+    )
+
+    assert "verbosity" not in run_options
+    assert run_options["text"] == {"verbosity": "low"}
+
+
+async def test_verbosity_option_merges_with_response_format() -> None:
+    """Verbosity merges into text config alongside response_format-derived format."""
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+    _, run_options, _ = await client._prepare_request(
+        messages=[Message(role="user", contents=["Test message"])],
+        options={
+            "verbosity": "high",
+            "response_format": OutputStruct,
+        },
+    )
+
+    assert "verbosity" not in run_options
+    assert run_options["text"]["verbosity"] == "high"
+    assert run_options["text_format"] is OutputStruct
+
+
+async def test_verbosity_option_top_level_overrides_nested_text_verbosity() -> None:
+    """When both top-level and text['verbosity'] are set, the top-level value wins."""
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+    _, run_options, _ = await client._prepare_request(
+        messages=[Message(role="user", contents=["Test message"])],
+        options={
+            "verbosity": "high",
+            "text": {"verbosity": "low"},
+        },
+    )
+
+    assert "verbosity" not in run_options
+    assert run_options["text"]["verbosity"] == "high"
+
+
+async def test_verbosity_option_merges_with_explicit_text_config() -> None:
+    """Verbosity merges into a user-provided text config without overwriting other keys."""
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+    _, run_options, _ = await client._prepare_request(
+        messages=[Message(role="user", contents=["Test message"])],
+        options={
+            "verbosity": "medium",
+            "text": {"format": {"type": "text"}},
+        },
+    )
+
+    assert "verbosity" not in run_options
+    assert run_options["text"]["verbosity"] == "medium"
+    assert run_options["text"]["format"] == {"type": "text"}
+
+
 @pytest.mark.asyncio
 async def test_web_search_tool_with_location() -> None:
     """Test web search tool with location parameters."""

python/packages/openai/tests/openai/test_openai_chat_completion_client.py

@@ -1563,6 +1563,27 @@ def test_prepare_options_removes_parallel_tool_calls_when_no_tools(
     assert "parallel_tool_calls" not in prepared_options
 
 
+def test_openai_chat_completion_options_declares_verbosity_field() -> None:
+    """OpenAIChatCompletionOptions declares verbosity as a typed Literal field."""
+    from typing import get_args, get_type_hints
+
+    from agent_framework_openai import OpenAIChatCompletionOptions
+
+    annotations = get_type_hints(OpenAIChatCompletionOptions)
+    assert "verbosity" in annotations
+    assert {"low", "medium", "high"} <= set(get_args(annotations["verbosity"]))
+
+
+def test_prepare_options_forwards_verbosity(openai_unit_test_env: dict[str, str]) -> None:
+    """Verbosity passes through unchanged for the Chat Completions API."""
+    client = OpenAIChatCompletionClient()
+
+    messages = [Message(role="user", contents=["test"])]
+    prepared_options = client._prepare_options(messages, {"verbosity": "low"})
+
+    assert prepared_options["verbosity"] == "low"
+
+
 def test_prepare_options_excludes_conversation_id(openai_unit_test_env: dict[str, str]) -> None:
     """Test that conversation_id is excluded from prepared options for chat completions."""
     client = OpenAIChatCompletionClient()

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())