Microsoft Foundry Araç Kutusu

Microsoft Foundry Toolbox, kod yorumlayıcı, dosya arama, görüntü oluşturma, MCP ve web araması gibi barındırılan araç yapılandırmalarının adlandırılmış, sürümlenmiş sunucu tarafı paketidir. Araç kutuları, Foundry'de bir kez araç yapılandırmasını yönetmenize ve aracılar arasında yeniden kullanmanıza olanak tanır.

Agent Framework, Toolbox tüketimini kapsar. Toolbox sürümlerini Foundry portalı veya SDK aracılığıyla oluşturun ve güncelleştirin azure-ai-projects .

Önemli

FoundryToolbox beta agent-framework-foundry-hosting paketi tarafından sağlanır ve kararlı sürümden önce değişebilir.

Hizmet tarafından yönetilen bir FoundryAgent için Araç Kutusu'nu Foundry'deki ajan tanımına ekleyin. İstemci tarafı .NET Araç Kutusu kullanım kılavuzu şu anda belgelenmemiştir.

Paketleri yükleme

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

FoundryToolbox, agent_framework.foundry'den içeri aktarılır ve agent-framework-foundry-hosting tarafından sağlanır.

Araç Kutusunu Yapılandırma

Açık bir Toolbox MCP uç noktası ayarlayın:

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

Veya uç noktayı oluşturmasına izin verin FoundryToolbox :

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

Barındırılan aracı örnekleri de FoundryChatClient için AZURE_AI_MODEL_DEPLOYMENT_NAME kullanır.

FoundryToolbox öğesini barındırılan aracıyla kullanın

FoundryToolbox kendi uç noktasını çözümler, sağlanan Azure kimlik bilgilerini kullanarak her MCP isteğinin kimlik doğrulamasını yapar, Foundry'nin istek başına çağrı kimliğini iletir ve aracının bağlantı yaşam döngüsünde yer alır.

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()

Araç Kutusu becerilerini gösterme

Araç Kutusu, MCP üzerinden Aracı Becerilerini kullanıma açabilir. Yalnızca becerilerin model tarafından görünür olması gerektiğinde load_tools=False ayarını yapın; ardından MCP oturumunun bağlanması için Toolbox'ı bir araç olarak ekleyin ve as_skills_provider() öğesini bağlam sağlayıcısı olarak kullanın.

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()

Onay, beceri işlemleri için varsayılan olarak etkin kalır. Yalnızca güvenilir, katılımsız senaryolar için tekil onayları devre dışı bırakın.

FoundryAgent ile Araç Kutusu Kullanımı

Araç Kutusunu Foundry'deki İstem ya da Barındırılan Aracı tanımına ekleyin. FoundryAgent bu saklanan araç yapılandırmasını kullanır; istemci tarafında bir Toolbox geçirmeniz, onu yönetilen aracıya eklemez.

Ham MCP üzerinden bağlanma

Uygulama FoundryToolbox barındırma kapsayıcısını kullanmıyorsa, MCPStreamableHTTPTool doğrudan kullanın. Araç Kutusu uç noktasını ve Entra ID bearer belirtecini header_provider aracılığıyla sağlayın.

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}")

Alt düzeydeki örnek FOUNDRY_TOOLBOX_ENDPOINT kullanır. Toolbox becerileri örneğinde FOUNDRY_TOOLBOX_MCP_SERVER_URL kullanılır; bu adlar bu örneklere aittir ve FoundryToolbox sınıfının TOOLBOX_ENDPOINT ve TOOLBOX_NAME ayarlarından ayrıdır.

Limitations

  • Araç Kutusu içindeki MCP araçları, Bir Foundry project_connection_idaracılığıyla sunucu tarafı kimlik doğrulaması kullanır; Agent Framework istemcisi yukarı akış MCP taşıyıcı belirtecini tutmaz.
  • Bir Araç Kutusu'nu MCP sunucusu olarak kullanmak, Toolbox uç noktası için istemci tarafı Entra ID kimlik doğrulaması gerektirir.
  • gibi CONSENT_REQUIRED onay akışı yanıtları, Araç Kutusu bağlantısı oluşturulurken değil aracı çalışırken işlenir.

Samples

Sample Açıklama
foundry_toolbox/main.py FoundryToolbox barındırılan Yanıtlar aracısı ile
foundry_toolbox_mcp_skills/main.py Toolbox Destekli Ajan Becerileri
foundry_chat_client_with_toolbox.py ile araç kutusu MCP tüketimi MCPStreamableHTTPTool
foundry_chat_client_with_toolbox_skills.py Araç kutusu destekli beceri yapılandırması
invoke_foundry_toolbox_mcp İş akışı tarafı MCP tüketimi

Go şu anda bir Foundry Toolbox yardımcısı sağlamıyor. Foundry aracılığıyla Araç Kutularını yapılandırın ve Go aracıları için desteklenen yerel veya barındırılan araç bildirimlerini kullanın.

  • Last updated on