Context engineering: cosa vede il modello e perché

Il context engineering (ingegneria del contesto) è la pratica di decidere tutto ciò che un modello linguistico vede quando risponde: non solo la domanda che scrivi, ma le istruzioni che la circondano, i documenti e i risultati degli strumenti inseriti, la memoria salvata sull'utente e la conversazione fin lì. Tutto questo condivide un'unica finestra di contesto, e il modello risponde a partire da quel testo e da nient'altro. Il termine si è diffuso nel 2025, quando sempre più prodotti di IA sono diventati agenti che assemblano da soli la maggior parte del loro contesto.

Il prompt engineering riguarda soprattutto come formulare una richiesta. Il context engineering riguarda cosa il modello deve avere davanti a ogni chiamata, e in quale ordine.

Da un prompt a un contesto

In un'app di chat scrivi tu la maggior parte del contesto: l'app aggiunge un prompt di sistema e la cronologia, e tu metti il resto. In un'applicazione l'equilibrio si ribalta. Un utente scrive una frase, e il codice intorno al modello aggiunge istruzioni, un profilo utente, tre articoli di assistenza trovati con una ricerca, l'elenco degli strumenti disponibili e l'output dell'ultima chiamata a uno strumento. La frase dell'utente può essere una piccola frazione di ciò che il modello legge.

Quando un sistema del genere risponde male, la soluzione raramente sta nella formulazione. La causa abituale è che il modello aveva il materiale sbagliato: un fatto mancante, un risultato di uno strumento superato, un documento irrilevante che alla ricerca era sembrato rilevante.

Cosa entra nella finestra di contesto

Una chiamata tipica in un'applicazione di IA contiene alcune di queste cose, o tutte, più o meno in quest'ordine:

• Istruzioni di sistema: il ruolo, le regole e il formato di output, di solito fissi per tutta l'app. Vedi prompt di sistema.
• Definizioni degli strumenti: nomi, descrizioni e parametri degli strumenti che il modello può chiamare.
• Esempi: alcuni input e output di esempio che mostrano il comportamento atteso.
• Memoria: fatti salvati da sessioni precedenti, come il piano dell'utente, la sua lingua o le sue preferenze.
• Documenti recuperati: passaggi trovati cercando in una base di conoscenza per questa domanda (retrieval-augmented generation, o RAG).
• Cronologia della conversazione: turni precedenti, alla lettera o riassunti.
• Risultati degli strumenti: l'output di ricerche, esecuzioni di codice o chiamate API fatte durante questo compito, come in un ciclo ReAct.
• Il messaggio attuale: quello che l'utente ha appena chiesto.

Il blocco qui sotto è un contesto già assemblato per un assistente di supporto. Disattiva le parti una alla volta. Senza la parte di contesto il modello non può conoscere il piano del cliente; senza la parte di input non ha fatti sul prodotto, e i suoi vincoli gli dicono di dirlo invece di tirare a indovinare.

Contesto per un assistente di supporto

EditCopy

PartsRoleConstraintsContextInputFormatTask

Role

Sei l'assistente di supporto di Acme Notes, un'app per prendere appunti.

Constraints

Rispondi solo in base ai documenti qui sotto. Se non coprono la domanda, dillo e offri di mettere il cliente in contatto con una persona. Non tirare mai a indovinare su funzioni o prezzi.

Context

Memoria del cliente: si chiama Dana, piano Free, usa l'app Android.

Input

<document source="help/offline-mode"> La modalità offline è disponibile con il piano Pro. Le note create offline si sincronizzano quando il dispositivo si riconnette. Gli allegati più grandi di 20 MB non sono disponibili offline. </document> <document source="help/plans"> Piano Free: fino a 3 dispositivi. Piano Pro: dispositivi illimitati, modalità offline, 30 giorni di cronologia delle versioni. </document>

Format

Da due a quattro frasi in linguaggio semplice. Rivolgiti al cliente per nome.

