Kotak Alat Microsoft Foundry

Microsoft Foundry Toolbox adalah bundel sisi server yang diberi nama dan memiliki versi, berisi konfigurasi alat yang dihosting, seperti interpreter kode, pencarian file, pembuatan gambar, MCP, dan pencarian web. Kotak alat memungkinkan Anda mengelola konfigurasi alat sekali di Foundry dan menggunakannya kembali di seluruh agen.

Kerangka kerja Agen mencakup penggunaan Toolbox. Buat dan perbarui versi Toolbox melalui portal Foundry atau azure-ai-projects SDK.

Penting

FoundryToolbox disediakan oleh paket beta agent-framework-foundry-hosting dan dapat berubah sebelum rilis stabil.

Untuk layanan yang dikelola FoundryAgent, lampirkan Kotak Alat ke definisi agen di Foundry.

Untuk agen yang dihosting yang dibangun dengan Microsoft Agent Framework, gunakan AddFoundryToolboxes dari Microsoft.Agents.AI.Foundry.Hosting, seperti yang ditunjukkan dalam contoh berikut.

Gunakan proyek web .NET 10 dengan penggunaan implisit diaktifkan, versi yang cocok dari Microsoft.Agents.AI.Foundry, Microsoft.Agents.AI.Foundry.Hosting, dan DotNetEnv. Atur TOOLBOX_NAME ke kotak alat yang sudah ada dan FOUNDRY_MODEL ke penyebaran model Anda. Foundry menyediakan FOUNDRY_PROJECT_ENDPOINT ke host yang di-deploy. Untuk akses model lokal, atur FOUNDRY_PROJECT_ENDPOINT dan masuk dengan Azure CLI. Penyebaran yang dihosting beralih ke azd-managed AZURE_AI_MODEL_DEPLOYMENT_NAME. Integrasi host memuat alat dalam kotak alat saat FOUNDRY_PROJECT_ENDPOINT tersedia.

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 ───────────────────────────────────────────────

Registrasi hosting yang sama mendukung alat yang dikonfigurasi untuk persetujuan OAuth tiap pengguna pada koneksi toolbox mereka. Pengguna masih memerlukan izin dan persetujuan yang diperlukan; tidak diperlukan blok pendaftaran host terpisah.

Untuk file proyek dan instruksi penyebaran, lihat Hosted-Toolbox. Untuk penyiapan persetujuan per pengguna, lihat Hosted-Toolbox-AuthPaths.

Instal paket-paket tersebut

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

FoundryToolbox diimpor dari agent_framework.foundry dan disediakan oleh agent-framework-foundry-hosting.

Konfigurasikan Kotak Alat

Atur endpoint MCP Toolbox secara eksplisit:

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

Atau biarkan FoundryToolbox membangun titik akhir:

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

Sampel agen yang dihosting lebih suka FOUNDRY_MODEL secara lokal dan kembali ke azd-managed AZURE_AI_MODEL_DEPLOYMENT_NAME saat dihosting.

Gunakan `FoundryToolbox` dengan agen yang dihosting

FoundryToolbox menentukan endpoint-nya, mengautentikasi setiap permintaan MCP dengan kredensial Azure yang disediakan, meneruskan ID panggilan Foundry untuk setiap permintaan, dan berpartisipasi dalam siklus hidup koneksi agen. Ini menentukan header platform di setiap batas operasi dan menyambungkan kembali sesi MCP-nya ketika identitas permintaan yang efektif berubah. Oleh karena itu, Toolbox berumur panjang tidak mempertahankan ID panggilan pemanggil sebelumnya.

Contoh ini membuat Toolbox, klien, dan kredensial di dalam pabrik agen dalam cakupan permintaan untuk kepemilikan dan pembersihan deterministik. Gunakan pola pabrik ini saat sumber daya terkait dimiliki oleh permintaan, tetapi tidak diperlukan hanya untuk menjaga ID panggilan Toolbox tetap terkini.

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

Ketika Toolbox Code Interpreter menghasilkan file dan respons asisten menamai file tersebut, adaptor Respons yang dihosting memancarkan anotasi asli container_file_citation dengan kontainer dan ID file. Klien dapat menggunakan ID tersebut untuk menemukan dan mengunduh file yang dihasilkan melalui API file kontainer.

