Architettura dell'Assistente AI: LLM, Memoria, Strumenti, Routing, Osservabilità

Un assistente AI in produzione non è “un LLM con un prompt”. È un sistema che accetta l’intento, mantiene lo stato, decide quando recuperare dati o agire ed espone dettagli sufficienti sul runtime per eseguire il debug delle anomalie.

Questa visione a livello di sistema è ciò che il cluster AI Systems esplora quando gli assistenti vanno oltre una singola invocazione di modello.

OpenAI descrive gli agenti come applicazioni che pianificano, chiamano strumenti, collaborano e mantengono uno stato sufficiente per lavori multi-step, mentre Anthropic inquadra lo stesso problema come un sistema gestito che può eseguire file, comandi, accesso web e codice in modo sicuro.

L’architettura più pulita divide le responsabilità in cinque livelli: LLM, Memoria, Strumenti (Tooling), Routing e Osservabilità. Questa divisione si allinea alle capacità esposte dalle API principali dei provider, da MCP, dai runtime auto-gestiti come vLLM e llama.cpp e dai veri sistemi di assistenza come OpenClaw e Hermes.

La memoria dovrebbe essere trattata come qualcosa di più del “contesto più lungo”. I sistemi di recupero trasformano la conoscenza esterna in memoria non parametrica esplicita — lo stesso spazio di progettazione approfondito in Retrieval-Augmented Generation (RAG) — e sia le linee guida sul contesto di Anthropic che il paper “Lost in the Middle” avvertono che semplicemente imballare più token nel contesto non garantisce un recupero affidabile.

L’uso degli strumenti è un confine contrattuale, non magia. La chiamata di funzioni di OpenAI, l’uso di strumenti di Anthropic e MCP si basano tutti sullo stesso schema: il modello emette una richiesta strutturata, un runtime la esegue e il risultato fluisce di nuovo nella conversazione. Se quel confine è approssimativo, l’assistente diventa approssimativo.

Il mio pregiudizio è semplice: inizia con l’essenziale. Un orchestratore, un percorso di memoria durevole, un trace per richiesta e una politica esplicita per l’esecuzione degli strumenti. I grafici multi-agente sono utili, ma solo dopo che puoi spiegare i casi di fallimento del tuo singolo agente senza indovinare.

Cos’è un sistema di assistenza AI

Una definizione pratica è questa: un sistema di assistenza AI è un runtime che trasforma l’intento dell’utente in una risposta o azione combinando un’interfaccia del modello, l’assemblaggio del contesto, l’esecuzione degli strumenti, la gestione dello stato e la telemetria. Ecco perché la documentazione utile non è solo costituita da schede del modello. La documentazione utile è costituita da riferimenti API, contratti degli strumenti, guide al recupero, documenti sul routing e documenti sui trace. L’API Responses di OpenAI espone interazioni con stato, strumenti integrati e chiamate di funzione. L’API Claude di Anthropic espone l’accesso diretto ai messaggi così come gli Agenti Gestiti. OpenClaw e Hermes vanno un passo oltre e mostrano cosa accade quando si mettono queste capacità dietro gateway persistenti, canali, sessioni e memoria.

In altre parole, un sistema di assistenza ha un contratto più ampio rispetto a un completamento della chat. Un buon contratto interno assomiglia a questo:

AssistantRequest  = intento dell'utente + identità + sessione + allegati + policy
AssistantResponse = risposta + azioni + citazioni + cambiamenti di stato + ID trace

Questo contratto è importante perché ogni disaccordo in produzione si riduce eventualmente a una di queste domande: quale contesto era visibile, quale strumento ha eseguito, quale modello ha risposto, quale memoria è stata letta o scritta e dove il trace indica che il sistema ha passato il tempo. OpenTelemetry definisce i trace come il percorso di una richiesta attraverso un’applicazione, che è esattamente l’astrazione di cui gli assistenti seri hanno bisogno. LangSmith e OpenLIT specializzano poi questa idea per LLM, strumenti, archivi vettoriali e flussi di lavoro degli agenti.

