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:

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.

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

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

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.

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.

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

Para HostedAgents que executam sessões do lado do serviço (/agents/{name}/sessions), use FoundryAgent com allow_preview=True para optar pela superfície de Respostas de pré-visualização 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 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

Dois padrões de consumo

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