Condividi tramite

Tipi di agente di Microsoft Agent Framework

Microsoft Agent Framework offre supporto per diversi tipi di agenti per soddisfare diversi casi d'uso e requisiti.

Tutti gli agenti sono derivati da una classe base comune, AIAgent, che fornisce un'interfaccia coerente per tutti i tipi di agente. In questo modo è possibile creare funzionalità comuni, indipendenti dall'agente e di livello superiore, ad esempio orchestrazioni multi-agente.

Tutti gli agenti sono derivati da una classe base comune, Agent, che fornisce un'interfaccia coerente per tutti i tipi di agente. In questo modo è possibile creare funzionalità comuni, indipendenti dall'agente e di livello superiore, ad esempio orchestrazioni multi-agente.

Modello di esecuzione predefinito del runtime dell'agente

Tutti gli agenti in Microsoft Agent Framework vengono eseguiti usando un modello di runtime strutturato. Questo modello coordina l'interazione dell'utente, l'inferenza del modello e l'esecuzione degli strumenti in un ciclo deterministico.

Diagramma dell'agente di intelligenza artificiale

Importante

Se si usa Microsoft Agent Framework per creare applicazioni che operano con server o agenti di terze parti, è possibile farlo a proprio rischio. È consigliabile esaminare tutti i dati condivisi con server o agenti di terze parti e riconoscere le procedure di terze parti per la conservazione e la posizione dei dati. È responsabilità dell'utente gestire se i dati verranno trasmessi al di fuori dei limiti geografici e di conformità di Azure dell'organizzazione e di eventuali implicazioni correlate.

Agenti semplici basati su servizi di inferenza

Agent Framework semplifica la creazione di agenti semplici basati su molti servizi di inferenza diversi. Qualsiasi servizio di inferenza che fornisce un'implementazione Microsoft.Extensions.AI.IChatClient può essere usato per compilare questi agenti. Microsoft.Agents.AI.ChatClientAgent è la classe agente usata per fornire un agente per qualsiasi IChatClient implementazione.

Questi agenti supportano un'ampia gamma di funzionalità integrate:

  1. Chiamata di funzione.
  2. Conversazioni a più turni con gestione della cronologia delle chat locali o gestione della cronologia delle chat fornita dal servizio.
  3. Strumenti forniti dal servizio personalizzato, ad esempio MCP, Esecuzione del codice.
  4. Output strutturato.

Per creare uno di questi agenti, è sufficiente costruire un ChatClientAgent oggetto usando l'implementazione IChatClient di propria scelta.

using Microsoft.Agents.AI;

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

Per semplificare ulteriormente la creazione di questi agenti, Agent Framework offre helper per molti servizi più diffusi. Per altre informazioni, vedere la documentazione per ogni servizio.

Servizio di inferenza sottostante Descrzione Archiviazione della cronologia delle chat del servizio supportata Supportata l'archiviazione della cronologia chat personalizzata/InMemory
Agente di Azure AI Foundry Agente che usa il servizio Azure AI Foundry Agents come back-end. Sì NO
Modelli di ChatCompletion di Azure AI Foundry Agente che usa uno dei modelli distribuiti nel servizio Azure AI Foundry come back-end tramite ChatCompletion. NO Sì
Risposte ai modelli di Foundry per intelligenza artificiale di Azure Agente che utilizza uno dei modelli distribuiti nel servizio Azure AI Foundry come back-end tramite Responses. Sì Sì
Completamento Chat di Azure OpenAI Agente che usa il servizio ChatCompletion OpenAI di Azure. NO Sì
Risposte OpenAI di Azure Agente che usa il servizio Risposte OpenAI di Azure. Sì Sì
OpenAI ChatCompletion Agente che usa il servizio OpenAI ChatCompletion. NO Sì
Risposte OpenAI Agente che usa il servizio Risposte OpenAI. Sì Sì
Assistenti OpenAI Agente che usa il servizio Assistenti OpenAI. Sì NO
Qualsiasi altro IChatClient È anche possibile usare qualsiasi altra Microsoft.Extensions.AI.IChatClient implementazione per creare un agente. Variabile Variabile

Agenti personalizzati complessi

