Python: Remove bespoke Foundry toolbox helpers; standardize on MCP for toolbox consumption

[moonbox3]

Motivation and Context

FoundryChatClient exposed a hand-rolled surface (get_toolbox, fetch_toolbox, select_toolbox_tools, get_toolbox_tool_name, get_toolbox_tool_type, FoundryHostedToolType) that required calers to manually fetch, filter, and normalize a ToolboxVersionObject before passing tools to an agent. Since every Foundry toolbox already exposes an MCP endpoint, this bespoke layer is redundant and adds unnecessary complexity.

Fixes #5670

Description

The fix removes the toolbox-specific helpers from _tools.py and _chat_client.py, drops their exports from both agent_framework_foundry and agent_framework.foundry, and removes the now-obsolete ExperimentalFeature.TOOLBOXES flag. Samples that used get_toolbox/select_toolbox_tools are rewritten to point MCPStreamableHTTPTool at the toolbox's MCP endpoint instead, with the existing MCP sample (foundry_chat_client_with_toolbox_mcp.py) renamed to become the canonical pattern. The _sanitize_foundry_response_tool helper and its docstrings are updated to remove toolbox-specific framing, since sanitization remains relevant for any hosted MCP tool definition delivered through the Responses API.

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.

---

Note: PR autogenerated by an agent

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_feature_stage.py	117	6	94%	99, 156, 167, 174, 207, 235
packages/foundry/agent_framework_foundry
_agent.py	236	54	77%	121, 124, 243–244, 248–250, 255–258, 348, 421–422, 434–435, 447–449, 451–452, 454–460, 462–463, 465, 467, 473–475, 478–487, 491–492, 679–680, 683, 709, 719, 735, 800
_chat_client.py	158	19	87%	85, 87–89, 93–94, 98, 192, 227, 327, 388, 390, 488, 492–493, 495–498
_tools.py	28	1	96%	72
TOTAL	33393	3914	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
6473	30 💤	0 ❌	0 🔥	1m 44s ⏱️

[moonbox3]

Automated Code Review

Reviewers: 4 | Confidence: 93%

✓ Correctness

All four changed files contain only cosmetic or housekeeping edits: a blank-line removal in a test file, three string-literal reformats in sample files, and removal of four symbols (FoundryHostedToolType, get_toolbox_tool_name, get_toolbox_tool_type, select_toolbox_tools) from the foundry stub (init.pyi). The removed symbols were already absent from init.py, so the stub now correctly reflects the package's public surface. No logic changes, no new code paths, and no correctness issues were identified.

✓ Security Reliability

This PR makes four unrelated changes: (1) removes a blank line in a test file, (2) removes four symbols from the foundry type stub that no longer exist in the underlying package, (3) reformats a long function call in a sample, and (4) joins a split string literal in another sample. The symbol removals from the .pyi stub are safe — a grep over the entire python/ tree finds zero references to FoundryHostedToolType, get_toolbox_tool_name, get_toolbox_tool_type, or select_toolbox_tools. No security or reliability issues were identified.

✓ Test Coverage

The PR makes four kinds of changes: (1) a blank-line removal in a test file, (2) removal of four stale symbols (FoundryHostedToolType, get_toolbox_tool_name, get_toolbox_tool_type, select_toolbox_tools) from the foundry/__init__.pyi type stub, and (3)/(4) line-length reformatting in two sample files. No new runtime behaviour is introduced, so there are no missing tests for new code paths. The removed symbols were never present in foundry/__init__.py's _IMPORTS dict (the actual lazy-loader), meaning they were never importable at runtime; the .pyi entries were simply stale. The existing test_foundry_namespace.py covers the positive surface (symbols that should be present) but has no negative assertion guarding against re-introduction of the removed names. This is a pre-existing gap rather than something introduced by this PR, so no change is blocked. A low-priority suggestion is to add a negative assertion so that accidental re-addition of these symbols is caught automatically.

✓ Design Approach

I did not find any design-approach issues in this diff. The sample and test edits are formatting-only, and the agent_framework.foundry.__init__.pyi change appears to remove stale type-stub exports that are already absent from the runtime lazy namespace (python/packages/core/agent_framework/foundry/__init__.py) and from the underlying agent_framework_foundry package surface, so it aligns the stub with the actual public contract rather than narrowing a supported API.

Suggestions

