Condividi tramite

integrazione di AG-UI con Agent Framework

Ag-UI è un protocollo che consente di creare applicazioni dell'agente di intelligenza artificiale basate sul Web con funzionalità avanzate come lo streaming in tempo reale, la gestione dello stato e i componenti interattivi dell'interfaccia utente. L'integrazione di Agent Framework AG-UI offre connettività perfetta tra gli agenti e i client Web.

Che cos'è AG-UI?

AG-UI è un protocollo standardizzato per la creazione di interfacce dell'agente di intelligenza artificiale che fornisce:

  • Hosting dell'agente remoto: distribuire agenti di intelligenza artificiale come servizi Web accessibili da più client
  • Streaming in tempo reale: eseguire lo streaming delle risposte dell'agente di flusso usando eventi Server-Sent (SSE) per un feedback immediato
  • Comunicazione standardizzata: formato di messaggio coerente per le interazioni con agenti affidabili
  • Gestione delle sessioni: mantenere il contesto della conversazione tra più richieste
  • Funzionalità avanzate: approvazioni human-in-the-loop, sincronizzazione dello stato e rendering personalizzato dell'interfaccia utente

Quando usare AG-UI

È consigliabile usare AG-UI quando è necessario:

  • Creare applicazioni Web o per dispositivi mobili che interagiscono con gli agenti di intelligenza artificiale
  • Distribuire gli agenti come servizi accessibili da più utenti contemporaneamente
  • Trasmettere le risposte dell'agente in tempo reale per fornire feedback immediato agli utenti
  • Implementare flussi di lavoro di approvazione in cui gli utenti confermano le azioni prima dell'esecuzione
  • Sincronizzare lo stato tra client e server per esperienze interattive
  • Eseguire il rendering di componenti dell'interfaccia utente personalizzati in base alle chiamate degli strumenti dell'agente

Funzionalità supportate

L'integrazione AG-UI di Agent Framework supporta tutte le 7 funzionalità del protocollo AG-UI:

  1. Chat agentic: chat di streaming di base con chiamate automatiche
  2. Rendering dello strumento backend: strumenti eseguiti nel backend con risultati trasmessi al client
  3. Human in the Loop: Richieste di approvazione delle funzioni per la conferma dell'utente
  4. Interfaccia utente generativa agentica: strumenti asincroni per operazioni a esecuzione prolungata con aggiornamenti di avanzamento
  5. Interfaccia utente generativa basata su strumenti: componenti dell'interfaccia utente personalizzati sottoposti a rendering in base alle chiamate degli strumenti
  6. Stato condiviso: sincronizzazione dello stato bidirezionale tra client e server
  7. Aggiornamenti dello stato predittivo: argomenti dello strumento di flusso come aggiornamenti dello stato ottimistico

Creare interfacce utente dell'agente con CopilotKit

CopilotKit offre componenti avanzati dell'interfaccia utente per la compilazione di interfacce utente agente basate sul protocollo di AG-UI standard. CopilotKit supporta le interfacce di chat in streaming, il richiamo di strumenti frontend e backend, le interazioni umane nel processo, la UI generativa, lo stato condiviso e molto altro ancora. È possibile visualizzare alcuni esempi dei vari scenari dell'interfaccia utente dell'agente supportati da CopilotKit nell'applicazione di esempioAG-UI Dojo .

CopilotKit ti aiuta a concentrarsi sulle funzionalità dell'agente, offrendo al tempo stesso un'esperienza utente lucida senza reinventare la ruota. Per altre informazioni su come iniziare a usare Microsoft Agent Framework e CopilotKit, vedere la documentazione sull'integrazione di Microsoft Agent Framework per CopilotKit .

AG-UI rispetto all'utilizzo diretto dell'agente

Anche se è possibile eseguire agenti direttamente nell'applicazione usando i metodi Run e RunStreamingAsync di Agent Framework, AG-UI offre funzionalità aggiuntive.

Caratteristica / Funzionalità Utilizzo agente diretto Integrazione di AG-UI
Distribuzione Incorporato nell'applicazione Servizio remoto tramite HTTP
Accesso del client Applicazione singola Più client (Web, dispositivi mobili)
Trasmissione in diretta Iterazione asincrona in-process Eventi Server-Sent (SSE)
Gestione dello stato Gestito dall'applicazione Snapshot dello stato a livello di protocollo
Contesto della sessione Gestito dall'applicazione ID sessione gestiti dal protocollo
Flussi di lavoro di approvazione Implementazione personalizzata Modello middleware predefinito

Panoramica dell'architettura

L'integrazione AG-UI usa ASP.NET Core e segue un'architettura pulita basata sul middleware:

┌─────────────────┐
│  Web Client     │
│  (Browser/App)  │
└────────┬────────┘
         │ HTTP POST + SSE
         ▼
┌─────────────────────────┐
│  ASP.NET Core           │
│  MapAGUI("/", agent)    │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  AIAgent                │
│  (with Middleware)      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  IChatClient            │
│  (Azure OpenAI, etc.)   │
└─────────────────────────┘

Componenti chiave

  • ASP.NET Endpoint core: MapAGUI il metodo di estensione gestisce le richieste HTTP e lo streaming SSE
  • AIAgent: agente di Agent Framework creato da IChatClient o implementazione personalizzata
  • Middleware Pipeline: Middleware opzionale per le approvazioni, la gestione dello stato e la logica personalizzata
  • Adattatore protocollo: esegue la conversione tra tipi di Framework agente ed eventi del protocollo AG-UI
  • Client chat: client chat di Microsoft.Extensions.AI (Azure OpenAI, OpenAI, Ollama e così via)