È anche possibile creare agenti completamente personalizzati che non fungono solo da wrapper intorno a un oggetto IChatClient. Il framework dell'agente fornisce il tipo base AIAgent. Questo tipo di base è l'astrazione principale per tutti gli agenti, che, se sottoclassati, consente il controllo completo sul comportamento e sulle funzionalità dell'agente.

Per altre informazioni, vedere la documentazione relativa agli agenti personalizzati.

Proxy per gli agenti remoti

Agent Framework offre implementazioni predefinite AIAgent per protocolli comuni per agenti ospitati dai servizi, ad esempio A2A. In questo modo è possibile connettersi facilmente e usare agenti remoti dall'applicazione.

Per altre informazioni, vedere la documentazione per ogni tipo di agente:

Protocollo Descrzione
A2A Agente che funge da proxy per un agente remoto tramite il protocollo A2A.

Informazioni di riferimento sulle opzioni di Azure e OpenAI SDK

Quando si usano i servizi Azure AI Foundry, Azure OpenAI o OpenAI, sono disponibili diverse opzioni SDK per connettersi a questi servizi. In alcuni casi, è possibile usare più SDK per connettersi allo stesso servizio o per usare lo stesso SDK per connettersi a servizi diversi. Di seguito è riportato un elenco delle diverse opzioni disponibili con l'URL da usare per la connessione a ogni url. Assicurarsi di sostituire <resource> e <project> con i nomi effettivi di risorse e progetti.

Servizio IA SDK Nuget URL
Modelli di Azure AI Foundry Azure OpenAI SDK 2 Azure.AI.OpenAI https://ai-foundry-<resource.services.ai.azure.com/>
Modelli di Azure AI Foundry OpenAI SDK 3 OpenAI https://ai-foundry-<resource.services.ai.azure.com/openai/v1/>
Modelli di Azure AI Foundry Azure AI Inference SDK 2 Azure.AI.Inference https://ai-foundry-<resource.services.ai.azure.com/models>
Agenti di Azure AI Foundry Azure AI Persistent Agents SDK - SDK per agenti persistenti di Azure AI 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:// resource.openai.azure.com/openai/v1/>
OpenAI OpenAI SDK OpenAI Nessun URL necessario
  1. Aggiornamento da Azure OpenAI a Azure AI Foundry
  2. È consigliabile usare OpenAI SDK.
  3. Sebbene sia consigliabile usare OpenAI SDK per accedere ai modelli di Azure AI Foundry, i modelli di Azure AI Foundry supportano modelli di molti fornitori diversi, non solo OpenAI. Tutti questi modelli sono supportati tramite OpenAI SDK.

Uso di OpenAI SDK

Come illustrato nella tabella precedente, è possibile usare OpenAI SDK per connettersi a più servizi. A seconda del servizio a cui ci si connette, potrebbe essere necessario impostare un URL personalizzato durante la creazione di OpenAIClient. È anche possibile usare meccanismi di autenticazione diversi a seconda del servizio.

Se è necessario un URL personalizzato (vedere la tabella precedente), è possibile impostarlo tramite OpenAIClientOptions.

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

È possibile usare una chiave API durante la creazione del client.

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

Quando si usa un servizio di Azure, è anche possibile usare le credenziali di Azure anziché una chiave API.

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

Avviso

DefaultAzureCredential è utile per lo sviluppo, ma richiede un'attenta considerazione nell'ambiente di produzione. Nell'ambiente di produzione prendere in considerazione l'uso di credenziali specifiche ,ad esempio ManagedIdentityCredential, per evitare problemi di latenza, probe di credenziali indesiderate e potenziali rischi per la sicurezza dai meccanismi di fallback.

Dopo aver creato OpenAIClient, è possibile ottenere un sottoclient per il servizio specifico che si desidera utilizzare e quindi crearci un AIAgent.

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

Uso di Azure OpenAI SDK

Questo SDK può essere usato per connettersi ai servizi Azure OpenAI e Azure AI Foundry Models. In entrambi i casi, sarà necessario specificare l'URL del servizio corretto durante la creazione di AzureOpenAIClient. Vedere la tabella precedente per l'URL corretto da usare.

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