• Consider adding negative assertions in python/packages/core/tests/core/test_foundry_namespace.py to guard against accidental re-introduction of the removed symbols — e.g. assert 'FoundryHostedToolType' not in dir(foundry). This mirrors the pattern used in test_azure_namespace_no_longer_exposes_foundry_symbols and would catch stale stub entries being re-synced with the wrong implementation.

---

Automated review by automated agents

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 90%

✓ Correctness

The PR cleanly removes the bespoke toolbox helpers and consistently updates all production code, exports, type stubs, and most samples. One .env.example file was missed — 04_foundry_toolbox/.env.example still references the old TOOLBOX_NAME variable while the corresponding main.py was updated to read FOUNDRY_TOOLBOX_ENDPOINT. The observability README also still references the now-removed client.get_toolbox(...) API, though that's informational rather than functional.

✓ Security Reliability

This PR cleanly removes the bespoke Foundry toolbox helpers (get_toolbox, select_toolbox_tools, etc.) and standardizes on MCPStreamableHTTPTool for toolbox consumption. The security-critical sanitization layer (_sanitize_foundry_response_tool) that strips extraneous fields and validates hosted tool payloads before sending to the Responses API is preserved. The sample rewrites use standard Azure credential patterns (DefaultAzureCredential, get_bearer_token_provider) and properly scope tokens to 'https://ai.azure.com/.default'. No injection risks, secrets, resource leaks, or unhandled failure modes were identified.

✓ Test Coverage

This PR cleanly removes bespoke toolbox helpers and their corresponding tests. The deleted test_toolbox.py (435 lines) tested exclusively the removed functions (get_toolbox, select_toolbox_tools, get_toolbox_tool_name, get_toolbox_tool_type, fetch_toolbox). The remaining sanitization logic (_sanitize_foundry_response_tool, _validate_hosted_tool_payload) retains comprehensive test coverage in test_foundry_chat_client.py covering all branches: MCP tool name stripping, code_interpreter container injection/preservation, file_search validation, mcp validation, and non-function hosted tool dict stripping. The MCPStreamableHTTPTool pattern used in rewritten samples is already tested in core/tests/core/test_mcp.py including the allowed_tools parameter. No test coverage gaps found.

✗ Design Approach

The MCP migration is directionally sound, but it drops one concrete capability the old toolbox surface explicitly supported: immutable version pining. The previous get_toolbox(..., version=...) path and its tests show callers could bind to a specific toolbox version, while the new endpoint-only guidance standardizes on a name-based /toolsets/<name>/mcp URL. That means a toolbox default-version flip can silently change the tools an agent gets, so I would request changes unless a version-aware MCP consumption path remains available or is documented.

Flagged Issues

• Immutable toolbox version pining is lost by the MCP-only replacement. The removed get_toolbox() API documented version as an 'Optional immutable version identifier to pin to' (_chat_client.py:520-533), and tests/test_toolbox.py:93-109 exercised that path. The new guidance standardizes on /toolsets/<name>/mcp (name-based), meaning a toolbox default-version change can silently alter the tools an agent receives. A version-aware MCP consumption path should be preserved or documented.

---

Automated review by moonbox3's agents

[Copilot]

Pull request overview

This PR removes the bespoke “Foundry toolbox helper” surface from the Python Foundry integration and standardizes toolbox consumption on MCP (MCPStreamableHTTPTool), updating samples/docs and cleaning up the related experimental flag and exports.

Changes:

