Microsoft Foundry

Introdução

Adicione os pacotes NuGet necessários ao seu projeto.

dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

Dois tipos de agentes

A integração com o Microsoft Foundry expõe dois padrões de utilização distintos:

Tipo	Tipo de produto produzido	Descrição	Utilizar quando
Agente de Respostas	ChatClientAgent	A sua aplicação fornece programaticamente um modelo, instruções e ferramentas em tempo de execução via AIProjectClient.AsAIAgent(...). Não é criado nenhum recurso agente do lado do servidor.	Tem a definição de agente e quer uma configuração simples e flexível. Este é o padrão usado na maioria das amostras.
Foundry Agent (versionado)	FoundryAgent	Gerido pelo servidor — as definições de agentes são criadas e versionadas quer através do portal Foundry, quer programaticamente via AIProjectClient.AgentAdministrationClient. Passe um ProjectsAgentVersion ou ProjectsAgentRecord ou AgentReference para AIProjectClient.AsAIAgent(...).	Precisas de definições estritas e versionadas de agentes geridas no portal Foundry, através de APIs de serviço

Agente de Respostas (inferência direta)

Use AsAIAgent diretamente no AIProjectClient com um modelo e instruções. Este é o ponto de partida recomendado para a maioria dos cenários.

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            name: "Joker",
            instructions: "You are good at telling jokes.");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Este caminho é centrado no código e não cria um recurso de agente gerido pelo servidor.

Foundry Agent (versionado)

Utilize as APIs nativas AIProjectClient.AgentAdministrationClient do SDK de Projetos de IA para obter recursos de agentes versionados, depois envolva-os com AsAIAgent. Os agentes podem ser criados e configurados diretamente no portal Foundry ou programaticamente através de AIProjectClient.AgentAdministrationClient.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;

var aiProjectClient = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential());

// Retrieve an existing agent by name (uses the latest version automatically)
ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Usando o agente

Tanto ChatClientAgent (Respostas) como FoundryAgent (versionado) são instâncias padrão AIAgent e suportam todas as operações padrão, incluindo sessões, ferramentas, middleware e streaming.

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));

Para mais informações sobre como gerir e interagir com agentes, consulte os tutoriais de Início de Agentes.

Tools

Os agentes Foundry criados a partir de AIProjectClient.AsAIAgent(...) (o percurso Responses) suportam o conjunto padrão de ferramentas do Agent Framework — consulte a visão geral das ferramentas para obter a lista completa e a matriz das funcionalidades suportadas. Para agentes Foundry carregados a partir de uma definição de agente versionada (FoundryAgent), as ferramentas do agente pertencem à definição de agente Foundry, não ao cliente.

Tool	Notes
Ferramentas Funcionais	Supported.
Aprovação de Ferramentas	Supported. Fornecido pelo cliente de chat que invoca funções do framework.
Intérprete de código	Supported.
Pesquisa de ficheiros	Supported.
Ferramentas alojadas do MCP	Supported.
Ferramentas MCP Locais	Supported.
Caixas de Ferramentas do Foundry	Supported.

Caixas de Ferramentas

Ferramenta Foundry em Python

Em Python, todos os clientes específicos da Foundry agora residem sob agent_framework.foundry.

• agent-framework-foundry fornece os conectores cloud Foundry: FoundryChatClient, FoundryAgent, FoundryEmbeddingClient, e FoundryMemoryProvider.
• agent-framework-foundry-local permite FoundryLocalClient a execução local do modelo.

Chat Foundry e padrões de agentes em Python

Scenario	Formato de Python	Utilizar quando
Inferência simples com o endpoint Foundry Answers	Agent(client=FoundryChatClient(...))	A tua aplicação detém a definição do agente, as ferramentas e o ciclo de conversa, e queres que um modelo seja implementado num projeto Foundry.
Agentes de gestão de serviços no Serviço de Agentes de Fundição	FoundryAgent(...)	Quer ligar-se a um PromptAgent ou HostedAgent que foi criado e configurado no portal Foundry ou através das APIs do serviço.