Tampilkan keterampilan Toolbox

Kotak Alat dapat mengekspos Keterampilan Agen melalui MCP. Atur load_tools=False saat hanya keterampilan yang harus terlihat oleh model, lalu tambahkan Toolbox sebagai alat agar sesi MCP-nya terhubung dan gunakan as_skills_provider() sebagai penyedia konteks.

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

Persetujuan tetap diaktifkan secara default untuk operasi keterampilan. Nonaktifkan persetujuan per pengguna hanya untuk skenario tepercaya tanpa pengawasan. Jaga Toolbox dan penyedia keterampilannya bersama-sama sehingga keduanya menggunakan sesi MCP yang sama. Untuk Toolbox berumur panjang, cache penemuan keterampilan diganti ketika identitas header platform yang efektif berubah. Fungsi kustom header_provider yang digunakan dengan skill harus diresolusikan dari konteks sekitarnya, seperti closure atau ContextVar, karena pembacaan skill dan resource tidak menerima argumen runtime fungsi.

Gunakan Kotak Peralatan dengan `FoundryAgent`

Lampirkan Kotak Alat ke definisi Prompt atau Hosted Agent di Foundry. FoundryAgent menggunakan konfigurasi tool yang tersimpan; meneruskan Toolbox di sisi klien tidak menambahkannya ke agen terkelola.

Menyambungkan melalui MCP dengan `FoundryToolbox`

Gunakan FoundryToolbox dengan ResponsesHostServer untuk menyambungkan agen yang dihosting ke titik akhir Toolbox MCP. Pembungkus mengautentikasi permintaan MCP dan meneruskan konteks pemanggil permintaan yang dihosting saat ini untuk passthrough identitas per pengguna. Factory dalam cakupan permintaan agent tetap menjadi opsi paling sederhana ketika klien, kredensial, dan Toolbox memerlukan satu batas pembersihan. Toolbox berumur panjang juga didukung dan terhubung kembali sebelum operasi saat identitas header platform berubah.

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

Atur TOOLBOX_ENDPOINT, atau atur FOUNDRY_PROJECT_ENDPOINT dan TOOLBOX_NAME sekaligus, seperti yang dijelaskan dalam Mengonfigurasi Toolbox. Atur FOUNDRY_MODEL untuk eksekusi lokal; penyebaran yang dihosting beralih ke azd-managed AZURE_AI_MODEL_DEPLOYMENT_NAME.

Limitations

Alat MCP di dalam Toolbox menggunakan autentikasi di sisi server melalui Foundry project_connection_id; klien Agent Framework tidak menyimpan token bearer MCP dari hulu.
Menggunakan Toolbox sebagai server MCP memerlukan autentikasi Entra ID di sisi klien untuk endpoint Toolbox.
Respons alur persetujuan seperti CONSENT_REQUIRED ditangani saat agen berjalan, bukan saat koneksi Toolbox dibuat.

Samples

Sample	Deskripsi
foundry_toolbox/main.py	`FoundryToolbox` dengan agen Responses yang terhosting
foundry_toolbox_mcp_skills/main.py	Keterampilan Agen yang didukung kotak alat
foundry_chat_client_with_toolbox.py	Penggunaan MCP dengan Toolbox `MCPStreamableHTTPTool`
foundry_chat_client_with_toolbox_skills.py	Konfigurasi keterampilan berbasis Toolbox
invoke_foundry_toolbox_mcp	Penggunaan MCP di sisi alur kerja

Go saat ini tidak menyediakan fungsi pembantu Foundry Toolbox. Konfigurasikan Kotak Alat melalui Foundry dan gunakan deklarasi alat lokal atau yang dihosting yang didukung untuk agen Go.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-10-06

Kotak Alat Microsoft Foundry

Instal paket-paket tersebut

Konfigurasikan Kotak Alat

Gunakan FoundryToolbox dengan agen yang dihosting

Tampilkan keterampilan Toolbox

Gunakan Kotak Peralatan dengan FoundryAgent

Menyambungkan melalui MCP dengan FoundryToolbox