Python: feat(foundry): add experimental hosted tool factories on FoundryChatClient

python/packages/core/agent_framework/_feature_stage.py

@@ -49,6 +49,8 @@ class ExperimentalFeature(str, Enum):
     EVALS = "EVALS"
     FILE_HISTORY = "FILE_HISTORY"
     FIDES = "FIDES"
+    FOUNDRY_TOOLS = "FOUNDRY_TOOLS"
+    FOUNDRY_PREVIEW_TOOLS = "FOUNDRY_PREVIEW_TOOLS"
     FUNCTIONAL_WORKFLOWS = "FUNCTIONAL_WORKFLOWS"
     HARNESS = "HARNESS"
     SKILLS = "SKILLS"

python/packages/foundry/README.md

@@ -39,3 +39,70 @@ async with Agent(
     result = await agent.run("What tools are available?")
     print(result.text)
 ```
+
+## Hosted tool factories
+
+`FoundryChatClient` exposes static factory methods that return Foundry SDK tool
+configurations ready to pass to an `Agent`'s `tools=[...]` argument. These
+factories don't require a `FoundryChatClient` instance — you can call them
+statically and reuse the same tool configuration across agents.
+
+```python
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
+
+agent = Agent(
+    client=FoundryChatClient(...),
+    instructions="...",
+    tools=[
+        FoundryChatClient.get_web_search_tool(),
+        FoundryChatClient.get_code_interpreter_tool(),
+    ],
+)
+```
+
+Generally available factories: `get_code_interpreter_tool`,
+`get_file_search_tool`, `get_web_search_tool`,
+`get_image_generation_tool`, `get_mcp_tool`.
+
+> **Choosing a web grounding tool.** `get_web_search_tool` is the recommended
+> default — it requires no separate Bing resource and works with Azure OpenAI
+> models out of the box. Reach for `get_bing_grounding_tool` (experimental,
+> see below) when you need finer Bing parameters (`count`, `freshness`,
+> `market`, `set_lang`), are grounding non-OpenAI Foundry models, or are
+> migrating from Grounding with Bing Search on the classic platform — it
+> requires a Grounding with Bing Search Azure resource that you manage.
+> `get_bing_custom_search_tool` (also experimental) is for grounding
+> restricted to a curated list of domains via a Bing Custom Search instance.
+> See the
+> [web grounding overview](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/web-overview)
+> for the full comparison.
+
+> **Experimental — `ExperimentalFeature.FOUNDRY_TOOLS`.** The following
+> factories wrap GA Foundry tool SDK classes but are new wrappers in
+> `agent-framework-foundry` and may change before the wrappers themselves
+> reach GA. Calls emit an `ExperimentalWarning` the first time the
+> `FOUNDRY_TOOLS` feature is exercised in a process (then deduplicated).
+
+| Factory | Foundry SDK tool |
+|---------|-----------------|
+| `get_azure_ai_search_tool(index_connection_id, index_name, ...)` | `AzureAISearchTool` |
+| `get_bing_grounding_tool(connection_id, ...)` | `BingGroundingTool` |
+
+> **Experimental — `ExperimentalFeature.FOUNDRY_PREVIEW_TOOLS`.** The
+> following factories wrap **preview** Foundry tool SDK types — the underlying
+> Foundry capability itself is in preview and may change or be removed before
+> reaching GA. Calls emit a separate `ExperimentalWarning` the first time the
+> `FOUNDRY_PREVIEW_TOOLS` feature is exercised in a process (then
+> deduplicated). Use `FOUNDRY_TOOLS` for "wrapper is new" and
+> `FOUNDRY_PREVIEW_TOOLS` for "underlying Foundry feature is preview".
+
+| Factory | Foundry SDK tool |
+|---------|-----------------|
+| `get_sharepoint_tool(connection_id)` | `SharepointPreviewTool` |
+| `get_fabric_tool(connection_id)` | `MicrosoftFabricPreviewTool` |
+| `get_memory_search_tool(memory_store_name, scope, ...)` | `MemorySearchPreviewTool` |
+| `get_computer_use_tool(environment, display_width, display_height)` | `ComputerUsePreviewTool` |
+| `get_browser_automation_tool(connection_id)` | `BrowserAutomationPreviewTool` |
+| `get_bing_custom_search_tool(connection_id, instance_name, ...)` | `BingCustomSearchPreviewTool` |
+| `get_a2a_tool(base_url=..., project_connection_id=..., ...)` | `A2APreviewTool` |