Nota
O acesso a esta página requer autorização. Podes tentar iniciar sessão ou mudar de diretório.
O acesso a esta página requer autorização. Podes tentar mudar de diretório.
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.
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.
Modelo de Execução do Agente Padrão
Todos os agentes no Microsoft Agent Framework executam usando um modelo de execução estruturado. Este modelo coordena a interação do utilizador, a inferência do modelo e a execução da ferramenta num ciclo determinístico.
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
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 Microsoft.Extensions.AI.IChatClient implementação pode ser usado para construir estes 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:
- Chamadas de função.
- 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.
- Ferramentas fornecidas por serviços personalizados (por exemplo, MCP, Execução de Código).
- 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.
| Serviço de inferência subjacente | Description | O armazenamento do histórico de serviço de chat é suportado. | Armazenamento de histórico de chat InMemory/Personalizado suportado |
|---|---|---|---|
| Microsoft Foundry Agent | Um agente que utiliza o Foundry Agent Service como o seu backend. | Yes | Não |
| Modelos de Foundry para ChatCompletion | Um agente que utiliza qualquer um dos modelos implementados no Foundry Service como backend via ChatCompletion. | Não | Yes |
| Respostas dos Modelos de Fundição | Um agente que utiliza qualquer um dos modelos implementados no Foundry Service como backend via Respostas. | Yes | Yes |
| Foundry Anthropic | Um agente que utiliza um modelo Claude através do Foundry Anthropic Service como backend. | 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 |
| Anthropic | Um agente que utiliza um modelo Claude através do Serviço Antrópico como backend. | Não | 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 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:
| 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 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.
| Serviço de IA | SDK | Nuget | Endereço URL |
|---|---|---|---|
| Modelos de Fundição | Azure OpenAI SDK 2 | Azure.AI.OpenAI | https://ai-foundry-<recurso.services.ai.azure.com/> |
| Modelos de Fundição | OpenAI SDK 3 | OpenAI | https://ai-foundry-<recurso.services.ai.azure.com/openai/v1/> |
| Modelos de Fundição | Azure AI Inference SDK 2 | Azure.AI.Inferência | https://ai-foundry-<recurso.services.ai.azure.com/models> |
| Agentes de Fundição | 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 OpenAI1 | Azure OpenAI SDK 2 | Azure.AI.OpenAI | https://<resource.openai.azure.com/> |
| Azure OpenAI1 | OpenAI SDK | OpenAI | https://< recurso.openai.azure.com/openai/v1/> |
| OpenAI | OpenAI SDK | OpenAI | Nenhuma URL necessária |
| Azure AI Foundry Anthropic | Anthropic Foundry SDK | Anthropic.Foundry | Nome do recurso necessário |
| Antrópico | Anthropic SDK | Anthropic | Não é necessário URL ou nome de recurso |
- Atualizar do Azure OpenAI para o Foundry
- Recomendamos o uso do OpenAI SDK.
- 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 do Azure, também é possível usar credenciais do Azure em vez de uma chave de API.
OpenAIClient client = new OpenAIClient(new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"), clientOptions)
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.
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)
.AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
Usando o SDK do Azure OpenAI
Este SDK pode ser usado para se ligar tanto ao Azure OpenAI como aos serviços 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 DefaultAzureCredential())
.GetChatClient(deploymentName)
.AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
Usando o SDK de Agentes Persistentes da IA do Azure
Este SDK é suportado apenas pelo Serviço de Agentes. Consulte a tabela acima para obter o URL correto a ser usado.
var persistentAgentsClient = new PersistentAgentsClient(serviceUrl, new DefaultAzureCredential());
AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
model: deploymentName,
instructions: "You are good at telling jokes.",
name: "Joker");
Utilização do Azure AI Foundry Anthropic SDK
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, que define um padrão para os métodos que um cliente precisa de suportar a serem usados com a classe padrão Agent .
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 fornecidas por serviços personalizados (por exemplo, MCP, Execução de Código)
- Produção estruturada
- 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.azure import AzureOpenAIResponsesClient
from azure.identity.aio import DefaultAzureCredential
Agent(
client=AzureOpenAIResponsesClient(credential=DefaultAzureCredential(), project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"), deployment_name=os.getenv("AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME")),
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 AzureOpenAIResponsesClient
from azure.identity.aio import DefaultAzureCredential
agent = AzureOpenAIResponsesClient(credential=DefaultAzureCredential(), project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"), deployment_name=os.getenv("AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME")).as_agent(
instructions="You are a helpful assistant"
)
Observação
Este exemplo mostra a utilização do AzureOpenAIRrespondsesClient, mas o mesmo padrão aplica-se a qualquer cliente de chat que implemente SupportsChatGetResponse, veja a visão geral dos fornecedores para mais detalhes sobre outros clientes.
Para obter exemplos detalhados, consulte as seções de documentação específicas do agente abaixo.
Fornecedores de Chat Suportados
| Serviço de inferência subjacente | Description | Armazenamento de Histórico de Chat de Serviço é suportado |
|---|---|---|
| Agente de Fundição | Um agente que utiliza o Serviço de Agente como o seu backend. | Yes |
| Conclusão do Chat do Azure OpenAI | Um agente que usa o serviço de Conclusão de Chat do Azure OpenAI. | Não |
| Respostas do Azure OpenAI | Um agente que usa o serviço Azure OpenAI Responses. | Yes |
| Assistentes do Azure OpenAI | Um agente que utiliza o serviço Azure OpenAI Assistants. | Yes |
| Conclusão do bate-papo OpenAI | Um agente que usa o serviço OpenAI Chat Completion. | Não |
| Respostas OpenAI | Um agente que usa o serviço OpenAI Responses. | Yes |
| Assistentes OpenAI | Um agente que usa o serviço OpenAI Assistants. | Yes |
| Anthropic Claude | Um agente que usa modelos Anthropic Claude. | Não |
| Substrato rochoso amazônico | Um agente que utiliza modelos Amazon Bedrock através do cliente de chat Agent Framework Bedrock. | Não |
| Copiloto do GitHub | Um agente que utiliza o backend do SDK do GitHub Copilot. | Não |
| Ollama (compatível com OpenAI) | Um agente que utiliza modelos Ollama alojados localmente através de APIs compatíveis com OpenAI. | Não |
| Qualquer outro ChatClient | Também pode usar qualquer outra implementação de SupportsChatGetResponse para criar um agente. |
Varies |
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 de IA do Azure
- Exemplos de streaming do Azure OpenAI
- Exemplos de streaming OpenAI
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.azure import AzureOpenAIResponsesClient
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 = AzureOpenAIResponsesClient(
credential=credential,
project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"),
deployment_name=os.getenv("AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"),
).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:
| Tipo de agente | Description |
|---|---|
| A2A | Um agente proxy que se liga e invoca agentes remotos compatíveis com A2A. |