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:

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.

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

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

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.

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.

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

Para HostedAgents que executam sessões do lado servidor (/agents/{name}/sessions), use FoundryAgent com allow_preview=True para usar a superfície de respostas do preview e passar version="v2":

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

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

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

Dois padrões de consumo

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