Tipos de agentes 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 agentes. Isso permite a criação de funcionalidades comuns, agnósticas e de nível mais alto, como orquestrações multiagentes.

Todos os agentes são derivados de uma classe base comum, Agentque fornece uma interface consistente para todos os tipos de agentes. Isso permite a criação de funcionalidades comuns, agnósticas e de nível mais alto, como orquestrações multiagentes.

Agentes simples baseados em serviços de inferência

O Agent Framework facilita a criação de agentes simples baseados 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 construir estes agentes. O Microsoft.Agents.AI.ChatClientAgent é a classe agente usada para fornecer um agente para qualquer implementação IChatClient.

Esses agentes oferecem suporte a uma ampla gama de funcionalidades prontas para uso:

1. Chamadas de função.
2. Conversas de múltiplos turnos com gestão de histórico de chat local ou gestão de histórico de chat por serviço fornecido.
3. Ferramentas fornecidas por serviços personalizados (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 destes agentes, o Agent Framework fornece ajudantes para muitos serviços populares. Para 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 sejam apenas wrappers em torno de um IChatClient. A estrutura do agente fornece o AIAgent tipo base. Este tipo base é a abstração central para todos os agentes, que, quando subclassificada, permite o controlo total sobre o comportamento e as capacidades do agente.

Para mais informações, consulte a documentação para Agentes Alfandegários.

Proxies para agentes remotos

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

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

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

Ao usar Foundry, Azure OpenAI, serviços OpenAI ou serviços Anthropic, tem várias opções de SDK para se ligar a estes 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 o url que você deve usar ao se conectar a cada um. Certifique-se de substituir <resource> e <project> com seus nomes reais de recursos e projetos.

1. A atualização de Azure OpenAI para Foundry
2. Recomendamos o uso do OpenAI SDK.
3. Embora recomendemos usar o SDK OpenAI para aceder a modelos Foundry, estes suportam modelos de vários fornecedores diferentes, não apenas OpenAI. Todos estes modelos são suportados através do OpenAI SDK.

Usando o OpenAI SDK

Como mostrado na tabela acima, o OpenAI SDK 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 diferentes mecanismos de autenticação, dependendo do serviço.

Se for necessário um URL personalizado (veja a tabela acima), você pode defini-lo através 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 Azure, também é possível usar credenciais Azure em vez de uma chave 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 disso.

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

A usar o SDK de Projetos de IA do Azure

Este SDK pode ser usado para ligar a serviços da Foundry. Terá de fornecer a URL correta do endpoint do projeto ao criar o AIProjectClient. Consulte a tabela acima para obter o URL correto a ser usado.

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

Usar o SDK de Projetos de IA Azure com Foundry Agents

Este SDK é usado tanto para agentes baseados em API de Respostas como para Agentes Foundry versionados. Consulte a tabela acima para obter o URL correto a ser usado.

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

Utilização do 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 baseados em serviços de inferência

O Agent Framework facilita a criação de agentes simples baseados 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. Isto pode ser feito usando o SupportsChatGetResponse protocolo, que define um padrão para os métodos que um cliente precisa de suportar para serem usados com a classe padrão Agent .

Esses agentes oferecem suporte a uma ampla gama de funcionalidades prontas para uso:

1. Chamada de função
2. Conversas em vários turnos com gerenciamento de histórico de bate-papo local ou gerenciamento de histórico de bate-papo fornecido pelo serviço
3. Ferramentas fornecidas por serviços personalizados (por exemplo, MCP, Execução de Código)
4. Produção estruturada
5. Respostas de streaming

Para criar um destes agentes, basta construir um Agent usando a implementação do cliente de chat que preferir.

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.

Fornecedores de Chat Suportados

O armazenamento personalizado do histórico de conversas é suportado sempre que o estado de conversa baseado em sessões é suportado.

Respostas de streaming

Os agentes suportam respostas regulares 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 exemplos de streaming, consulte:

• Exemplos de streaming da Foundry
• Exemplos de streaming do Azure OpenAI para conclusão de chat
• Azure Exemplos de streaming de Respostas OpenAI
• Exemplos de streaming do OpenAI Chat Completion
• Exemplos de streaming OpenAI Responses

Para mais padrões de invocação, veja Agentes em Corrida.

Ferramentas de Função

Você pode fornecer ferramentas funcionais aos agentes para melhorar as capacidades.

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 ferramentas e padrões de ferramentas, veja Visão Geral das Ferramentas.

Agentes aduaneiros

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

Outros tipos de agentes

O Agent Framework inclui também agentes apoiados por protocolo, tais como: