Partilhar via

Microsoft Foundry

Microsoft Agent Framework suporta tanto a inferência direta de modelos do projeto Microsoft Foundry a partir dos endpoints, como de agentes geridos por 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 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."));

Advertência

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

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

Importante

As ferramentas e instruções dos Foundry Agents devem ser usadas estritamente com as versões para as quais foram criadas; não são suportadas tentativas de modificar ferramentas ou instruções em tempo de execução.

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.

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.

Importante

Esta página cobre os clientes Python atuais para os endpoints do projeto Microsoft Foundry, endpoints de modelos e o Foundry Agent Service. Se tiver um endpoint de recursos Azure OpenAI autónomo (https://<your-resource>.openai.azure.com), utilize as orientações Python na página do fornecedor OpenAI. Se quiser executar modelos suportados localmente, consulte a página do fornecedor local da Foundry.

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.

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.

Advertência

As superfícies de compatibilidade Python AzureAIClient, AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider e de embedding de IA do Azure mais antigas foram removidas do atual espaço de nomes agent_framework.azure. Para código Python atual, use FoundryChatClient quando a sua aplicação possui instruções e ferramentas, FoundryAgent quando a definição do agente está no Foundry, e FoundryEmbeddingClient para embeddings de modelos e endpoints do Foundry.

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.

Passos seguintes

Fundição Local

  • Last updated on