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.

Örneği Azure Developer CLI ile dağıtın

Geçerli Python örneği, barındırılan aracıyı, bağlantıları, Araç Kutusu'nu ve ortam değişkeni eşlemesini tanımlamak için bir azure.yaml kullanır. Birleşik microsoft.foundry uzantıyla Azure Geliştirici CLI 1.34.2 veya sonraki bir sürümü kullanın:

azd ext install microsoft.foundry
azd provision
azd deploy --all

Yönetici bağlı Azure kaynakları üzerinde gerekli rolleri vermeden önce Foundry projesinin yönetilen kimliğinin mevcut olması için önce oluşturun. azure.yaml öğesini içeren başlatılmış proje dizininden sonraki komutları çalıştırın.

Entra pass-through ile yapılandırılan araçlar için, Foundry geçerli çağıranın kimliğini iletir. Çağıranın yine de hedef kaynağa erişmesi gerekir ve barındırılan uygulamanın önceki bir isteğin üst bilgilerini yeniden kullanmak yerine platform çağrısı bağlamını iletmesi gerekir.

Tam ortam, rol ataması, yerel çalıştırma, dağıtım ve çağırma sırası için Python Foundry Toolbox örneğine bakın.

Araç Kutusu araç aramasını etkinleştir

Araç kutusu aracı araması, modelin ilk araç listesini küçük tutar. ToolSearchToolboxTool ögesini MCP araçlarıyla bir Toolbox sürümüne ekleyin. Model başlangıçta call_tool ve tool_search öğelerini görür, ardından gerektiği gibi temel alınan MCP araçlarını bulur.

Bu örneği çalıştırmadan önce Foundry SDK'sını yükseltin:

pip install --upgrade "azure-ai-projects>=2.4.0"

Python örneği, hem MCPToolboxTool hem de azure-ai-projects içeren yeni bir Toolbox sürümü oluşturmak için ToolSearchToolboxTool 2.4.0 veya üzerini kullanır. Tam olarak o sürüme bağlanır ve mevcut sürümleri silmez. Çalıştırmanın başında alttaki araç listesinin tamamını görmek istediğinizde araç arama girdisini kaldırın.

Sürüm oluşturma ve MCP bağlantı deseni için bkz. Toolbox tool search ile Foundry Chat Client.

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	MCP üzerinden tool_search ve call_tool aracılığıyla isteğe bağlı Araç Kutusu keşfi
foundry_chat_client_with_toolbox_skills.py	Araç kutusu destekli beceri yapılandırması
invoke_foundry_toolbox_mcp	İş akışı tarafı MCP tüketimi

Go, toolbox'ın bağlı olduğu hizmet tarafından yönetilen bir aracıyı çağırabilir veya standart MCP tümleştirmesi aracılığıyla Toolbox uç noktasını kullanabilir. Diğer sekmelerde gösterilen özel FoundryToolbox veya AddFoundryToolboxes yardımcılarını sağlamaz.

Hizmet tarafından yönetilen bir aracıyla Araç Kutusu kullanın

Araç Kutusu'nu Foundry'deki ajan tanımına ekleyin, ardından mevcut ajanı foundryprovider.ServerAgent("<agent-name>") ve foundryprovider.NewAgent ile çağırın. Hizmet, depolanan Toolbox yapılandırmasının sahibidir.

Tek tek yerel veya barındırılan araç bildirimlerini bir model dağıtım aracısına geçirmek bir Toolbox eklemez. Bağlantı kurulumu için bkz. Mevcut sunucu tarafı Foundry aracısı.

MCP ile bağlanın

Uygulama tarafından yönetilen Go aracısından Araç Kutusu araçlarını kullanmak için:

1. Mevcut bir Araç Kutusu'nun MCP uç noktasını alın.
2. Toolbox isteklerinin kimliğini doğrulamak için https://ai.azure.com/.default için Azure kimlik bilgileriyle uygulamaya ait bir HTTP istemcisi yapılandırın. Belirteci gerektiği gibi yenileyin ve kimlik bilgisi iletmeyi hedeflenen Araç Kutusu uç noktasına kısıtlayın.
3. Bu istemciyi Endpoint üzerinden, mcp.StreamableClientTransport.HTTPClient içindeki Araç Kutusu uç noktasıyla iletin.
4. Önce mcptool.Connect çağrısını, sonra mcptool.ListTools çağrısını yapın ve döndürülen araçları agent.Config.Tools içine kaydedin.
5. Ajan araçlarını kullanırken MCP oturumunu açık tutun ve bu işlemler tamamlandığında kapatın.

Bu, yerel MCP araçlarıyla aynı bulma ve çağırma desenini izler. Go aktarım ve araç kayıt API'leri için bkz. MCP sunucusuna bağlanma .

Go tümleştirme sınırları

Genel Go MCP tümleştirmesi, .NET ve Python örneklerinde açıklanan barındırılan Toolbox yaşam döngüsünü, platform-header kimlik iletimini veya Toolbox destekli beceri bağdaştırıcısını sağlamaz. Bu yardımcıların otomatik olarak çalıştığını varsaymak yerine uygulamanızda kimlik doğrulama ve kaynak sahipliğini yapılandırın.

İlgili yönergeler

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