agent/agent-framework
2
0
Fork 0
mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* feat(foundry): add experimental hosted tool factories on FoundryChatClient

Adds eight new `@experimental` static factory methods on `FoundryChatClient`
covering Foundry-hosted tools that previously had no helper:

- get_azure_ai_search_tool
- get_sharepoint_tool
- get_fabric_tool
- get_memory_search_tool
- get_computer_use_tool
- get_browser_automation_tool
- get_bing_custom_search_tool
- get_a2a_tool

All factories are marked with the new `ExperimentalFeature.FOUNDRY_TOOLS` tag
and resolve the underlying `azure-ai-projects` preview classes lazily through
a `_require_sdk_class` helper so older SDK versions still import cleanly and
fail with a clear `ImportError` only on use.

Tests cover each factory's return type and field wiring, the experimental
metadata, and the missing-SDK-class fallback.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* test(foundry): address review comments on tool-factory tests

* Skip preview-tool tests gracefully (`_skip_if_sdk_class_missing`) when
  the installed `azure-ai-projects` does not expose the required preview
  class, matching the lazy-import guard in production code so the test
  suite stays green on older SDK installs.
* Add `filterwarnings("ignore::FutureWarning")` to each new tool-factory
  test (and the parametrized metadata test) so they remain stable under
  strict warning configurations \u2014 the global dedup in
  `_feature_stage._WARNED_FEATURES` makes `pytest.warns` brittle across
  ordered runs.
* Use `monkeypatch.setattr(..., None, raising=False)` instead of
  `delattr` in the missing-SDK-class test so it works for modules that
  implement PEP 562 `__getattr__`.
* Split the long `get_bing_custom_search_tool` return into two lines for
  readability.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(foundry): harden tool-factory kwargs against silent override

* Reorder the dict-literal kwargs assembly in get_azure_ai_search_tool,
  get_memory_search_tool, and get_bing_custom_search_tool so explicit
  parameters always take precedence over **kwargs (matching the safe
  pattern already used in get_a2a_tool). This prevents a caller
  passing `project_connection_id`, `index_name`, `memory_store_name`,
  `scope`, or `instance_name` through `**kwargs` from silently
  overriding the explicit security-sensitive arguments.
* Update the README experimental note to reflect once-per-feature-id
  dedup semantics of `_feature_stage._WARNED_FEATURES` rather than
  claiming a per-factory "first use" warning.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* feat(foundry): split FOUNDRY_TOOLS / FOUNDRY_PREVIEW_TOOLS, add bing-grounding

- Add ExperimentalFeature.FOUNDRY_PREVIEW_TOOLS to distinguish wrappers around
  preview Foundry SDK tool classes (Sharepoint/Fabric/Memory/ComputerUse/
  BrowserAutomation/BingCustomSearch/A2A) from FOUNDRY_TOOLS, which is for
  GA-SDK wrappers that are simply new in agent-framework-foundry
  (AzureAISearch, BingGrounding).
- Add get_bing_grounding_tool factory and a 'Choosing a web grounding tool'
  comparison block on get_web_search_tool / get_bing_grounding_tool /
  get_bing_custom_search_tool docstrings.
- Drop the _require_sdk_class lazy resolver: every guarded class is available
  at azure-ai-projects>=2.1.0 (the package floor), so import them eagerly.
  Concrete return types replace 'Any'.
- README: split the experimental factories into two tables, one per feature
  flag, with a note explaining the distinction.
- Tests: split into FOUNDRY_TOOLS / FOUNDRY_PREVIEW_TOOLS factory cases;
  drop the obsolete missing-SDK-class ImportError test.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Eduard van Valkenburg
