Zestaw narzędzi Microsoft Foundry

Microsoft Foundry Toolbox to nazwany, wersjonowany pakiet hostowanych konfiguracji narzędzi, takich jak interpreter kodu, wyszukiwanie plików, generowanie obrazów, mcp i wyszukiwanie w Internecie. Przyborniki umożliwiają skonfigurowanie narzędzi raz w Foundry i ponowne wykorzystywanie ich w różnych agentach.

Framework agenta obejmuje korzystanie z narzędzia Toolbox. Twórz i aktualizuj wersje Toolbox za pośrednictwem portalu Foundry lub azure-ai-projects SDK.

Important

FoundryToolbox jest dostarczany przez pakiet beta agent-framework-foundry-hosting i może ulec zmianie przed stabilną wersją.

W przypadku zarządzanej przez FoundryAgentusługę dołącz przybornik do definicji agenta w narzędziu Foundry. Wskazówki dotyczące korzystania po stronie klienta z zestawu narzędzi .NET nie są obecnie udokumentowane.

Instalowanie pakietów

pip install agent-framework-foundry-hosting agent-framework-foundry --pre

FoundryToolbox jest importowany z agent_framework.foundry i dostarczany przez agent-framework-foundry-hosting.

Skonfiguruj przybornik

Ustaw jawnie adres punktu końcowego MCP dla Toolbox:

TOOLBOX_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<name>/mcp?api-version=v1"

Lub pozwól, aby FoundryToolbox skonstruował punkt końcowy:

FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
TOOLBOX_NAME="<toolbox-name>"

W przykładach hostowanych agentów również używa się elementu AZURE_AI_MODEL_DEPLOYMENT_NAME dla FoundryChatClient.

Użyj FoundryToolbox z hostowanym agentem

FoundryToolbox ustala adres swojego punktu końcowego, uwierzytelnia każde żądanie MCP przy użyciu podanego poświadczenia platformy Azure, przekazuje identyfikator wywołania usługi Foundry dla danego żądania i uczestniczy w cyklu życia połączenia agenta.

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox, ResponsesHostServer
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()


async def main():
    credential = DefaultAzureCredential()

    # FoundryToolbox resolves the toolbox endpoint from the environment
    # (TOOLBOX_ENDPOINT, or FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME), authenticates
    # every request with the credential, and transparently forwards the platform
    # per-request call-id to the toolbox. The hosting server enters the agent, which
    # connects the toolbox on first use and closes it at shutdown.
    toolbox = FoundryToolbox(credential)

    # Create the chat client
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=credential,
    )

    agent = Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        tools=toolbox,
        # History will be managed by the hosting infrastructure, thus there
        # is no need to store history by the service. Learn more at:
        # https://developers.openai.com/api/reference/resources/responses/methods/create
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    await server.run_async()

Wyświetl umiejętności Toolbox

Zestaw narzędzi może udostępniać umiejętności agenta za pośrednictwem MCP. Ustaw load_tools=False, gdy tylko umiejętności powinny być widoczne dla modelu, a następnie dodaj Toolbox jako narzędzie, aby jego sesja MCP mogła się połączyć, i użyj as_skills_provider() jako dostawcy kontekstu.

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox, ResponsesHostServer
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()


