Context Engineering per agenti IA: cosa entra davvero nella finestra di contesto

Indice

Pubblicato ad agosto 2026.

TL;DR: Il context engineering è la disciplina di decidere quali token si guadagnano un posto nella finestra di contesto di un agente a ogni passaggio — istruzioni di sistema, definizioni degli strumenti, dati recuperati e cronologia della conversazione competono tutti per lo stesso spazio limitato. Il prompt engineering chiede come formulo questo; il context engineering chiede cosa deve sapere davvero il modello adesso. La modalità di fallimento di solito non è troppo poco contesto — è troppo: cronologia obsoleta, schemi di strumenti irrilevanti e documenti recuperati che nessuno ha chiesto, tutto ciò diluisce il segnale e fa salire i costi. Applico un budget fisso per categoria, taglio la cronologia prima dell’identità, e riassumo prima di troncare.

Lettura dell’operatore: Gli agenti più difficili da debuggare non fallivano perché il modello era debole. Fallivano perché avevo lasciato che la finestra di contesto diventasse un cassetto disordinato: sei schemi di strumenti che il compito non richiedeva, una cronologia della conversazione che si era allontanata di 40 turni dalla richiesta originale, un documento recuperato tecnicamente rilevante e praticamente inutile. Sistemare il prompt non aiutava. Sistemare ciò che stava davanti al prompt, sì.

Il prompt engineering ti ha dato un agente funzionante. Il context engineering è ciò che lo mantiene funzionante quando gestisce volumi reali, cronologia reale e casi limite reali — ed è la competenza a cui ormai dedico più tempo rispetto alla formulazione del prompt.

Prompt engineering e context engineering non sono lo stesso lavoro

Un prompt è un’istruzione. Il contesto è tutto ciò che il modello vede quando agisce su quell’istruzione: il prompt di sistema, gli strumenti che può chiamare, ciò che hai recuperato o consultato, e quanta conversazione o cronologia di esecuzioni precedenti hai deciso di portare avanti. Il prompt engineering ottimizza la formulazione della prima cosa. Il context engineering ottimizza la composizione di tutte e quattro.

Questa distinzione conta nella pratica, non solo nel vocabolario. Se scrivo un prompt calibrato con cura e do all’agente cinque schemi di strumenti irrilevanti e quaranta turni di cronologia obsoleta, la formulazione non conta più — il modello sta ragionando su un contesto che è per lo più rumore. Ognuno dei miei agenti passato da “funziona nella demo” a “funziona alle 3 del mattino con un input strano” ci è arrivato sistemando ciò che era nella finestra, non riformulando le istruzioni al suo interno.

Le quattro cose che competono per lo spazio

A ogni turno, quattro categorie combattono per lo stesso spazio limitato:

1. Istruzioni di sistema — identità, regole, formato di output. Vedi i cinque livelli che uso per i prompt di sistema — questa è l’unica categoria che dovrebbe restare quasi fissa, perché il prompt caching ripaga solo se il prefisso non si muove.
2. Definizioni degli strumenti — gli schemi di ogni strumento che l’agente potrebbe chiamare in questo turno, che gli serva o meno.
3. Dati recuperati — qualsiasi cosa estratta da un database, un vector store o una chiamata API: memoria, documenti, schede cliente.
4. Cronologia di conversazione o di esecuzione — cosa è già successo in questa sessione o esecuzione.

Nessuna di queste è gratuita. Ogni token di qualsiasi categoria è un token che il modello deve soppesare rispetto a tutti gli altri per decidere cosa fare dopo, ed è un token che paghi a ogni richiesta che non è un cache hit.

L’errore è quasi sempre troppo, non troppo poco

Quando un agente si comporta male, l’istinto è aggiungere più contesto — più istruzioni, più background, più cronologia “per sicurezza”. Nella mia esperienza è spesso il contrario a essere vero.

Troppi schemi di strumenti. Ho visto un agente chiamare lo strumento sbagliato non perché quello giusto mancasse, ma perché era sepolto dietro altri sei che non servivano per quel compito. Invia solo gli strumenti rilevanti per il passaggio corrente, non l’intera cassetta degli attrezzi a ogni chiamata. Uno strato di routing che decide quale sottoinsieme di strumenti esporre è economico da costruire e si ripaga già la prima volta che evita una chiamata sbagliata.