Task

Domanda del cliente: Posso usare l'app in aereo senza internet?

Try it

Example replyReplies vary between models and runs.

Ciao Dana, la modalità offline fa parte del piano Pro, e il tuo account al momento è sul piano Free, quindi per ora non è disponibile per te. Con Pro, le note che crei durante il volo si sincronizzano automaticamente quando il telefono si riconnette. Un limite da sapere: gli allegati più grandi di 20 MB non sono disponibili offline.

Nota che la risposta corretta dipende dall'unire due fonti: la memoria (piano Free) e un documento (la modalità offline è solo per Pro). Nessuna delle due basta da sola, ed è una situazione tipica. Gran parte del context engineering consiste nell'assicurarsi che i pezzi che hanno bisogno l'uno dell'altro arrivino insieme.

Quattro modi in cui un contesto va storto

1. Informazioni mancanti. Il modello riempie i vuoti con ipotesi plausibili, ed è da lì che nascono molte allucinazioni. Aggiungi il fatto, oppure di' al modello cosa fare quando un fatto manca.
2. Troppo materiale. Ogni paragrafo irrilevante costa token e si contende l'attenzione. Liu et al. 2023, "Lost in the Middle: How Language Models Use Long Contexts", hanno scoperto che i modelli testati usavano in modo più affidabile le informazioni all'inizio o alla fine di un input lungo rispetto a quelle nel mezzo. I modelli più recenti gestiscono meglio gli input lunghi, ma inviare i pochi passaggi che rispondono alla domanda resta più economico, e più facile da usare per il modello, che incollare l'intero manuale.
3. Informazioni superate. Il risultato di uno strumento di dieci passaggi fa può descrivere un file o un saldo che nel frattempo è cambiato. Se il modello vede entrambe le versioni, potrebbe usare quella vecchia.
4. Conflitti. Due documenti non sono d'accordo, oppure la memoria dice una cosa e l'utente un'altra. Di' al modello quale fonte prevale, per esempio "l'ultimo messaggio dell'utente prevale sulla memoria salvata".

Ordinare il contesto

L'ordine cambia sia i risultati sia i costi.

• Prima le parti stabili. Istruzioni di sistema, definizioni degli strumenti e materiale di riferimento fisso cambiano raramente tra una chiamata e l'altra. Diversi fornitori di API offrono il prompt caching, che riusa l'elaborazione di un inizio identico dell'input, quindi un prefisso che non cambia rende le chiamate ripetute più economiche e veloci.
• Il materiale lungo prima della domanda. Per un documento lungo o un grande insieme di passaggi, metti prima il materiale e dopo la domanda e le istruzioni finali. La guida al prompting di Anthropic, per esempio, consiglia quest'ordine per gli input lunghi, con la domanda subito prima che il modello inizi a scrivere.
• Etichetta ogni pezzo. Racchiudi ogni fonte in tag come <document>, <memory> o <tool_result>, con il nome della fonte. Le etichette permettono al modello di distinguere i dati dalle istruzioni e ti permettono di chiedergli di citare da dove viene una risposta. Delimitatori e tag XML illustra i formati.

Sfoltire un contesto lungo

Ogni turno di una chat rinvia l'intera cronologia, quindi le sessioni lunghe crescono finché qualcosa deve uscire. A seconda dell'app, può riassumere o scartare i messaggi più vecchi, oppure chiederti di aprire una nuova chat. Ottieni risultati migliori se sfoltisci di proposito.

• Tieni alla lettera gli ultimi turni e sostituisci quelli più vecchi con un riepilogo.
• Quando un risultato di uno strumento è stato usato, sostituiscilo con una nota di una riga su cosa mostrava.
• Conserva gli identificatori esatti in ogni riepilogo: nomi di file, nomi di funzioni, ID, messaggi di errore e numeri. Un riepilogo che dice "il file di configurazione" dove la cronologia diceva settings.prod.yaml perde proprio il dettaglio che contava.
• In un'app di chat, quando la conversazione si allontana dal tema, apri una nuova chat con una nota di passaggio di consegne. Il prompt qui sotto ne scrive una.

