Tipos de agente do Microsoft Agent Framework

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

A estrutura do agente 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 Microsoft.Extensions.AI.IChatClient implementação pode ser usado para criar esses agentes. A Microsoft.Agents.AI.ChatClientAgent classe de agente é usada para fornecer um agente para qualquer IChatClient implementação.

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 muitos serviços populares, também temos auxiliares para facilitar ainda mais a criação desses agentes. Consulte a documentação de cada serviço para obter mais informações:

Agentes personalizados complexos

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

Consulte a documentação dos Agentes Personalizados para obter mais informações.

Proxies para agentes remotos

A estrutura do AIAgent agente fornece implementações prontas para protocolos comuns de agente hospedados no 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 Azure AI Foundry, o Azure OpenAI ou os serviços OpenAI, 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 Azure AI Foundry
2. É recomendável usar o SDK do OpenAI.
3. Embora seja recomendável usar o SDK do OpenAI para acessar modelos do Azure AI Foundry, os Modelos de Descoberta de IA do Azure dão suporte a modelos de vários 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 do Azure, também é possível usar as credenciais do Azure em vez de uma chave de API.

OpenAIClient client = new OpenAIClient(new BearerTokenPolicy(new AzureCliCredential(), "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
    .GetChatClient(model)
    .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

Usando o SDK do Azure OpenAI

Esse SDK pode ser usado para se conectar aos serviços do Azure OpenAI e do Azure AI Foundry Models. De qualquer forma, você precisará fornecer a URL de serviço correta ao criar a AzureOpenAIClient. Consulte a tabela acima para obter a URL correta a ser usada.

AIAgent agent = new AzureOpenAIClient(
    new Uri(serviceUrl),
    new AzureCliCredential())
     .GetChatClient(deploymentName)
     .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

Usando o SDK de Agentes Persistentes de IA do Azure

Esse SDK só tem suporte com o serviço Azure AI Foundry Agents. Consulte a tabela acima para obter a URL correta a ser usada.

var persistentAgentsClient = new PersistentAgentsClient(serviceUrl, new AzureCliCredential());
AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
    model: deploymentName,
    name: "Joker",
    instructions: "You are good at telling jokes.");

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

A estrutura do agente 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.

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 de transmissão em fluxo

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

from agent_framework import ChatAgent
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential

async with (
    DefaultAzureCredential() as credential,
    ChatAgent(
        chat_client=AzureAIAgentClient(async_credential=credential),
        instructions="You are a helpful assistant"
    ) as agent
):
    response = await agent.run("Hello!")

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

from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential

async with DefaultAzureCredential() as credential:
    agent = AzureAIAgentClient(async_credential=credential).create_agent(
        instructions="You are a helpful assistant"
    )

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

Tipos de agente com suporte

Ferramentas de Funções

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

from typing import Annotated
from pydantic import Field
from azure.identity.aio import DefaultAzureCredential
from agent_framework.azure import AzureAIAgentClient

def get_weather(location: Annotated[str, Field(description="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,
    AzureAIAgentClient(async_credential=credential).create_agent(
        instructions="You are a helpful weather assistant.",
        tools=get_weather
    ) as agent
):
    response = await agent.run("What's the weather in Seattle?")

Para obter exemplos completos com ferramentas de função, consulte:

• IA do Azure com ferramentas de função
• Azure OpenAI com ferramentas de função
• OpenAI com ferramentas de funções

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_stream("What's the weather like in Portland?"):
    if chunk.text:
        print(chunk.text, end="", flush=True)

Para obter exemplos de streaming, consulte:

• Exemplos de streaming de IA do Azure
• Exemplos de streaming do Azure OpenAI
• Exemplos de streaming do OpenAI

Ferramentas de Interpretador de Código

Os agentes de IA do Azure dão suporte a ferramentas de interpretador de código hospedadas para executar o código python:

from agent_framework import ChatAgent, HostedCodeInterpreterTool
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential

async with (
    DefaultAzureCredential() as credential,
    ChatAgent(
        chat_client=AzureAIAgentClient(async_credential=credential),
        instructions="You are a helpful assistant that can execute Python code.",
        tools=HostedCodeInterpreterTool()
    ) as agent
):
    response = await agent.run("Calculate the factorial of 100 using Python")

Para obter exemplos de interpretador de código, consulte:

• IA do Azure com interpretador de código
• Assistentes do Azure OpenAI com interpretador de código
• Assistentes do OpenAI com interpretador de código

Agentes personalizados

Também é possível criar agentes totalmente personalizados que não são apenas wrappers em torno de um cliente de chat. O Agent Framework fornece o protocolo AgentProtocol e a BaseAgent classe base, que quando implementada/subclassificada permite o controle completo sobre o comportamento e as capacidades do agente.

from agent_framework import BaseAgent, AgentRunResponse, AgentRunResponseUpdate, AgentThread, ChatMessage
from collections.abc import AsyncIterable

class CustomAgent(BaseAgent):
    async def run(
        self,
        messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
        *,
        thread: AgentThread | None = None,
        **kwargs: Any,
    ) -> AgentRunResponse:
        # Custom agent implementation
        pass

    def run_stream(
        self,
        messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
        *,
        thread: AgentThread | None = None,
        **kwargs: Any,
    ) -> AsyncIterable[AgentRunResponseUpdate]:
        # Custom streaming implementation
        pass