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 agente

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

Tipo	Tipo produzido	Descrição	Usar quando
Agente de Respostas	ChatClientAgent	Seu aplicativo fornece programaticamente um modelo, instruções e ferramentas em runtime por meio de AIProjectClient.AsAIAgent(...). Nenhum recurso de agente do lado do servidor é criado.	Você é o proprietário da definição do agente e deseja uma configuração simples e flexível. Esse é o padrão usado na maioria dos exemplos.
Foundry Agent (versionado)	FoundryAgent	Gerenciado pelo servidor — as definições de agente são criadas e atualizadas por meio do portal do Foundry ou programaticamente via AIProjectClient.AgentAdministrationClient. Passar um ProjectsAgentVersion ou ProjectsAgentRecord para AgentReferenceAIProjectClient.AsAIAgent(...).	Você precisa de definições de agente estritas e com controle de versão gerenciadas no portal do Foundry por meio de APIs de serviço

Agente de Respostas (inferência direta)

Use AsAIAgent diretamente no AIProjectClient com um modelo e instruções. Esse é 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 é baseado em código e não cria um recurso de agente gerenciado pelo servidor.

Foundry Agent (versionado)

Use as APIs nativas AIProjectClient.AgentAdministrationClient do SDK de Projetos de IA para recuperar recursos de agente com versão e embrulhá-los com AsAIAgent. Os agentes podem ser criados e configurados diretamente no portal do Foundry ou programaticamente por meio 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

Ambos ChatClientAgent (Responses) e FoundryAgent (versioned) são instâncias padrão e oferecem AIAgent suporte a 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 obter mais informações sobre como executar e interagir com agentes, consulte os tutoriais de introdução do Agente.

Tools

Os agentes do Foundry criados com AIProjectClient.AsAIAgent(...) (o caminho Responses) oferecem suporte ao conjunto padrão de ferramentas do Agent Framework — confira a visão geral das ferramentas para ver a lista completa e a matriz completa de recursos compatíveis. Para agentes do Foundry carregados a partir de uma definição versionada de agente (FoundryAgent), as ferramentas do agente pertencem à definição de agente do Foundry, não ao cliente.

Tool	Observações
Ferramentas de Funções	Supported.
Aprovação da ferramenta	Supported. Fornecido pelo cliente de chat com invocação de função do framework.
Interpretador de Código	Supported.
Pesquisa de Arquivo	Supported.
Ferramentas MCP hospedadas	Supported.
Ferramentas MCP locais	Supported.
Caixas de ferramentas do Foundry	Supported.

Caixas de Ferramentas

Fundição no Python

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

• agent-framework-foundryfornece os conectores do Cloud Foundry: FoundryChatClient, , FoundryAgente FoundryEmbeddingClientFoundryMemoryProvider.
• agent-framework-foundry-local fornece FoundryLocalClient para a execução do modelo local.

Padrões de agente e chat de fundição em Python

Scenario	Python formato	Usar quando
Inferência simples com o endpoint Foundry Responses	Agent(client=FoundryChatClient(...))	Seu aplicativo possui a definição do agente, as ferramentas e o loop de conversa, e você deseja um modelo implantado em um projeto do Foundry.
Agentes gerenciados pelo serviço no Serviço de Agentes da Foundry	FoundryAgent(...)	Você deseja se conectar a um PromptAgent ou HostedAgent criado e configurado no portal do Foundry ou por meio das APIs de serviço.

Installation

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

O mesmo agent-framework-foundry pacote também inclui FoundryEmbeddingClient para inserções de ponto de extremidade de modelos do 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"

Use FOUNDRY_AGENT_VERSION para agentes de prompt. Os agentes hospedados podem omitê-lo.

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 use o ponto de extremidade do projeto. FoundryEmbeddingClient usa o ponto de extremidade de modelos separados.

Escolha o cliente de Python certo