Modalità di conversione di Agent Framework in AG-UI

Comprendere il mapping dei concetti di Agent Framework alle AG-UI consente di creare integrazioni efficaci:

Concetto di framework dell'agente AG-UI equivalente Description
AIAgent Endpoint agente Ogni agente diventa un endpoint HTTP
agent.Run() Richiesta HTTP POST Il client invia messaggi tramite HTTP
agent.RunStreamingAsync() SSE (Server-Sent Event) Streaming di risposte tramite SSE
AgentResponseUpdate Eventi AG-UI Convertito automaticamente in eventi del protocollo
AIFunctionFactory.Create() Strumenti back-end Eseguito nel server, risultati trasmessi
ApprovalRequiredAIFunction Interazione Umana nel Loop Il middleware converte al protocollo di approvazione
AgentSession Gestione delle sessioni ConversationId mantiene il contesto
ChatResponseFormat.ForJsonSchema<T>() Istantanee di stato L'output strutturato diventa eventi di stato

Installazione

L'integrazione AG-UI è inclusa nel pacchetto di hosting ASP.NET Core:

dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore

Questo pacchetto include tutte le dipendenze necessarie per l'integrazione di AG-UI incluso Microsoft.Extensions.AI.

Passaggi successivi

Per iniziare a usare AG-UI integrazione:

  1. Introduzione: Creare il primo server AG-UI e il client
  2. Rendering degli strumenti del back-end: Aggiungi strumenti funzionali ai tuoi agenti

Risorse aggiuntive

AG-UI rispetto all'utilizzo diretto dell'agente

Anche se è possibile eseguire agenti direttamente nell'applicazione usando i metodi run e run(..., stream=True) di Agent Framework, AG-UI offre funzionalità aggiuntive.

Caratteristica / Funzionalità Utilizzo agente diretto Integrazione di AG-UI
Distribuzione Incorporato nell'applicazione Servizio remoto tramite HTTP
Accesso del client Applicazione singola Più client (Web, dispositivi mobili)
Trasmissione in diretta Iterazione asincrona in-process Eventi Server-Sent (SSE)
Gestione dello stato Gestito dall'applicazione Sincronizzazione a livello di protocollo bidirezionale
Contesto del thread Gestito dall'applicazione Identificatori di thread gestiti dal protocollo
Flussi di lavoro di approvazione Implementazione personalizzata Supporto del protocollo integrato

Panoramica dell'architettura

L'integrazione AG-UI usa un'architettura pulita e modulare:

┌─────────────────┐
│  Web Client     │
│  (Browser/App)  │
└────────┬────────┘
         │ HTTP POST + SSE
         ▼
┌─────────────────────────┐
│  FastAPI Endpoint       │
│  (add_agent_framework_  │
│   fastapi_endpoint)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  AgentFrameworkAgent    │
│  (Protocol Wrapper)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Orchestrators          │
│  (Execution Flow Logic) │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Agent              │
│  (Agent Framework)      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Chat Client            │
│  (Azure OpenAI, etc.)   │
└─────────────────────────┘

Componenti chiave

  • Endpoint FastAPI: endpoint HTTP che gestisce il flusso SSE e il routing delle richieste
  • AgentFrameworkAgent: wrapper leggero che adatta gli agenti di Agent Framework al protocollo di AG-UI
  • Agenti di orchestrazione: gestire flussi di esecuzione diversi (impostazione predefinita, human-in-the-loop, gestione dello stato)
  • Event Bridge: converte gli eventi di Agent Framework in eventi di protocollo AG-UI
  • Adattatori messaggi: conversione bidirezionale tra AG-UI e formati di messaggio di Agent Framework
  • Strategie di conferma: strategie estendibili per i messaggi di conferma specifici del dominio

Modalità di conversione di Agent Framework in AG-UI

Comprendere il mapping dei concetti di Agent Framework alle AG-UI consente di creare integrazioni efficaci:

Concetto di framework dell'agente AG-UI equivalente Description
Agent Endpoint agente Ogni agente diventa un endpoint HTTP
agent.run() Richiesta HTTP POST Il client invia messaggi tramite HTTP
agent.run(..., stream=True) SSE (Server-Sent Event) Streaming di risposte tramite SSE
Aggiornamenti delle risposte dell'agente Eventi AG-UI TEXT_MESSAGE_CONTENT, TOOL_CALL_STARTe così via.
Strumenti per le funzioni (@tool) Strumenti back-end Eseguito nel server, i risultati trasmessi al client
Modalità di approvazione dello strumento Interazione Umana nel Loop Richieste/risposte di approvazione tramite protocollo
Cronologia conversazioni Gestione dei thread threadId gestisce il contesto tra le richieste

Installazione

Installare il pacchetto di integrazione AG-UI:

pip install agent-framework-ag-ui --pre

In questo modo vengono installati sia il framework dell'agente principale che i componenti di integrazione AG-UI.

Passaggi successivi

Per iniziare a usare AG-UI integrazione:

  1. Introduzione: Creare il primo server AG-UI e il client
  2. Rendering degli strumenti del back-end: Aggiungi strumenti funzionali ai tuoi agenti

Risorse aggiuntive

  • Last updated on