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. Panduan penggunaan .NET Toolbox di sisi klien saat ini belum didokumentasikan.

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

Contoh hosted-agent juga menggunakan AZURE_AI_MODEL_DEPLOYMENT_NAME untuk FoundryChatClient.

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.

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

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

Persetujuan tetap diaktifkan secara default untuk operasi keterampilan. Nonaktifkan persetujuan per pengguna hanya untuk skenario tepercaya tanpa pengawasan.

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 mentah

Gunakan MCPStreamableHTTPTool secara langsung ketika aplikasi tidak menggunakan pembungkus FoundryToolbox hosting. Berikan titik akhir Kotak Alat dan token pembawa Entra ID melalui 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}")

Sampel tingkat bawah menggunakan FOUNDRY_TOOLBOX_ENDPOINT. Contoh keterampilan Toolbox menggunakan FOUNDRY_TOOLBOX_MCP_SERVER_URL; nama-nama ini termasuk dalam contoh tersebut dan terpisah dari pengaturan TOOLBOX_ENDPOINT dan TOOLBOX_NAME milik kelas FoundryToolbox.

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?

Last updated on 2026-08-25