Scenario	Cliente preferencial	Observações
Recurso do Azure OpenAI	OpenAIChatCompletionClient / OpenAIChatClient	Use a página do provedor OpenAI.
Inferência do projeto Microsoft Foundry	Agent(client=FoundryChatClient(...))	Usa o endpoint de Respostas do Foundry.
Agente gerenciado pelo serviço Microsoft Foundry	FoundryAgent	É recomendado para Agentes de Prompt e Agentes Hospedados.
Microsoft inserções de ponto de extremidade de modelos do Foundry	FoundryEmbeddingClient	Usa FOUNDRY_MODELS_ENDPOINT mais FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Runtime local do Foundry	Agent(client=FoundryLocalClient(...))	Consulte Foundry Local.

Criar um agente com FoundryChatClient

FoundryChatClient conecta-se a um modelo implantado em um projeto Foundry e usa o endpoint Respostas. Emparelhe-o com um padrão Agent quando seu aplicativo deve possuir instruções, ferramentas e gerenciamento de sessão.

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 caminho de Python da Foundry para inferência direta e dá suporte a ferramentas, saídas estruturadas e streaming.

Tools

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

As fábricas são métodos de classe, portanto você não precisa 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 a seguir lista todas as ferramentas que o Python FoundryChatClient expõe hoje. FoundryAgent funciona com as mesmas ferramentas, mas elas devem ser configuradas na definição do agente do Foundry em vez de serem passadas no código.

Tool	Fábrica em FoundryChatClient	Status	Detalhes
Ferramentas de Funções	n/a — passe qualquer chamável Python ou @ai_function	GA	Invocado localmente em seu processo de Python.
Aprovação da ferramenta	n/a — encapsula as ferramentas existentes	GA	Funciona com MCP hospedado e ferramentas de funções.
Interpretador de Código	get_code_interpreter_tool	GA	Execução de código em área restrita na Foundry.
Pesquisa de Arquivo	get_file_search_tool	GA	Pesquise arquivos carregados por meio de repositórios de vetores do Foundry.
Pesquisa na Web	get_web_search_tool	GA	Aterramento na Web com suporte do Bing gerenciado por Microsoft. Somente modelos do Azure OpenAI.
Geração de Imagem	get_image_generation_tool	GA	Geração de imagem hospedada no Foundry.
MCP hospedado	get_mcp_tool	GA	Servidor MCP remoto invocado pelo Foundry.
Local MCP	n/a — use MCPStreamableHTTPTool / MCPStdioTool	GA	É executado no seu processo; funciona com qualquer cliente.
Caixas de ferramentas do Foundry	MCPStreamableHTTPTool para o ponto de extremidade MCP da caixa de ferramentas	GA	Consumido por MCP de FoundryChatClient; anexado no lado do servidor em FoundryAgent.
Aterramento do Bing	get_bing_grounding_tool	Experimental	Traga seu próprio grounding com o recurso do Bing Search.
Pesquisa Personalizada do Bing	get_bing_custom_search_tool	Preview	Fundamentação do Bing restrita a uma lista selecionada de domínios.
Pesquisa de IA do Azure	get_azure_ai_search_tool	Experimental	Pesquise em um índice do Pesquisa de IA do Azure  usando uma conexão do Foundry.
SharePoint	get_sharepoint_tool	Preview	Respostas básicas no conteú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 um repositório de memória gerenciado pela Foundry.
Uso de Computadores	get_computer_use_tool	Preview	Permitir que o agente conduza um ambiente de desktop ou navegador.
Automação do navegador	get_browser_automation_tool	Preview	Controle um navegador usando uma conexão do Azure Playwright.
Agente para Agente (A2A)	get_a2a_tool	Preview	Chame outro agente A2A para usá-lo como ferramenta.

Variantes de pesquisa na Web

A Foundry expõe três opções de aterramento com suporte do Bing. Escolha aquele que corresponda ao seu cenário:

• get_web_search_tool (GA) — padrão sem configuração; recurso do Bing gerenciado pela Microsoft. Somente modelos do Azure OpenAI. Limitado a user_location e search_context_size.
• get_bing_grounding_tool (experimental) – traga seu próprio recurso de aterramento com a pesquisa do Bing Azure. Compatível com count, freshness, market, set_lang e modelos Foundry não OpenAI.
• get_bing_custom_search_tool (versão prévia) — use sua própria instância do Bing Custom Search para restringir a fundamentação a um conjunto selecionado de domínios.

Todos os três enviam dados de pesquisa fora do limite de conformidade Azure. Confira a visão geral do embasamento na Web para ver 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 imagem

get_image_generation_tool configura a ferramenta de geração de imagem hospedada do Foundry. O modelo produz conteúdo de imagem na resposta – não há arquivos extras para gerenciar.

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

Aterramento do Bing

get_bing_grounding_tool envolve a ferramenta Grounding with Bing Search Foundry. Crie você mesmo o recurso Grounding with Bing Search e adicione-o como uma conexão do projeto do Foundry; em seguida, forneça o ID da conexão.

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

Pesquisa personalizada do Bing

get_bing_custom_search_tool restringe a fundamentação à lista de permissões definida em um recurso de Pesquisa Personalizada do Bing.

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 que o agente consulte um índice de Pesquisa de IA do Azure  por meio de uma conexão de projeto do 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údo do SharePoint acessível por meio de uma conexão do Foundry com o SharePoint.

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

Microsoft Fabric

get_fabric_tool conecta o agente a um agente de dados do Microsoft Fabric por meio de uma conexão Foundry para que o agente possa responder a perguntas sobre seus dados do Fabric.

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

Pesquisa de memória

get_memory_search_tool permite que o agente pesquise um repositório de memória gerenciado pelo Foundry, opcionalmente com escopo para um usuário ou locatário.

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

Uso do computador

get_computer_use_tool configura a ferramenta de pré-visualização do Computer Use — o modelo pode controlar um ambiente de desktop ou navegador por meio de ações de ponteiro e teclado.

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

Automação de navegador

get_browser_automation_tool conecta o agente a um recurso do Azure Playwright Testing via uma conexão do Foundry. O agente pode controlar um navegador real por meio do 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 uma ferramenta para que um agente do Foundry possa chamá-lo. Forneça uma base_url (e, opcionalmente, agent_card_path) ou um project_connection_id para uma conexão A2A armazenada.

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

Para orientações gerais sobre A2A — descoberta, sessões, streaming — consulte a página do provedor Agent-to-Agent.

Criar inserções com FoundryEmbeddingClient

Use FoundryEmbeddingClient quando quiser incorporar textos ou imagens 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)

Conectar-se a um agente gerenciado pelo serviço com FoundryAgent

Use FoundryAgent quando a definição do agente reside na Foundry. Essa é a API recomendada de Python para Agentes de Prompt e Agentes Hospedados.

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 use o nome do agente hospedado.

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

FoundryAgent conecta-se a um agente que já existe na Foundry (um Agente de Prompt ou um Agente Hospedado). A definição do agente — suas instruções e sua configuração de ferramenta — reside na Foundry, não no código Python. Isso significa que vários recursos de nível Agent se comportam de maneira diferente de como se comportam com Agent(client=FoundryChatClient(...)) ou com outros agentes baseados em cliente de chat.

Tools

Tipo de ferramenta passado para FoundryAgent(...)	Behavior
FunctionTool (um chamável local em Python)	Compatível, mas apenas se a definição de função correspondente já existir no agente Foundry. O runtime do Foundry decide quais ferramentas expor ao modelo com base na definição do agente. Quando o modelo chama uma função, o Foundry retorna uma chamada de ferramenta ao cliente e o framework invoca seu callable Python local no seu processo (não no Foundry) e, em seguida, envia o resultado de volta. Passar um FunctionTool no lado do cliente só disponibiliza essa implementação local — se a função não for declarada no agente Foundry, o modelo nunca a chamará.
Ferramentas hospedadas (pesquisa na Web, interpretador de código, pesquisa de arquivos, MCP, geração de imagem etc.)	Ignorado. Elas devem ser configuradas na própria definição do agente do Foundry, no portal do Foundry ou por meio das APIs de serviço. Passá-los do lado do cliente não tem efeito porque o runtime do Foundry só sabe sobre as ferramentas anexadas à definição do agente.