async def main() -> None:
    credential = DefaultAzureCredential()

    # FoundryToolbox resolves the toolbox endpoint from the environment
    # (TOOLBOX_ENDPOINT, or FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME), authenticates
    # every request with the credential, and forwards the platform per-request
    # call-id. ``load_tools=False`` keeps the toolbox's tools hidden so only its
    # Agent Skills (SEP-2640) are surfaced; passing it via ``tools=`` connects the
    # MCP session that ``as_skills_provider()`` reads from.
    toolbox = FoundryToolbox(credential, load_tools=False)

    # as_skills_provider() discovers skills from skill://index.json on the toolbox
    # MCP session and exposes them as an agent context provider; SKILL.md bodies are
    # fetched on demand via resources/read. disable_load_skill_approval=True registers
    # the load_skill tool with approval_mode="never_require" so this unattended agent
    # can load skills without an approval round-trip -- the Responses host runs the
    # agent without an AgentSession, which the default approval flow requires.
    skills_provider = toolbox.as_skills_provider(disable_load_skill_approval=True)

    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=credential,
    )

    agent = Agent(
        client=client,
        name=os.environ.get("AGENT_NAME", "hosted-toolbox-mcp-skills"),
        instructions="You are a helpful assistant.",
        tools=toolbox,
        context_providers=[skills_provider],
        # History will be managed by the hosting infrastructure, thus there
        # is no need to store history by the service. Learn more at:
        # https://developers.openai.com/api/reference/resources/responses/methods/create
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    await server.run_async()

Zatwierdzanie pozostaje domyślnie włączone dla operacji dotyczących umiejętności. Wyłącz indywidualne zatwierdzenia tylko w zaufanych, nienadzorowanych scenariuszach.

Używanie Przybornika z FoundryAgent

Dołącz Toolbox do definicji promptu lub agenta hostowanego w Foundry. FoundryAgent używa zapisanej konfiguracji narzędzia; przekazanie obiektu Toolbox po stronie klienta nie powoduje dodania go do agenta zarządzanego.

Nawiązywanie połączenia za pośrednictwem surowego protokołu MCP

Użyj MCPStreamableHTTPTool bezpośrednio, jeśli aplikacja nie używa otoczki hostingu FoundryToolbox. Podaj punkt końcowy zestawu narzędzi oraz token okaziciela Entra ID za pośrednictwem header_provider.

import asyncio
import os
from collections.abc import Callable
from typing import Any, cast

from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.foundry import FoundryChatClient
from azure.core.credentials import TokenCredential
from azure.identity import AzureCliCredential, DefaultAzureCredential, get_bearer_token_provider
from dotenv import load_dotenv
def make_toolbox_header_provider(credential: TokenCredential) -> Callable[[dict[str, Any]], dict[str, str]]:
    """Build a header_provider that injects a fresh Azure AI bearer token on every MCP request."""
    get_token = get_bearer_token_provider(credential, "https://ai.azure.com/.default")

    def provide(_kwargs: dict[str, Any]) -> dict[str, str]:
        return {
            "Authorization": f"Bearer {get_token()}",
        }

    return provide


async def main() -> None:
    credential = DefaultAzureCredential()

    toolbox_tool = MCPStreamableHTTPTool(
        name="foundry_toolbox",
        description="Tools exposed by the configured Foundry toolbox",
        url=os.environ["FOUNDRY_TOOLBOX_ENDPOINT"],
        header_provider=make_toolbox_header_provider(credential),
        load_prompts=False,
    )

    async with Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=credential,
        ),
        instructions="You are a helpful assistant. Use the available toolbox tools to answer the user.",
        tools=toolbox_tool,
    ) as agent:
        query = "What tools do you have access to?"
        print(f"User: {query}")
        result = await agent.run(query)
        print(f"Assistant: {result}")

W niskopoziomowym przykładzie użyto FOUNDRY_TOOLBOX_ENDPOINT. Przykładowe umiejętności zestawu narzędzi używają FOUNDRY_TOOLBOX_MCP_SERVER_URL; te nazwy należą do tych przykładów i są odrębne od ustawień TOOLBOX_ENDPOINT i TOOLBOX_NAME klasy FoundryToolbox.

Limitations

  • Narzędzia MCP w przyborniku używają uwierzytelniania po stronie serwera za pośrednictwem rozwiązania Foundry project_connection_id; klient programu Agent Framework nie przechowuje nadrzędnego tokenu elementu nośnego MCP.
  • Korzystanie z Przybornika jako z serwera MCP wymaga uwierzytelniania Entra ID po stronie klienta na potrzeby punktu końcowego Przybornika.
  • Odpowiedzi w przepływie zgody, takie jak CONSENT_REQUIRED, są obsługiwane podczas działania agenta, a nie podczas tworzenia połączenia z Toolbox.

Samples

Sample Opis
foundry_toolbox/main.py FoundryToolbox z hostowanym agentem Responses
foundry_toolbox_mcp_skills/main.py Umiejętności agenta oparte na zestawie narzędzi
foundry_chat_client_with_toolbox.py Korzystanie z Toolbox MCP przy użyciu MCPStreamableHTTPTool
foundry_chat_client_with_toolbox_skills.py Konfiguracja umiejętności oparta na zestawie narzędzi
invoke_foundry_toolbox_mcp Korzystanie z MCP w przepływie pracy

Go obecnie nie udostępnia pomocnika Foundry Toolbox. Skonfiguruj zestawy narzędzi w Foundry i używaj obsługiwanych lokalnych lub hostowanych deklaracji narzędzi dla agentów Go.

  • Last updated on