Componenti principali e interfacce

La suddivisione dei componenti qui sotto è quella che trovo più duratura. È anche la suddivisione che si allinea meglio con le API ufficiali e i runtime open-source che le persone effettivamente gestiscono.

La tabella sopra è derivata dalle interfacce ufficiali dei provider, da MCP, dalla documentazione dei database vettoriali e dalla documentazione dei runtime per vLLM, llama.cpp, OpenClaw e Hermes.

Il livello LLM dovrebbe fare bene tre cose: consumare un contesto di lavoro corrente, emettere o una risposta finale o una richiesta di azione strutturata e restituire metadati sufficienti per supportare i tentativi e il tracciamento. L’API Responses di OpenAI è esplicitamente progettata per interazioni con stato, strumenti integrati e chiamate di funzione. L’API Messages di Anthropic espone lo stesso ciclo principale attraverso blocchi tool_use e restituzioni tool_result, mentre gli Agenti Gestiti ti offrono un sistema ospitato se non vuoi costruire il ciclo da solo. I runtime auto-gestiti come vLLM e llama.cpp sono importanti perché preservano interfacce simili a quelle dei provider consentendoti di posizionare l’inferenza all’interno del tuo ambiente.

Il livello Memoria dovrebbe essere diviso mentalmente in tre categorie: memoria di lavoro, memoria simbolica durevole e memoria semantica ricercabile. Gli embedding di OpenAI restituiscono vettori che possono essere indicizzati e cercati; Retrieval e File Search di OpenAI stratificano poi la ricerca semantica e per parole chiave sugli archivi vettoriali. Pinecone, Weaviate, pgvector e Milvus rappresentano quattro forme di archiviazione comuni: completamente gestita, database vettoriale open-source, nativo Postgres e database vettoriale distribuito. Hermes e OpenClaw aggiungono un utile promemoria che non tutta la memoria appartiene a un archivio vettoriale: note basate su file, promozioni revisionate e snapshot limitati alla sessione sono spesso il design più onesto — schemi spiegati in Sistema di Memoria dell’Agente Hermes per la memoria centrale limitata e gli snapshot di sessione congelati.

Il livello Strumenti è dove un assistente smette di essere un riassuntore e inizia ad essere software. Le chiamate di funzione di OpenAI trattano gli strumenti come funzionalità definite da schema che il modello può decidere di invocare. Anthropic dice la stessa cosa in modo più esplicito: l’uso degli strumenti è un contratto tra la tua applicazione e il modello, e il modello non esegue mai nulla da solo. MCP generalizza quel contratto in un protocollo client-server dove gli host si connettono a uno o più server che espongono strumenti, prompt e risorse — lo stesso confine descritto passo dopo passo in Server MCP in Go. LangChain e LlamaIndex si collocano comodamente qui come librerie di orchestrazione: LangChain si concentra su un’architettura di agente pre-costruita e integrazioni, mentre LlamaIndex si concentra sull’accesso ai dati aumentati dal contesto, motori di query e flussi di lavoro.

Il livello Routing esiste perché “quale modello?” non è mai l’unica domanda. Hai anche bisogno di “quale percorso provider, quale tenant, quale budget, quale classe di latenza e quale fallback?”. LiteLLM è utile perché la sua documentazione ufficiale è sorprendentemente concreta: selezione ponderata, meno occupato, routing basato sulla latenza, basato sui costi e failover limitati sono tutti schemi di prima classe. OpenClaw estende il routing verso l’alto nell’isolamento dei canali e degli agenti, mentre Hermes lo estende verso il basso negli slot del modello per il lavoro principale e ausiliario come la compressione, il riassunto e il routing degli strumenti MCP. Questo è il modello mentale corretto: il router sceglie più di un modello, sceglie una corsia di esecuzione.

