Kotak Alat Microsoft Foundry

Microsoft Foundry Toolbox adalah bundel sisi server bernama versi konfigurasi alat yang dihosting, seperti penerjemah 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 konsumsi Kotak Alat. Buat dan perbarui versi Toolbox melalui portal Foundry atau azure-ai-projects SDK.

Important

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 konsumsi Kotak Alat .NET sisi klien saat ini tidak didokumenkan.

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.

Mengonfigurasi Kotak Alat

Atur titik akhir MCP Kotak Alat 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 juga digunakan AZURE_AI_MODEL_DEPLOYMENT_NAME untuk FoundryChatClient.

Gunakan `FoundryToolbox` dengan agen yang dihosting

FoundryToolboxmenyelesaikan titik akhirnya, mengautentikasi setiap permintaan MCP dengan kredensial Azure yang disediakan, meneruskan ID panggilan per permintaan Foundry, 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()

Mengekspos keterampilan Kotak Alat

Kotak Alat dapat mengekspos Keterampilan Agen melalui MCP. Atur load_tools=False ketika hanya keterampilan yang harus terlihat model, lalu tambahkan Kotak Alat sebagai alat sehingga sesi MCP-nya terhubung dan digunakan 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 individual hanya untuk skenario tepercaya dan tidak dijaga.

Menggunakan Kotak Alat dengan `FoundryAgent`

Lampirkan Kotak Alat ke definisi Prompt atau Hosted Agent di Foundry. FoundryAgent menggunakan konfigurasi alat yang disimpan; meneruskan sisi klien Toolbox 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. Sampel keterampilan Toolbox menggunakan FOUNDRY_TOOLBOX_MCP_SERVER_URL; nama-nama ini milik sampel tersebut FoundryToolbox dan terpisah dari kelas TOOLBOX_ENDPOINT dan TOOLBOX_NAME pengaturan.

Limitations

Alat MCP di dalam Kotak Alat menggunakan autentikasi sisi server melalui Foundry project_connection_id; klien Agent Framework tidak memegang token pembawa MCP upstream.
Menggunakan Kotak Alat sebagai server MCP memerlukan autentikasi Entra ID sisi klien untuk titik akhir Kotak Alat.
Respons alur persetujuan seperti CONSENT_REQUIRED ditangani saat agen berjalan, bukan saat koneksi Toolbox dibuat.

Samples

Sample	Description
foundry_toolbox/main.py	`FoundryToolbox` dengan agen Respons yang dihosting
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	Konsumsi MCP sisi alur kerja

Go saat ini tidak mengekspos 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-13