• Removed toolbox-fetching/selection helpers (get_toolbox, fetch_toolbox, select_toolbox_tools, etc.) and the ExperimentalFeature.TOOLBOXES flag, plus associated exports/re-exports.
• Updated Foundry toolbox samples and hosted-agent samples to connect via the toolbox MCP endpoint using MCPStreamableHTTPTool.
• Removed now-obsolete toolbox-focused tests and updated remaining sanitizer tests/docstrings to be toolbox-agnostic (“hosted tool” framing).

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
python/samples/04-hosting/foundry-hosted-agents/responses/06_files/README.md	Updates run instructions to use FOUNDRY_TOOLBOX_ENDPOINT (MCP endpoint).
python/samples/04-hosting/foundry-hosted-agents/responses/06_files/main.py	Switches from toolbox helpers to MCPStreamableHTTPTool (with bearer token header provider).
python/samples/04-hosting/foundry-hosted-agents/responses/06_files/.env.example	Replaces TOOLBOX_NAME with FOUNDRY_TOOLBOX_ENDPOINT.
python/samples/04-hosting/foundry-hosted-agents/responses/04_foundry_toolbox/README.md	Documents MCP endpoint pattern for toolboxes.
python/samples/04-hosting/foundry-hosted-agents/responses/04_foundry_toolbox/main.py	Uses MCPStreamableHTTPTool against toolbox MCP endpoint.
python/samples/04-hosting/container/hyperlight_codeact/call_server.py	Minor string formatting cleanup for default endpoint value.
python/samples/02-agents/security/email_security_example.py	Formatting-only change (wraps a long agent.run(...) call).
python/samples/02-agents/providers/foundry/README.md	Removes separate “toolbox vs toolbox_mcp” listing; keeps MCP pattern as canonical.
python/samples/02-agents/providers/foundry/foundry_chat_client_with_toolbox.py	Reworked to demonstrate toolbox consumption via MCP endpoint (and deletes prior multi-toolbox helper flows).
python/samples/02-agents/providers/foundry/foundry_chat_client_with_toolbox_mcp.py	Deleted (superseded by the canonical toolbox sample).
python/samples/02-agents/context_providers/README.md	Removes the toolbox-context-provider sample entry and prerequisites.
python/samples/02-agents/context_providers/foundry_toolbox_context_provider.py	Deleted (relied on removed helper APIs).
python/packages/foundry/tests/test_toolbox.py	Deleted (tests for removed toolbox helper surface).
python/packages/foundry/tests/foundry/test_foundry_chat_client.py	Renames/retargets tests/docs from “toolbox” to “hosted tool” framing for sanitization.
python/packages/foundry/README.md	Drops toolbox-helper pattern docs; documents MCP endpoint approach.
python/packages/foundry/agent_framework_foundry/_tools.py	Removes toolbox helper implementations; keeps/updates hosted tool sanitization and error messages.
python/packages/foundry/agent_framework_foundry/_chat_client.py	Removes get_toolbox and related imports; keeps hosted tool sanitization in tool preparation.
python/packages/foundry/agent_framework_foundry/_agent.py	Updates docstring wording to “hosted MCP tools” (sanitization rationale).
python/packages/foundry/agent_framework_foundry/init.py	Removes toolbox helper exports.
python/packages/core/agent_framework/foundry/init.pyi	Removes re-exported toolbox helper symbols from the public stub.
python/packages/core/agent_framework/foundry/init.py	Removes lazy-export mappings for toolbox helper symbols.
python/packages/core/agent_framework/_feature_stage.py	Removes ExperimentalFeature.TOOLBOXES.
python/packages/bedrock/tests/test_bedrock_client.py	Removes an extra blank line (formatting-only).

[moonbox3]

Automated Code Review

Reviewers: 4 | Confidence: 86%

✓ Correctness

The PR removes toolbox helpers from the foundry namespace, adds a test to enforce that, and introduces a _resolve_toolbox_endpoint() helper in two sample main.py files that supports both a direct FOUNDRY_TOOLBOX_ENDPOINT env var and a constructed URL from FOUNDRY_PROJECT_ENDPOINT+TOOLBOX_NAME. All changes are internally consistent and correct: the namespace __init__.py already lacks the four tested symbols, the URL-building logic correctly strips trailing slashes, and the README/agent.yaml docs match the new behavior.

✓ Security Reliability

The changes introduce a _resolve_toolbox_endpoint() helper (duplicated in two sample main.py files) that resolves the MCP toolbox URL from env vars. The logic is straightforward and correct for its purpose. One reliability edge case exists: if FOUNDRY_TOOLBOX_ENDPOINT is set to an empty string ", the walrus-operator truthiness check silently skips it and falls through to the TOOLBOX_NAME-based fallback, which may then raise a confusing KeyError rather than surfacing the real misconfiguration. This is a developer-facing sample so the blast radius is small, and none of the changes introduce injection risks, secret leakage, resource leaks, or unhandled failure modes at real trust boundaries.

✓ Test Coverage

The PR adds a _resolve_toolbox_endpoint() helper function (duplicated in two sample main.py files) with two distinct code paths: (1) return FOUNDRY_TOOLBOX_ENDPOINT directly if set, and (2) fall back to constructing the URL from FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME. Neither code path has any unit tests. The new namespace test for removed toolbox helpers is well-structured and meaningful. However, the untested _resolve_toolbox_endpoint logic is the substantive new behaviour introduced by this PR, and given that it runs at startup and raises KeyError on missing env vars, both the happy paths and the error path should be covered.