Il livello Osservabilità è ciò che impedisce all’architettura di trasformarsi in folklore. OpenTelemetry ti dà l’astrazione del trace. LangSmith ti dà visibilità end-to-end sui passaggi dell’applicazione LLM e supporta forme di distribuzione cloud, ibride e auto-gestite. OpenLIT ti dà osservabilità AI nativa di OpenTelemetry con opzioni di strumentazione zero-code e manuale, incluso il supporto per LLM, framework agent, database vettoriali e GPU. Per metriche di produzione, trace e schemi SLO attraverso i flussi di lavoro di inferenza e agenti, vedi Osservabilità per Sistemi LLM. Se il tuo assistente non ha un trace per richiesta, uno span per chiamata del modello e una cronologia eventi per l’esecuzione degli strumenti, non hai davvero un’architettura. Hai delle sensazioni.

Catturare, arricchire, rispondere

La sequenza che continua a comparire nei sistemi reali è catturare -> arricchire -> rispondere -> registrare. Diversi framework la avvolgono in modo diverso, ma il flusso è abbastanza stabile da trattarlo come la spina dorsale.

sequenceDiagram
    participant U as Utente o Canale
    participant G as Gateway o UI
    participant R as Router
    participant M as Memoria e Recupero
    participant L as LLM
    participant T as Strumenti o MCP
    participant O as Osservabilità

    U->>G: messaggio, file o comando
    G->>O: avvia trace radice
    G->>R: richiesta + identità + sessione + policy
    R->>M: carica stato della sessione e recupera contesto
    M-->>R: note, chunk, metadati
    R->>L: prompt + contesto + schemi degli strumenti
    L-->>R: risposta o chiamata di strumento
    alt chiamata di strumento
        R->>T: esegui strumento o azione MCP
        T-->>R: risultato dello strumento
        R->>L: risultato dello strumento + contesto aggiornato
        L-->>R: risposta finale
    end
    R->>M: persisti cambiamenti della sessione e candidati di memoria
    R->>O: span, metriche, eventi di valutazione
    G-->>U: risposta

Il passaggio di cattura è solitamente più importante di quanto appaia. OpenClaw e Hermes mettono entrambi un gateway persistente davanti all’assistente perché l’ingress non è solo l’inserimento di testo. Include metadati del canale, identità, autorizzazione, confini della sessione, messaggi diretti, gruppi, tick cron e semantiche di consegna. Se salti quel livello e ti affidi a un’astrazione di widget di chat grezza, alla fine lo aggancerai comunque come middleware ad hoc.

Il passaggio di arricchimento è dove i sistemi maturi si differenziano dalle demo giocattolo. Retrieval e File Search di OpenAI rendono il recupero esplicito attraverso archivi vettoriali e chiamate di ricerca. LlamaIndex formalizza lo stesso schema attraverso connettori di dati, indici, motori di query e flussi di lavoro. Hermes va oltre dividendo il parco modelli in slot principali e ausiliari, delegando lavori come compressione, riassunto e routing a modelli più piccoli o specializzati. Questo è uno schema di design da rubare: non spendere i token del tuo modello più costoso per faccende domestiche.

Il passaggio di risposta non è “generare testo”. È “chiudere il ciclo corrente”. Se il modello può rispondere direttamente, lo fa. Se ha bisogno di uno strumento, emette una richiesta strutturata. Il contratto di uso degli strumenti di Anthropic e la guida alle chiamate di funzione di OpenAI rendono questo esplicito. Il motivo per cui questo è importante a livello architetturale è che gli output ora includono sia linguaggio che flusso di controllo. Il tuo oggetto risposta è in parte prosa e in parte piano di runtime.

Il passaggio di registrazione è dove emergono le semantiche di coerenza. Pinecone separa i percorsi di scrittura e lettura e elabora le scritture dopo l’acknowledgement durevole. La memoria di Hermes viene iniettata come uno snapshot congelato per sessione per preservare le prestazioni della cache prefix, il che significa che le nuove scritture non appaiono automaticamente nel prompt della sessione corrente. Il sistema Dreaming di OpenClaw promuove solo candidati revisionati e fondati in MEMORY.md, ed è opt-in piuttosto che sempre attivo. La lezione pratica è che la memoria raramente è veramente read-after-write attraverso ogni livello. Devi progettare per una visibilità a stadi.