Uso di Azure AI Persistent Agents SDK

Questo SDK è supportato solo con il servizio Azure AI Foundry Agents. Vedere la tabella precedente per l'URL corretto da usare.

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

Agenti semplici basati su servizi di inferenza

Agent Framework semplifica la creazione di agenti semplici basati su molti servizi di inferenza diversi. Qualsiasi servizio di inferenza che fornisce un'implementazione client di chat può essere usato per sviluppare questi agenti. A tale scopo, è possibile usare SupportsChatGetResponse, che definisce uno standard per i metodi che un client deve supportare per l'uso con la classe standard Agent .

Questi agenti supportano un'ampia gamma di funzionalità integrate:

  1. Chiamata di funzione
  2. Conversazioni a più turni con la gestione della cronologia delle chat locali o la gestione della cronologia delle chat fornita dal servizio
  3. Strumenti forniti dal servizio personalizzato (ad esempio, MCP, esecuzione del codice)
  4. Output strutturato
  5. Risposte in streaming

Per creare uno di questi agenti, è sufficiente costruire un Agent utilizzando l'implementazione del client di chat di propria scelta.

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!")

In alternativa, è possibile usare il metodo pratico nel client di chat:

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

agent = AzureOpenAIResponsesClient(async_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"
)

Annotazioni

Questo esempio mostra l'uso di SupportsChatGetResponse, ma lo stesso modello si applica a qualsiasi client di chat che implementa SupportsChatGetResponse, consulta la panoramica dei fornitori per ulteriori dettagli su altri client.

Per esempi dettagliati, vedere le sezioni della documentazione specifica dell'agente di seguito.

Provider di chat supportati

Servizio di inferenza sottostante Descrzione Supportata l'archiviazione della cronologia della chat del servizio
Agente di Azure AI Foundry Agente che usa il servizio Azure AI Agents come back-end. Sì
Completamento della chat OpenAI di Azure Un agente che utilizza il servizio di completamento della chat OpenAI di Azure. NO
Risposte OpenAI di Azure Agente che usa il servizio Risposte OpenAI di Azure. Sì
Assistenti OpenAI di Azure Agente che usa il servizio Azure OpenAI Assistants. Sì
Completamento della chat OpenAI Agente che usa il servizio OpenAI Chat Completion. NO
Risposte OpenAI Agente che usa il servizio Risposte OpenAI. Sì
Assistenti OpenAI Agente che usa il servizio Assistenti OpenAI. Sì
Anthropic Claude Agente che usa modelli Anthropic Claude. NO
Roccia amazzonica Agente che usa i modelli Amazon Bedrock tramite il client di chat Bedrock di Agent Framework. NO
GitHub Copilot Agente che usa il back-end di GitHub Copilot SDK. NO
Ollama (compatibile con OpenAI) Agente che usa modelli Ollama ospitati localmente tramite API compatibili con OpenAI. NO
Qualsiasi altro ChatClient È anche possibile usare qualsiasi altra implementazione di SupportsChatGetResponse per creare un agente. Variabile

L'archiviazione della cronologia chat personalizzata è supportata ogni volta che è supportato lo stato della conversazione basato su sessione.

Risposte in streaming

Gli agenti supportano risposte regolari e in 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)

Per esempi di streaming, vedere:

Per altri modelli di chiamata, vedere Running Agents .For more invocation patterns, see Running Agents.

Strumenti per le funzioni

È possibile fornire strumenti di funzione agli agenti per funzionalità avanzate:

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(
        async_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?")

Per gli strumenti e i modelli di strumenti, vedere Panoramica degli strumenti.

Agenti personalizzati

Per le implementazioni completamente personalizzate (ad esempio agenti deterministici o agenti supportati dall'API), vedere Agenti personalizzati. Tale pagina illustra l'implementazione di SupportsAgentRun o l'estensione di BaseAgent, inclusi gli aggiornamenti streaming con AgentResponseUpdate.

Altri tipi di agente

Agent Framework include anche agenti supportati dal protocollo, ad esempio:

Tipo di agente Descrzione
A2A Agente proxy che si connette e richiama agenti conformi a A2A remoti.

Passaggi successivi

Esecuzione di agenti

  • Last updated on