Python: raise clear error for runtime response_format on FoundryAgent (#5467)

[GitAashishG]

Fixes #5467

Problem

When a user passes response_format= (per-call or via default_options) to a
FoundryAgent, the request fails at the wire with an opaque server error:

openai.BadRequestError: Error code: 400 - {'error': {
  'code': 'invalid_payload',
  'message': "Not allowed when agent is specified."
}}

The Foundry agent endpoint owns response-schema configuration at agent
creation time — so per-call text / response_format options are not a
supported runtime knob for FoundryAgent.

Approach

Per @moonbox3's review, silently stripping the option would be wrong — it
would turn response_format into a client-side parse hint that contradicts
the FoundryAgent design. Instead this PR raises an explicit, actionable
error up-front:

raise ChatClientInvalidRequestException(
    "FoundryAgent does not support per-call 'response_format'. "
    "Foundry agents are created with a fixed response schema. "
    "Either (a) recreate the Foundry agent with the desired "
    "response_format on the server side, or (b) use "
    "FoundryChatClient (without binding to a Foundry agent) "
    "wrapped in Agent for per-call structured output."
)

The guard sits at the top of _RawFoundryAgentChatClient._prepare_options,
so it covers both streaming and non-streaming entry points and also catches
response_format set via Agent.default_options.

Scope

• Affects only FoundryAgent (bound to a server-side agent)
• FoundryChatClient is unchanged — per-call response_format continues to
  work there (existing test_response_format_parse_path covers this)
• No public API surface change; only adds a clearer error path

Testing

• New unit test test_raw_foundry_agent_chat_client_prepare_options_rejects_runtime_response_format
  covers both the Pydantic BaseModel and dict / json_schema variants
• Full Foundry suite: 293 passed, 15 skipped
• ruff check, ruff format --check, pyright — all clean

Files changed

• python/packages/foundry/agent_framework_foundry/_agent.py — guard +
  import of ChatClientInvalidRequestException
• python/packages/foundry/tests/foundry/test_foundry_agent.py — new guard
  test

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/foundry/agent_framework_foundry
_agent.py	232	54	76%	122, 125, 232–233, 237–239, 244–247, 355, 428–429, 441–442, 454–456, 458–459, 461–467, 469–470, 472, 474, 480–482, 485–494, 498–499, 686–687, 690, 716, 726, 742, 807
TOTAL	30505	3560	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
6132	30 💤	0 ❌	0 🔥	1m 38s ⏱️

[Copilot]

Pull request overview

This PR fixes a regression in agent-framework-foundry where providing response_format at runtime caused Foundry agent endpoint requests to fail with 400 invalid_payload due to disallowed per-call text configuration. The fix removes text and text_format from the outgoing request payload in the Foundry agent chat client so structured output is handled client-side via ChatResponse’s lazy parsing instead of being sent to the service.

Changes:

• Strip text and text_format from RawFoundryAgentChatClient._prepare_options request payload.
• Extend the existing _prepare_options stripping test to cover text/text_format.
• Add a new test to ensure runtime response_format variants (Pydantic and dict/json_schema) don’t result in text/text_format being sent.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
python/packages/foundry/agent_framework_foundry/_agent.py	Drops text/text_format from prepared run options to avoid Foundry agent endpoint rejection and rely on client-side structured parsing.
python/packages/foundry/tests/foundry/test_foundry_agent.py	Adds/extends unit tests to assert text/text_format are stripped, including runtime response_format scenarios.

[Copilot]

The explanatory comment implies that when the bound agent output doesn’t match the runtime schema, accessing response.value will raise pydantic.ValidationError. That’s only true for Pydantic response_format; for the dict/json_schema variant the lazy parsing path only does json.loads(...) and will raise ValueError on invalid JSON (and does not validate against the schema). Consider adjusting the comment to reflect both behaviors to avoid confusing users.

Suggested change

	# configured to emit JSON matching the requested schema; otherwise
	# ``response.value`` will raise ``pydantic.ValidationError`` on access.
	# configured to emit JSON compatible with the requested format; for a
	# Pydantic ``response_format``, accessing ``response.value`` may raise
	# ``pydantic.ValidationError`` if validation fails, while for a dict/
	# ``json_schema`` format the lazy path only parses JSON and may raise
	# ``ValueError`` for invalid JSON without validating against the schema.

[moonbox3]

As I eluded to in the original issue: the preferred direction here is to raise a clear runtime error in _prepare_options when response_format is provided, pointing the caller to either configure it at agent creation or use FoundryChatClient + Agent for per-call response formats.

[moonbox3]

The 400 going away isn't equivalent to runtime response_format being supported: silently stripping it turns the option into a client-side parse hint, which contradicts the FoundryAgent design (settings at creation time).

[GitAashishG]

As I eluded to in the original issue: the preferred direction here is to raise a clear runtime error in _prepare_options when response_format is provided, pointing the caller to either configure it at agent creation or use FoundryChatClient + Agent for per-call response formats.

---

Thanks, that makes sense. Pivoted to the guard approach: _prepare_options now raises ChatClientInvalidRequestException with a message pointing to the two supported paths (recreate the agent server-side, or FoundryChatClient + Agent). Updated tests accordingly. Let me know if the message wording works for you.