Il tuo agente AI funziona alla grande per i primi 10 passi.
Poi, verso il passo 15, inizia a diventare approssimativo.
Chiamate di strumenti sbagliate. Dimentica le tue istruzioni originali. Output di bassa qualità.
La maggior parte delle persone incolpa il modello.
Quasi mai è colpa del modello.
È quello che il modello sta vedendo.
Organizzare ciò che il modello vede si chiama ingegneria del contesto.
Sta diventando rapidamente la competenza più importante per chiunque costruisca agenti AI.
Ecco il manuale completo.
L'ingegneria dei prompt è morta. L'ingegneria del contesto è ciò che conta ora.
Hai sentito parlare dell'ingegneria dei prompt.
Scrivere istruzioni chiare. Buoni esempi. Dire al modello che ruolo interpretare.
Funziona perfettamente per un chatbot.
Smette di funzionare nel momento in cui costruisci un agente.
Ecco perché.
Un chatbot risponde a una domanda e si ferma.
Un agente esegue azioni — navigare sul web, chiamare API, scrivere codice, eseguire comandi — passo dopo passo dopo passo, a volte per dozzine di passi.
Ogni singolo passo produce un output che viene aggiunto al contesto del modello.
E quel contesto è finito.
Il team di ingegneria di Anthropic lo definisce così:
"Il contesto è l'insieme di token inclusi quando campioni da un LLM. L'ingegneria del contesto è l'ottimizzazione dell'utilità di quei token per ottenere costantemente un risultato desiderato."
In parole povere: assicurati che il tuo agente veda le informazioni giuste, nel formato giusto, al momento giusto.
L'ingegneria dei prompt è un sottoinsieme dell'ingegneria del contesto.
L'ingegneria del contesto è tutto.
La finestra di contesto del tuo agente è la RAM. E si sta riempiendo.
LangChain ha l'analogia giusta per questo.
Pensa a un LLM come a un nuovo tipo di sistema operativo.
Il modello è la CPU — fa il pensiero.
La finestra di contesto è la RAM — la memoria di lavoro dove risiede tutto ciò che il modello può attualmente vedere e su cui ragionare.
Proprio come il tuo computer rallenta quando la RAM si riempie, il ragionamento del tuo agente si degrada quando la finestra di contesto è affollata.
Questo si chiama marciume del contesto.
Chroma ha condotto uno studio valutando 18 modelli all'avanguardia — GPT-4.1, Claude 4, Gemini 2.5, Qwen3 e altri.
Le prestazioni di ogni singolo modello sono diminuite all'aumentare della lunghezza degli input.
Non al limite massimo. Ben prima.
Un modello con una finestra da 200.000 token potrebbe mostrare un degrado significativo a 50.000 token.
Il declino è continuo. Non un precipizio.
Perché? I Transformer funzionano facendo sì che ogni token presti attenzione a ogni altro token — creando relazioni n-quadro. Man mano che il contesto cresce, la capacità del modello di mantenere tutte quelle relazioni si assottiglia.
E poi c'è il problema del "Perso nel Mezzo".
Gli LLM mostrano una curva di attenzione a forma di U.
→ Inizio del contesto: ben ricordato
→ Fine del contesto: ben ricordato
→ Metà: ampiamente ignorato
I ricercatori hanno misurato un calo di accuratezza di oltre 30 punti percentuali quando le informazioni rilevanti venivano spostate dall'inizio del contesto al centro.
Le tue istruzioni originali — sepolte sotto 50.000 token di output degli strumenti — di fatto scompaiono.
Gli utenti di Claude Code hanno scoperto che la qualità dell'output si degrada al 40–60% della capacità del contesto. Ben prima di qualsiasi limite massimo.
Cosa compete effettivamente per lo spazio nel contesto del tuo agente
7 categorie. Tutte in lotta per la stessa finestra finita.
1. Prompt di Sistema
L'identità dell'agente. Regole comportamentali. Logica del flusso di controllo. Istruzioni per diversi tipi di attività. In un agente, questo non è solo "sii utile". Può definire l'intera architettura.
2. Definizioni degli Strumenti
Ogni strumento che l'agente potrebbe chiamare necessita di uno schema che descriva cosa fa, quali parametri accetta e quando usarlo.
3. Risultati delle Chiamate agli Strumenti
Ogni chiamata a uno strumento aggiunge il suo output al contesto. Un recupero di una pagina web: 5.000–10.000 token. Una lettura di un file: simile. Questi si accumulano rapidamente.
4. Conoscenza Recuperata (RAG)
Documenti estratti da database vettoriali, risultati di ricerca, risposte API — qualsiasi cosa recuperata per informare le decisioni dell'agente.
5. Cronologia della Conversazione
La trascrizione completa di tutto ciò che è successo. Messaggi dell'utente, risposte dell'agente, ragionamenti, decisioni precedenti. Cresce linearmente con ogni turno.
6. Memoria
Memoria a breve termine della sessione corrente. Memoria a lungo termine delle sessioni precedenti — preferenze dell'utente, risultati precedenti, modelli appresi.
7. Stato dell'Agente
Piano corrente, lista delle cose da fare, indicatori di progresso, note del blocco appunti. Le meta-informazioni che tracciano dove si trova l'agente in un'attività multi-step.
Tutti e 7 in competizione per la stessa finestra.
L'ingegneria del contesto significa decidere cosa vince.
Le 4 Strategie Fondamentali
LangChain ha pubblicato il framework che organizza ogni tecnica di ingegneria del contesto in 4 categorie.
Ogni tecnica che imparerai mai si inserisce in una di queste.
Scrivi. Seleziona. Comprimi. Isola.
Strategia 1 — Scrivi (Gli agenti dimenticano. Dai loro un modo per ricordare.)
Quando il contesto di un agente si riempie e viene compattato, perde informazioni.
Se l'agente non ha scritto nulla prima che ciò accadesse — quelle informazioni sono perse per sempre.
Scrivi significa dare all'agente dei modi per preservare le informazioni al di fuori della finestra di contesto.
Tre forme:
Blocchi Appunti (Scratchpads)
Dai all'agente uno strumento che gli permetta di prendere appunti durante un'attività. Risultati intermedi. Decisioni prese. Informazioni che sa di dover utilizzare in seguito.
Anthropic ha costruito uno strumento "pensa" — uno spazio dedicato per Claude per elaborare i problemi.
Sul benchmark tau-bench, questo ha migliorato le prestazioni fino al 54% in alcune attività.
File di Regole
Memoria procedurale persistente.
Se hai usato Claude Code, hai visto CLAUDE.md.
Istruzioni caricate all'inizio di ogni sessione — architettura del progetto, convenzioni, come eseguire i test, a cosa prestare attenzione.
L'agente lo legge ogni volta che inizia.
Non dimentica mai le basi.
Estrazione della Memoria
L'agente salva fatti, preferenze dell'utente e modelli appresi in modo da poterli recuperare tra le sessioni.
Vive interamente al di fuori della finestra di contesto.
Le informazioni di cui l'agente avrà bisogno domani sono lì ad aspettarlo quando arriverà domani.
Strategia 2 — Seleziona (Non dare tutto all'agente. Dagli solo ciò di cui ha bisogno in questo momento.)
Un agente con 40 strumenti, una vasta base di conoscenza e diverse sessioni di cronologia non può caricare tutto in una volta.
Qualcosa deve decidere cosa è rilevante per questo passo.
RAG Tradizionale: lo decide il sistema.
Utente chiede → recupera documenti → inserisci nel prompt → fatto.
Statico. Unico colpo. Il modello non ha voce in capitolo.
RAG Agentico: lo decide l'agente. Cerca ciò di cui ha bisogno, perfeziona le query, sceglie gli strumenti, determina quando ha informazioni sufficienti.
Il recupero come processo iterativo, non come pipeline a colpo singolo.
Questo è importante perché ciò che è rilevante cambia a ogni passo — e solo l'agente sa cosa gli serve dopo.
Il problema della selezione degli strumenti è quello che fa inciampare la maggior parte delle persone.
Se il tuo agente ha 40+ strumenti, potenzialmente sono 10.000 token di definizioni di strumenti che occupano spazio nel contesto prima ancora che inizi qualsiasi lavoro.
La soluzione: RAG sulle descrizioni degli strumenti.
Invece di scaricare tutte le definizioni degli strumenti in ogni chiamata, usa la ricerca semantica per far emergere solo gli strumenti rilevanti per il passo corrente.
Un documento chiamato RAG-MCP ha testato questa idea.
Accuratezza della selezione degli strumenti: dal 14% al 43% (miglioramento di 3 volte). Utilizzo dei token: ridotto circa della metà.
Anthropic la chiama una strategia ibrida: carica il contesto essenziale in anticipo (come CLAUDE.md), lascia che l'agente faccia il recupero just-in-time per tutto il resto.
Carica le basi in anticipo. Recupera il resto su richiesta.
Strategia 3 — Comprimi (Il contesto si accumula. Mantieni il significato, taglia i token.)
Anche con una buona selezione, il contesto si accumula.
Ogni chiamata a uno strumento, documento recuperato e decisione rimane nella finestra.
Immagina che il tuo agente abbia effettuato 20 chiamate a strumenti.
Contesto: 80.000 token di output accumulati degli strumenti, cronologia della conversazione, tracce di ragionamento.
La maggior parte di ciò non è più rilevante. L'agente ha già agito su di esso.
Ma è ancora lì, occupa spazio, degrada l'attenzione, aumenta i costi e la latenza.
Puoi comprimere in 3 punti.
Prima che le informazioni entrino nel contesto:
→ Suddividi i documenti grandi in pezzi coerenti prima del recupero
→ Riordina in modo che solo i pezzi più utili entrino
→ Riepiloga gli output degli strumenti al volo prima che entrino nel contesto principale
Mentre l'agente sta lavorando:
→ Riepilogo continuo della cronologia della conversazione — aggiornato continuamente
→ Ibrido popolare: mantieni gli ultimi 10 messaggi testuali + riepiloga tutto ciò che è più vecchio
→ Taglio rigido: rimuovi i messaggi più vecchi una volta che il contesto raggiunge una soglia di dimensione
→ Compattazione automatica di Claude Code: si attiva al 95% di capacità, riepiloga automaticamente l'intera traiettoria
Dopo che l'agente ha agito su qualcosa:
→ Cancellazione dei risultati degli strumenti: una volta che un risultato di uno strumento è stato utilizzato 15 passi fa, eliminalo
→ Sostituisci con un riepilogo di una riga o rimuovi completamente
→ L'agente non ha bisogno del testo completo di una pagina web che ha recuperato 20 passi fa
L'obiettivo: ridurre il conteggio dei token. Preservare ciò che conta davvero.
Strategia 4 — Isola (La strategia più potente. Abilita i sistemi multi-agente.)
Ecco il problema più profondo con le lunghe esecuzioni degli agenti.
Non è solo lo spazio. È la contaminazione.
Le ricerche dettagliate dei file della fase di ricerca sono ancora nel contesto quando l'agente passa a scrivere codice.
Il vecchio contesto di ricerca ora è rumore. Distrae il modello durante una fase in cui deve concentrarsi sull'implementazione pulita.
Isolare significa dare alle diverse parti del lavoro le proprie finestre di contesto separate.
Sub-agenti
Un agente genitore delega un sotto-compito mirato — "cerca nel codebase tutti i file relativi all'autenticazione" — a un sub-agente.
Il sub-agente lavora nella sua finestra di contesto pulita.
Quando riporta i risultati, restituisce solo un riepilogo condensato.
Tutte le operazioni di ricerca disordinate rimangono isolate nel contesto del sub-agente e non inquinano mai il genitore.
Isolamento dello schema di stato (l'approccio di LangGraph)
Progetta lo stato dell'agente in modo che diversi campi memorizzino diversi tipi di contesto.
L'LLM vede solo i campi rilevanti per il passo corrente.
I risultati degli strumenti risiedono in un campo "dietro le quinte" — invisibili al modello finché non vengono esplicitamente portati alla luce.
Controllo granulare su ciò che l'agente vede in ogni fase senza dover creare sub-agenti separati.
L'isolamento è ciò che rende effettivamente affidabili i flussi di lavoro complessi multi-step.
Lavori diversi. Finestre di contesto diverse. Nessuna contaminazione.
4 Modi in cui gli Agenti Falliscono (Dai un nome al fallimento. Risolvilo.)
Drew Breunig ha identificato quattro distinte modalità di fallimento man mano che il contesto dell'agente cresce.
Ogni agente rotto che tu abbia mai visto rientra in una di queste.
Fallimento 1: Avvelenamento del Contesto
Un'allucinazione o un errore entra nel contesto.
L'agente vi fa riferimento ancora e ancora nei passaggi successivi.
Dati errati del passo 5 si accumulano in ogni passo successivo.
Soluzione: Convalida gli output degli strumenti prima che entrino nel contesto. Dopo esserti ripreso da un errore, comprimi la cronologia del tentativo fallito. Non lasciare 10 passi di debugging senza uscita visibili quando solo la risoluzione è importante.
━━━
Fallimento 2: Distrazione del Contesto
Il contesto diventa così lungo che il modello inizia a fare eccessivo affidamento sulla cronologia recente.
Invece di sintetizzare un piano nuovo, si limita a ripetere ciò che ha fatto di recente.
Smette di pensare. Inizia a ripetersi.
Soluzione: Riepiloga e pota in modo aggressivo. Anche quando hai a disposizione una grande finestra di contesto. Finestra grande non significa riempirla.
━━━
Fallimento 3: Confusione del Contesto
Il contenuto superfluo porta il modello a decisioni di bassa qualità.
Esempio classico: un modello fallisce in un benchmark quando gli vengono dati 46 strumenti — anche se il contesto era ben entro i limiti — ma funziona bene con solo 19 strumenti.
Gli strumenti non erano troppi per essere contenuti nel contesto.
Erano troppi perché il modello potesse ragionare chiaramente su di essi.
Soluzione: Gestione dinamica degli strumenti. Usa RAG-MCP per far emergere solo gli strumenti rilevanti per il passo corrente. Mantieni il set di strumenti abbinato alla fase corrente.
━━━
Fallimento 4: Conflitto di Contesto
Nuove informazioni contraddicono qualcosa già presente nel contesto.
Il prompt di sistema dice una cosa. Un documento recuperato dice qualcosa di diverso.
L'agente non riesce a conciliare la contraddizione. Produce un comportamento incoerente.
Soluzione: Stabilisci un chiaro ordinamento dell'autorità. Prompt di sistema > fatti recuperati > cronologia della conversazione. Convalida le nuove informazioni rispetto al contesto esistente prima di iniettarle. Usa tag XML e intestazioni chiare in modo che il modello sappia a quale fonte fidarsi.
Come Scrivere Prompt di Sistema per Agenti (Non chatbot. Agenti.)
Il prompt di sistema di un chatbot imposta un tono.
"Sei un assistente utile. Sii conciso e amichevole."
Il prompt di sistema di un agente definisce l'architettura.
Specifica il flusso di controllo — come affrontare i tipi di attività, quali strumenti usare quando, cosa fare in caso di errori, quali linee guida seguire.
È più simile a scrivere una descrizione del lavoro per un dipendente autonomo che a un prompt di personalità.
Anthropic lo chiama scrivere alla "giusta altitudine".
Troppo prescrittivo:"Se l'utente menziona la fatturazione E menziona un rimborso E l'importo è superiore a $100, chiama lo strumento X." Fragile. Si rompe su ogni caso limite che non hai previsto.
Troppo vago:"Sii utile e usa gli strumenti appropriati." Non dà nulla all'agente. Non può prendere buone decisioni autonome senza segnali concreti.
Il punto ideale:Sufficientemente specifico per guidare il comportamento autonomo. Abbastanza flessibile perché il modello possa applicare il giudizio in situazioni nuove. Euristiche forti. Non regole rigide.
Consigli pratici:
→ Organizza con tag XML o intestazioni markdown — Background, Istruzioni, Guida agli Strumenti
→ Inizia in modo minimale e itera sui fallimenti — non cercare di anticipare ogni caso limite in anticipo
→ Minimale non significa breve — un prompt di sistema per un agente complesso può essere di migliaia di token e va bene finché ogni token guadagna il suo posto
→ Usa esempi few-shot — mostra all'agente come si presenta un buon comportamento invece di cercare di descrivere ogni regola a parole
La KV-Cache: Il motivo $$$ per preoccuparsi dell'ordine del contesto
La maggior parte dei costruttori di agenti non sa che esiste.
Quando invii token a un LLM, il modello calcola rappresentazioni chiave-valore per ogni token.
Computazionalmente costoso.
Quindi i provider di inferenza memorizzano nella cache queste rappresentazioni.
Se l'inizio del tuo contesto — il prefisso — rimane lo stesso tra le chiamate API, il provider riutilizza la computazione memorizzata nella cache e processa solo i nuovi token alla fine.
Veloce. Economico.
Ma se riorganizzi o modifichi la parte iniziale del tuo contesto tra le chiamate — invalidi la cache. Il provider ricalcola tutto da capo.
La differenza di costo su Claude Sonnet:
→ Token di input memorizzati nella cache: $0,30 per milione
→ Token di input non memorizzati nella cache: $3,00 per milione
Differenza di 10 volte.
Per un agente che effettua 30–40 chiamate API per attività, questo si accumula rapidamente.
Regole pratiche per l'efficienza della KV-cache:
→ Il contenuto stabile va all'INIZIO del contesto — prompt di sistema, definizioni degli strumenti, tutto ciò che non cambia tra i turni
→ Il contenuto dinamico va alla FINE — cronologia della conversazione, passo corrente, stato dell'agente → Non aggiungere e rimuovere dinamicamente strumenti a metà conversazione — invalida la cache
→ Usa il mascheramento degli strumenti invece della rimozione degli strumenti — mantieni tutte le definizioni degli strumenti stabili nel prefisso (memorizzate nella cache), segna solo quelli irrilevanti come non disponibili per la fase corrente
Il Flusso di Lavoro che Pubblica 35.000 Righe di Codice in 7 Ore
Dex Horthy (CEO di HumanLayer) ha presentato questo al AI Engineer Code Summit.
Il suo team lo ha utilizzato per pubblicare circa 35.000 righe di codice in un grande codebase Rust in una singola sessione di 7 ore.
Il metodo: Compattazione Intenzionale Frequente.
Struttura il lavoro dell'agente in fasi. Ogni fase produce un artefatto compattato. Ogni nuova fase inizia con una finestra di contesto fresca contenente solo quell'artefatto.
Rimani deliberatamente al di sotto del 40–60% della finestra di contesto in ogni momento.
Fase 1 — Ricerca
I sub-agenti esplorano il codebase. Leggono file. Tracciano i flussi di dati. Mappano l'architettura.
Tutti i disordinati risultati di grep e i contenuti dei file rimangono nei contesti dei sub-agenti. Non toccano mai il genitore. (Isola)
Output: un research.md compatto — percorsi dei file, firme delle funzioni, modelli, insidie. (Scrivi)
Reset del contesto: la ricerca grezza utilizzava il 60–80% della finestra. L'artefatto di ricerca lo comprime al 15–20%. (Comprimi)
Fase 2 — Pianificazione
Nuova finestra di contesto. Contiene solo: documento di ricerca + definizione del problema.
L'agente produce un piano di implementazione dettagliato.
Questo è il punto di controllo di revisione umana più importante.
Cattura qui gli errori logici dove risolverli è facile e gratuito. Più tardi costa ore.
Fase 3 — Implementazione
Un'altra finestra di contesto fresca. Contiene solo: il piano.
L'agente lo segue passo dopo passo.
Per attività complesse: un progress.md tiene traccia di ciò che è stato completato e di ciò che rimane. (Scrivi)
Il risultato: un agente pulito e concentrato in ogni fase. Nessuna contaminazione. Nessun marciume del contesto. Nessun "passo 20 approssimativo".
Come le migliori piattaforme gestiscono questo in modo diverso
Claude Code
Recupero ibrido. CLAUDE.md viene caricato all'inizio. Strumenti come glob e grep gestiscono la navigazione just-in-time del codebase.
Compattazione automatica al 95% — preserva le decisioni architetturali e i 5 file a cui si è avuto accesso più di recente.
Può creare sub-agenti per sotto-compiti complessi, ciascuno con il proprio contesto pulito.
Filosofia: "fai la cosa più semplice che funziona." Lascia che il modello sia intelligente su ciò di cui ha bisogno e dagli gli strumenti per andare a trovarlo.
Manus
Ordinamento del contesto consapevole della KV-cache: prefisso stabile, suffisso dinamico. Mascheramento degli strumenti, non rimozione.
Pipeline di compressione dell'osservazione — ogni output dello strumento viene processato prima di entrare nel contesto dell'agente.
Lista di cose da fare persistente per il monitoraggio dello stato.
File system come memoria di overflow per il contesto espulso.
Costruito per la scalabilità. Serve centinaia di migliaia di utenti dove l'efficienza è un problema di costo aziendale.
ChatGPT Agent
Approccio prima visivo. L'agente interagisce con un browser GUI.
Screenshot aggiunti al contesto come istantanee visive. Il modello ragiona su ciò che vede.
I token visivi sono costosi, quindi l'agente è selettivo sul numero di screenshot.
Usa RL per apprendere strategie ottimali di utilizzo degli strumenti attraverso migliaia di macchine virtuali, piuttosto che programmarle esplicitamente.
Google ADK
L'approccio architetturale più rigoroso.
Tre principi di progettazione:
- Separare l'archiviazione dalla presentazione — lo stato durevole non è la stessa cosa di ciò che appare in ogni chiamata API
- Trasformazioni esplicite — processori nominati e ordinati che trasformano il contesto in passaggi testabili e componibili
- Ambito del contesto per impostazione predefinita — ogni chiamata al modello vede solo le informazioni minime richieste
Disciplina ingegneristica sulla creazione di prompt.
La pipeline universale del turno dell'agente
Ogni piattaforma seria converge sullo stesso ciclo di 5 passi per turno dell'agente:
→ Raccogli — input utente, cronologia conversazione, risultati strumenti, documenti recuperati, stato agente
→ Seleziona — cosa è rilevante per questo passo nel budget di token rimanente
→ Comprimi — riepiloga, tronca o ristruttura per adattarlo al contesto
→ Disponi — contenuto stabile prima (cache), contenuto dinamico dopo
→ Assembla e chiama — contesto finale → chiamata API → ottieni output → ciclo
Questo è il ciclo che gira all'interno di ogni agente di produzione che tu abbia mai usato.
Comprenderlo è ciò che separa i costruttori che pubblicano agenti affidabili dai costruttori che si chiedono perché il loro agente diventi approssimativo al passo 15.
Il riepilogo
Il marciume del contesto è reale e inizia ben prima del limite di contesto.
Le 4 strategie che lo risolvono:
→ Scrivi — persisti le informazioni al di fuori del contesto in modo che gli agenti non dimentichino
→ Seleziona — tira dentro solo ciò che è necessario per questo passo
→ Comprimi — taglia i token, mantieni il significato, in modo proattivo non reattivo
→ Isola — contesti separati per lavori separati, nessuna contaminazione
Le 4 modalità di fallimento da tenere d'occhio:
→ Avvelenamento — i dati errati si accumulano attraverso ogni passo
→ Distrazione — la lunga cronologia fa sì che gli agenti ripetano invece di pensare
→ Confusione — troppi strumenti degradano la qualità delle decisioni
→ Conflitto — le contraddizioni producono un comportamento incoerente
La KV-cache vale un risparmio di costi di 10 volte. Metti prima il contenuto stabile.
Il miglior flusso di lavoro: ricerca → compatta → pianifica → compatta → implementa. Contesto fresco in ogni fase.
L'ingegneria del contesto non è opzionale per il lavoro serio con gli agenti.
È il lavoro stesso.
Se questo è stato utile:
→ Ripubblica per condividerlo con ogni costruttore di agenti che conosci
→ Segui @sairahul1 per altri sistemi che funzionano mentre dormi
→ Aggiungilo ai segnalibri — tornerai al framework delle 4 strategie
Scrivo di AI, costruzione di prodotti e sistemi che funzionano davvero.