Resumindo: não é possível adicionar novas ferramentas em tempo de construção. Todas as ferramentas que o modelo pode chamar , incluindo funções de Python locais, já devem fazer parte da definição do agente na Foundry. Passar um FunctionTool para FoundryAgent(...) fornece apenas a implementação local que é executada em seu processo de Python quando a função definida pela Foundry é chamada; ela não registra uma nova ferramenta com o agente.

Provedores de contexto

context_providers=[...] é parcialmente compatível. Se um provedor de contexto funciona depende do que o provedor tenta fazer:

Comportamento do provedor de contexto	Funciona com FoundryAgent?
Adiciona contexto extra como mensagens (por exemplo, memória recuperada, snippets de RAG, informações de perfil do usuário)	Sim. O contexto injetado é encaminhado com a solicitação.
Persiste ou observa a conversa (por exemplo, gravando os turnos em um armazenamento externo)	Sim. É executado localmente em torno da solicitação/resposta.
Adiciona ferramentas dinamicamente (por exemplo, SkillsProviderou qualquer provedor que retorna ferramentas de invoking())	Não, a menos que as ferramentas já façam parte da definição do agente do Foundry. O runtime do Foundry executa o modelo nas ferramentas anexadas ao agente na Foundry; as ferramentas que existem apenas localmente não são expostas ao modelo e não serão invocadas.

Se você precisar de seleção dinâmica de ferramentas, carregamento de habilidades 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 gerencia localmente o loop do modelo e oferece suporte ao conjunto completo de tipos de ferramentas e aos provedores de contexto para adição de ferramentas.

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

As opções que você passa para FoundryAgent(default_options=...) ou para 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, o framework remove explicitamente ou substitui o seguinte antes de enviar a requisição para a API Foundry Responses:

Option	Comportamento com FoundryAgent
model	Ignorado. O modelo é extraído da definição do agente Foundry.
tools, tool_choice, parallel_tool_calls	Removido do corpo da solicitação. As ferramentas devem ser declaradas na definição de agente do Foundry (consulte a seção anterior). FunctionTool os callables ainda estão configurados localmente para invocar funções, mas a própria lista de ferramentas não é enviada ao serviço.
instructions e mensagens de sistema/desenvolvedor	Ignorado. As instruções do próprio agente Foundry têm autoridade. As mensagens do sistema/desenvolvedor são removidas da lista de mensagens antes que a solicitação seja enviada.
conversation_id	Usado e mapeado para a sessão do agente do Foundry quando se refere a uma.
extra_body	Encaminhado, mesclado 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. O fato de o Foundry realmente aplicá-las depende da configuração do agente e do modelo — a definição do agente pode sobrescrevê-las ou restringi-las — portanto, não presuma que elas serão aplicadas no caso de um Prompt Agent.

Para agentes hospedados, a mesma remoção do lado do cliente se aplica, mas tudo além disso depende do que o agente hospedado específico implementa. Um agente hospedado pode aceitar, ignorar ou reinterpretar qualquer opção encaminhada. Trate as opções de tempo de execução apenas como orientação e verifique o comportamento real comparando-o com o agente hospedado que você está chamando.

Conectando-se a um agente de fundimento implantado (hospedado)

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

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

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

Quando você precisar gerenciar a sessão de serviço subjacente por conta própria , por exemplo, para associar uma sessão a um locatário ou usuário específico, crie a sessão por meio da API de visualização AIProjectClient e embrulhe-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 quanto FoundryAgent integram-se à experiência padrão Python Agent, incluindo chamadas de ferramentas, sessões e respostas de streaming. Para runtimes locais, use a página separada do provedor Local do Foundry.

Caixas de Ferramentas

