Strategie di contesto per gli agent
In questa pagina
La sfida del contesto per gli agent
Un agent autonomo concatena decine di chiamate API: ragiona, utilizza strumenti, legge i risultati e itera. A ogni passo, il contesto cresce. La differenza rispetto a una conversazione ordinaria è che questa crescita non deriva dall’utente, ma dall’agent stesso: una query SQL che restituisce trecento righe, un’intera pagina web recuperata o un file di log letto per intero. Senza una strategia di gestione, un agent raggiunge il limite del contesto in poche iterazioni, spesso prima di completare il compito che gli hai assegnato.
Progettare un agent che gestisca efficacemente la propria memoria significa quindi rispondere a tre domande: cosa deve rimanere intatto, cosa può essere riassunto e cosa non avrebbe mai dovuto entrare nel contesto fin dall’inizio. Affronteremo questi punti in quest’ordine.
Una memoria a tre livelli
La struttura che utilizziamo si basa sulla classica distinzione tra memoria di lavoro, memoria episodica e memoria semantica. La memoria di lavoro contiene le azioni più recenti nella loro forma grezza, poiché l’agent ne ha bisogno esattamente così come sono per decidere il passo successivo. La memoria episodica conserva i riassunti dei passaggi passati: l’agent sa di aver esplorato una certa pista e quali risultati ha ottenuto, senza dover rileggere i dettagli. Infine, la memoria semantica accumula fatti stabiliti una volta per tutte—l’ID cliente, la versione dello schema del database, il vincolo di budget—che non devono mai andare persi in un riassunto.
from dataclasses import dataclass, field
@dataclass
class AgentMemory:
"""Sistema di memoria a tre livelli per un agent."""
# Livello 1: memoria di lavoro (contesto corrente)
working: list[dict] = field(default_factory=list)
# Livello 2: memoria episodica (riassunti dei passaggi passati)
episodes: list[str] = field(default_factory=list)
# Livello 3: memoria semantica (fatti permanenti)
facts: list[str] = field(default_factory=list)
max_tokens_working: int = 20_000
max_episodes: int = 10
def add_action(self, action: str, result: str):
"""Aggiunge un'azione alla memoria di lavoro."""
self.working.append({
"action": action,
"result": result[:2000], # Tronca i risultati lunghi
})
self._check_compaction()
def add_fact(self, fact: str):
"""Aggiunge un fatto permanente."""
if fact not in self.facts:
self.facts.append(fact)
def _check_compaction(self):
tokens = sum(
len(str(e)) // 4 for e in self.working
)
if tokens > self.max_tokens_working:
self._compact()
def _compact(self):
"""Compatta la memoria di lavoro in un episodio."""
import openai
client = openai.OpenAI()
text = "\n".join(
f"Action: {a['action']}\nResult: {a['result']}"
for a in self.working[:-2]
)
response = client.responses.create(
model="gpt-5.6-terra",
input=(
"Summarize these agent actions in 3-5 key points. "
"Keep important facts, results, and decisions.\n\n"
f"{text}"
),
max_output_tokens=300,
)
self.episodes.append(response.output_text)
self.working = self.working[-2:] # Mantiene le ultime 2 azioni
# Limita il numero di episodi
if len(self.episodes) > self.max_episodes:
self.episodes = self.episodes[-self.max_episodes:]
def build_context(self) -> str:
"""Costruisce il contesto completo per la prossima chiamata."""
parts = []
if self.facts:
parts.append(
"Established facts:\n" + "\n".join(f"- {f}" for f in self.facts)
)
if self.episodes:
parts.append(
"Summarized history:\n" + "\n---\n".join(self.episodes)
)
if self.working:
parts.append(
"Recent actions:\n" + "\n".join(
f"- {a['action']} → {a['result'][:500]}"
for a in self.working
)
)
return "\n\n".join(parts)
Due parametri meritano una discussione prima di copiarli così come sono. Il troncamento a 2.000 caratteri in add_action protegge da strumenti verbosi, ma taglia alla cieca: se i tuoi strumenti restituiscono JSON, ti ritroverai con un oggetto non valido nel mezzo del tuo contesto. E max_episodes: 10 impone un’amnesia limitata: all’undicesimo riassunto, il primo scompare. Per un agent che esegue compiti di lunga durata, promuovi i fatti importanti a facts prima che escano dalla finestra episodica, altrimenti li perderai permanentemente.
Domare i risultati degli strumenti
Gli strumenti restituiscono spesso risultati ingombranti: pagine web, risultati SQL, contenuti di file. Questa è di gran lunga la causa principale della saturazione del contesto per un agent, ed è anche la più facile da risolvere perché la gestisci in fase di ingestione piuttosto che dopo il fatto.
La funzione seguente offre tre strategie di troncamento. La modalità start è adatta ai documenti in cui l’essenziale si trova all’inizio, come un articolo o un rapporto. La modalità start_end funziona quando la fine contiene le informazioni decisive: una traccia di esecuzione in cui l’errore appare per ultimo, un file di log o una risposta paginata in cui il totale appare alla fine. La modalità summary costa una chiamata API extra, giustificata solo per contenuti lunghi davvero utili per il resto del ragionamento.
def truncate_tool_result(
result: str,
max_tokens: int = 2000,
strategy: str = "start_end",
) -> str:
"""Tronca il risultato di uno strumento preservando le informazioni chiave."""
estimated_tokens = len(result) // 4
if estimated_tokens <= max_tokens:
return result
max_chars = max_tokens * 4
match strategy:
case "start":
return result[:max_chars] + "\n[... truncated]"
case "start_end":
half = max_chars // 2
return (
result[:half]
+ "\n[... middle truncated ...]\n"
+ result[-half:]
)
case "summary":
import openai
client = openai.OpenAI()
response = client.responses.create(
model="gpt-5.6-terra",
input=f"Summarize this data keeping the essentials:\n{result}",
max_output_tokens=max_tokens,
)
return response.output_text
return result[:max_chars]
I risultati tabellari richiedono un trattamento speciale. Tagliare una tabella SQL a metà rimuove l’intestazione o distorce il senso del volume: l’agent vede venti righe e conclude che la tabella ne contiene solo venti. Il filtro seguente mantiene l’intestazione, un campione dall’inizio e dalla fine e, punto cruciale, indica esplicitamente il numero di righe omesse e il totale. L’agent sa quindi di stare guardando un estratto e può decidere di eseguire una query di aggregazione piuttosto che ragionare su un campione.
def filter_sql_result(result: str, question: str) -> str:
"""Filtra un risultato SQL mantenendo solo ciò che è rilevante."""
lines = result.strip().split("\n")
if len(lines) <= 20:
return result
# Mantiene l'intestazione e le prime/ultime righe
header = lines[0]
first_lines = lines[1:6]
last_lines = lines[-5:]
return (
f"{header}\n"
+ "\n".join(first_lines)
+ f"\n[... {len(lines) - 11} lines omitted ...]\n"
+ "\n".join(last_lines)
+ f"\n\nTotal: {len(lines) - 1} rows"
)
Quando più agent lavorano insieme
Quando diversi sub-agent lavorano in parallelo, la tentazione è dare a tutti il contesto completo, tanto per sicurezza. È il modo migliore per moltiplicare la tua fattura per il numero di agent degradando al contempo le loro prestazioni, poiché un contesto ingombro rende il modello meno preciso sul proprio compito. Condividi invece il contesto minimo: l’obiettivo globale affinché l’agent capisca a cosa sta contribuendo, il suo ruolo specifico, i vincoli comuni e un estratto limitato dei risultati prodotti dai suoi pari.
@dataclass
class SharedContext:
"""Contesto condiviso tra sub-agent."""
objective: str
constraints: list[str]
partial_results: dict[str, str] = field(default_factory=dict)
def context_for_sub_agent(self, role: str) -> str:
"""Genera un contesto mirato per un sub-agent."""
return (
f"Global objective: {self.objective}\n"
f"Your role: {role}\n"
f"Constraints: {', '.join(self.constraints)}\n"
f"Results from other agents:\n"
+ "\n".join(
f"- {k}: {v[:200]}"
for k, v in self.partial_results.items()
)
)
Il limite di 200 caratteri per risultato parziale riflette un’intenzione precisa: un sub-agent deve sapere cosa hanno trovato gli altri, non come lo hanno trovato. Se i tuoi agent hanno bisogno del dettaglio completo dei risultati vicini, probabilmente devi ripensare al modo in cui hai suddiviso i ruoli.
Punti chiave
- Struttura la memoria dell’agent su tre livelli: lavoro, episodica, semantica
- Compatta automaticamente quando la memoria di lavoro supera la soglia
- Tronca i risultati degli strumenti prima di iniettarli nel contesto
- Segnala sempre che un risultato è stato troncato e in che misura
- Per configurazioni multi-agent, condividi un contesto minimo mirato per ruolo