Instalação

pip install agent-framework-foundry
pip install azure-identity

O mesmo agent-framework-foundry pacote também inclui FoundryEmbeddingClient embeddings de endpoints de modelos Foundry.

Configuração

FoundryChatClient

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_MODEL="gpt-4o-mini"

FoundryAgent

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

Utilize FOUNDRY_AGENT_VERSION para os Agentes de Prompt. Os agentes alojados podem omitir isso.

FoundryEmbeddingClient

FOUNDRY_MODELS_ENDPOINT="https://<apim-instance>.azure-api.net/<foundry-instance>/models"
FOUNDRY_MODELS_API_KEY="<api-key>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"
FOUNDRY_IMAGE_EMBEDDING_MODEL="Cohere-embed-v3-english"  # optional

FoundryChatClient e FoundryAgent utilizem o endpoint do projeto. FoundryEmbeddingClient utiliza o endpoint de modelos separados.

Escolha o cliente Python certo

Scenario	Cliente preferencial	Notes
Azure OpenAI recurso	OpenAIChatCompletionClient / OpenAIChatClient	Utilize a página do fornecedor OpenAI.
Inferência do projeto Microsoft Foundry	Agent(client=FoundryChatClient(...))	Utiliza o endpoint Foundry Responses.
Microsoft Foundry agente gerido por serviço	FoundryAgent	Recomendado para Prompt Agents e HostedAgents.
Microsoft Foundry incorporações de modelos-ponto final	FoundryEmbeddingClient	Usa FOUNDRY_MODELS_ENDPOINT com FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Tempo de execução Local do Foundry	Agent(client=FoundryLocalClient(...))	Ver o Foundry Local.

Crie um agente com FoundryChatClient

FoundryChatClient liga-se a um modelo implementado num projeto Foundry e utiliza o endpoint Responses. Emparelhe-o com um padrão Agent quando a aplicação deve ter instruções, ferramentas e manuseio de sessões.

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-project.services.ai.azure.com",
        model="gpt-4o-mini",
        credential=AzureCliCredential(),
    ),
    name="FoundryWeatherAgent",
    instructions="You are a helpful assistant.",
)

FoundryChatClient é o primeiro caminho de Python da Foundry para inferência direta e suporta ferramentas, saídas estruturadas e streaming.

Tools

FoundryChatClient inclui métodos de fábrica estáticos para cada ferramenta Foundry alojada. As fábricas devolvem os objetos da ferramenta SDK que passa para tools= em Agent ou diretamente para client.get_response(..., tools=[...]). Para FoundryAgent, as ferramentas do agente estão na própria definição do agente no Foundry — consulte O que funciona e o que não funciona com FoundryAgent.

As fábricas são métodos de classes, por isso não precisas de uma instância para criar uma ferramenta:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(credential=AzureCliCredential()),
    instructions="You can search the web and run code.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        FoundryChatClient.get_code_interpreter_tool(),
    ],
)

Suporte de ferramentas

A tabela abaixo lista todas as ferramentas que o Python FoundryChatClient expõe hoje. FoundryAgent funciona com as mesmas ferramentas, mas estas têm de ser configuradas na definição do agente Foundry, em vez de serem passadas no código.

Tool	Modo de fábrica ativado FoundryChatClient	Status	Detail
Ferramentas Funcionais	N/A — Passe qualquer Python chamável ou @ai_function	disponibilidade geral	Executado localmente no seu processo Python.
Aprovação de Ferramentas	n/a — encapsula ferramentas existentes	disponibilidade geral	Funciona com MCP hospedado e ferramentas funcionais.
Intérprete de código	get_code_interpreter_tool	disponibilidade geral	Execução de código em sandbox no Foundry.
Pesquisa de ficheiros	get_file_search_tool	disponibilidade geral	Pesquise ficheiros carregados através de lojas vetoriais Foundry.
Pesquisa na Web	get_web_search_tool	disponibilidade geral	Ancoragem na Web suportada pelo Bing, gerida pela Microsoft. Apenas modelos do Azure OpenAI.
Geração de Imagem	get_image_generation_tool	disponibilidade geral	Geração de imagens alojada no Foundry.
MCP alojado	get_mcp_tool	disponibilidade geral	Servidor MCP remoto invocado pela Foundry.
Local MCP	n/a — utilize MCPStreamableHTTPTool / MCPStdioTool	disponibilidade geral	É executado no seu processo; funciona com qualquer cliente.
Caixas de Ferramentas do Foundry	MCPStreamableHTTPTool para o endpoint MCP da caixa de ferramentas	disponibilidade geral	Consumido através do MCP a partir de FoundryChatClient; anexado no lado do servidor em FoundryAgent.
Aterramento do Bing	get_bing_grounding_tool	Experimental	Traz o teu próprio recurso de Pesquisa sobre Grounding com Bing.
Pesquisa Personalizada Bing	get_bing_custom_search_tool	Preview	Base do Bing limitada a uma lista selecionada de domínios.
Pesquisa de IA do Azure	get_azure_ai_search_tool	Experimental	Pesquise num índice Pesquisa de IA do Azure através de uma ligação Foundry.
SharePoint	get_sharepoint_tool	Preview	Baseie as respostas no conteúdo do SharePoint.
Microsoft Fabric	get_fabric_tool	Preview	Consultar um agente de dados do Fabric.
Pesquisa de Memória	get_memory_search_tool	Preview	Pesquise numa loja de memórias gerida pela Foundry.
Utilização de computadores	get_computer_use_tool	Preview	Deixe o agente controlar um ambiente de trabalho ou de navegador.
Automação de Navegadores	get_browser_automation_tool	Preview	Controle um navegador através de uma ligação ao Azure Playwright.
Agente-para-Agente (A2A)	get_a2a_tool	Preview	Chama outro agente da A2A como ferramenta.

Variantes da pesquisa web

Foundry disponibiliza três opções de ancoragem suportadas pelo Bing. Escolhe aquele que corresponde ao teu cenário:

• get_web_search_tool (GA) — predefinição sem configuração; recurso do Bing gerido pela Microsoft. Apenas modelos do Azure OpenAI. Limitado a user_location e search_context_size.
• get_bing_grounding_tool (experimental) — utilize o seu próprio recurso do Azure para Grounding with Bing Search. Suporta count, freshness, market, set_lang, e modelos Foundry não-OpenAI.
• get_bing_custom_search_tool (versão preliminar) — utilize a sua própria instância do Bing Custom Search para restringir a fundamentação a um conjunto selecionado de domínios.

Os três enviam dados de pesquisa fora do limite de conformidade do Azure. Consulte a visão geral do grounding web para a comparação completa.

client = FoundryChatClient(credential=AzureCliCredential())

# Default (GA): minimal configuration
web_search = client.get_web_search_tool(
    user_location={"city": "Amsterdam", "country": "NL"},
    search_context_size="medium",
)

Geração de imagens

get_image_generation_tool configura a ferramenta de geração de imagens alojada do Foundry. O modelo produz conteúdo de imagem na resposta — não há ficheiros extra para gerir.

image_gen = FoundryChatClient.get_image_generation_tool(
    model="gpt-image-1",
    size="1024x1024",
    output_format="png",
    quality="high",
)

Fundamentação no Bing

get_bing_grounding_tool encapsula a ferramenta Grounding with Bing Search Foundry. Crias tu próprio o recurso de pesquisa Grounding with Bing e adicionas-no como ligação ao projeto Foundry, depois passas o ID da ligação.

bing = FoundryChatClient.get_bing_grounding_tool(
    connection_id="/subscriptions/.../connections/my-bing",
    market="en-US",
    freshness="Day",
    count=10,
)

Pesquisa personalizada no Bing

get_bing_custom_search_tool restringe a fundamentação à lista de permissões definida no recurso Bing Custom Search.

bing_custom = FoundryChatClient.get_bing_custom_search_tool(
    connection_id="/subscriptions/.../connections/my-bing-custom",
    instance_name="docs-only",
    market="en-US",
)

