Python: update FoundryAgent for hosted agent sessions

[eavanvalkenburg]

Motivation and Context

Foundry hosted agents now rely on preview session APIs, and the current Python Foundry agent and sample flow did not handle lazy service session creation or the new hosted request payload shape. This change aligns the Foundry agent, foundry_hosting server, and hosted-agent samples with the new hosted-agent flow.

Description

• add hosted-agent session support to FoundryAgent and RawFoundryAgent, including FoundryAgentOptions, lazy service-session creation and deletion, and agent-session mapping through AgentSession.service_session_id and conversation_id
• pass hosted-agent request data through the Foundry chat client while preserving caller extra_body, and document the allow_preview=True requirement for HostedAgent preview session APIs
• refresh the hosted-agent samples and fix foundry_hosting non-streaming response handling and related tests

Closes: #5416

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_telemetry.py	52	5	90%	63, 78–80, 126
packages/foundry/agent_framework_foundry
_agent.py	226	58	74%	118, 121, 228–229, 233–235, 240–243, 333, 377, 383–385, 403–404, 416–417, 429–431, 433–434, 436–442, 444–445, 447, 449, 455–457, 460–469, 473–474, 661–662, 665, 691, 701, 717, 782
_chat_client.py	155	19	87%	84, 86–88, 92–93, 97, 191, 226, 319, 380, 382, 480, 484–485, 487–490
packages/foundry_hosting/agent_framework_foundry_hosting
_responses.py	506	114	77%	150–151, 160–161, 165, 170, 184, 208, 234–236, 255–257, 259–261, 263–265, 269–272, 275–280, 287, 292, 295, 302–303, 305–306, 308, 310, 312–315, 317–319, 323, 326–333, 336–337, 339–340, 348–353, 425–426, 1071–1073, 1075, 1097–1098, 1100–1101, 1103–1104, 1106–1107, 1118–1122, 1124, 1142, 1145, 1180–1184, 1188–1194, 1201–1205, 1211–1217, 1224, 1230, 1233
TOTAL	29331	3456	88%

Python Unit Test Overview

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

[github-actions]

Automated Code Review

Reviewers: 3 | Confidence: 92%

✗ Correctness

The _handle_inner_agent method in _responses.py has an inverted isinstance(self._agent, RawAgent) check: it warns and skips options for RawAgent (which supports options in .run() — see _agents.py:896) and passes options to non-RawAgent agents (whose SupportsAgentRun.run() at _agents.py:271-278 has no options parameter). This inverts the correct old behavior. The corresponding tests were updated to match the inverted logic (using raw_agent=False), masking the bug. The rest of the changes (FoundryAgentOptions, service session management, extra_body merging, allow_preview plumbing) look correct.

✓ Test Coverage

The PR adds substantial new functionality (FoundryAgentOptions, service session management, extra_body merging, conversation_id suppression) with generally good test coverage for the happy paths. However, there are notable test gaps: the streaming _parse_chunk_from_openai override has zero test coverage despite being a mirror of the tested _parse_response_from_openai; the allow_preview=True branch that preserves tools/tool_choice in _prepare_options is untested; and get_agent_version() error paths (TypeError raises) lack coverage. The _responses.py refactoring inverts the RawAgent/non-RawAgent options-forwarding logic, and the test was updated to match the new non-RawAgent path, but no test verifies the new RawAgent warning behavior.

✗ Design Approach

I found two design-level problems in the new hosted-session path. The first is a real identity mix-up: the code now allows the local wrapper name to diverge from the remote Foundry agent_name, but the new session-management methods call the service with self.name, so a custom display name will target the wrong hosted agent. The second is an abstraction mismatch around preview enablement: the docs say a caller can pass an already preview-configured project_client, but the implementation gates hosted-session behavior off the wrapper's allow_preview flag instead of the supplied client capability, so that path is disabled unless callers redundantly set both.

Suggestions

• Add a streaming-path test for _parse_chunk_from_openai analogous to test_raw_foundry_agent_chat_client_parse_response_suppresses_conversation_id_for_agent_sessions — the conversation_id suppression logic is identical but has zero test coverage.
• Model preview enablement as a single source of truth — either require the wrapper flag consistently and document it, or derive capability from the supplied project_client — so calers don't need to configure both.

---

Automated review by eavanvalkenburg's agents