Microsoft مربع أدوات Foundry

مربع أدوات Microsoft Foundry عبارة عن مجموعة من تكوينات الأدوات المستضافة المسماة والمصدارة من جانب الخادم، مثل مترجم التعليمات البرمجية والبحث عن الملفات وإنشاء الصور وMCP والبحث على الويب. تتيح لك مربعات الأدوات إدارة تكوين الأدوات مرة واحدة في Foundry وإعادة استخدامه عبر العوامل.

يغطي إطار عمل العامل استهلاك مربع الأدوات. إنشاء وتحديث إصدارات مربع الأدوات من خلال مدخل Foundry أو azure-ai-projects SDK.

Important

FoundryToolbox يتم توفيرها بواسطة حزمة بيتا agent-framework-foundry-hosting ويمكن أن تتغير قبل الإصدار المستقر.

بالنسبة إلى خدمة مدارة FoundryAgent، قم بإرفاق مربع الأدوات بتعريف العامل في Foundry.

بالنسبة إلى عامل مستضاف تم إنشاؤه باستخدام إطار عمل عامل Microsoft، استخدم AddFoundryToolboxes من Microsoft.Agents.AI.Foundry.Hosting، كما هو موضح في المثال التالي.

استخدم مشروع ويب .NET 10 مع تمكين الاستخدامات الضمنية ومطابقة الإصدارات من Microsoft.Agents.AI.Foundry و Microsoft.Agents.AI.Foundry.Hostingو.DotNetEnv قم بتعيين TOOLBOX_NAME إلى مربع أدوات موجود وإلى AZURE_AI_MODEL_DEPLOYMENT_NAME توزيع النموذج الخاص بك. مستلزمات FOUNDRY_PROJECT_ENDPOINT Foundry للمضيف المنشور. للوصول إلى النموذج المحلي، قم بتعيين AZURE_AI_PROJECT_ENDPOINT وتسجيل الدخول باستخدام Azure CLI. يقوم تكامل الاستضافة بتحميل أدوات مربع الأدوات عند FOUNDRY_PROJECT_ENDPOINT توفرها.

using Azure.AI.Projects;
using Azure.Identity;
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")
    ?? System.Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException(
        "Neither FOUNDRY_PROJECT_ENDPOINT (platform-injected in hosted runtime) " +
        "nor AZURE_AI_PROJECT_ENDPOINT (local-dev convention) is set.");
string deploymentName = FirstNonBlank(
    System.Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
    System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL"),
    "gpt-4o")!;
string toolboxName = FirstNonBlank(
    System.Environment.GetEnvironmentVariable("TOOLBOX_NAME"),
    "my-toolset")!;

var credential = new DefaultAzureCredential();

AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
    .AsAIAgent(
        model: deploymentName,
        instructions: """
            You are a helpful assistant with access to tools provided by the Foundry Toolbox.
            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");

var builder = WebApplication.CreateBuilder(args);

// Register the agent and response handler
builder.Services.AddFoundryResponses(agent);

builder.Services.AddFoundryToolboxes(credential, toolboxName);

var app = builder.Build();
app.MapFoundryResponses();


app.Run();

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

يدعم نفس تسجيل الاستضافة الأدوات التي تم تكوينها للموافقة على OAuth لكل مستخدم على اتصالات مربع الأدوات الخاصة بهم. لا يزال المستخدمون بحاجة إلى الأذونات والموافقة المطلوبة؛ لا يلزم وجود كتلة تسجيل مضيف منفصلة.

للحصول على ملفات المشروع وإرشادات النشر، راجع مربع الأدوات المستضافة. لإعداد الموافقة لكل مستخدم، راجع Hosted-Toolbox-AuthPaths.

ثبت الحزم

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

FoundryToolbox يتم استيرادها من agent_framework.foundry وتوفيرها بواسطة agent-framework-foundry-hosting.

تكوين مربع الأدوات

تعيين نقطة نهاية MCP ل Toolbox صريحة:

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

أو اسمح FoundryToolbox بإنشاء نقطة النهاية:

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

تستخدم AZURE_AI_MODEL_DEPLOYMENT_NAME نماذج الوكيل المستضاف أيضا ل FoundryChatClient.

استخدام `FoundryToolbox` مع عامل مستضاف

FoundryToolboxيحل نقطة النهاية الخاصة به، ويصادق كل طلب MCP مع بيانات اعتماد Azure المتوفرة، ويحيل معرف استدعاء Foundry لكل طلب، ويشارك في دورة حياة اتصال العامل. في عامل الاستجابات المستضاف، قم بإنشاء Toolbox والعميل الخاص به وبيانات الاعتماد الخاصة به داخل مصنع عامل نطاق الطلب. يلتقط كاتب MCP سياق الطلب عند الاتصال، لذلك لا تشارك مربع أدوات متصلا واحدا عبر المتصلين.

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 tools inside this request so the MCP writer captures its call ID."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = 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()

كشف مهارات مربع الأدوات

يمكن أن يعرض مربع الأدوات مهارات العامل عبر MCP. قم بتعيين load_tools=False متى يجب أن تكون المهارات فقط مرئية للنموذج، ثم أضف Toolbox كأداة بحيث تتصل جلسة MCP الخاصة بها وتستخدم as_skills_provider() كموفر سياق.

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 writer within this request."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = 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()

تظل الموافقة ممكنة بشكل افتراضي لعمليات المهارة. تعطيل الموافقات الفردية فقط للسيناريوهات الموثوق بها وغير المراقب. احتفظ ب Toolbox وموفر المهارات في نفس مصنع الطلب بحيث يستخدم كلاهما نفس جلسة MCP ويتم التخلص منها معا.

استخدام مربع أدوات مع `FoundryAgent`

إرفاق Toolbox بتعريف Prompt أو Hosted Agent في Foundry. FoundryAgent يستخدم تكوين الأداة المخزنة؛ لا يؤدي تمرير جانب عميل Toolbox إلى إضافته إلى العامل المدار.

الاتصال من خلال MCP باستخدام `FoundryToolbox`

استخدم FoundryToolbox مع ResponsesHostServer لتوصيل عامل مستضاف بنقطة نهاية Toolbox MCP. يقوم برنامج التضمين بمصادقة طلبات MCP وإعادة توجيه سياق المتصل للطلب المستضاف الحالي لتمرير الهوية لكل مستخدم. إنشاء الاتصال داخل agent المصنع بحيث يتلقى كل طلب سياق المتصل الخاص به.

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 tools inside this request so the MCP writer captures its call ID."""
    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    model = 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_ENDPOINT، أو تعيين كل من FOUNDRY_PROJECT_ENDPOINT و TOOLBOX_NAME، كما هو موضح في تكوين مربع الأدوات. يستخدم AZURE_AI_MODEL_DEPLOYMENT_NAME النموذج لنشر النموذج.

Limitations

تستخدم أدوات MCP داخل مربع الأدوات المصادقة من جانب الخادم من خلال Foundry project_connection_id؛ لا يحتفظ عميل Agent Framework بالرمز المميز لحامل MCP المصدر.
يتطلب استهلاك مربع أدوات كخادم MCP مصادقة Entra ID من جانب العميل لنقطة نهاية مربع الأدوات.
تتم معالجة استجابات تدفق الموافقة مثل CONSENT_REQUIRED أثناء تشغيل العامل، وليس أثناء إنشاء اتصال مربع الأدوات.

Samples

عينة	Description
foundry_toolbox/main.py	`FoundryToolbox` مع عامل استجابات مستضاف
foundry_toolbox_mcp_skills/main.py	مهارات العامل المدعومة من مربع الأدوات
foundry_chat_client_with_toolbox.py	استهلاك MCP في مربع الأدوات مع `MCPStreamableHTTPTool`
foundry_chat_client_with_toolbox_skills.py	تكوين المهارات المدعومة من مربع الأدوات
invoke_foundry_toolbox_mcp	استهلاك MCP من جانب سير العمل

لا يعرض Go حاليا مساعد "مربع أدوات Foundry". تكوين مربعات الأدوات من خلال Foundry واستخدام إعلانات الأدوات المحلية أو المستضافة المدعومة لوكلاء Go.

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-10-01

Microsoft مربع أدوات Foundry

ثبت الحزم

تكوين مربع الأدوات

استخدام FoundryToolbox مع عامل مستضاف

كشف مهارات مربع الأدوات

استخدام مربع أدوات مع FoundryAgent

الاتصال من خلال MCP باستخدام FoundryToolbox