Pesquisa de IA do Azure

get_azure_ai_search_tool permite ao agente consultar um índice de Pesquisa de IA do Azure através de uma ligação ao projeto Foundry.

ai_search = FoundryChatClient.get_azure_ai_search_tool(
    index_connection_id="/subscriptions/.../connections/my-search",
    index_name="product-docs",
    query_type="vector_semantic_hybrid",
    top_k=5,
)

SharePoint

get_sharepoint_tool baseia as respostas em conteúdos do SharePoint acessíveis através de uma ligação do Foundry ao SharePoint.

sharepoint = FoundryChatClient.get_sharepoint_tool(
    connection_id="/subscriptions/.../connections/my-sharepoint",
)

Microsoft Fabric

get_fabric_tool liga o agente a um agente de dados Microsoft Fabric através de uma ligação Foundry para que o agente possa responder a perguntas sobre os seus dados Fabric.

fabric = FoundryChatClient.get_fabric_tool(
    connection_id="/subscriptions/.../connections/my-fabric",
)

Pesquisa na memória

get_memory_search_tool permite ao agente pesquisar num arquivo de memória gerido pela Foundry, opcionalmente limitado a um utilizador ou inquilino.

memory = FoundryChatClient.get_memory_search_tool(
    memory_store_name="user-preferences",
    scope="{{$userId}}",
)

Utilização do computador

get_computer_use_tool configura a ferramenta de Pré-visualização do Uso do Computador — o modelo pode controlar um ambiente de trabalho ou navegador emitindo ações de ponteiro e teclado.

computer = FoundryChatClient.get_computer_use_tool(
    environment="browser",
    display_width=1280,
    display_height=800,
)

Automatização do browser

get_browser_automation_tool liga o agente a um recurso do Azure Playwright Testing por meio de uma ligação do Foundry. O agente pode controlar um navegador real utilizando o Playwright.

browser = FoundryChatClient.get_browser_automation_tool(
    connection_id="/subscriptions/.../connections/my-playwright",
)

Agente-para-Agente (A2A)

get_a2a_tool expõe um agente A2A remoto como ferramenta para que um agente da Foundry o possa invocar. Forneça um base_url (e opcionalmente agent_card_path) ou um project_connection_id para uma ligação A2A armazenada.

a2a = FoundryChatClient.get_a2a_tool(
    base_url="https://remote-agent.example.com",
    agent_card_path="/.well-known/agent-card.json",
)

Para as orientações gerais sobre A2A — descoberta, sessões, transmissão — consulte a página do fornecedor Agent-to-Agent.

Criar embeddings com FoundryEmbeddingClient

Use FoundryEmbeddingClient quando quiser embeddings de texto ou imagem a partir de um endpoint de modelos Foundry.

from agent_framework.foundry import FoundryEmbeddingClient

async with FoundryEmbeddingClient() as client:
    result = await client.get_embeddings(["hello from Agent Framework"])
    print(result[0].dimensions)

Ligue-se a um agente de gestão de serviços com FoundryAgent

Utilize FoundryAgent quando a definição de agente estiver na Foundry. Esta é a API Python recomendada para Prompt Agents e HostedAgents.

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    agent_version="1.0",
    credential=AzureCliCredential(),
)

Para um HostedAgent, omita agent_version e usa o nome do agente hospedado em vez disso.

O que funciona e o que não funciona com FoundryAgent

FoundryAgent liga-se a um agente que já existe no Foundry (um Prompt Agent ou um Hosted Agent). A definição do agente — as suas instruções e a configuração da sua ferramenta — está no Foundry, não no seu código Python. Isto significa que várias funcionalidades de nível Agent se comportam de forma diferente de como se comportam com Agent(client=FoundryChatClient(...)) ou outros agentes suportados por clientes de chat.

Tools