Comprimi una chat lunga in un nuovo inizio

EditCopy

Fill inprogettoparole

Questa conversazione si sta allungando. Scrivi una nota di passaggio di consegne che posso incollare in una nuova chat perché continui il lavoro senza la cronologia. Includi: 1. L'obiettivo di il refactoring del modulo di registrazione, in una frase. 2. Le decisioni che abbiamo preso e il motivo di ciascuna. 3. Lo stato attuale: cosa funziona e cosa è incompleto. 4. I nomi esatti che contano: file, funzioni, messaggi di errore, numeri. Copiali esattamente. 5. Le domande aperte e il prossimo passo. Lascia fuori i vicoli ciechi, a meno che non spieghino una decisione. Massimo 200 parole.

Try it

Example replyReplies vary between models and runs.

Obiettivo: sostituire i controlli scritti a mano del modulo di registrazione con un unico schema di validazione condiviso da browser e server.

Decisioni

1. Un solo file di schema, signupSchema.ts, importato da SignupForm.tsx e da api/signup.ts, così le due serie di regole non possono divergere.
2. I messaggi di errore restano parola per parola, perché il centro assistenza li cita.

Stato attuale

1. La validazione nel browser usa lo schema e SignupForm.test.tsx passa.
2. Il server chiama ancora il vecchio validateSignup() in api/signup.ts.

Dettagli esatti: le password richiedono almeno 8 caratteri e un numero. Testo dell'errore sull'email: "Inserisci un indirizzo email valido."

Prossimo passo: sostituire validateSignup() con lo schema ed eseguire i test dell'API.

Domanda aperta: un'email già registrata deve restituire 409 o 400?

Memoria tra le sessioni

La memoria è contesto che sopravvive a una conversazione: fatti scritti in un archivio alla fine di una sessione e caricati in quella successiva. Le app di chat ne offrono delle versioni, come i ricordi salvati o le istruzioni di progetto aggiunte a ogni chat di un progetto. Nella tua applicazione, la memoria è una tabella o un file di note che il tuo codice legge e inserisce. Due regole la mantengono utile: salva fatti che restano veri (piano, lingua, stack preferito), non trascrizioni; e carica solo ciò che è rilevante per il compito attuale, perché la memoria si contende lo stesso spazio di tutto il resto.

Assemblare il contesto nel codice

In un'applicazione, il context engineering è codice normalissimo. Questo abbozzo con l'SDK Python di Anthropic mette le regole fisse e la memoria nel prompt di sistema, tiene solo la cronologia recente e colloca i documenti etichettati prima della domanda.

import anthropic

client = anthropic.Anthropic()
MODEL = "your-model-id"  # e.g. from your provider's model list

def build_context(question, docs, history, memory, max_messages=6):
    documents = "\n".join(
        f'<document source="{d["source"]}">\n{d["text"]}\n</document>' for d in docs
    )
    system = (
        "You are the support assistant for Acme Notes. Answer only from the documents. "
        "If they do not cover the question, say so.\n"
        f"<memory>\n{memory}\n</memory>"
    )
    # history holds complete user/assistant pairs, so an even slice starts with a user turn
    recent = history[-max_messages:]
    user = f"<documents>\n{documents}\n</documents>\n\n{question}"
    return system, recent + [{"role": "user", "content": user}]

# question, docs, history and memory come from your application
system, messages = build_context(question, docs, history, memory)
response = client.messages.create(model=MODEL, max_tokens=1024, system=system, messages=messages)
print(response.content[0].text)

Ogni decisione in quella funzione (quali documenti, quanti messaggi, dove va la memoria) è una scelta di context engineering, e vale la pena testarle tutte su domande reali, proprio come testeresti una modifica alla formulazione.