Architettura dell'assistente AI: LLM, memoria, strumenti, routing, osservabilità

Un assistente AI di produzione non è “un LLM con un prompt”. È un sistema che accetta l’intento, mantiene lo stato, decide quando recuperare dati o eseguire azioni ed espone dettagli sufficienti a livello di runtime per eseguire il debug dei guasti.

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

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

L’architettura più pulita divide le responsabilità in cinque layer: LLM, Memoria, Tooling (strumenti), Routing (instradamento) e Osservabilità. Questa divisione corrisponde alle capacità esposte dalle API dei principali provider, da MCP, da runtime self-hosted come vLLM e llama.cpp e da sistemi di assistenza reali 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 progettuale coperto in profondità da Retrieval-Augmented Generation (RAG) — e sia le linee guida sul contesto di Anthropic che il paper “Lost in the Middle” avvertono che inserire ciecamente più token nel contesto non garantisce un richiamo affidabile.

L’uso dei tool è un confine contrattuale, non magia. Le chiamate a funzione di OpenAI, l’uso dei tool di Anthropic e MCP si basano tutti sullo stesso schema: il modello emette una richiesta strutturata, un runtime la esegue e il risultato fluisce nuovamente nella conversazione. Se quel confine è disordinato, l’assistente diventa disordinato.

Il mio pregiudizio è semplice: iniziare in modo noioso. Un orchestratore, un percorso di memoria durevole, un trace per richiesta e una politica esplicita per l’esecuzione dei tool. I grafi multi-agente sono utili, ma solo dopo che sei in grado di 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 dei tool, la gestione dello stato e la telemetria. Ecco perché la documentazione utile non è solo costituita da schede del modello (model cards). La documentazione utile comprende riferimenti API, contratti per i tool, guide per il recupero, documenti sul routing e documenti sui trace. L’API Responses di OpenAI espone interazioni con stato, tool integrati e chiamate a funzione. L’API Claude di Anthropic espone l’accesso diretto ai Messages (messaggi) così come gli Agenti Gestiti (Managed Agents). OpenClaw e Hermes vanno un passo oltre e mostrano cosa accade quando si mettono quelle capacità dietro gateway persistenti, canali, sessioni e memoria.

In altre parole, un sistema di assistenza ha un contratto più ampio di una semplice chat completion. Un buon contratto interno assomiglia a questo:

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

Questo contratto è importante perché ogni disaccordo in produzione si riduce in definitiva a una di queste domande: quale contesto era visibile, quale tool è stato eseguito, quale modello ha risposto, quale memoria è stata letta o scritta e dove il trace indica che il sistema ha speso 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 quell’idea per LLM, tool, store vettoriali e flussi di lavoro degli agenti.

Componenti principali e interfacce

La divisione dei componenti di seguito è quella che trovo più durevole. È anche la divisione che si allinea meglio con le API ufficiali e i runtime open-source che le persone operano effettivamente.

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

Il layer LLM dovrebbe fare bene tre cose: consumare un contesto di lavoro corrente, emettere una risposta finale o una richiesta di azione strutturata e restituire metadati sufficienti per supportare i retry e i trace. L’API Responses di OpenAI è esplicitamente progettata per interazioni con stato più tool integrati e chiamate a funzione. L’API Messages di Anthropic espone lo stesso ciclo core attraverso blocchi tool_use e restituzioni tool_result, mentre Managed Agents ti offre un’infrastruttura ospitata se non vuoi costruire il ciclo tu stesso. I runtime self-hosted come vLLM e llama.cpp sono importanti perché preservano interfacce simili a quelle dei provider consentendoti allo stesso tempo di posizionare l’inferenza all’interno del tuo ambiente.

Il layer 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; OpenAI Retrieval e File Search sovrappongono poi la ricerca semantica e per parole chiave sugli store vettoriali. Pinecone, Weaviate, pgvector e Milvus rappresentano quattro forme comuni di archiviazione: completamente gestita, open-source vector-native, Postgres-native e database vettoriale distribuito. Hermes e OpenClaw aggiungono un utile promemoria: non tutta la memoria appartiene a uno store vettoriale: note supportate da file, promozioni revisionate e snapshot dello scope di sessione sono spesso il design più onesto. Memory Systems in AI Assistants mappa il modello cross-framework; Hermes Agent Memory System analizza la memoria core delimitata e gli snapshot di sessione congelati in un prodotto.

Il layer Tooling è dove un assistente smette di essere un riassuntatore e inizia a essere software. Le chiamate a funzione di OpenAI trattano i tool come funzionalità definite da schema che il modello può decidere di invocare. Anthropic dice la stessa cosa in modo più esplicito: l’uso dei tool è 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 espone tool, prompt e risorse — lo stesso confine descritto passo per passo in MCP Server in Go. LangChain e LlamaIndex si inseriscono comodamente qui come librerie di orchestrazione: LangChain si concentra su un’architettura di agente predefinita e integrazioni, mentre LlamaIndex si concentra sull’accesso ai dati aumentato dal contesto, motori di query e flussi di lavoro.

Il layer 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é i suoi documenti ufficiali sono sorprendentemente concreti: selezione ponderata, meno impegnato, routing basato sulla latenza, basato sul costo e failover delimitati sono tutti pattern di primo livello. 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 lavori principali e ausiliari come riassunto, compressione del contesto e routing dei tool MCP. Questo è il modello mentale giusto: il router sceglie più di un modello, sceglie una corsia di esecuzione.

Il layer Osservabilità è ciò che impedisce all’architettura di trasformarsi in folklore. OpenTelemetry ti fornisce l’astrazione del trace. LangSmith ti fornisce visibilità end-to-end sui passaggi delle applicazioni LLM e supporta forme di deployment cloud, ibride e self-hosted. OpenLIT ti fornisce osservabilità AI nativa 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 pattern SLO attraverso inferenza e flussi di lavoro degli agenti, vedi Osservabilità per Sistemi LLM. Se il tuo assistente non ha un trace per richiesta, uno span per chiamata al modello e nessuna cronologia degli eventi per l’esecuzione dei tool, non hai davvero un’architettura. Hai delle “vibes” (impressioni).

Catturare, arricchire, rispondere

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

Il passo di cattura è di solito più importante di quanto appaia. Sia OpenClaw che Hermes pongono un gateway persistente davanti all’assistente perché l’ingress non è solo l’inserimento di testo. Include metadati del canale, identità, autorizzazione, confini di sessione, messaggi diretti, gruppi, tic cron e semantiche di consegna. Se salti quel layer e ti affidi a un’astrazione di widget di chat grezzo, alla fine lo aggancerai di nuovo come middleware ad hoc comunque.

Il passo di arricchimento è dove i sistemi maturi divergono dalle demo giocattolo. OpenAI Retrieval e File Search rendono esplicito il recupero attraverso store 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 più specializzati. Questo è un pattern di progettazione da rubare: non spendere i token del modello più costoso per faccende domestiche.

Il passo di risposta non è “generare testo”. È “chiudere il ciclo corrente”. Se il modello può rispondere direttamente, lo fa. Se ha bisogno di un tool, emette una richiesta strutturata. Il contratto di uso dei tool di Anthropic e la guida alle chiamate a funzione di OpenAI rendono entrambi questo esplicito. Il motivo per cui questo è importante architetturalmente è 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 passo di registrazione è dove appaiono le semantiche di coerenza. Pinecone separa i percorsi di scrittura e lettura e processa le scritture dopo l’acknowledgement durevole. La memoria di Hermes viene iniettata come uno snapshot congelato per sessione per preservare le prestazioni della cache dei prefissi, 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 radicati in MEMORY.md, ed è opzionale piuttosto che sempre attivo. La lezione pratica è che la memoria raramente è veramente read-after-write (lettura dopo scrittura) attraverso ogni layer. 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 di provider. Entrambi presentano un assistente come un sistema a lunga esecuzione con gateway, sessioni, tool, memoria e più backend di modello.

Questo mapping si basa sui documenti e repo ufficiali di OpenClaw e Hermes. OpenClaw documenta un’architettura gateway, routing multi-agente, supporto provider personalizzato e self-hosted incluso vLLM e Ollama, memoria attiva opzionale e promozione basata su Dreaming. Hermes documenta un gateway di messaggio, un loop centrale AIAgent, slot di modello principali e ausiliari, memoria integrata e integrazione MCP nativa.

La mia lettura leggermente opinata è che entrambi i sistemi fanno lo stesso argomento 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 dei tool e eterogeneità dei backend come preoccupazioni di primo livello. 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 or openclaw

routing:
  proxy: litellm
  policy: latency and budget aware
  tenancy: session and channel scoped

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

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

tools:
  contract: json schema tools plus mcp
  examples: filesystem, browser, web search, internal APIs

observability:
  traces: opentelemetry
  ai_dashboards: openlit or langsmith
  evals: openai evals plus app-specific regression sets

Questo stack è un pattern di deployment ragionevole piuttosto che una blueprint prescritta dal vendor. Funziona perché le interfacce ufficiali si allineano: OpenAI e Anthropic espone API orientate ai tool, vLLM e llama.cpp emulano endpoint stile provider, Ollama gestisce modelli e embedding locali, MCP standardizza i tool esterni, LiteLLM gestisce routing e failover, e piattaforme compatibili con OpenTelemetry possono tracciare l’intero percorso.

Pattern, tabelle e compromessi

Ci sono alcuni pattern di assistente ripetibili da 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 differenziatore principale. Un assistente tool-first si comporta più come un operatore che come un chatbot. Un assistente gateway priorizza l’accesso sempre attivo attraverso superfici di messaggio. Una mesh di specialisti decompone il lavoro in più agenti o route. I documenti ufficiali su OpenAI, Anthropic, LlamaIndex, LiteLLM, OpenClaw e Hermes supportano tutti versioni di questi pattern, anche se li chiamano diversamente.

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

Note della tabella: OpenAI hosted File Search è un tool gestito, Anthropic offre un’infrastruttura gestita, Pinecone è un servizio vettoriale gestito, mentre vLLM, llama.cpp, Ollama, pgvector, Weaviate, Milvus, LangSmith self-hosted e OpenLIT supportano tutti operazioni self-managed 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 del vicino più prossimo esatta e approssimativa a 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 tool integrati. Anthropic documenta l’API Messages e il contratto di uso dei tool separatamente da Managed Agents. vLLM espone un server compatibile OpenAI più il supporto API Messages Anthropic. Ollama documenta flussi di lavoro di embedding e modelli locali. llama.cpp documenta route di chat, risposte e embedding compatibili OpenAI, più completamenti della chat compatibili Anthropic.

Questa matrice dei compromessi è un’inferenza architetturale dai documenti ufficiali, non un benchmark del vendor. La riga della coerenza è più importante di quanto ammettono molti post di blog: Pinecone separa i percorsi di scrittura e lettura, Hermes congela la memoria nei prompt dell’inizio 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 base è “cattivo”. Falliscono perché il sistema circostante mente al modello, gli affama il contesto giusto, lascia che i tool derivino o rende impossibile il debug.

La base di prove per questa tabella è ampia ma coerente. I documenti dei tool di Anthropic chiariscono che l’uso dei tool è 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 di “Lost in the Middle” e le linee guida sul contesto di Anthropic rafforzano entrambi 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, versiona i prompt, valuta il recupero in modo indipendente, mantieni i tool idempotenti ed esegui eval di regressione prima di cambiare route o politica della memoria. I documenti e il repo di Evals di OpenAI sono diretti sul perché: senza eval, è 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 al routing 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 assistente.

• OpenAI: Panoramica Responses, Chiamate a Funzione, Uso dei Tool, Retrieval, File Search, Evals e MCP per server tool remoti.

• Anthropic: Panoramica API, Uso dei Tool, il contratto di uso dei tool, 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, tool, 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 self-hosted 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.