Aggiungere middleware

La pagina precedente ha mostrato come i pacchetti di competenze racchiudano l'esperienza di dominio riutilizzabile — cioè istruzioni, materiale di riferimento e script — in unità autonome che qualsiasi agente può caricare su richiesta. Tuttavia, quando si distribuiscono gli agenti nell'ambiente di produzione, emerge una nuova categoria di problemi: problemi che attraversano ogni interazione indipendentemente dalle operazioni eseguite dall'agente.

È necessario registrare ogni richiesta e risposta. Sono necessarie protezioni che bloccano il contenuto dannoso prima che il modello lo veda. È necessario applicare limiti di frequenza, intercettare le eccezioni normalmente e inserire i dati di telemetria, senza toccare la logica di base dell'agente. Copiare queste questioni in ogni agente (o ogni strumento, o ogni competenza) non è scalabile e crea incubi di manutenzione.

Il middleware risolve questo problema. Il middleware consente di eseguire il wrapping della pipeline di esecuzione dell'agente con comportamenti riutilizzabili che intercettano, controllano e modificano richieste e risposte in punti ben definiti. Si pensi al middleware come una serie di livelli concentrici intorno all'agente: ogni livello può agire sull'input prima che raggiunga l'agente e sull'output prima che raggiunga il chiamante.

Quando usare questa opzione

Aggiungere middleware all'agente quando:

  • È necessario utilizzare barriere di protezione per bloccare i contenuti dannosi, fuori tema o che violano le politiche, prima o dopo che il modello li elabora.
  • Si desidera registrazione centralizzata o telemetria per tutte le interazioni degli agenti senza modificare individualmente ogni agente.
  • È necessario modificare le richieste o le risposte, arricchire le richieste , trasformare gli output o sostituire completamente i risultati, senza modificare la logica dell'agente.
  • Si vogliono applicare criteri come la limitazione della frequenza, il filtro del contenuto o i controlli di autenticazione che si applicano a ogni esecuzione.
  • È necessario gestire le eccezioni in modo coerente: ripetizione di tentativi in caso di errori temporanei, restituzione di risposte di fallback normale o registrazione degli errori per la diagnostica.
  • Si vuole condividere lo stato nella pipeline, ad esempio tenere traccia dei tempi delle richieste o accumulare metriche necessarie a più componenti middleware.

Suggerimento

Agent Framework include la strumentazione predefinita per il tracciamento e le metriche. Per informazioni dettagliate, vedere Observability (in inglese, "Osservabilità").

Come funziona la pipeline middleware

Quando si chiama il metodo run dell'agente, la richiesta non passa direttamente al modello. Passa invece attraverso una pipeline di livelli middleware, ognuno dei quali può esaminare o modificare la richiesta, delegare al livello successivo e quindi controllare o modificare la risposta al ritorno.

┌─────────────────────────────────────────────────────────┐
│  Caller: agent.run("What's the weather?")               │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Middleware 1 (Logging)                                  │
│  • Logs the incoming request                            │
│  • Calls next middleware                                │
│  • Logs the outgoing response                           │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Middleware 2 (Guardrails)                               │
│  • Checks input against content policy                  │
│  • If blocked → returns early with rejection message    │
│  • If allowed → calls next middleware                   │
│  • Checks output against content policy                 │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Agent core (model invocation, tool calls, etc.)        │
└─────────────────────────────────────────────────────────┘

Punti principali:

  1. Ogni middleware decide se continuare. Un middleware può chiamare il livello successivo nella catena per procedere normalmente oppure può interrompere la pipeline restituendo una risposta direttamente, ad esempio quando una protezione blocca una richiesta.
  2. Il middleware vede entrambe le direzioni. Un middleware esegue il codice prima di delegare (per verificare o modificare l'input) e dopo quando la risposta torna (per verificare o modificare l'output). Questo è il classico modello "cipolla".
  3. Molti middleware si concatenano. Quando si registrano diversi componenti middleware, si annidano; il primo middleware registrato è il livello più esterno e l'ultimo registrato è il livello più interno più vicino all'agente.

Suggerimento

Per una visualizzazione dettagliata del modo in cui il middleware rientra nella pipeline di esecuzione completa dell'agente, inclusi i provider di contesto e i livelli client di chat, vedere Architettura della pipeline dell'agente.

Cosa può fare il middleware

Agent Framework supporta il middleware a tre livelli della pipeline, ovvero l'esecuzione dell'agente, la chiamata di funzioni e il client di chat, offrendo un controllo granulare sulla posizione in cui si intercetta l'esecuzione. I modelli comuni includono:

Modello Esempio Riferimento
Guardrail e terminazione Bloccare il contenuto dannoso, limitare la lunghezza della conversazione Chiusura & Linee guida di sicurezza
Gestione delle eccezioni Riprovare in caso di errori transitori, restituire risposte di fallback Gestione delle eccezioni
Sostituzioni dei risultati Redigere dati sensibili, arricchire o sostituire l'output dell'agente Sostituzione dei risultati
Stato condiviso Trasmettere ID della richiesta o dati temporali tra middleware Stato condiviso
Contesto di runtime Variare il comportamento in base alla sessione, all'utente o alla configurazione per esecuzione Contesto di runtime
Definizione dell'ambito Applicare il middleware a tutte le esecuzioni o solo a una singola esecuzione Agent vs Run Scope

Per una procedura dettagliata completa per la definizione e la registrazione del middleware, vedere Definizione del middleware. Per la panoramica completa dell'architettura, vedere la Panoramica del Middleware.

Considerazioni

Considerazione dettagli
Separazione delle responsabilità Il middleware mantiene la logica trasversale fuori dal codice dell'agente, dagli strumenti e dalle competenze. Ogni componente middleware ha una singola responsabilità, ovvero registrazione, protezioni, gestione degli errori, che è possibile aggiungere, rimuovere o riordinare in modo indipendente.
Dipendenza dell'ordine Il middleware costituisce una catena. L'ordine in cui si registra il middleware è importante: un middleware di registrazione che viene eseguito per primo vedrà l'input non elaborato, mentre quello eseguito per ultimo vedrà l'input già modificato dal middleware precedente. Pianifica con attenzione l'ordine della pipeline.
Analisi della complessità Quando il middleware modifica input o output, il debug richiede la comprensione della pipeline completa. Una risposta potrebbe sembrare errata non a causa dell'agente, ma perché un middleware lo ha trasformato. Un buon middleware di registrazione (posizionato all'inizio della catena) consente di diagnosticare questi casi.
Sovraccarico delle prestazioni Ogni livello middleware aggiunge tempo di elaborazione a ogni richiesta. Per operazioni leggere come la registrazione, ciò è trascurabile. Per operazioni dispendiose come la chiamata di un'API di moderazione del contenuto esterno, la latenza aumenta, soprattutto quando più middleware sono concatenati.

Passaggi successivi

Ora che l'agente dispone di strumenti, competenze e middleware, il passaggio successivo è costituito dai provider di contesto , ovvero componenti che inseriscono memoria, profili utente e conoscenze dinamiche nella finestra di contesto dell'agente prima di ogni esecuzione.

Provider di contesto

Approfondimento:

  • Last updated on