Cronologia di conversazione obsoleta. Un agente di supporto che trascina 60 turni di cronologia da tre problemi non correlati di tempo fa non sta “ricordando il cliente” — sta diluendo la richiesta corrente con rumore irrilevante, e occasionalmente agendo su qualcosa che non è più vero. Questa è esattamente la modalità di fallimento che la memoria episodica con una finestra limitata dovrebbe prevenire, e vale la pena verificare se la tua finestra è davvero limitata o è cresciuta senza limiti silenziosamente.

Documenti recuperati che nessuno ha chiesto. Un recupero semantico che restituisce i 10 frammenti “più simili” invece dei 2 rilevanti seppellisce la risposta in una distrazione dall’aspetto plausibile. Più contesto recuperato non significa più segnale — oltre un certo punto è attivamente peggio, perché il modello deve lavorare di più per trovare la parte che conta.

Istruzioni ripetute per difesa. Lo vedo in prompt che ripetono la stessa regola in quattro modi diversi perché una versione precedente dell’agente l’ha ignorata una volta. È un segnale che la regola andava spostata prima nel prompt o resa vincolante strutturalmente (un vincolo nello schema di uno strumento, un passaggio di validazione) — non un segnale per riempire il contesto di ripetizioni.

Il budget che applico davvero

Su oltre 30 agenti in produzione, fisso un budget esplicito di token per categoria prima di costruire l’agente, non dopo che ha iniziato a comportarsi male:

L’ordine di quest’ultima colonna è il vero schema decisionale: prima la cronologia, poi l’ampiezza del recupero, poi l’ambito degli strumenti, e le istruzioni di sistema per ultime. La cronologia è la più economica da comprimere senza perdere correttezza — un riassunto di due frasi di “cosa è successo nei turni 1-30” di solito porta lo stesso valore operativo della trascrizione completa. Tagliare le istruzioni di sistema è il più pericoloso, perché è lì che vive il comportamento reale dell’agente.

Riassumi prima di troncare

Il troncamento — semplicemente scartare i turni più vecchi — ne è la versione grezza. Funziona finché il turno scartato non conteneva l’unico fatto di cui l’agente aveva bisogno. Il pattern migliore è la compattazione: prima di scartare la cronologia grezza, farla collassare in un breve riassunto strutturato che catturi decisioni e fatti, e conservare quel riassunto permanentemente anche dopo che i turni grezzi sono spariti.

// workers/compact-history.ts

interface HistoryDigest {
  summary: string; // 2-3 frasi: cosa è stato deciso, risolto, o resta aperto
  keyFacts: Record<string, string>; // fatti stabili che vale la pena conservare alla lettera
  turnCount: number; // quanti turni grezzi sostituisce questo riassunto
}

async function compactIfNeeded(
  history: ConversationTurn[],
  env: Env
): Promise<{ digest: HistoryDigest | null; recent: ConversationTurn[] }> {
  const RECENT_WINDOW = 10;
  if (history.length <= RECENT_WINDOW) {
    return { digest: null, recent: history };
  }

  const toCompact = history.slice(0, -RECENT_WINDOW);
  const recent = history.slice(-RECENT_WINDOW);

  // Un modello economico che riassume è quasi sempre sufficiente per questo passaggio
  const digest = await summarizeTurns(toCompact, env);
  return { digest, recent };
}

È lo stesso principio di un eval harness che trasforma ogni fallimento di produzione in un caso di test permanente (vedi l’eval harness che uso per rilasciare agenti IA): non scartare l’informazione, comprimila in una forma economica da conservare e ancora utile. I turni grezzi sono usa e getta. I fatti al loro interno di solito non lo sono.

Recupero: meno risultati, più rilevanti, battono più risultati

La stessa disciplina si applica a tutto ciò che viene estratto da un vector store o un database. È allettante recuperare generosamente — top-10, top-20 — con la teoria che più contesto non possa far male. Può farlo. Ogni frammento irrilevante è un frammento che il modello deve leggere, soppesare e scartare, e un mucchio abbastanza grande di quasi corrispondenze può pesare più del singolo frammento che risponde davvero alla domanda.

Il mio default è partire con un k piccolo (2-4) e ampliarlo solo se riesco a dimostrare, con casi reali, che la risposta manca davvero a quell’ampiezza — non perché una rete più larga sembri più sicura. Se la qualità del recupero è incostante, la soluzione di solito è una query migliore o un passaggio di re-ranking, non un k più grande.

