Caixa de ferramentas do Microsoft Foundry

Para um FoundryAgent gerenciado por serviço, anexe a caixa de ferramentas à definição do agente no Foundry.

Para um agente hospedado criado com Microsoft Agent Framework, use AddFoundryToolboxes de Microsoft.Agents.AI.Foundry.Hosting, conforme mostrado no exemplo a seguir.

Use um projeto Web .NET 10 com usos implícitos habilitados, versões correspondentes de Microsoft.Agents.AI.Foundry e Microsoft.Agents.AI.Foundry.Hosting.DotNetEnv Defina TOOLBOX_NAME como uma toolbox existente e FOUNDRY_MODEL como a implantação do seu modelo. Foundry fornece FOUNDRY_PROJECT_ENDPOINT ao host implantado. Para acesso ao modelo local, defina FOUNDRY_PROJECT_ENDPOINT e entre com CLI do Azure. As implantações hospedadas recorrem ao AZURE_AI_MODEL_DEPLOYMENT_NAME gerenciado pelo azd. A integração de hospedagem 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 registro de hospedagem dá suporte a ferramentas configuradas para consentimento OAuth por usuário em suas conexões de caixa de ferramentas. Os usuários ainda precisam das permissões e do consentimento necessários; nenhum bloco de registro de host separado é necessário.

Para obter os arquivos de projeto e as instruções de implantação, consulte Hosted-Toolbox. Para a configuração de consentimento por usuário, consulte Hosted-Toolbox-AuthPaths.

Instalar 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 MCP explícito do Toolbox:

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

Ou deixe que FoundryToolbox construa o endpoint:

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

Os exemplos de hosted-agent preferem FOUNDRY_MODEL localmente e recorrem ao AZURE_AI_MODEL_DEPLOYMENT_NAME gerenciado pelo azd quando hospedados.

Usar FoundryToolbox com um agente hospedado

FoundryToolbox resolve seu ponto de extremidade, autentica cada solicitação MCP com a credencial do Azure fornecida, encaminha o ID de chamada por solicitação do Foundry e participa do ciclo de vida da conexão do agente. Ele resolve cabeçalhos de plataforma em cada limite de cada operação e reconecta sua sessão MCP quando a identidade de solicitação efetiva é alterada. Portanto, uma Toolbox de longa duração não retém a ID de chamada de um chamador anterior.

O exemplo cria a Toolbox, o cliente e a credencial dentro da fábrica de agentes com escopo de solicitação para controle determinístico e limpeza. Use este padrão de fábrica quando os recursos relacionados são de propriedade da solicitação, mas não é necessário apenas para manter as IDs de chamada da Toolbox atualizadas.

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 arquivo e a resposta do assistente nomeia esse arquivo, o adaptador de respostas hospedado emite uma anotação nativa container_file_citation com o contêiner e as IDs de arquivo. Os clientes do Responses podem usar essas IDs para descobrir e baixar o arquivo gerado por meio da API de arquivos de contêiner.

Exponha as habilidades da caixa de ferramentas

Uma caixa de ferramentas pode expor as Habilidades do Agente via MCP. Defina load_tools=False quando apenas as habilidades devem ser visíveis para o modelo e, em seguida, adicione a Caixa de Ferramentas como uma ferramenta para que sua sessão MCP se conecte e use as_skills_provider() como um provedor 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 permanece habilitada por padrão para operações de habilidade. Desative as aprovações individuais apenas para cenários confiáveis e sem supervisão. Mantenha a Toolbox e seu provedor de habilidades juntos para que ambos usem a mesma sessão MCP. Para uma Toolbox de longa duração, o cache de descoberta de habilidades é substituído quando a identidade efetiva do cabeçalho da plataforma é alterada. Um header_provider personalizado usado com habilidades deve ser resolvido do estado ambiente, como um fechamento ou ContextVar, porque as leituras de habilidade e recurso não recebem argumentos de runtime de função.

Use uma Caixa de Ferramentas com FoundryAgent

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

Conectar-se por meio do MCP com FoundryToolbox

Use FoundryToolbox com ResponsesHostServer para conectar um agente hospedado ao endpoint MCP do Toolbox. O wrapper autentica solicitações MCP e encaminha o contexto de chamador da solicitação hospedada atual para passagem de identidade por usuário. A fábrica com agent escopo de solicitação continua sendo a opção mais simples quando o cliente, a credencial e a Toolbox precisam de um limite de descarte. Um Toolbox de longa duração também é suportado e se reconecta antes de uma operação quando a identidade do cabeçalho da plataforma é alterada.

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 implantações hospedadas recorrem ao AZURE_AI_MODEL_DEPLOYMENT_NAME gerenciado pelo azd.

Limitações

• As ferramentas MCP dentro de uma caixa de ferramentas usam autenticação do lado do servidor por meio de um project_connection_id do Foundry; o cliente do Agent Framework não possui o token de portador MCP upstream.
• Consumir uma caixa de ferramentas como servidor MCP requer autenticação do Entra ID do lado do cliente para o ponto de extremidade da caixa de ferramentas.
• Respostas de fluxo de consentimento, como CONSENT_REQUIRED são tratadas enquanto o agente é executado, não enquanto a conexão da Caixa de Ferramentas é criada.

Samples

Atualmente, o Go não disponibiliza uma função auxiliar do Foundry Toolbox. Configure caixas de ferramentas pelo Foundry e use declarações de ferramentas locais ou hospedadas compatíveis para agentes Go.