Tipo de ferramenta transmitido a FoundryAgent(...)	Comportamento
FunctionTool (um Python local que pode ser chamado)	Suportado, mas apenas se a definição da função de correspondência já existir no agente Foundry. O runtime do Foundry decide que ferramentas expor ao modelo com base na definição do agente. Quando o modelo chama uma função, Foundry devolve uma chamada de ferramenta ao cliente e a framework invoca o seu callable Python local no seu processo (não no Foundry) e, em seguida, envia o resultado de volta. Passar um FunctionTool do lado do cliente limita-se a fornecer essa implementação local — se a função não estiver declarada no agente do Foundry, o modelo nunca a chamará.
Ferramentas alojadas (pesquisa web, interpretador de código, pesquisa de ficheiros, MCP, geração de imagens, etc.)	Ignorado. Estas devem ser configuradas na própria definição do agente Foundry, seja no portal Foundry ou através das APIs de serviço. Passá-los do lado do cliente não tem efeito porque o runtime do Foundry só conhece as ferramentas associadas à definição do agente.

Resumindo: não pode adicionar novas ferramentas no momento da construção. Todas as ferramentas que o modelo pode chamar — incluindo funções de Python locais — devem já fazer parte da definição do agente no Foundry. Passar um FunctionTool para FoundryAgent(...) só fornece a implementação local que corre no seu processo Python quando a função definida pelo Foundry é chamada; não regista uma nova ferramenta com o agente.

Fornecedores de contexto

context_providers=[...] é parcialmente suportado. Se um prestador de contexto funciona depende do que o prestador tenta fazer:

Comportamento do fornecedor de contexto	Funciona com FoundryAgent?
Adiciona contexto extra como mensagens (por exemplo, memória recuperada, excertos RAG, informação do perfil do utilizador)	Yes. O contexto injetado é encaminhado juntamente com o pedido.
Guarda ou observa a conversa (por exemplo, escrevendo as interações num armazenamento externo)	Yes. É executado localmente em torno do ciclo de pedido/resposta.
Adiciona ferramentas dinamicamente (por exemplo, SkillsProvider, ou qualquer provedor que forneça ferramentas a partir de invoking())	Não, a menos que as ferramentas já façam parte da definição de agente da Foundry. O runtime do Foundry executa o modelo contra as ferramentas associadas ao agente no Foundry; Ferramentas que só existem localmente não estão expostas ao modelo e não serão invocadas.

Se precisar de seleção dinâmica de ferramentas, carregamento de competências ou qualquer outro comportamento que dependa da adição de ferramentas em tempo de execução, use Agent(client=FoundryChatClient(...)) em vez disso — esse caminho controla localmente o ciclo do modelo e suporta todo o conjunto de tipos de ferramentas e fornecedores de contexto para adicionar ferramentas.

Opções de execução (opções default_options e agent.run(...))

As opções que passas a FoundryAgent(default_options=...) ou a agent.run(..., **options) (como temperature, top_p, max_tokens, instructions, tool_choice, response_format, metadata, etc.) nem todas são respeitadas. Como a definição do agente na Foundry é a fonte da verdade, muitas opções são silenciosamente ignoradas.

Para Prompt Agents, a estrutura remove explicitamente ou substitui o seguinte antes de enviar o pedido para a API Foundry Responses:

Option	Comportamento com FoundryAgent
model	Ignorado. O modelo é retirado da definição de agente da Foundry.
tools, tool_choice, parallel_tool_calls	Removido do corpo do pedido. As ferramentas devem ser declaradas na definição de agente Foundry (ver a secção anterior). FunctionTool as funções invocáveis continuam configuradas localmente para invocar funções, mas a própria lista de ferramentas não é enviada ao serviço.
instructions e mensagens do sistema/programador	Ignorado. As instruções do próprio agente da Foundry são autoritárias. As mensagens do sistema/programador são removidas da lista de mensagens antes do pedido ser enviado.
conversation_id	Usado e mapeado para a sessão do agente Foundry quando se refere a um.
extra_body	Encaminhado, fundido com a carga útil definida pelo framework agent_reference.
Parâmetros de amostragem (temperature, top_p, max_tokens, seed, frequency_penalty, presence_penalty, stop, …), metadata, user, store, response_format, etc.	Encaminhado para a API de Respostas. Se o Foundry os aplica realmente depende da configuração do agente e do modelo — a definição do agente pode sobrepô-los ou restringi-los — por isso não confie que tenham efeito para um Prompt Agent.

