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