OpenClaw e Hermes come sistemi di riferimento

OpenClaw e Hermes sono casi di riferimento utili perché non sono solo wrapper intorno a un’API del provider. Entrambi presentano un assistente come un sistema a lunga esecuzione con gateway, sessioni, strumenti, memoria e più backend del modello.

Questo mapping è basato sulla documentazione e sui repo ufficiali di OpenClaw e Hermes. OpenClaw documenta un’architettura di gateway, routing multi-agente, supporto per provider personalizzati e auto-gestiti inclusi vLLM e Ollama, memoria attiva opzionale e promozione basata su Dreaming. Hermes documenta un gateway di messaggizzazione, un ciclo centrale AIAgent, slot del modello principali e ausiliari, memoria integrata e integrazione MCP nativa.

La mia lettura leggermente opinione è che entrambi i sistemi fanno la stessa argomentazione architetturale con accenti diversi. OpenClaw è fortemente gateway-first. Hermes è fortemente agent-loop-first. Ma entrambi rifiutano l’idea superficiale che un assistente sia solo “prompt più modello”. Modellano canali, identità, semantiche di memoria, superfici degli strumenti e eterogeneità del backend come preoccupazioni di prima classe. Questo è esattamente ciò che un’architettura di produzione dovrebbe fare.

Uno stack ibrido pratico ispirato da entrambi i sistemi assomiglia a questo:

edge:
  gateway: hermes o openclaw

routing:
  proxy: litellm
  policy: consapevole di latenza e budget
  tenancy: limitato a sessione e canale

llm:
  primary: openai responses o anthropic messages
  local_fallback: vllm
  local_dev: ollama o llama.cpp

memory:
  session: sqlite o postgres
  semantic: pgvector o weaviate
  embeddings: openai embeddings o ollama embeddings

tools:
  contract: strumenti schema json più mcp
  examples: filesystem, browser, ricerca web, API interne

observability:
  traces: opentelemetry
  ai_dashboards: openlit o langsmith
  evals: openai evals più set di regressione specifici dell'app

Questo stack è uno schema di distribuzione ragionata piuttosto che una blueprint prescritta dal vendor. Funziona perché le interfacce ufficiali si allineano: OpenAI e Anthropic espongono API orientate agli strumenti, vLLM e llama.cpp emulano endpoint stile provider, Ollama gestisce modelli ed embedding locali, MCP standardizza gli strumenti esterni, LiteLLM gestisce il routing e il failover, e le piattaforme compatibili con OpenTelemetry possono tracciare l’intero percorso.

Schemi, tabelle e compromessi

Ci sono alcuni schemi di assistenza ripetibili che vale la pena nominare. Un assistente gestito mantiene la maggior parte del runtime all’interno delle API del provider. Un assistente retrieval-first tratta memoria e ricerca come il principale differenziale. Un assistente tool-first si comporta più come un operatore che come un chatbot. Un assistente gateway dà priorità all’accesso sempre attivo attraverso le superfici di messaggistica. Una mesh specialistica decompone il lavoro in più agenti o percorsi. I documenti ufficiali di OpenAI, Anthropic, LlamaIndex, LiteLLM, OpenClaw e Hermes supportano versioni di questi schemi, anche se li chiamano diversamente.

Questa tabella degli schemi è una sintesi dai documenti dei provider, dei documenti dei framework e dei sistemi di riferimento, piuttosto che un’affermazione di un singolo vendor.

Note della tabella: File Search ospitato da OpenAI è uno strumento gestito, Anthropic offre un sistema gestito, Pinecone è un servizio vettoriale gestito, mentre vLLM, llama.cpp, Ollama, pgvector, Weaviate, Milvus, LangSmith auto-gestito e OpenLIT supportano tutti operazioni auto-gestite o ibride in vari gradi.

