tipos de agente do Microsoft Agent Framework

Todos os agentes são derivados de uma classe base comum, AIAgentque fornece uma interface consistente para todos os tipos de agente. Isso permite a criação de funcionalidades comuns, independentes do agente e de nível superior, como orquestrações de vários agentes.

Todos os agentes são derivados de uma classe base comum, Agentque fornece uma interface consistente para todos os tipos de agente. Isso permite a criação de funcionalidades comuns, independentes do agente e de nível superior, como orquestrações de vários agentes.

Agentes simples com base em serviços de inferência

O Agent Framework facilita a criação de agentes simples com base em muitos serviços de inferência diferentes. Qualquer serviço de inferência que forneça uma implementação Microsoft.Extensions.AI.IChatClient pode ser usado para criar esses agentes. O Microsoft.Agents.AI.ChatClientAgent é a classe de agente usada para fornecer um agente para qualquer implementação IChatClient.

Esses agentes dão suporte a uma ampla gama de funcionalidades prontas para uso:

1. Chamada de função.
2. Conversas de vários turnos com gerenciamento de histórico de chat local ou gerenciamento de histórico de chat fornecido pelo serviço.
3. Ferramentas personalizadas fornecidas pelo serviço (por exemplo, MCP, Execução de Código).
4. Saída estruturada.

Para criar um desses agentes, basta construir um ChatClientAgent usando a IChatClient implementação de sua escolha.

using Microsoft.Agents.AI;

var agent = new ChatClientAgent(chatClient, instructions: "You are a helpful assistant");

Para facilitar ainda mais a criação desses agentes, o Agent Framework fornece auxiliares para muitos serviços populares. Para obter mais informações, consulte a documentação de cada serviço.

Agentes personalizados complexos

Também é possível criar agentes totalmente personalizados que não são apenas envoltórios em torno de um IChatClient. A estrutura do agente fornece o AIAgent tipo base. Esse tipo base é a abstração principal para todos os agentes, que, quando subclassificado, permite controle completo sobre o comportamento e as capacidades do agente.

Para obter mais informações, consulte a documentação dos Agentes Personalizados.

Proxies para agentes remotos

O Agent Framework fornece implementações prontas AIAgent para protocolos comuns de agente hospedado do serviço, como a A2A. Dessa forma, você pode se conectar facilmente e usar agentes remotos de seu aplicativo.

Consulte a documentação de cada tipo de agente para obter mais informações:

Referência de opções do SDK do Azure e do OpenAI

Ao usar o Foundry, Azure OpenAI, serviços OpenAI ou serviços antropáticos, você tem várias opções de SDK para se conectar a esses serviços. Em alguns casos, é possível usar vários SDKs para se conectar ao mesmo serviço ou usar o mesmo SDK para se conectar a serviços diferentes. Aqui está uma lista das diferentes opções disponíveis com a URL que você deve usar ao se conectar a cada uma delas. Certifique-se de substituir <resource> e <project> por seus nomes de projeto e recursos reais.

1. Atualizando do Azure OpenAI para o Foundry
2. É recomendável usar o SDK do OpenAI.
3. Embora seja recomendável usar o SDK do OpenAI para acessar modelos do Foundry, o Foundry Models dá suporte a modelos de muitos fornecedores diferentes, não apenas ao OpenAI. Todos esses modelos têm suporte por meio do SDK do OpenAI.

Usando o SDK do OpenAI

Conforme mostrado na tabela acima, o SDK do OpenAI pode ser usado para se conectar a vários serviços. Dependendo do serviço ao qual você está se conectando, talvez seja necessário definir uma URL personalizada ao criar o OpenAIClient. Você também pode usar mecanismos de autenticação diferentes dependendo do serviço.

Se uma URL personalizada for necessária (consulte a tabela acima), você poderá defini-la por meio do OpenAIClientOptions.

var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri(serviceUrl) };

É possível usar uma chave de API ao criar o cliente.

OpenAIClient client = new OpenAIClient(new ApiKeyCredential(apiKey), clientOptions);

Ao usar um serviço de Azure, também é possível usar credenciais Azure em vez de uma chave de API.

