Microsoft Foundry Toolbox

Para um FoundryAgent gerido pelo serviço, anexe a Toolbox à definição do agente no Foundry.

Para um agente alojado criado com o Microsoft Agent Framework, use AddFoundryToolboxes de Microsoft.Agents.AI.Foundry.Hosting, conforme mostrado no exemplo seguinte.

Use um projeto web .NET 10 com usos implícitos ativados, versões correspondentes de Microsoft.Agents.AI.Foundry e Microsoft.Agents.AI.Foundry.Hosting, e DotNetEnv. Define TOOLBOX_NAME para uma caixa de ferramentas existente e FOUNDRY_MODEL para a implementação do teu modelo. Foundry fornece FOUNDRY_PROJECT_ENDPOINT ao anfitrião implementado. Para acesso local ao modelo, defina FOUNDRY_PROJECT_ENDPOINT e inicie sessão com o CLI do Azure. As implantações hospedadas recorrem ao AZURE_AI_MODEL_DEPLOYMENT_NAME gerido pelo azd. A integração de alojamento carrega as ferramentas da caixa de ferramentas quando FOUNDRY_PROJECT_ENDPOINT está disponível.

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

O mesmo registo de alojamento suporta ferramentas configuradas para consentimento OAuth por utilizador nas respetivas ligações da caixa de ferramentas. Os utilizadores ainda precisam das permissões e consentimento necessários; não é necessário um bloqueio separado de registo do host.

Para os ficheiros do projeto e instruções de implementação, consulte Hosted-Toolbox. Para a configuração por consentimento por utilizador, veja Hosted-Toolbox-AuthPaths.

Instale os pacotes

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

FoundryToolbox é importado de agent_framework.foundry e fornecido por agent-framework-foundry-hosting.

Configurar a Caixa de Ferramentas

Defina um endpoint explícito do Toolbox MCP:

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

Ou deixe que FoundryToolbox crie o endpoint:

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

As amostras dos agentes hospedados preferem FOUNDRY_MODEL localmente e recorrem ao azd-managed AZURE_AI_MODEL_DEPLOYMENT_NAME quando hospedadas.

Utilize FoundryToolbox com um agente alojado

FoundryToolbox resolve o respetivo ponto final, autentica cada pedido MCP com a credencial do Azure fornecida, encaminha o ID de chamada por pedido do Foundry e participa no ciclo de vida da ligação do agente. Resolve os cabeçalhos de plataforma em cada limite de operação e restabelece a sua sessão MCP quando a identidade efetiva do pedido muda. Um Toolbox de longa duração, portanto, não mantém o ID de chamada de um chamador anterior.

O exemplo cria a Toolbox, o cliente e a credencial dentro da fábrica de agentes com âmbito de pedido, para propriedade determinística e limpeza. Use este padrão de fábrica quando os recursos relacionados pertencem ao pedido, mas não é necessário apenas para manter atualizados os IDs de chamadas do Toolbox.

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

Quando o Toolbox Code Interpreter produz um ficheiro e o assistente de resposta nomeia esse ficheiro, o adaptador de Respostas hospedado emite uma anotação nativa container_file_citation com os IDs do contentor e do ficheiro. Os clientes Responses podem usar esses IDs para descobrir e descarregar o ficheiro gerado através da API de ficheiros do contentor.

Competências do Expose Toolbox

Uma Caixa de Ferramentas pode expor as Competências do Agente em relação ao MCP. Defina load_tools=False quando apenas as competências devem ser visíveis no modelo, depois adicione a Toolbox como ferramenta para que a sua sessão MCP se conecte e use as_skills_provider() como fornecedora de contexto.

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

A aprovação continua ativada por predefinição para operações relacionadas com competências. Desative as aprovações individuais apenas para cenários de confiança e não supervisionados. Mantém o Toolbox e o seu fornecedor de competências juntos para que ambos usem a mesma sessão MCP. Para um Toolbox de longa duração, a cache de descoberta de skills é substituída quando a identidade efetiva do cabeçalho da plataforma muda. Um header_provider personalizado usado com skills deve ser resolvido a partir do estado envolvente, como um fecho ou ContextVar, porque as leituras de skill e resource não recebem argumentos de runtime de funções.

Utilize uma Caixa de Ferramentas com FoundryAgent

Anexe a caixa de ferramentas à definição de Prompt ou Agente Hospedado no Foundry. FoundryAgent utiliza essa configuração de ferramentas armazenada; passar Toolbox no lado do cliente não o adiciona ao agente gerido.

Ligue-se através do MCP com FoundryToolbox

Utilize FoundryToolbox com ResponsesHostServer para ligar um agente alojado ao endpoint MCP do Toolbox. O componente autentica os pedidos MCP e encaminha o contexto do chamador do pedido alojado atual para a transmissão da identidade de cada utilizador. A fábrica com agent âmbito por pedido continua a ser a opção mais simples quando o cliente, a credencial e a Toolbox precisam de um limite para a libertação de recursos. Também é suportado um Toolbox de longa duração que se reconecta antes de uma operação quando a identidade do cabeçalho da plataforma muda.

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

Defina TOOLBOX_ENDPOINT, ou defina ambos FOUNDRY_PROJECT_ENDPOINT e TOOLBOX_NAME, conforme descrito em Configurar a Caixa de Ferramentas. Defina FOUNDRY_MODEL para execuções locais; as implementações hospedadas recorrem ao AZURE_AI_MODEL_DEPLOYMENT_NAME gerido pelo azd.

Limitações

• As ferramentas MCP dentro de um Toolbox usam autenticação do lado do servidor através de um Foundry project_connection_id; o cliente do Agent Framework não detém o token portador MCP a montante.
• Utilizar a Toolbox como um servidor MCP requer autenticação Entra ID no lado do cliente para o endpoint da Toolbox.
• As respostas de fluxo de consentimento, como a CONSENT_REQUIRED , são tratadas enquanto o agente está em execução, e não enquanto a ligação Toolbox é criada.

Samples

O Go não disponibiliza atualmente um auxiliar do Foundry Toolbox. Configure as Toolboxes no Foundry e utilize declarações de ferramentas locais ou alojadas suportadas para agentes Go.