2026-05-21 08:39:08 +00:00
committed by GitHub
co-authored by Copilot
parent 01a3c5be8a
commit 47f5c3397f
4 changed files with 699 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python/packages/foundry/agent_framework_foundry/_chat_client.py
+393 -10
View File
@@ -16,14 +16,35 @@ from agent_framework import (
load_settings,
)
from agent_framework._compaction import CompactionStrategy, TokenizerProtocol
from agent_framework._feature_stage import ExperimentalFeature, experimental
from agent_framework._telemetry import get_user_agent
from agent_framework.observability import ChatTelemetryLayer
from agent_framework_openai._chat_client import OpenAIChatOptions, RawOpenAIChatClient
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import (
A2APreviewTool,
AISearchIndexResource,
AutoCodeInterpreterToolParam,
AzureAISearchTool,
AzureAISearchToolResource,
BingCustomSearchConfiguration,
BingCustomSearchPreviewTool,
BingCustomSearchToolParameters,
BingGroundingSearchConfiguration,
BingGroundingSearchToolParameters,
BingGroundingTool,
BrowserAutomationPreviewTool,
BrowserAutomationToolConnectionParameters,
BrowserAutomationToolParameters,
CodeInterpreterTool,
ComputerUsePreviewTool,
FabricDataAgentToolParameters,
ImageGenTool,
MemorySearchPreviewTool,
MicrosoftFabricPreviewTool,
SharepointGroundingToolParameters,
SharepointPreviewTool,
ToolProjectConnection,
WebSearchApproximateLocation,
WebSearchTool,
WebSearchToolFilters,
@@ -381,17 +402,44 @@ class RawFoundryChatClient( # type: ignore[misc]
custom_search_configuration: dict[str, Any] | None = None,
**kwargs: Any,
) -> WebSearchTool:
"""Create a web search tool configuration for Microsoft Foundry.
"""Create a Web Search tool configuration for Microsoft Foundry.
**Choosing a web grounding tool.** Foundry exposes three options that all reach
the public web via Bing. Pick the one that matches your scenario:
* :py:meth:`get_web_search_tool` (this one, GA) — recommended starting point.
The Bing resource is managed by Microsoft, no extra Azure setup is required,
and only Azure OpenAI models are supported. Parameters are limited to
``user_location`` and ``search_context_size``.
* :py:meth:`get_bing_grounding_tool` (preview) — use when you need finer Bing parameters (``count``,
``freshness``, ``market``, ``set_lang``), want to ground non-OpenAI
Foundry models, or are migrating from Grounding with Bing Search on the
classic agents platform. You manage the Grounding with Bing Search
resource yourself (Contributor/Owner to create the resource, Foundry
Project Manager to wire the connection).
* :py:meth:`get_bing_custom_search_tool` (preview) — use when you need to
restrict grounding to a curated set of domains defined in a Bing Custom
Search instance.
For all three, search data flows outside the Azure compliance boundary. See
https://learn.microsoft.com/azure/foundry/agents/how-to/tools/web-overview for
the full comparison.
Keyword Args:
user_location: Location context with keys like "city", "country", "region", "timezone".
search_context_size: Amount of context from search results ("low", "medium", "high").
allowed_domains: List of domains to restrict search results to.
custom_search_configuration: Custom Bing search configuration.
**kwargs: Additional arguments passed to the SDK WebSearchTool constructor.
user_location: Location context with keys like ``"city"``, ``"country"``,
``"region"``, ``"timezone"``.
search_context_size: Amount of context from search results
(``"low"``, ``"medium"``, ``"high"``).
allowed_domains: List of domains to restrict search results to. Wrapped
into ``WebSearchToolFilters`` and passed as the ``filters`` field on
the SDK ``WebSearchTool``.
custom_search_configuration: Custom Bing search configuration for
domain-restricted scenarios.
**kwargs: Additional arguments passed to the SDK ``WebSearchTool``
constructor.
Returns:
A WebSearchTool ready to pass to an Agent.
A ``WebSearchTool`` ready to pass to an Agent.
"""
ws_kwargs: dict[str, Any] = {**kwargs}
if search_context_size:
@@ -400,15 +448,137 @@ class RawFoundryChatClient( # type: ignore[misc]
ws_kwargs["filters"] = WebSearchToolFilters(allowed_domains=allowed_domains)
if custom_search_configuration:
ws_kwargs["custom_search_configuration"] = custom_search_configuration
ws_tool = WebSearchTool(**ws_kwargs)
if user_location:
ws_tool.user_location = WebSearchApproximateLocation(
ws_kwargs["user_location"] = WebSearchApproximateLocation(
city=user_location.get("city"),
country=user_location.get("country"),
region=user_location.get("region"),
timezone=user_location.get("timezone"),
)
return ws_tool
return WebSearchTool(**ws_kwargs)
@staticmethod
@experimental(feature_id=ExperimentalFeature.FOUNDRY_TOOLS)
def get_bing_grounding_tool(
*,
connection_id: str,
market: str | None = None,
set_lang: str | None = None,
count: int | None = None,
freshness: str | None = None,
**kwargs: Any,
) -> BingGroundingTool:
"""Create a Grounding with Bing Search tool configuration for Foundry.
Use this factory when :py:meth:`get_web_search_tool` is too restrictive — for
example when you need ``count``/``freshness``/``market``/``set_lang``
parameters, want to ground a non-OpenAI Foundry model, or are migrating an
agent that already uses Grounding with Bing Search on the classic agents
platform. You manage the Grounding with Bing Search Azure resource yourself
(Contributor or Owner to create the resource, Foundry Project Manager to
create the project connection). Search data flows outside the Azure
compliance boundary.
For domain-restricted grounding to a curated allow-list, use
:py:meth:`get_bing_custom_search_tool` instead. For a zero-setup default that
works for most agents, see :py:meth:`get_web_search_tool`. The full
comparison lives at
https://learn.microsoft.com/azure/foundry/agents/how-to/tools/web-overview.
Keyword Args:
connection_id: The Foundry project connection ID for the Grounding with
Bing Search resource.
market: Optional Bing market identifier (e.g. ``"en-US"``).
set_lang: Optional UI language code passed to the Bing API.
count: Optional number of search results to return.
freshness: Optional time-range filter for search results. See
https://learn.microsoft.com/bing/search-apis/bing-web-search/reference/query-parameters
for accepted values.
**kwargs: Additional arguments forwarded to the SDK
``BingGroundingSearchConfiguration``.
Returns:
A ``BingGroundingTool`` ready to pass to an Agent.
"""
config_kwargs: dict[str, Any] = {
**kwargs,
"project_connection_id": connection_id,
}
if market is not None:
config_kwargs["market"] = market
if set_lang is not None:
config_kwargs["set_lang"] = set_lang
if count is not None:
config_kwargs["count"] = count
if freshness is not None:
config_kwargs["freshness"] = freshness
return BingGroundingTool(
bing_grounding=BingGroundingSearchToolParameters(
search_configurations=[BingGroundingSearchConfiguration(**config_kwargs)],
),
)
@staticmethod
@experimental(feature_id=ExperimentalFeature.FOUNDRY_PREVIEW_TOOLS)
def get_bing_custom_search_tool(
*,
connection_id: str,
instance_name: str,
market: str | None = None,
set_lang: str | None = None,
count: int | None = None,
freshness: str | None = None,
**kwargs: Any,
) -> BingCustomSearchPreviewTool:
"""Create a Grounding with Bing Custom Search tool configuration for Foundry.
Use this factory (preview) when you need to restrict grounding to a curated
list of domains. The allow/block list is defined ahead of time on a Bing
Custom Search resource (in the Bing portal) and referenced here by
``instance_name``. Like the other Bing-backed tools, search data flows
outside the Azure compliance boundary, and you must create the Bing Custom
Search resource yourself.
For unrestricted public-web grounding with no extra Azure setup, prefer
:py:meth:`get_web_search_tool`. For unrestricted grounding with finer Bing
parameters or non-OpenAI models, prefer :py:meth:`get_bing_grounding_tool`.
See
https://learn.microsoft.com/azure/foundry/agents/how-to/tools/web-overview
for the full comparison.
Keyword Args:
connection_id: The Foundry project connection ID for the Grounding with
Bing Custom Search resource.
instance_name: The custom configuration instance name defined on the
Bing Custom Search resource.
market: Optional Bing market identifier (e.g. ``"en-US"``).
set_lang: Optional UI language code passed to the Bing API.
count: Optional number of search results to return.
freshness: Optional time-range filter for search results.
**kwargs: Additional arguments forwarded to the SDK
``BingCustomSearchConfiguration``.
Returns:
A ``BingCustomSearchPreviewTool`` ready to pass to an Agent.
"""
config_kwargs: dict[str, Any] = {
**kwargs,
"project_connection_id": connection_id,
"instance_name": instance_name,
}
if market is not None:
config_kwargs["market"] = market
if set_lang is not None:
config_kwargs["set_lang"] = set_lang
if count is not None:
config_kwargs["count"] = count
if freshness is not None:
config_kwargs["freshness"] = freshness
return BingCustomSearchPreviewTool(
bing_custom_search_preview=BingCustomSearchToolParameters(
search_configurations=[BingCustomSearchConfiguration(**config_kwargs)],
),
)
@staticmethod
def get_image_generation_tool( # type: ignore[override]
@@ -513,6 +683,219 @@ class RawFoundryChatClient( # type: ignore[misc]
# endregion
# region Experimental Foundry tool factories (preview SDK types)
@staticmethod
@experimental(feature_id=ExperimentalFeature.FOUNDRY_TOOLS)
def get_azure_ai_search_tool(
*,
index_connection_id: str,
index_name: str,
query_type: str | None = None,
top_k: int | None = None,
filter: str | None = None,
index_asset_id: str | None = None,
**kwargs: Any,
) -> AzureAISearchTool:
"""Create an Azure AI Search tool configuration for Foundry.
Keyword Args:
index_connection_id: The Foundry project connection ID for the Azure AI Search index.
index_name: The name of the index to search.
query_type: Optional query type (``"simple"``, ``"semantic"``, ``"vector"``,
``"vector_simple_hybrid"``, or ``"vector_semantic_hybrid"``).
top_k: Optional number of documents to retrieve.
filter: Optional OData filter expression.
index_asset_id: Optional index asset id for the search resource.
**kwargs: Additional arguments forwarded to the SDK ``AISearchIndexResource``.
Returns:
An ``AzureAISearchTool`` ready to pass to an Agent.
"""
index_kwargs: dict[str, Any] = {
**kwargs,
"project_connection_id": index_connection_id,
"index_name": index_name,
}
if query_type is not None:
index_kwargs["query_type"] = query_type
if top_k is not None:
index_kwargs["top_k"] = top_k
if filter is not None:
index_kwargs["filter"] = filter
if index_asset_id is not None:
index_kwargs["index_asset_id"] = index_asset_id
return AzureAISearchTool(
azure_ai_search=AzureAISearchToolResource(indexes=[AISearchIndexResource(**index_kwargs)]),
)
@staticmethod
@experimental(feature_id=ExperimentalFeature.FOUNDRY_PREVIEW_TOOLS)
def get_sharepoint_tool(
*,
connection_id: str,
**kwargs: Any,
) -> SharepointPreviewTool:
"""Create a SharePoint grounding tool configuration for Foundry.
Keyword Args:
connection_id: The Foundry project connection ID for the SharePoint resource.
**kwargs: Additional arguments forwarded to the SDK
``SharepointGroundingToolParameters``.
Returns:
A ``SharepointPreviewTool`` ready to pass to an Agent.
"""
return SharepointPreviewTool(
sharepoint_grounding_preview=SharepointGroundingToolParameters(
project_connections=[ToolProjectConnection(project_connection_id=connection_id)],
**kwargs,
)
)
@staticmethod
@experimental(feature_id=ExperimentalFeature.FOUNDRY_PREVIEW_TOOLS)
def get_fabric_tool(
*,
connection_id: str,
**kwargs: Any,
) -> MicrosoftFabricPreviewTool:
"""Create a Microsoft Fabric data agent tool configuration for Foundry.
Keyword Args:
connection_id: The Foundry project connection ID for the Fabric data agent.
**kwargs: Additional arguments forwarded to the SDK
``FabricDataAgentToolParameters``.
Returns:
A ``MicrosoftFabricPreviewTool`` ready to pass to an Agent.
"""
return MicrosoftFabricPreviewTool(
fabric_dataagent_preview=FabricDataAgentToolParameters(
project_connections=[ToolProjectConnection(project_connection_id=connection_id)],
**kwargs,
)
)
@staticmethod
@experimental(feature_id=ExperimentalFeature.FOUNDRY_PREVIEW_TOOLS)
def get_memory_search_tool(
*,
memory_store_name: str,
scope: str,
search_options: Any | None = None,
update_delay: int | None = None,
**kwargs: Any,
) -> MemorySearchPreviewTool:
"""Create a Memory Search tool configuration for Foundry.
Keyword Args:
memory_store_name: The name of the memory store to use.
scope: The namespace used to group and isolate memories (e.g. a user ID).
Use ``"{{$userId}}"`` to scope memories to the current signed-in user.
search_options: Optional ``MemorySearchOptions`` instance.
update_delay: Optional seconds to wait before updating memories after inactivity.
**kwargs: Additional arguments forwarded to the SDK ``MemorySearchPreviewTool``.
Returns:
A ``MemorySearchPreviewTool`` ready to pass to an Agent.
"""
params: dict[str, Any] = {
**kwargs,
"memory_store_name": memory_store_name,
"scope": scope,
}
if search_options is not None:
params["search_options"] = search_options
if update_delay is not None:
params["update_delay"] = update_delay
return MemorySearchPreviewTool(**params)
@staticmethod
@experimental(feature_id=ExperimentalFeature.FOUNDRY_PREVIEW_TOOLS)
def get_computer_use_tool(
*,
environment: str,
display_width: int,
display_height: int,
**kwargs: Any,
) -> ComputerUsePreviewTool:
"""Create a Computer Use tool configuration for Foundry.
Keyword Args:
environment: The computer environment to control. One of ``"windows"``,
``"mac"``, ``"linux"``, ``"ubuntu"``, or ``"browser"``.
display_width: The width of the computer display.
display_height: The height of the computer display.
**kwargs: Additional arguments forwarded to the SDK ``ComputerUsePreviewTool``.
Returns:
A ``ComputerUsePreviewTool`` ready to pass to an Agent.
"""
return ComputerUsePreviewTool(
environment=environment,
display_width=display_width,
display_height=display_height,
**kwargs,
)
@staticmethod
@experimental(feature_id=ExperimentalFeature.FOUNDRY_PREVIEW_TOOLS)
def get_browser_automation_tool(
*,
connection_id: str,
**kwargs: Any,
) -> BrowserAutomationPreviewTool:
"""Create a Browser Automation tool configuration for Foundry.
Keyword Args:
connection_id: The Foundry project connection ID for the Azure Playwright resource.
**kwargs: Additional arguments forwarded to the SDK
``BrowserAutomationToolParameters``.
Returns:
A ``BrowserAutomationPreviewTool`` ready to pass to an Agent.
"""
return BrowserAutomationPreviewTool(
browser_automation_preview=BrowserAutomationToolParameters(
connection=BrowserAutomationToolConnectionParameters(project_connection_id=connection_id),
**kwargs,
)
)
@staticmethod
@experimental(feature_id=ExperimentalFeature.FOUNDRY_PREVIEW_TOOLS)
def get_a2a_tool(
*,
base_url: str | None = None,
agent_card_path: str | None = None,
project_connection_id: str | None = None,
**kwargs: Any,
) -> A2APreviewTool:
"""Create an Agent-to-Agent (A2A) tool configuration for Foundry.
Keyword Args:
base_url: Base URL of the remote A2A agent.
agent_card_path: Path to the agent card relative to ``base_url``.
Defaults to ``"/.well-known/agent-card.json"`` server-side.
project_connection_id: Foundry connection ID for the A2A server. Stores
authentication and other connection details.
**kwargs: Additional arguments forwarded to the SDK ``A2APreviewTool``.
Returns:
An ``A2APreviewTool`` ready to pass to an Agent.
"""
params: dict[str, Any] = dict(kwargs)
if base_url is not None:
params["base_url"] = base_url
if agent_card_path is not None:
params["agent_card_path"] = agent_card_path
if project_connection_id is not None:
params["project_connection_id"] = project_connection_id
return A2APreviewTool(**params)
# endregion
class FoundryChatClient( # type: ignore[misc]
FunctionInvocationLayer[FoundryChatOptionsT],