Ricollegalo a costo e correttezza

Il context engineering non è solo un problema di qualità — è la singola leva più grande su quanto costa far funzionare un agente, perché nella maggior parte dei carichi di lavoro degli agenti si paga molto di più per i token in input che per quelli in output. Una finestra di contesto gonfiata è una fattura gonfiata prima di essere un bug di comportamento. Se non hai ancora visto la matematica dei costi per scegliere tra livelli di modello, il budget di contesto che applichi cambia direttamente quella matematica: un contesto più piccolo e ben delimitato rende un modello più economico praticabile per più dei tuoi compiti, perché al modello non viene chiesto di cercare un ago in un pagliaio inutilmente grande.

Ogni agente che gestisco gira su Claude, e la decisione sul livello di modello ha senso solo una volta fissato il budget di contesto — confrontare i costi su un contesto gonfiato e non delimitato non ti dice nulla su ciò di cui il compito ha davvero bisogno.

E poiché cambiare ciò che c’è nella finestra di contesto cambia il comportamento tanto quanto cambiare il prompt, ogni modifica al contesto passa dallo stesso cancello di una modifica al prompt: farla girare contro il set di eval costruito da fallimenti di produzione reali prima di rilasciarla. Ridurre la cronologia o restringere l’ampiezza di un recupero è esattamente il tipo di modifica “ovviamente sicura” che fa regredire silenziosamente un caso limite se non verifichi.

Il bilancio dell’operatore

Il context engineering è decidere, a ogni turno, cosa si guadagna un posto in una finestra limitata — e il fallimento predefinito è includerne troppo, non troppo poco. Mantieni le istruzioni di sistema stabili e come ultima cosa da tagliare. Limita le definizioni degli strumenti al passaggio corrente. Recupera in modo ristretto e amplia solo con prove. Compatta la cronologia in riassunti prima di scartarla, e taglia prima i turni grezzi più vecchi. Poi verifica ogni modifica contro i tuoi eval, perché le modifiche al contesto alterano il comportamento esattamente come le modifiche al prompt — solo che è più facile far finta che non sia così.

FAQ

Cos’è il context engineering per gli agenti IA?

È la disciplina di decidere quali token — istruzioni di sistema, definizioni degli strumenti, dati recuperati e cronologia della conversazione — entrano nella finestra di contesto di un agente a ogni passaggio, a differenza del prompt engineering, che riguarda come viene formulata una singola istruzione. Conta di più in produzione, dove tutte e quattro le categorie competono per lo stesso spazio limitato a ogni richiesta.

Il context engineering è diverso dal prompt engineering?

Sì. Il prompt engineering ottimizza la formulazione di un’istruzione. Il context engineering ottimizza tutto il resto che il modello vede insieme a quell’istruzione — quali strumenti sono esposti, cosa è stato recuperato, e quanta cronologia viene portata avanti. Un prompt ben formulato fallisce comunque se circondato da schemi di strumenti irrilevanti o cronologia obsoleta.

Quanta cronologia di conversazione dovrebbe conservare un agente IA?

Meno di quanto pensi. Una finestra scorrevole limitata (10-20 turni recenti è tipico) più un riassunto condensato di tutto ciò che è più vecchio di solito supera una trascrizione grezza completa, perché rimuove il rumore senza perdere i fatti che contano. Compatta prima di scartare la cronologia, non limitarti a troncarla.

Una finestra di contesto più grande significa che serve meno context engineering?

No — rimuove il tetto tecnico rigido ma non il problema di costo o rumore. Una finestra più grande rende la trascuratezza più economica, ma ogni token irrilevante continua a diluire il segnale che il modello deve elaborare e continua a costare denaro a ogni richiesta che non è un cache hit. La disciplina conta tanto a 200K token quanto a 8K.

Correlato: Come scrivere prompt di sistema per agenti IA che non falliscono in produzione · Come aggiungere memoria a un agente IA · Prompt caching: riduci i costi Claude senza cambiare modello · L’eval harness che uso per rilasciare agenti IA

Hai bisogno di aiuto per progettare il contesto e la memoria di un agente? Contattami — progetto sistemi di agenti in produzione per team operativi.