Compartilhar via

Microsoft Foundry

Microsoft Agent Framework oferece suporte tanto à inferência direta de modelos a partir dos endpoints de projetos do Microsoft Foundry quanto aos agentes geridos pelo serviço no Foundry Agent Service.

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."));

Aviso

DefaultAzureCredential é conveniente para o desenvolvimento, mas requer uma consideração cuidadosa na produção. Em produção, considere o uso de uma credencial específica (por exemplo, ManagedIdentityCredential) para evitar problemas de latência, investigação de credenciais não intencionais e possíveis riscos de segurança de mecanismos de fallback.

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."));

Importante

As ferramentas e instruções do Foundry Agents são restritas às que foram criadas com elas, e não há suporte para a tentativa de modificar ferramentas ou instruções no tempo de execução.

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.

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.

Importante

Esta página aborda os clientes Python atuais para pontos de extremidade de projeto do Microsoft Foundry, pontos de extremidade de modelos e o Serviço do Agente Foundry. Se você tiver um endpoint de recurso autônomo do Azure OpenAI (), use as diretrizes de Python na página do provedor OpenAI . Se você quiser executar modelos com suporte localmente, consulte a página do provedor Local do Foundry.

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.

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.

Aviso

Os antigos ambientes de compatibilidade de inserção do Python AzureAIClient, AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider e Azure AI foram removidos do namespace agent_framework.azure atual. Para o código de Python atual, use FoundryChatClient quando seu aplicativo possui instruções e ferramentas, FoundryAgent quando a definição do agente reside na Foundry e FoundryEmbeddingClient para embeddings de endpoint de modelos do Foundry.

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.

Próximas Etapas 

Fábrica Local

  • Last updated on