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.

Microsoft Agent Framework ile oluşturulmuş barındırılan bir aracı için, aşağıdaki örnekte gösterildiği gibi AddFoundryToolboxes içinden Microsoft.Agents.AI.Foundry.Hosting kullanın.

Örtük using’leri etkinleştirilmiş, Microsoft.Agents.AI.Foundry ile Microsoft.Agents.AI.Foundry.Hosting sürümleri birbiriyle uyumlu olan ve DotNetEnv içeren bir .NET 10 web projesi kullanın. FOUNDRY_MODEL öğesini mevcut bir araç kutusuna, TOOLBOX_NAME öğesini ise model dağıtımınıza ayarlayın. Foundry, dağıtılan ana bilgisayara FOUNDRY_PROJECT_ENDPOINT sağlar. Yerel model erişimi için FOUNDRY_PROJECT_ENDPOINT ayarlayın ve Azure CLI ile oturum açın. Barındırılan dağıtımlar azd tarafından yönetilen AZURE_AI_MODEL_DEPLOYMENT_NAME öğesini kullanır. Barındırma tümleştirmesi, kullanılabilir olduğunda FOUNDRY_PROJECT_ENDPOINT araç kutusu araçlarını yükler.

using DotNetEnv;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

// Load .env file if present (for local development)
Env.TraversePath().Load();

string endpoint = System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = FirstNonBlank(
    System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL"),
    System.Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
    "gpt-4o")!;
string toolboxName = FirstNonBlank(
    System.Environment.GetEnvironmentVariable("TOOLBOX_NAME"),
    "my-toolset")!;

// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
// Use a chained credential: try a temporary dev token first (for local Docker debugging),
// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity in production).
    .AsAIAgent(
        model: deploymentName,
            Use the available tools to answer user questions.
            If a tool is not available for a request, let the user know clearly.
            """,
        name: System.Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-toolbox-agent",
        description: "Hosted agent backed by Foundry Toolbox MCP tools");

// ── Build the host ────────────────────────────────────────────────────────────

var builder = WebApplication.CreateBuilder(args);

// Register the agent and response handler
// Register Foundry Toolbox: connects to the MCP proxy at startup and makes tools available.
// The toolbox name must match a toolbox registered in your Foundry project.
// When FOUNDRY_PROJECT_ENDPOINT is absent (e.g., in local development without Foundry
// infrastructure), startup succeeds without error and no toolbox tools are loaded.
builder.Services.AddFoundryToolboxes(credential, toolboxName);

app.Run();

static string? FirstNonBlank(params string?[] candidates) =>
    Array.Find(candidates, candidate => !string.IsNullOrWhiteSpace(candidate));

// ── DevTemporaryTokenCredential ───────────────────────────────────────────────

Aynı barındırma kaydı, araç kutusu bağlantılarında kullanıcı başına OAuth onayı için yapılandırılmış araçları destekler. Kullanıcıların hala gerekli izinlere ve onaylara ihtiyacı vardır; ayrı bir konak kayıt bloğu gerekmez.

Proje dosyaları ve dağıtım yönergeleri için bkz . Barındırılan Araç Kutusu. Kullanıcı başına onay kurulumu için bkz . Hosted-Toolbox-AuthPaths.

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, yerelde FOUNDRY_MODEL öğesini tercih eder ve barındırıldığında azd tarafından yönetilen AZURE_AI_MODEL_DEPLOYMENT_NAME öğesine geri döner.

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. Her işlem sınırında platform başlıklarını çözümler ve etkin istek kimliği değiştiğinde MCP oturumunu yeniden kurar. Bu nedenle, uzun ömürlü bir Toolbox önceki bir çağıranın arama kimliğini tutmaz.

Örnek, öngörülebilir sahiplik ve temizleme için istek kapsamındaki aracı fabrikası içinde Araç Kutusu, istemci ve kimlik bilgilerini oluşturur. İlgili kaynaklar isteğe aitse bu fabrika düzenini kullanın, ancak yalnızca Toolbox çağrı kimliklerini güncel tutmak için gerekli değildir.

import asyncio
import os
from contextlib import AsyncExitStack
from types import TracebackType

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.ai.agentserver.core import AgentConfig, get_request_context
from azure.identity.aio import AzureCliCredential, ManagedIdentityCredential
from dotenv import load_dotenv


def create_agent() -> Agent:
    """Create request-owned SDK resources and close them with the agent."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
    credential = (
        ManagedIdentityCredential(client_id=os.environ.get("FOUNDRY_AGENT_INSTANCE_CLIENT_ID"))
        if AgentConfig.from_env().is_hosted
        else AzureCliCredential()
    )

    class RequestClient(FoundryChatClient):
        async def __aenter__(self) -> RequestClient:
            return self

        async def __aexit__(
            self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
        ) -> None:
            async with AsyncExitStack() as cleanup:
                cleanup.push_async_callback(credential.close)
                cleanup.push_async_callback(self.project_client.close)
                cleanup.push_async_callback(self.client.close)

    toolbox = FoundryToolbox(credential)
    client = RequestClient(
        project_endpoint=endpoint,
        model=model,
        credential=credential,
        default_headers=get_request_context().platform_headers(),
    )
    return Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        tools=toolbox,
    )


async def main() -> None:
    load_dotenv()
    server = ResponsesHostServer(agent=create_agent, history_source="agent_server")
    await server.run_async()