No caso dos Agentes Hospedados, aplica-se a mesma remoção no lado do cliente, mas tudo o que vai além disso depende do que cada agente hospedado específico implementa. Um agente alojado pode aceitar, ignorar ou reinterpretar qualquer opção que seja encaminhada. Trate as opções de tempo de execução como meramente indicativas e verifique o comportamento real comparando-o com o agente alojado que está a invocar.

Ligação a um agente Foundry destacado (alojado)

Para HostedAgents que executam sessões no lado do serviço (/agents/{name}/sessions), use FoundryAgent com allow_preview=True para aderir à interface de Respostas em pré-visualização:

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    agent_name="my-hosted-agent",
    credential=AzureCliCredential(),
    allow_preview=True,
)

Quando precisar de gerir a sessão de serviço subjacente — por exemplo, para vincular uma sessão a um inquilino ou utilizador específico — crie a sessão através da API de pré-visualização AIProjectClient e envolva-a com agent.get_session(...):

from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import VersionRefIndicator

service_session = await project_client.beta.agents.create_session(
    agent_name="my-hosted-agent",
    isolation_key="user-123",
    version_indicator=VersionRefIndicator(agent_version="1.0"),
)
session = agent.get_session(service_session.agent_session_id)

response = await agent.run("Hello!", session=session)

Usando o agente

Tanto FoundryChatClient como FoundryAgent integram-se com a experiência padrão Python Agent, incluindo chamadas de ferramentas, sessões e respostas em streaming. Para tempos de execução locais, utilize a página separada do fornecedor local da Foundry.

Caixas de Ferramentas

Uma caixa de ferramentas Foundry é um conjunto nomeado e versionado do lado do servidor de configurações de ferramentas alojadas (interpretador de código, pesquisa de ficheiros, geração de imagens, MCP, pesquisa web) configuradas num projeto Microsoft Foundry. As caixas de ferramentas permitem-te gerir a configuração das ferramentas uma vez no portal da Foundry e reutilizá-las entre agentes.

O Agent Framework cobre apenas o consumo — a criação e atualização das versões da toolbox é realizada através do portal Foundry ou do SDK nativo azure-ai-projects (azure-ai-projects>=2.1.0).

FoundryAgent vs FoundryChatClient

Tipo de agente	Comportamento da caixa de ferramentas
FoundryAgent (hospedado)	A ligação da caixa de ferramentas acontece no servidor. Não é necessário cablagem do lado do cliente.
FoundryChatClient (inferência direta)	Vai buscar a caixa de ferramentas com get_toolbox() e passa-a como tools=.

Dois padrões de consumo

Pattern	Descrição
Nativas (ferramentas hospedadas)	As configurações de ferramentas são executadas no runtime do Foundry. Passa a caixa de ferramentas diretamente como tools=.
MCP	Usar MCPStreamableHTTPTool para o endpoint MCP da toolbox. Funciona com qualquer cliente de chat, não só FoundryChatClient.

Buscar uma caixa de ferramentas

Usar FoundryChatClient.get_toolbox() para recuperar uma caixa de ferramentas:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential

async with AzureCliCredential() as credential:
    client = FoundryChatClient(credential=credential)
    toolbox = await client.get_toolbox("research_toolbox")

    async with Agent(client=client, name="ResearchAgent", tools=toolbox) as agent:
        result = await agent.run("Summarize recent findings.")
        print(result.text)

Quando version é omitido, get_toolbox resolve a versão padrão em dois pedidos. Prenda uma versão específica para evitar a viagem extra de ida e volta:

toolbox = await client.get_toolbox("research_toolbox", version="v3")

Achatamento implícito

