Python: Add support for Foundry Toolboxes (#5346)

* Add support for the Foundry Toolbox in MAF

Introduces a Foundry Toolbox integration: FoundryChatClient gains a
get_toolbox() helper plus select_toolbox_tools(), normalize_tools in
the core package flattens tool-collection wrappers (ToolboxVersionObject
and generic iterables, while leaving Pydantic BaseModel instances
alone), and the new agent_framework.foundry namespace re-exports the
toolbox helpers. Ships with unit tests, a sample, and a design doc.

azure-ai-projects is pinned to the public >=2.0.0,<3.0 range and the
lockfile resolves from public PyPI. The toolbox test module skips when
Toolbox* types are unavailable so CI stays green until the public 2.1.0
SDK lands. OMC tooling directories (.omc/, .omx/) are gitignored.

* Update to latest azure ai projects package

* Improve sample

* Rename ADR to 0025

* Update ADR

* Apply suggestion from @alliscode

Co-authored-by: Ben Thomas <ben.thomas@microsoft.com>

* Improve samples

* Update test

---------

Co-authored-by: Ben Thomas <ben.thomas@microsoft.com>

python/packages/foundry/tests/foundry/test_foundry_chat_client.py

@@ -15,6 +15,7 @@ from agent_framework import ChatResponse, Content, Message, SupportsChatGetRespo
 from agent_framework._telemetry import AGENT_FRAMEWORK_USER_AGENT
 from agent_framework.exceptions import ChatClientException, ChatClientInvalidRequestException
 from agent_framework_openai import OpenAIContentFilterException
+from azure.ai.projects.models import MCPTool as FoundryMCPTool
 from azure.core.exceptions import ResourceNotFoundError
 from azure.identity import AzureCliCredential
 from openai import BadRequestError
@@ -608,6 +609,82 @@ def test_get_mcp_tool_with_project_connection_id() -> None:
     assert tool_config["server_label"] == "Docs_MCP"
 
 
+def test_prepare_tools_for_openai_strips_extraneous_name_from_foundry_mcp_tool() -> None:
+    """Toolbox-returned MCP tools may carry ``name``; Foundry Responses rejects it."""
+    project_client = MagicMock()
+    project_client.get_openai_client.return_value = _make_mock_openai_client()
+    client = FoundryChatClient(project_client=project_client, model="test-model")
+
+    tool = FoundryMCPTool(
+        server_label="githubmcp",
+        server_url="https://api.githubcopilot.com/mcp",
+    )
+    tool["project_connection_id"] = "githubmcp"
+    tool["name"] = "githubmcp"
+
+    response_tools = client._prepare_tools_for_openai([tool])
+
+    assert len(response_tools) == 1
+    prepared = response_tools[0]
+    assert prepared["type"] == "mcp"
+    assert prepared["server_label"] == "githubmcp"
+    assert prepared["project_connection_id"] == "githubmcp"
+    assert "name" not in prepared
+
+
+def test_prepare_tools_for_openai_strips_read_model_fields_from_toolbox_code_interpreter() -> None:
+    """Toolbox-returned code interpreter tools may carry read-model-only name/description."""
+    project_client = MagicMock()
+    project_client.get_openai_client.return_value = _make_mock_openai_client()
+    client = FoundryChatClient(project_client=project_client, model="test-model")
+
+    tool = {
+        "type": "code_interpreter",
+        "name": "code_interpreter_t6bbtm",
+        "description": "Toolbox read model description",
+        "container": {"file_ids": [], "type": "auto"},
+    }
+
+    response_tools = client._prepare_tools_for_openai([tool])
+
+    assert len(response_tools) == 1
+    prepared = response_tools[0]
+    assert prepared["type"] == "code_interpreter"
+    assert prepared["container"] == {"file_ids": [], "type": "auto"}
+    assert "name" not in prepared
+    assert "description" not in prepared
+
+
+def test_prepare_tools_for_openai_strips_name_from_non_function_hosted_tool_dicts() -> None:
+    """All non-function hosted tool payloads should drop top-level read-model names."""
+    project_client = MagicMock()
+    project_client.get_openai_client.return_value = _make_mock_openai_client()
+    client = FoundryChatClient(project_client=project_client, model="test-model")
+
+    response_tools = client._prepare_tools_for_openai([
+        {
+            "type": "file_search",
+            "name": "file_search_tool_123",
+            "description": "toolbox decoration",
+            "vector_store_ids": ["vs_123"],
+        },
+        {
+            "type": "web_search",
+            "name": "web_search_tool_456",
+            "description": "toolbox decoration",
+        },
+    ])
+
+    assert len(response_tools) == 2
+    assert response_tools[0]["type"] == "file_search"
+    assert response_tools[0]["vector_store_ids"] == ["vs_123"]
+    assert "name" not in response_tools[0]
+    assert "description" not in response_tools[0]
+    assert response_tools[1]["type"] == "web_search"
+    assert "name" not in response_tools[1]
+    assert "description" not in response_tools[1]
+
+
 @pytest.mark.flaky
 @pytest.mark.integration
 @skip_if_foundry_integration_tests_disabled