OpenAIClient client = new OpenAIClient(new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"), clientOptions)

Depois de criar o OpenAIClient, você pode obter um subcliente para o serviço específico que deseja usar e, em seguida, criar um AIAgent a partir dele.

AIAgent agent = client
    .AsAIAgent(model: model, instructions: "You are good at telling jokes.", name: "Joker");

Usando o SDK de projetos de IA do Azure

Esse SDK pode ser usado para se conectar aos serviços do Foundry. Você precisará fornecer a URL correta do ponto de extremidade do projeto ao criar a AIProjectClient. Consulte a tabela acima para obter a URL correta a ser usada.

AIAgent agent = new AIProjectClient(
    new Uri(serviceUrl),
    new DefaultAzureCredential())
     .AsAIAgent(
         model: deploymentName,
         instructions: "You are good at telling jokes.",
         name: "Joker");

Usando o SDK de projetos de IA Azure com o Foundry Agents

Esse SDK é usado para agentes baseados em API de Respostas e agentes Foundry versionados. Consulte a tabela acima para obter a URL correta a ser usada.

var aiProjectClient = new AIProjectClient(new Uri(serviceUrl), new DefaultAzureCredential());
AIAgent agent = aiProjectClient.AsAIAgent(
    model: deploymentName,
    instructions: "You are good at telling jokes.",
    name: "Joker");

Usando o SDK Foundry Anthropic

O recurso é o nome do subdomínio/nome que vem antes de '.services.ai.azure.com' no URI do endpoint.

Por exemplo: https://(resource name).services.ai.azure.com/anthropic/v1/chat/completions

var client = new AnthropicFoundryClient(new AnthropicFoundryApiKeyCredentials(apiKey, resource));
AIAgent agent = client.AsAIAgent(
    model: deploymentName,
    instructions: "Joker",
    name: "You are good at telling jokes.");

Usando o SDK Anthropic

var client = new AnthropicClient() { ApiKey = apiKey };
AIAgent agent = client.AsAIAgent(
    model: deploymentName,
    instructions: "Joker",
    name: "You are good at telling jokes.");

Agentes simples com base em serviços de inferência

O Agent Framework facilita a criação de agentes simples com base em muitos serviços de inferência diferentes. Qualquer serviço de inferência que forneça uma implementação de cliente de chat pode ser usado para criar esses agentes. Isso pode ser feito usando o SupportsChatGetResponse protocolo, que define um padrão para os métodos que um cliente precisa dar suporte para serem usados com a classe padrão Agent .

Esses agentes dão suporte a uma ampla gama de funcionalidades prontas para uso:

1. Chamada de função
2. Conversas de vários turnos com gerenciamento de histórico de chat local ou gerenciamento de histórico de chat fornecido pelo serviço
3. Ferramentas personalizadas fornecidas pelo serviço (por exemplo, MCP, Execução de Código)
4. Saída estruturada
5. Respostas em streaming

Para criar um desses agentes, basta construir um cliente de chat com a implementação de sua escolha.

import os
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import DefaultAzureCredential

agent = Agent(
    client=FoundryChatClient(
        credential=DefaultAzureCredential(),
        project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
        model=os.getenv("FOUNDRY_MODEL"),
    ),
    instructions="You are a helpful assistant",
)
response = await agent.run("Hello!")

Como alternativa, você pode usar o método de conveniência no cliente de chat:

from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import DefaultAzureCredential

agent = FoundryChatClient(
    credential=DefaultAzureCredential(),
    project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
    model=os.getenv("FOUNDRY_MODEL"),
).as_agent(
    instructions="You are a helpful assistant"
)

Para obter exemplos detalhados, consulte as seções de documentação específicas do agente abaixo.

Provedores de chat com suporte

O armazenamento de histórico de chat personalizado é suportado sempre que há suporte para o estado de conversa baseado em sessão.

Respostas de transmissão contínua

Os agentes suportam respostas convencionais e de streaming.

# Regular response (wait for complete result)
response = await agent.run("What's the weather like in Seattle?")
print(response.text)

# Streaming response (get results as they are generated)
async for chunk in agent.run("What's the weather like in Portland?", stream=True):
    if chunk.text:
        print(chunk.text, end="", flush=True)

Para obter exemplos de streaming, consulte:

• Exemplos de streaming de foundry
• Exemplos de transmissão do Azure OpenAI Chat Completion
• Exemplos de streaming do Azure OpenAI Responses
• Exemplos de streaming de conclusão de chat do OpenAI
• Exemplos de streaming de respostas da OpenAI

Para obter mais padrões de invocação, consulte Agentes em Execução.

Ferramentas de Funções

Você pode fornecer ferramentas funcionais aos agentes para capacidades aprimoradas.

import os
from typing import Annotated
from azure.identity.aio import DefaultAzureCredential
from agent_framework.foundry import FoundryChatClient

def get_weather(location: Annotated[str, "The location to get the weather for."]) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny with a high of 25°C."

async with DefaultAzureCredential() as credential:
    agent = FoundryChatClient(
        credential=credential,
        project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
        model=os.getenv("FOUNDRY_MODEL"),
    ).as_agent(
        instructions="You are a helpful weather assistant.",
        tools=get_weather,
    )
    response = await agent.run("What's the weather in Seattle?")

Para obter ferramentas e padrões de ferramenta, consulte a visão geral das Ferramentas.

Agentes personalizados

Para implementações totalmente personalizadas (por exemplo, agentes determinísticos ou agentes com suporte de API), consulte Agentes Personalizados. Essa página aborda a implementação SupportsAgentRun ou a extensão BaseAgent, incluindo atualizações de streaming com AgentResponseUpdate.

Outros tipos de agente

O Agent Framework também inclui agentes com suporte de protocolo, como: