Microsoft Foundry 도구 상자

Microsoft Foundry 도구 상자는 코드 인터프리터, 파일 검색, 이미지 생성, MCP 및 웹 검색과 같은 호스트된 도구 구성의 명명된 버전이 지정된 서버 쪽 번들입니다. 도구 상자를 사용하면 Foundry에서 도구 구성을 한 번 관리하고 에이전트 간에 다시 사용할 수 있습니다.

에이전트 프레임워크는 도구 상자 사용을 다룹니다. Foundry 포털 또는 azure-ai-projects SDK를 통해 도구 상자 버전을 만들고 업데이트합니다.

중요합니다

FoundryToolbox 는 베타 agent-framework-foundry-hosting 패키지에서 제공되며 안정적인 릴리스 전에 변경할 수 있습니다.

서비스 관리 FoundryAgent의 경우 Foundry의 에이전트 정의에 도구 상자를 연결합니다.

Microsoft Agent Framework로 빌드한 호스팅 에이전트의 경우 다음 예제와 같이 AddFoundryToolboxes에서 Microsoft.Agents.AI.Foundry.Hosting를 사용합니다.

암시적 using이 사용 설정되고 Microsoft.Agents.AI.Foundry, Microsoft.Agents.AI.Foundry.Hosting, DotNetEnv의 버전이 서로 일치하는 .NET 10 웹 프로젝트를 사용합니다. AZURE_AI_MODEL_DEPLOYMENT_NAME을 기존 도구 상자로, TOOLBOX_NAME을 모델 배포로 설정합니다. Foundry는 배포된 호스트에 FOUNDRY_PROJECT_ENDPOINT를 제공합니다. 로컬 모델에 액세스하려면 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를 참조하세요. 사용자별 동의 설정은 Hosted-Toolbox-AuthPaths를 참조하세요.

패키지 설치

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

FoundryToolbox은(는) agent_framework.foundry에서 가져오며 agent-framework-foundry-hosting에서 제공합니다.

도구 상자 구성

명시적 도구 상자 MCP 엔드포인트를 설정합니다.

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

호스티드 에이전트 샘플은 FoundryChatClient에도 AZURE_AI_MODEL_DEPLOYMENT_NAME를 사용합니다.

호스트된 에이전트와 함께 사용 `FoundryToolbox`

FoundryToolbox는 엔드포인트를 확인하고, 제공된 Azure 자격 증명을 사용하여 모든 MCP 요청을 인증하고, 요청당 Foundry 호출 ID를 전달하며, 에이전트의 연결 수명 주기에 참여합니다. 호스팅된 Responses 에이전트에서 요청 범위 에이전트 팩터리 안에 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로 설정한 다음, 해당 MCP 세션이 연결되도록 Toolbox를 도구로 추가하고 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()

기술 작업에 대한 승인은 기본적으로 활성화된 상태로 유지됩니다. 신뢰할 수 있는 무인 시나리오에 대해서만 개별 승인을 사용하지 않도록 설정합니다. 동일한 MCP 세션을 사용하고 함께 삭제되도록 도구 상자와 기술 공급자를 동일한 요청 팩터리에 유지합니다.

다음과 함께 툴박스 사용: `FoundryAgent`

Foundry의 프롬프트 또는 호스트된 에이전트 정의에 도구 상자를 연결합니다. FoundryAgent 는 저장된 도구 구성을 사용합니다. 도구 상자 클라이언트 쪽을 전달해도 관리되는 에이전트에 추가되지 않습니다.

MCP를 통해 연결 `FoundryToolbox`

호스팅된 에이전트를 Toolbox MCP 엔드포인트에 연결하려면 ResponsesHostServer와(과) FoundryToolbox를 사용하세요. 래퍼는 MCP 요청을 인증하고 사용자별 ID 통과를 위해 현재 호스팅된 요청의 호출자 컨텍스트를 전달합니다. 각 요청이 자체 호출자 컨텍스트를 받도록 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를 사용합니다.

제한 사항

도구 상자 내의 MCP 도구는 Foundry project_connection_id를 통해 서버 쪽 인증을 사용합니다. 에이전트 프레임워크 클라이언트는 업스트림 MCP 전달자 토큰을 보유하지 않습니다.
도구 상자를 MCP 서버로 사용하려면 도구 상자 엔드포인트에 대한 클라이언트 쪽 Entra ID 인증이 필요합니다.
이러한 동의 흐름 응답 CONSENT_REQUIRED 은 도구 상자 연결이 만들어지는 동안이 아니라 에이전트가 실행되는 동안 처리됩니다.

Samples

Sample	설명
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

제한 사항

Samples

관련 참고 자료

피드백

추가 리소스

호스트된 에이전트와 함께 사용 `FoundryToolbox`

다음과 함께 툴박스 사용: `FoundryAgent`

MCP를 통해 연결 `FoundryToolbox`