Skip to content

Commit f3db60f

Browse files
authored
Python: Support GPT-5 verbosity option and restore Foundry agent_reference (microsoft#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 microsoft#5582: PR microsoft#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 microsoft#5516 Closes microsoft#5582 * Python: Address Copilot review on PR microsoft#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.
1 parent 4a2da95 commit f3db60f

8 files changed

Lines changed: 323 additions & 2 deletions

File tree

‎python/packages/foundry/agent_framework_foundry/_agent.py‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,18 @@ def _uses_foundry_agent_session(conversation_id: Any) -> bool:
135135
)
136136

137137

138+
def _build_agent_reference(agent_name: str, agent_version: str | None) -> dict[str, str]:
139+
"""Build the Responses API ``agent_reference`` payload for non-preview Foundry agent calls.
140+
141+
Used for both Prompt Agents and HostedAgents on the ``allow_preview=False`` code path —
142+
the preview branch instead injects identity via ``project_client.get_openai_client(agent_name=...)``.
143+
"""
144+
ref: dict[str, str] = {"name": agent_name, "type": "agent_reference"}
145+
if agent_version:
146+
ref["version"] = agent_version
147+
return ref
148+
149+
138150
class RawFoundryAgentChatClient( # type: ignore[misc]
139151
RawOpenAIChatClient[FoundryAgentOptionsT],
140152
Generic[FoundryAgentOptionsT],
@@ -342,6 +354,12 @@ async def _prepare_options(
342354
run_options.pop("previous_response_id", None)
343355
run_options.pop("conversation", None)
344356
extra_body["agent_session_id"] = conversation_id
357+
# Non-preview Prompt/Hosted Agent calls need agent_reference in the request body to
358+
# tell the Responses API which Foundry agent (and version) is in use, since ``model``
359+
# is stripped below. The preview path injects the reference via the OpenAI client kwarg
360+
# ``agent_name`` instead, so skip there. See issue #5582.
361+
if not self.allow_preview:
362+
extra_body.setdefault("agent_reference", _build_agent_reference(self.agent_name, self.agent_version))
345363
if extra_body:
346364
run_options["extra_body"] = extra_body
347365

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

Lines changed: 127 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -196,7 +196,10 @@ def my_func() -> str:
196196
options={"tools": [my_func]},
197197
)
198198

199-
assert result == {}
199+
# agent_reference is required so the Responses API can resolve model server-side; see #5582.
200+
assert result == {
201+
"extra_body": {"agent_reference": {"name": "test-agent", "type": "agent_reference"}},
202+
}
200203

201204

202205
async def test_raw_foundry_agent_chat_client_prepare_options_strips_client_side_fields() -> None:
@@ -236,7 +239,128 @@ def my_func() -> str:
236239
assert "tools" not in result
237240
assert "tool_choice" not in result
238241
assert "parallel_tool_calls" not in result
239-
assert result == {}
242+
# agent_reference is required so the Responses API can resolve model server-side; see #5582.
243+
assert result == {
244+
"extra_body": {"agent_reference": {"name": "test-agent", "type": "agent_reference"}},
245+
}
246+
247+
248+
async def test_raw_foundry_agent_chat_client_prepare_options_injects_agent_reference_first_turn() -> None:
249+
"""First-turn (no conversation_id) Prompt Agent calls must carry agent_reference in extra_body.
250+
251+
Regression test for https://github.com/microsoft/agent-framework/issues/5582 — without this
252+
the Responses API rejects with "Missing required parameter: 'model'", because both ``model``
253+
and ``agent_reference`` are absent from the request body.
254+
"""
255+
256+
mock_project = MagicMock()
257+
mock_project.get_openai_client.return_value = MagicMock()
258+
259+
client = RawFoundryAgentChatClient(
260+
project_client=mock_project,
261+
agent_name="test-agent",
262+
agent_version="2",
263+
)
264+
265+
with patch(
266+
"agent_framework_openai._chat_client.RawOpenAIChatClient._prepare_options",
267+
new_callable=AsyncMock,
268+
return_value={"model": "gpt-4.1"},
269+
):
270+
result = await client._prepare_options(
271+
messages=[Message(role="user", contents="hi")],
272+
options={},
273+
)
274+
275+
assert "model" not in result
276+
assert result["extra_body"] == {
277+
"agent_reference": {"name": "test-agent", "type": "agent_reference", "version": "2"},
278+
}
279+
280+
281+
async def test_raw_foundry_agent_chat_client_prepare_options_agent_reference_omits_version_when_unset() -> None:
282+
"""When agent_version is unset, agent_reference should omit the version key entirely."""
283+
284+
mock_project = MagicMock()
285+
mock_project.get_openai_client.return_value = MagicMock()
286+
287+
client = RawFoundryAgentChatClient(
288+
project_client=mock_project,
289+
agent_name="hosted-agent",
290+
)
291+
292+
with patch(
293+
"agent_framework_openai._chat_client.RawOpenAIChatClient._prepare_options",
294+
new_callable=AsyncMock,
295+
return_value={"model": "gpt-4.1"},
296+
):
297+
result = await client._prepare_options(
298+
messages=[Message(role="user", contents="hi")],
299+
options={},
300+
)
301+
302+
assert result["extra_body"] == {
303+
"agent_reference": {"name": "hosted-agent", "type": "agent_reference"},
304+
}
305+
306+
307+
async def test_raw_foundry_agent_chat_client_prepare_options_skips_agent_reference_when_allow_preview() -> None:
308+
"""Hosted-agent (allow_preview=True) requests must NOT add agent_reference in the body.
309+
310+
The preview path injects the agent identity via ``project_client.get_openai_client(agent_name=...)``
311+
at the SDK wrapper level. Adding it again in extra_body would either duplicate or conflict
312+
with the wrapper's injection. Keep this gate aligned with the constructor branch in
313+
``RawFoundryAgentChatClient.__init__``.
314+
"""
315+
316+
mock_project = MagicMock()
317+
mock_project.get_openai_client.return_value = MagicMock()
318+
319+
client = RawFoundryAgentChatClient(
320+
project_client=mock_project,
321+
agent_name="hosted-agent",
322+
agent_version="3",
323+
allow_preview=True,
324+
)
325+
326+
with patch(
327+
"agent_framework_openai._chat_client.RawOpenAIChatClient._prepare_options",
328+
new_callable=AsyncMock,
329+
return_value={"model": "gpt-4.1"},
330+
):
331+
result = await client._prepare_options(
332+
messages=[Message(role="user", contents="hi")],
333+
options={},
334+
)
335+
336+
assert "model" not in result
337+
# No extra_body at all is the cleanest signal — agent_reference must not be injected here.
338+
assert "extra_body" not in result
339+
340+
341+
async def test_raw_foundry_agent_chat_client_prepare_options_respects_caller_agent_reference() -> None:
342+
"""A caller-supplied extra_body['agent_reference'] should not be overwritten."""
343+
344+
mock_project = MagicMock()
345+
mock_project.get_openai_client.return_value = MagicMock()
346+
347+
client = RawFoundryAgentChatClient(
348+
project_client=mock_project,
349+
agent_name="default-agent",
350+
)
351+
352+
caller_reference = {"name": "override-agent", "type": "agent_reference", "version": "5"}
353+
with patch(
354+
"agent_framework_openai._chat_client.RawOpenAIChatClient._prepare_options",
355+
new_callable=AsyncMock,
356+
return_value={"model": "gpt-4.1", "extra_body": {"agent_reference": caller_reference}},
357+
):
358+
result = await client._prepare_options(
359+
messages=[Message(role="user", contents="hi")],
360+
options={"extra_body": {"agent_reference": caller_reference}},
361+
)
362+
363+
assert result["extra_body"]["agent_reference"] == caller_reference
240364

241365

242366
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_
267391
assert result["extra_body"] == {
268392
"custom": "value",
269393
"agent_session_id": "agent-session-123",
394+
"agent_reference": {"name": "test-agent", "type": "agent_reference"},
270395
}
271396
assert "previous_response_id" not in result
272397
assert "conversation" not in result

‎python/packages/openai/agent_framework_openai/_chat_client.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,11 @@ class OpenAIChatOptions(ChatOptions[ResponseFormatT], Generic[ResponseFormatT],
204204
"""Configuration for reasoning models (gpt-5, o-series).
205205
See: https://platform.openai.com/docs/guides/reasoning"""
206206

207+
verbosity: Literal["low", "medium", "high"]
208+
"""Output verbosity for GPT-5 family models. Lower values yield shorter responses.
209+
Translated to ``text.verbosity`` when sent to the Responses API.
210+
See: https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_new_params_and_tools#1-verbosity-parameter"""
211+
207212
safety_identifier: str
208213
"""A stable identifier for detecting policy violations.
209214
Recommend hashing username/email to avoid sending identifying info."""
@@ -1322,6 +1327,11 @@ async def _prepare_options(
13221327
response_format, text_config = self._prepare_response_and_text_format(
13231328
response_format=response_format, text_config=text_config
13241329
)
1330+
# The Responses API nests verbosity under ``text.verbosity``; surface it as a
1331+
# top-level option for parity with ``reasoning`` and translate here.
1332+
if (verbosity := run_options.pop("verbosity", None)) is not None:
1333+
text_config = dict(text_config) if text_config else {}
1334+
text_config["verbosity"] = verbosity
13251335
if text_config:
13261336
run_options["text"] = text_config
13271337
if response_format:

‎python/packages/openai/agent_framework_openai/_chat_completion_client.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,9 @@ class OpenAIChatCompletionOptions(ChatOptions[ResponseModelT], Generic[ResponseM
145145
logprobs: bool
146146
top_logprobs: int
147147
prediction: Prediction
148+
verbosity: Literal["low", "medium", "high"]
149+
"""Output verbosity for GPT-5 family models. Lower values yield shorter responses.
150+
See: https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_new_params_and_tools#1-verbosity-parameter"""
148151

149152

150153
OpenAIChatCompletionOptionsT = TypeVar(

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

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -343,6 +343,76 @@ async def test_get_response_with_all_parameters() -> None:
343343
assert run_options["input"][1]["content"][0]["text"] == "Test message"
344344

345345

346+
def test_openai_chat_options_declares_verbosity_field() -> None:
347+
"""OpenAIChatOptions declares verbosity as a typed Literal field."""
348+
from typing import get_args, get_type_hints
349+
350+
from agent_framework_openai import OpenAIChatOptions
351+
352+
annotations = get_type_hints(OpenAIChatOptions)
353+
assert "verbosity" in annotations
354+
assert {"low", "medium", "high"} <= set(get_args(annotations["verbosity"]))
355+
356+
357+
async def test_verbosity_option_translates_to_text_field() -> None:
358+
"""Top-level verbosity is translated to text.verbosity for the Responses API."""
359+
client = OpenAIChatClient(model="test-model", api_key="test-key")
360+
_, run_options, _ = await client._prepare_request(
361+
messages=[Message(role="user", contents=["Test message"])],
362+
options={"verbosity": "low"},
363+
)
364+
365+
assert "verbosity" not in run_options
366+
assert run_options["text"] == {"verbosity": "low"}
367+
368+
369+
async def test_verbosity_option_merges_with_response_format() -> None:
370+
"""Verbosity merges into text config alongside response_format-derived format."""
371+
client = OpenAIChatClient(model="test-model", api_key="test-key")
372+
_, run_options, _ = await client._prepare_request(
373+
messages=[Message(role="user", contents=["Test message"])],
374+
options={
375+
"verbosity": "high",
376+
"response_format": OutputStruct,
377+
},
378+
)
379+
380+
assert "verbosity" not in run_options
381+
assert run_options["text"]["verbosity"] == "high"
382+
assert run_options["text_format"] is OutputStruct
383+
384+
385+
async def test_verbosity_option_top_level_overrides_nested_text_verbosity() -> None:
386+
"""When both top-level and text['verbosity'] are set, the top-level value wins."""
387+
client = OpenAIChatClient(model="test-model", api_key="test-key")
388+
_, run_options, _ = await client._prepare_request(
389+
messages=[Message(role="user", contents=["Test message"])],
390+
options={
391+
"verbosity": "high",
392+
"text": {"verbosity": "low"},
393+
},
394+
)
395+
396+
assert "verbosity" not in run_options
397+
assert run_options["text"]["verbosity"] == "high"
398+
399+
400+
async def test_verbosity_option_merges_with_explicit_text_config() -> None:
401+
"""Verbosity merges into a user-provided text config without overwriting other keys."""
402+
client = OpenAIChatClient(model="test-model", api_key="test-key")
403+
_, run_options, _ = await client._prepare_request(
404+
messages=[Message(role="user", contents=["Test message"])],
405+
options={
406+
"verbosity": "medium",
407+
"text": {"format": {"type": "text"}},
408+
},
409+
)
410+
411+
assert "verbosity" not in run_options
412+
assert run_options["text"]["verbosity"] == "medium"
413+
assert run_options["text"]["format"] == {"type": "text"}
414+
415+
346416
@pytest.mark.asyncio
347417
async def test_web_search_tool_with_location() -> None:
348418
"""Test web search tool with location parameters."""

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1563,6 +1563,27 @@ def test_prepare_options_removes_parallel_tool_calls_when_no_tools(
15631563
assert "parallel_tool_calls" not in prepared_options
15641564

15651565

1566+
def test_openai_chat_completion_options_declares_verbosity_field() -> None:
1567+
"""OpenAIChatCompletionOptions declares verbosity as a typed Literal field."""
1568+
from typing import get_args, get_type_hints
1569+
1570+
from agent_framework_openai import OpenAIChatCompletionOptions
1571+
1572+
annotations = get_type_hints(OpenAIChatCompletionOptions)
1573+
assert "verbosity" in annotations
1574+
assert {"low", "medium", "high"} <= set(get_args(annotations["verbosity"]))
1575+
1576+
1577+
def test_prepare_options_forwards_verbosity(openai_unit_test_env: dict[str, str]) -> None:
1578+
"""Verbosity passes through unchanged for the Chat Completions API."""
1579+
client = OpenAIChatCompletionClient()
1580+
1581+
messages = [Message(role="user", contents=["test"])]
1582+
prepared_options = client._prepare_options(messages, {"verbosity": "low"})
1583+
1584+
assert prepared_options["verbosity"] == "low"
1585+
1586+
15661587
def test_prepare_options_excludes_conversation_id(openai_unit_test_env: dict[str, str]) -> None:
15671588
"""Test that conversation_id is excluded from prepared options for chat completions."""
15681589
client = OpenAIChatCompletionClient()

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ This folder contains OpenAI provider samples for the generic clients in
2424
| [`client_image_generation.py`](client_image_generation.py) | Generate images from text prompts. |
2525
| [`client_reasoning.py`](client_reasoning.py) | Reasoning-focused sample for models such as `gpt-5`. |
2626
| [`client_streaming_image_generation.py`](client_streaming_image_generation.py) | Streaming image generation sample. |
27+
| [`client_verbosity.py`](client_verbosity.py) | GPT-5 `verbosity` option (`low`/`medium`/`high`) with default and per-call overrides. |
2728
| [`client_with_agent_as_tool.py`](client_with_agent_as_tool.py) | Agent-as-tool orchestration pattern. |
2829
| [`client_with_code_interpreter.py`](client_with_code_interpreter.py) | Code interpreter sample. |
2930
| [`client_with_code_interpreter_files.py`](client_with_code_interpreter_files.py) | Code interpreter sample with uploaded files. |

0 commit comments

Comments
 (0)