Tipos de agente do Microsoft Agent Framework

O Microsoft Agent Framework fornece suporte para vários tipos de agentes para acomodar diferentes casos de uso e requisitos.

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.

Importante

Se você usar o Microsoft Agent Framework para criar aplicativos que operam com servidores ou agentes de terceiros, o fará por sua conta e risco. Recomendamos analisar todos os dados que estão sendo compartilhados com servidores ou agentes de terceiros e estar ciente das práticas de terceiros para retenção e localização de dados. É sua responsabilidade gerenciar se seus dados fluirão fora dos limites geográficos e de conformidade do Azure da sua organização e de quaisquer implicações relacionadas.

Agentes simples baseados 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 é a classe de agente usada para fornecer um agente para qualquer IChatClient implementação.

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

Chamada de função
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
Ferramentas personalizadas fornecidas pelo serviço (por exemplo, MCP, Execução de Código)
Produção 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 ajudantes para tornar a criação desses agentes ainda mais fácil. Consulte a documentação de cada serviço, para obter mais informações:

Serviço de inferência subjacente	Description	Armazenamento de Histórico de Chat de Serviço é suportado	Armazenamento de Histórico de Chat Personalizado suportado
Azure AI Foundry Agent	Um agente que usa o Azure AI Foundry Agents Service como back-end.	Yes	Não
Azure AI Foundry Models ChatCompletion	Um agente que usa qualquer um dos modelos implantados no Azure AI Foundry Service como seu back-end por meio do ChatCompletion.	Não	Yes
Respostas dos modelos do Azure AI Foundry	Um agente que utiliza qualquer um dos modelos implementados no Azure AI Foundry Service como seu back-end através do uso das Responses.	Não	Yes
Azure OpenAI ChatCompletion	Um agente que usa o serviço Azure OpenAI ChatCompletion .	Não	Yes
Respostas do Azure OpenAI	Um agente que usa o serviço Azure OpenAI Responses.	Yes	Yes
OpenAI Conclusão de Chat	Um agente que usa o serviço OpenAI ChatComplete.	Não	Yes
Respostas OpenAI	Um agente que usa o serviço OpenAI Responses.	Yes	Yes
Assistentes OpenAI	Um agente que usa o serviço OpenAI Assistants.	Yes	Não
Qualquer outro `IChatClient`	Você também pode usar qualquer outra `Microsoft.Extensions.AI.IChatClient` implementação para criar um agente.	Varies	Varies

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 central para todos os agentes, que quando subclassificados permitem o controle completo sobre o comportamento e as capacidades do agente.

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

Proxies para agentes remotos

A estrutura do agente fornece implementações prontas para uso imediato para protocolos de serviços de agente hospedado comuns, como 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:

Protocolo	Description
A2A	Um agente que serve como proxy para um agente remoto através do protocolo A2A.

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

Ao usar os serviços Azure AI Foundry, Azure OpenAI ou 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 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.

Serviço de IA	SDK	Nuget	Endereço URL
Azure AI Foundry Models	Azure OpenAI SDK ²	Azure.AI.OpenAI	https://ai-foundry-<recurso.services.ai.azure.com/>
Azure AI Foundry Models	OpenAI SDK ³	OpenAI	https://ai-foundry-<recurso.services.ai.azure.com/openai/v1/>
Azure AI Foundry Models	Azure AI Inference SDK ²	Azure.AI.Inferência	https://ai-foundry-<recurso.services.ai.azure.com/models>
Azure AI Foundry Agents	SDK de Agentes Persistentes da IA do Azure	Azure.AI.Agents.Persistent	https://ai-foundry-<resource.services.ai.azure.com/api/projects/ai-project->project<>
Azure OpenAI¹	Azure OpenAI SDK ²	Azure.AI.OpenAI	https://<resource.openai.azure.com/>
Azure OpenAI¹	OpenAI SDK	OpenAI	https://< recurso.openai.azure.com/openai/v1/>
OpenAI	OpenAI SDK	OpenAI	Nenhuma URL necessária

Atualizando do Azure OpenAI para o Azure AI Foundry
Recomendamos o uso do OpenAI SDK.
Embora seja recomendável usar o SDK do OpenAI para acessar os modelos do Azure AI Foundry, os Modelos do Azure AI Foundry oferecem suporte a modelos de muitos fornecedores diferentes, não apenas do 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 do Azure, também é possível usar 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 disso.

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 Azure OpenAI e Azure AI Foundry Models. De qualquer forma, você precisará fornecer a URL de serviço correta ao criar o AzureOpenAIClient. Consulte a tabela acima para obter o URL correto a ser usado.

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 da IA do Azure

Este SDK só é suportado com o serviço Azure AI Foundry Agents. Consulte a tabela acima para obter o URL correto a ser usado.

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 baseados 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 oferecem suporte a uma ampla gama de funcionalidades prontas para uso:

Chamada de função
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
Ferramentas personalizadas fornecidas pelo serviço (por exemplo, MCP, Execução de Código)
Produção estruturada
Respostas de streaming

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 agentes suportados

Serviço de inferência subjacente	Description	Armazenamento de Histórico de Chat de Serviço é suportado	Armazenamento de Histórico de Chat Personalizado suportado
Azure AI Agent	Um agente que usa o Serviço de Agentes de IA do Azure como back-end.	Yes	Não
Conclusão do Chat do Azure OpenAI	Um agente que usa o serviço de Conclusão de Chat do Azure OpenAI.	Não	Yes
Respostas do Azure OpenAI	Um agente que usa o serviço Azure OpenAI Responses.	Yes	Yes
Conclusão do bate-papo OpenAI	Um agente que usa o serviço OpenAI Chat Completion.	Não	Yes
Respostas OpenAI	Um agente que usa o serviço OpenAI Responses.	Yes	Yes
Assistentes OpenAI	Um agente que usa o serviço OpenAI Assistants.	Yes	Não
Qualquer outro ChatClient	Você também pode usar qualquer outra implementação de cliente de chat para criar um agente.	Varies	Varies

Ferramentas de Função

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

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:

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

Para exemplos de streaming, consulte:

Ferramentas de interpretação de código

Os agentes de IA do Azure dão suporte a ferramentas de interpretador de código hospedado para executar 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 exemplos de interpretadores de código, consulte:

Agentes aduaneiros

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 AgentProtocol protocolo e a classe base BaseAgent, que, quando implementados/subclassificados, permitem o controle completo sobre o comportamento e os recursos 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

Feedback

Esta página foi útil?

Last updated on 2025-11-10

Partilhar via

Tipos de agente do Microsoft Agent Framework

Agentes simples baseados em serviços de inferência

Agentes personalizados complexos

Proxies para agentes remotos

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

Usando o OpenAI SDK

Usando o SDK do Azure OpenAI

Usando o SDK de Agentes Persistentes da IA do Azure

Agentes simples baseados em serviços de inferência

Tipos de agentes suportados

Ferramentas de Função

Respostas de streaming

Ferramentas de interpretação de código

Agentes aduaneiros

Feedback

Recursos adicionais