Não precisa de escrever toolbox.tools. O normalize_tools sistema reconhece ToolboxVersionObject e achata automaticamente. Todos estes funcionam:

# Single toolbox
agent = Agent(client=client, tools=toolbox)

# Toolbox in a list
agent = Agent(client=client, tools=[toolbox])

# Mix local function tools with a toolbox
agent = Agent(client=client, tools=[get_internal_metrics, toolbox])

# Combine multiple toolboxes
agent = Agent(client=client, tools=[toolbox_a, toolbox_b])

Ferramentas de filtragem com select_toolbox_tools

Se a sua caixa de ferramentas incluir várias ferramentas mas um agente só precisar de um subconjunto, use select_toolbox_tools para restringir o conjunto depois de buscar. Isto evita enviar definições desnecessárias de ferramentas para o modelo, o que reduz o uso de tokens e impede que o modelo invoque ferramentas que não pretende expor:

from agent_framework.foundry import select_toolbox_tools, get_toolbox_tool_name

# Filter by tool name
tools = select_toolbox_tools(toolbox, include_names=["web_search", "code_interpreter"])

# Filter by tool type
tools = select_toolbox_tools(toolbox, include_types=["mcp", "web_search"])

# Filter with a custom predicate
tools = select_toolbox_tools(toolbox, predicate=lambda t: "search" in (get_toolbox_tool_name(t) or ""))

As funções auxiliares get_toolbox_tool_name(tool) e get_toolbox_tool_type(tool) devolvem, respetivamente, o nome da seleção e o tipo bruto de uma entrada de ferramenta. FoundryHostedToolType é um TypeAlias (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str) para auto-completação guiada por IDE em include_types / exclude_types.

Caminho de consumo de MCP

Também pode consumir uma caixa de ferramentas como servidor MCP ao apontar MCPStreamableHTTPTool para o URL do endpoint MCP da caixa de ferramentas.

A URL do endpoint MCP é mostrada no Portal da Foundry ou segue o formato:

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

Como o cliente conecta-se diretamente ao endpoint da caixa de ferramentas Foundry, deve autenticar-se com um token portador do Entra ID através de header_provider.

from azure.identity.aio import DefaultAzureCredential
from azure.identity.aio import get_bearer_token_provider
from agent_framework import Agent, MCPStreamableHTTPTool

credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")

mcp_tool = MCPStreamableHTTPTool(
    name="research_mcp",
    url="https://<your-toolbox-mcp-endpoint>",
    header_provider=lambda: {"Authorization": f"Bearer {token_provider()}"},
)

async with Agent(client=client, name="MCPAgent", tools=[mcp_tool]) as agent:
    result = await agent.run("Search for recent papers on LLM agents.")
    print(result.text)

Limitações

• As ferramentas MCP dentro de uma caixa de ferramentas usam autenticação do lado do servidor. A autenticação no servidor MCP a montante é gerida através de project_connection_id (uma ligação OAuth configurada no projeto Foundry). O cliente nunca detém bearer tokens para o upstream server.
• Consumir um conjunto de ferramentas como um servidor MCP requer autenticação no lado do cliente. Quando aponta MCPStreamableHTTPTool para o endpoint MCP de uma toolbox, deve fornecer um token portador do Entra ID (por exemplo, via get_bearer_token_provider(credential, "https://ai.azure.com/.default")) através de header_provider.
• A gestão do fluxo de consentimento é uma preocupação em tempo de execução. Se uma ferramenta MCP da caixa de ferramentas for CONSENT_REQUIRED ativada durante agent.run(), é tratada em tempo de execução, não durante a busca da caixa de ferramentas.

Samples

Sample	Descrição
foundry_chat_client_with_toolbox.py	Busca básica da caixa de ferramentas, fixação de versões, combinação de caixas de ferramentas e filtragem
foundry_chat_client_with_toolbox_mcp.py	Caminho de consumo MCP com MCPStreamableHTTPTool
foundry_toolbox_context_provider.py	Seleção dinâmica de ferramentas por iteração através de um provedor de contexto