✓ Design Approach

I did not find a design-approach issue that warrants changes. The new toolbox endpoint resolution is consistent with the surrounding sample contracts: both hosted-agent samples declare TOLBOX_NAME in their manifest/runtime YAML, both manifests provision a toolbox named agent-tools, and the code still preserves the explicit FOUNDRY_TOOLBOX_ENDPOINT override for local/manual setups. The added namespace regression test also fits the intended API-surface cleanup.

Suggestions

• In _resolve_toolbox_endpoint() (both 04_foundry_toolbox/main.py and 06_files/main.py, around line 26), the check if endpoint := os.environ.get("FOUNDRY_TOOLBOX_ENDPOINT"): silently ignores an explicitly set empty-string value and falls through to the fallback. Use if (endpoint := os.environ.get("FOUNDRY_TOOLBOX_ENDPOINT")) is not None: to distinguish between 'not set' (fall back) and 'set to empty string' (fail fast with a clear error).
• The _resolve_toolbox_endpoint() function (added to both 04_foundry_toolbox/main.py and 06_files/main.py) has no unit tests. Consider adding tests for: (a) FOUNDRY_TOOLBOX_ENDPOINT set → returned as-is; (b) fallback URL construction with trailing-slash stripping; (c) neither variable group set → KeyError.

---

Automated review by automated agents

[moonbox3]

Automated Code Review

Reviewers: 4 | Confidence: 96%

✓ Correctness

The changes correctly fix a subtle bug where FOUNDRY_TOOLBOX_ENDPOINT set to an empty string would silently fall through to the fallback path instead of raising an error. The is not None guard properly distinguishes 'not set' from 'set but empty', and the new ValueError is clear. The accompanying tests cover all meaningful branches (explicit value, empty string, fallback construction, trailing slash stripping, and missing variables). No correctness issues found.

✓ Security Reliability

The two sample files correctly tighten the empty-string edge case that the walrus-operator truthiness check previously silently swallowed, and the new test file provides thorough branch coverage. No security or reliability issues were found: the ValueError is raised before the empty string can be used as a URL, the sys.modules stub uses setdefault (non-destructive), and all error paths (KeyError, ValueError) are tested. Nothing in the diff introduces injection risks, resource leaks, or unhandled failure modes.

✓ Test Coverage

The new test file provides thorough coverage for the changed _resolve_toolbox_endpoint() behavior in both sample modules. All five test cases (explicit endpoint returned as-is, empty string raises ValueError, fallback URL construction, trailing-slash stripping, and missing vars raising KeyError) directly exercise the changed/new code paths. The URL format asserted in tests exactly matches the f-string on line 32 of both sample files. The stubing strategy for unavailable packages is appropriate and the parameterization across both modules ensures identical coverage. No gaps or issues found.

✗ Design Approach

The change improves one narrow failure mode, but it does not address the configuration problem these samples actually expose to users. Both samples still treat any non-empty FOUNDRY_TOOLBOX_ENDPOINT as authoritative, while their own .env.example files ship that variable with a non-empty placeholder ("...") and the READMEs document TOLBOX_NAME as the alternative configuration path. As a result, a copied sample .env can still bypass the fallback entirely and produce an invalid endpoint, so the approach is a symptom-level fix rather than aligning the runtime behavior with the sample contract.

Flagged Issues

• The guard in python/samples/04-hosting/foundry-hosted-agents/responses/04_foundry_toolbox/main.py:26-29 and python/samples/04-hosting/foundry-hosted-agents/responses/06_files/main.py:26-29 only treats an empty string as invalid, but the shipped templates still define FOUNDRY_TOOLBOX_ENDPOINT="..." (responses/04_foundry_toolbox/.env.example:1-3, responses/06_files/.env.example:1-3) while the READMEs document TOLBOX_NAME as a supported alternative (responses/04_foundry_toolbox/README.md:31-50, responses/06_files/README.md:34-53). A user who copies the template without editing it will bypass the fallback and use a bogus endpoint.

Suggestions

• Align the configuration model across code, .env.example, and README: either remove FOUNDRY_TOOLBOX_ENDPOINT from the sample templates when TOLBOX_NAME fallback is supported, or validate the explicit endpoint as a real URL (rejecting sentinel-like placeholders such as "...") before treating it as authoritative.

---

Automated review by automated agents