Note della tabella: Pinecone documenta un piano di controllo gestito e piani di dati regionali. Weaviate documenta indici vettoriali e invertiti con più tipi di indice vettoriale. pgvector aggiunge la ricerca esatta e approssimativa del più vicino al Postgres. Milvus si posiziona come un database vettoriale open-source ad alte prestazioni e scalabile, con Zilliz Cloud come opzione gestita.

Note della tabella: OpenAI documenta Responses come la sua interfaccia avanzata per risposte con stato e strumenti integrati. Anthropic documenta l’API Messages e il contratto di uso degli strumenti separatamente dagli Agenti Gestiti. vLLM espone un server compatibile con OpenAI più il supporto per l’API Messages di Anthropic. Ollama documenta flussi di lavoro per embedding e modelli locali. llama.cpp documenta route di chat, risposte ed embedding compatibili con OpenAI, più completamenti di chat compatibili con Anthropic.

Questa matrice dei compromessi è un’inferenza architetturale dai documenti ufficiali, non un benchmark del vendor. La riga della coerenza è più importante di quanto molti post sul blog ammettono: Pinecone separa i percorsi di scrittura e lettura, Hermes congela la memoria nei prompt di avvio della sessione e OpenClaw promuove la memoria durevole attraverso revisioni a stadi. Questo significa che “memoria aggiornata” e “memoria visibile alla risposta corrente” sono spesso verità diverse.

Modalità di fallimento e mitigazioni

La maggior parte degli assistenti non fallisce perché il modello di base è “cattivo”. Falliscono perché il sistema circostante mente al modello, lo priva del contesto giusto, lascia che gli strumenti si discostino o rende impossibile il debug.

La base di evidenze per questa tabella è ampia ma coerente. I documenti degli strumenti di Anthropic rendono chiaro che l’uso degli strumenti è un confine contrattuale. OpenAI Guardrails include il rilevamento delle allucinazioni contro una base di conoscenza di riferimento tramite File Search. SelfCheckGPT mostra che l’auto-coerenza tra i campioni può aiutare a rilevare affermazioni non supportate. I risultati “Lost in the Middle” e le linee guida sul contesto di Anthropic rinforzano entrambe la stessa lezione operativa: più token non rimuovono la necessità di curazione del contesto.

Lo stack di mitigazione preferito potrebbe essere noioso e ripetitivo: traccia ogni richiesta, versioni i prompt, valuta il recupero indipendentemente, mantieni gli strumenti idempotenti ed esegui valutazioni di regressione prima di cambiare percorsi o policy di memoria. I documenti e il repo di Evals di OpenAI sono diretti sul perché: senza valutazioni, è difficile e dispendioso in termini di tempo capire come i cambiamenti del modello o del prompt influenzino il tuo caso d’uso. Questo si applica tanto ai router e al recupero quanto ai prompt.

Letture aggiuntive

Se vuoi approfondire, queste sono le fonti primarie più utili da tenere aperte mentre progetti o revisioni un’architettura di assistenza.

• OpenAI: Panoramica Responses, Chiamata di Funzioni, Uso degli Strumenti, Retrieval, File Search, Evals e MCP per server di strumenti remoti.

• Anthropic: Panoramica API, Uso degli Strumenti, il contratto di uso degli strumenti, Agenti Gestiti, Finestre di Contesto e il connettore MCP.

• MCP stesso: la Panoramica Architetturale e la Specifica valgono la pena essere lette direttamente, perché spiegano host, client, server, strumenti, prompt, risorse, trasporti e negoziazione delle capacità in modo pulito.

• Framework e routing: Panoramica LangChain, documenti di aumento del contesto LlamaIndex, documenti di routing LiteLLM, documenti di osservabilità LangSmith.

• Runtime auto-gestiti e sistemi di assistenza: vLLM, server llama.cpp, embedding Ollama, documenti e repo OpenClaw, documenti e repo Hermes.

• Archiviazione e osservabilità: Pinecone, Weaviate, pgvector, Milvus, OpenTelemetry, OpenLIT.

• Paper di ricerca: Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks, Lost in the Middle e SelfCheckGPT.