Uma caixa de ferramentas Foundry é um pacote de ferramentas hospedadas no lado do servidor nomeado e com versão (interpretador de código, pesquisa de arquivos, geração de imagem, MCP, pesquisa na Web) configurado em um projeto do Microsoft Foundry. As caixas de ferramentas permitem gerenciar a configuração da ferramenta uma vez no portal do Foundry e reutilizá-la entre agentes.

O Agent Framework abrange somente o consumo – a criação e atualização de versões da caixa de ferramentas é feita por meio do portal do Foundry ou do SDK bruto azure-ai-projects (azure-ai-projects>=2.1.0).

FoundryAgent vs FoundryChatClient

Tipo de agente	Comportamento da caixa de ferramentas
FoundryAgent (hospedado)	A fixação da caixa de ferramentas ocorre no lado do servidor. Nenhuma fiação do lado do cliente é necessária.
FoundryChatClient (inferência direta)	Buscar a caixa de ferramentas com get_toolbox() e passá-la como tools=.

Dois padrões de consumo

Pattern	Descrição
Nativo (ferramentas hospedadas)	As configurações de ferramenta são executadas no runtime do Foundry. Passe a caixa de ferramentas diretamente como tools=.
PCM	Use MCPStreamableHTTPTool no ponto de extremidade MCP da caixa de ferramentas. Funciona com qualquer cliente de chat, não apenas FoundryChatClient.

Buscando uma caixa de ferramentas

Use 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 duas solicitações. Fixe uma versão específica para evitar a viagem de ida e volta extra:

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

Nivelamento implícito

Você não precisa escrever toolbox.tools. A estrutura normalize_tools reconhece ToolboxVersionObject e nivela automaticamente. Todos esses trabalhos:

# 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 caixa de ferramentas agrupar várias ferramentas, mas um agente precisar apenas de um subconjunto, use select_toolbox_tools para restringir o conjunto após a busca. Isso evita o envio de definições de ferramentas desnecessárias para o modelo, o que reduz o uso de tokens e impede que o modelo invoca ferramentas que você 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 ""))

Funções auxiliares get_toolbox_tool_name(tool) e get_toolbox_tool_type(tool) retornam o nome da seleção e o tipo cru de uma entrada de ferramenta, respectivamente. FoundryHostedToolType é um TypeAlias (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str) para conclusão guiada por IDE em include_types / exclude_types.

Caminho de consumo do MCP

Você também pode consumir uma caixa de ferramentas como um servidor MCP, apontando para a URL do endpoint MCP da caixa de ferramentas com MCPStreamableHTTPTool.

A URL do ponto de extremidade MCP é mostrada no Portal Foundry ou segue o formato:

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

Como o cliente se conecta diretamente ao ponto de extremidade da caixa de ferramentas do Foundry, você deve autenticar com um token de acesso do Entra ID por meio 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 a autenticação do lado do servidor. A autenticação com o servidor MCP upstream é realizada via project_connection_id (uma conexão OAuth configurada no projeto Foundry). O cliente nunca contém tokens de portador para o servidor upstream.
• Consumir um conjunto de ferramentas como um servidor MCP requer autenticação do lado do cliente. Quando você aponta MCPStreamableHTTPTool para o ponto de extremidade MCP de uma caixa de ferramentas, você deve fornecer um token de portador da ID da Entra (por exemplo, via get_bearer_token_provider(credential, "https://ai.azure.com/.default")) por meio de header_provider.
• O tratamento de fluxo de consentimento é uma preocupação de tempo de execução. Se uma ferramenta MCP da caixa de ferramentas CONSENT_REQUIRED for ativada durante agent.run(), ela é tratada em tempo de execução, não durante o carregamento da caixa de ferramentas.

Exemplos

Sample	Descrição
foundry_chat_client_with_toolbox.py	Busca básica de caixa de ferramentas, fixação de versão, combinação de caixas de ferramentas e filtragem
foundry_chat_client_with_toolbox_mcp.py	Caminho de consumo do MCP com MCPStreamableHTTPTool
foundry_toolbox_context_provider.py	Seleção de ferramenta dinâmica por turno por meio de um provedor de contexto