Toolbox Code Interpreter bir dosya ürettiğinde ve yardımcı yanıt bu dosyayı adlandırdığında, barındırılan Responses bağdaştırıcısı kapsayıcı ve dosya kimlikleriyle yerel container_file_citation bir ek açıklama yayar. Responses istemcileri, kapsayıcı dosyaları API'sini kullanarak oluşturulan dosyayı bulmak ve indirmek için bu kimlikleri kullanabilir.

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 contextlib import AsyncExitStack
from types import TracebackType

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.ai.agentserver.core import AgentConfig, get_request_context
from azure.identity.aio import AzureCliCredential, ManagedIdentityCredential
from dotenv import load_dotenv


def create_agent() -> Agent:
    """Keep skill caches, credentials and the MCP lifecycle request-owned."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
    credential = (
        ManagedIdentityCredential(client_id=os.environ.get("FOUNDRY_AGENT_INSTANCE_CLIENT_ID"))
        if AgentConfig.from_env().is_hosted
        else AzureCliCredential()
    )

    class RequestClient(FoundryChatClient):
        async def __aenter__(self) -> RequestClient:
            return self

        async def __aexit__(
            self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
        ) -> None:
            async with AsyncExitStack() as cleanup:
                cleanup.push_async_callback(credential.close)
                cleanup.push_async_callback(self.project_client.close)
                cleanup.push_async_callback(self.client.close)

    # tools= connects the MCP session; context_providers= reads skills from that same session.
    toolbox = FoundryToolbox(credential, load_tools=False)
    skills_provider = toolbox.as_skills_provider(disable_load_skill_approval=True)
    client = RequestClient(
        project_endpoint=endpoint,
        model=model,
        credential=credential,
        default_headers=get_request_context().platform_headers(),
    )
    return 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],
    )


async def main() -> None:
    load_dotenv()
    server = ResponsesHostServer(agent=create_agent, history_source="agent_server")
    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. Araç Kutusu'nu ve beceri sağlayıcısını bir arada tutun, böylece her ikisi de aynı MCP oturumunu kullansın. Uzun ömürlü bir Toolbox için, etkili platform-header kimliği değiştiğinde beceri bulma önbelleği değiştirilir. Beceri ve kaynak okumaları işlev çalışma zamanı bağımsız değişkenlerini almadığından, becerilerle kullanılan özel header_provider closure veya ContextVar gibi ortam durumundan çözümlenmesi gerekir.

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.

MCP aracılığıyla bağlanın FoundryToolbox

Barındırılan bir aracıyı Toolbox MCP uç noktasına bağlamak için ResponsesHostServer ile FoundryToolbox kullanın. Sarmalayıcı bileşen, MCP isteklerini kimlik doğrulamasından geçirir ve kullanıcı başına kimlik aktarımı için mevcut barındırılan isteğin çağıran kimlik bağlamını iletir. İstemci, kimlik bilgileri ve Toolbox için tek bir temizleme sınırı gerektiğinde istek kapsamındaki agent fabrikası en basit seçenek olmaya devam eder. Uzun ömürlü bir Araç Kutusu da desteklenir ve platform üst bilgisi kimliği değiştiğinde bir işlemden önce yeniden bağlanır.

import asyncio
import os
from contextlib import AsyncExitStack
from types import TracebackType

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.ai.agentserver.core import AgentConfig, get_request_context
from azure.identity.aio import AzureCliCredential, ManagedIdentityCredential
from dotenv import load_dotenv


def create_agent() -> Agent:
    """Create request-owned SDK resources and close them with the agent."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
    credential = (
        ManagedIdentityCredential(client_id=os.environ.get("FOUNDRY_AGENT_INSTANCE_CLIENT_ID"))
        if AgentConfig.from_env().is_hosted
        else AzureCliCredential()
    )

    class RequestClient(FoundryChatClient):
        async def __aenter__(self) -> RequestClient:
            return self

        async def __aexit__(
            self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
        ) -> None:
            async with AsyncExitStack() as cleanup:
                cleanup.push_async_callback(credential.close)
                cleanup.push_async_callback(self.project_client.close)
                cleanup.push_async_callback(self.client.close)

    toolbox = FoundryToolbox(credential)
    client = RequestClient(
        project_endpoint=endpoint,
        model=model,
        credential=credential,
        default_headers=get_request_context().platform_headers(),
    )
    return Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        tools=toolbox,
    )


async def main() -> None:
    load_dotenv()
    server = ResponsesHostServer(agent=create_agent, history_source="agent_server")
    await server.run_async()

FOUNDRY_PROJECT_ENDPOINT bölümünde açıklandığı gibi, TOOLBOX_ENDPOINT değerini ayarlayın veya hem hem de TOOLBOX_NAME değerlerini ayarlayın. Yerel çalıştırmalar için FOUNDRY_MODEL ayarlanır; barındırılan dağıtımlar yedek olarak azd tarafından yönetilen AZURE_AI_MODEL_DEPLOYMENT_NAME öğesini kullanır.

OAuth onay isteklerini işleme

Bir Araç Kutusu veya MCP işlemi OAuth onayı gerektirdiğinde, FoundryAgent akış ve akış dışı FoundryChatClient çağrılar, boş bir assistant mesajı yerine onay bağlantısıyla birlikte Content(type="oauth_consent_request") döndürür. Bu içeriği kullanıcı girişi isteği olarak işleyip içeriğini consent_link kullanıcıya sunun.

İstemci yalnızca HTTPS şemasına ve geçerli bir ana bilgisayara sahip bağlantıları gösterir. Eksik veya geçersiz bağlantılar atlanır ve günlüğe kaydedilir.

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.

İlgili yönergeler

• Microsoft Döküm modeli sağlayıcısı
• Microsoft Foundry Ajan Hizmeti
• Yerel MCP araçları