Aspetto
Anatomia di un harness
Ultimo aggiornamento: 2026-11-20. Le descrizioni dei sistemi reali si riferiscono alle versioni studiate in [F-0001], fissate a luglio 2026; le indicazioni di [F-0004] risalgono a dicembre 2024 e la pagina stessa avverte che il panorama degli strumenti è cambiato da allora.
Obiettivi di apprendimento
Alla fine di questo livello dovresti saper:
- dire che cosa appartiene all'harness e che cosa al modello, e perché la distinzione conta;
- distinguere un workflow da un agente e scegliere fra i due;
- descrivere il ciclo agentico come aggiornamento di un contesto, e indicare dove e perché si ferma;
- nominare i sette sottosistemi di un harness e, per ciascuno, la forma minima che basta per funzionare.
Prerequisiti. Livello 0, Fondamenti: che cos'è un token, che cos'è la finestra di contesto, perché il modello non ha memoria fra una chiamata e l'altra. Il livello 0 è ancora in preparazione; per questa pagina basta sapere che il modello è una funzione che riceve un testo (il contesto) e produce un testo.
Agente = modello + harness
La definizione che [F-0001] adotta è un'equazione: un agente è un modello più un harness (letteralmente «imbracatura»). L'harness è «everything except the model»: il runtime che collega il modello al mondo attraverso un ciclo di controllo, dei tool, la gestione del contesto, i controlli di sicurezza, l'orchestrazione e i punti di estensione. Harness engineering è la disciplina che progetta ed evolve questo runtime; il termine è entrato in circolazione a febbraio 2026 [F-0001].
Il motivo per cui la distinzione conta si vede ragionando dai primi principi (sintesi nostra). Un modello linguistico, a pesi fissati, è una funzione senza stato: dato un contesto restituisce una distribuzione sul testo successivo. Non legge file, non esegue comandi, non ricorda la chiamata precedente. Tutto ciò che un agente fa (leggere, scrivere, chiedere un permesso, fermarsi) e tutto ciò che ricorda passa per codice che non è il modello. Quel codice è l'harness, e la qualità di un agente dipende da entrambi i fattori.
[F-0001] delimita il concetto rispetto a quattro casi limite con cui viene confuso:
| Non è… | Perché |
|---|---|
| uno scaffold (impalcatura), quasi | I due termini sono quasi sinonimi. Dove serve distinguerli, lo scaffold è il codice strutturale (il ciclo, i registri dei tool), l'harness è il prodotto che lo incorpora: lo scaffold di Mini-SWE-Agent sono 100 righe di Python, l'harness di Claude Code è un prodotto con interfaccia, permessi e plugin. |
| un framework agentico | Un framework (LangChain, AutoGen, CrewAI) è una libreria che si importa per costruire un agente; un harness è un runtime dentro cui si lavora. La distinzione era netta nel 2025 e si sta sciogliendo nel 2026. |
| un evaluation harness | L'harness di SWE-bench avvolge un agente per eseguirlo su dei compiti; un harness per agenti avvolge un modello per farlo agire. Stessa parola, direzione opposta. |
| un orchestratore | Un orchestratore (o meta-harness) coordina uno o più harness dall'alto e non ha un proprio ciclo di modifica del codice. |
Workflow e agenti
[F-0004] chiama sistemi agentici tutto ciò che combina un modello con dei tool, e al loro interno traccia una distinzione architetturale:
- un workflow (flusso predefinito) orchestra modello e tool lungo percorsi di codice scritti in anticipo;
- un agente lascia al modello la decisione dinamica dei propri passi e dell'uso dei tool, mantenendo il controllo su come arrivare al risultato.
In termini di controllo (sintesi nostra): in un workflow il grafo delle chiamate lo scrive lo sviluppatore e il modello riempie i nodi; in un agente il grafo lo genera il modello a tempo di esecuzione, un passo alla volta, e lo sviluppatore scrive solo il ciclo che lo esegue e i limiti entro cui può svolgersi.
Il mattone comune a entrambi è il LLM aumentato: un modello con accesso a retrieval, tool e memoria, in grado di generare da sé le proprie query, scegliere i tool e decidere cosa conservare [F-0004]. I pattern costruiti sopra questo mattone (prompt chaining, routing, parallelizzazione, orchestrator-workers, evaluator-optimizer) sono materia del livello 2.
Quando usare un agente
La raccomandazione di [F-0004] è cercare la soluzione più semplice e aumentare la complessità solo quando serve, il che può voler dire non costruire nessun sistema agentico. I sistemi agentici scambiano latenza e costo con prestazioni migliori sul compito. Per molte applicazioni basta ottimizzare una singola chiamata al modello con retrieval ed esempi nel prompt. Quando serve di più:
- i workflow danno prevedibilità e coerenza su compiti ben definiti, scomponibili in passi fissi;
- gli agenti servono per problemi aperti, dove non si può prevedere il numero di passi né scrivere a priori il percorso, e dove si è disposti a fidarsi delle decisioni del modello.
L'autonomia ha due costi espliciti: spesa più alta ed errori che si accumulano da un passo all'altro. Per questo [F-0004] raccomanda test estesi in ambienti isolati (sandbox) e limiti adeguati.
Sui framework, [F-0004] suggerisce di partire dalle API del modello usate direttamente, perché gli strati di astrazione possono «obscure the underlying prompts and responses» e rendere il debug più difficile. Diciotto mesi dopo, [F-0001] trova lo stesso orientamento nel codice: nessuno degli undici harness studiati, circa quattro milioni di righe complessive, importa un framework agentico generico, e Gemini CLI non usa nemmeno quelli di Google.
Il ciclo agentico
[F-0004] descrive un agente come, tipicamente, «just LLMs using tools based on environmental feedback in a loop»: un modello che usa dei tool in un ciclo, guidato da ciò che l'ambiente gli restituisce. La forma di questo ciclo viene dal paper ReAct [F-0008], che tutti gli undici harness di [F-0001] implementano in qualche variante.
La formulazione di ReAct
[F-0008] parte dal modello generale di un agente che interagisce con un ambiente. Al passo
L'idea di ReAct è allargare lo spazio delle azioni con lo spazio del linguaggio,
Nell'articolo originale (2022) questo comportamento si otteneva con un modello congelato (PaLM-540B) e pochi esempi di traiettorie scritte a mano nel prompt. Gli harness attuali ottengono lo stesso schema con modelli addestrati a produrre chiamate a tool strutturate (sintesi nostra; il passaggio dal prompting alle API di tool use non è trattato in queste tre fonti).
Lette dal lato dell'harness, le equazioni dicono una cosa precisa (sintesi nostra): il contesto
flowchart TB
T[Compito] --> C[(Contesto c_t)]
C --> M[Modello: sceglie il passo successivo]
M -->|pensiero| C
M -->|azione| E[Harness esegue il tool]
E -->|osservazione| B{Budget esaurito o stallo?}
B -->|no| C
B -->|sì| S[Arresto]
M -->|risposta finale| S
Il ciclo agentico visto dall'harness. Il modello sceglie fra pensare, agire o rispondere; tutto il resto (eseguire, osservare, limitare, fermare) è codice dell'harness. Schema nostro, da [F-0004] e [F-0008].
Perché alternare ragionamento e azione
[F-0008] confronta il ragionamento puro (chain-of-thought, CoT) con ReAct su HotpotQA, un dataset di domande che richiedono di combinare più pagine di Wikipedia, usando un'API di Wikipedia ridotta a tre azioni: search, lookup, finish. Gli autori hanno etichettato a mano 200 traiettorie. La tabella dei modi di errore mostra lo scambio meglio dei punteggi aggregati:
La ricerca senza risultato non si applica a CoT, che non fa ricerche. Fonte: [F-0008], tabella 2.
Tre letture:
- L'azione ancora il ragionamento ai fatti. L'allucinazione è il primo modo di errore di CoT (56% dei fallimenti) e scompare in ReAct (0%). Anche fra le risposte giuste, quelle con ragionamento o fatti inventati sono il 14% per CoT e il 6% per ReAct [F-0008].
- La struttura ha un costo. Alternare pensiero, azione e osservazione riduce la flessibilità del ragionamento: gli errori di ragionamento salgono dal 16% al 47%. Fra questi c'è un caso tipico di ReAct, il modello che ripete i pensieri e le azioni precedenti senza riuscire a uscirne [F-0008]. È lo stesso fenomeno che gli harness di produzione intercettano con il rilevamento dello stallo (paragrafo seguente).
- Il ciclo vale quanto i suoi tool. Una ricerca che non restituisce nulla di utile fa deragliare il ragionamento nel 23% degli errori [F-0008]. Da qui l'attenzione che [F-0004] chiede per la progettazione dei tool, trattata al livello 3.
Nei compiti decisionali (ALFWorld, un gioco testuale, e WebShop, navigazione in un negozio web) ReAct con uno o due esempi supera metodi di imitazione e di reinforcement learning addestrati su
Quando il ciclo si ferma
In [F-0004] il compito termina di norma quando è completato, ma è comune aggiungere condizioni di arresto, come un numero massimo di iterazioni, per mantenere il controllo; l'agente può anche fermarsi per chiedere un riscontro a una persona a un checkpoint o davanti a un ostacolo.
Il confronto fra gli undici harness di [F-0001] mostra quante scelte diverse stanno dietro questa frase:
| Sistema | Quando si ferma | Rilevamento dello stallo |
|---|---|---|
| Claude Code, Codex | quando il modello termina il turno senza chiamare tool | nessuno automatico |
| Pi | come sopra, senza tetto di iterazioni | nessuno, per scelta dichiarata |
| Gemini CLI | fine turno, oppure 100 turni | hash di chiamate ripetute; dopo 30 turni un controllo fatto da un modello |
| Hermes | budget di 90 iterazioni; una guardia può rifiutare la risposta finale | firme delle chiamate: avvisi, arresto disattivato di default |
| OpenCode | nessuna chiamata a tool; nessun limite di passi di default | tre chiamate identiche fanno chiedere un permesso all'utente |
| OpenHands | stato «FINISHED» | cinque scenari enumerati |
| Mini-SWE-Agent | messaggio di uscita, limite di passi, tempo massimo | tetto agli errori di formato consecutivi |
Sintesi da [F-0001], tabella 5 e paragrafo 6.2.
Due casi meritano attenzione. La guardia verify-on-stop di Hermes trasforma una risposta finale in una continuazione se il turno ha modificato del codice senza produrre prove di verifica: è il controllo di qualità spostato nella condizione di arresto [F-0001]. OpenCode, quando rileva tre chiamate identiche, non interrompe: chiede all'utente se la ripetizione è un errore [F-0001]. La raccomandazione 18 di [F-0001] riassume il punto: non complicare troppo il rilevamento dello stallo, ma mettere i limiti economici (numero di passi, tempo, errori consecutivi), che costano una dozzina di righe.
I sette sottosistemi
[F-0001] sostiene che ogni harness, dalle 100 righe di un prototipo di ricerca al milione di righe di un prodotto, deve prendere posizione su sette sottosistemi, anche quando la posizione è l'assenza deliberata.
flowchart LR
I[Livello di interfaccia
TUI, CLI, IDE, server, SDK] --> L((Ciclo
agentico))
L --- M[Integrazione col modello]
L --- T[Tool e azioni]
L --- C[Memoria e contesto]
L --- P[Sicurezza e permessi]
L --- O[Orchestrazione]
L --- X[Estensibilità]
S[(Substrato di sessione
trascrizioni, ripresa, diramazioni)] -.- L
I sette sottosistemi intorno al ciclo, più le due superfici trasversali. Ridisegnato da [F-0001], figura 1.
| Sottosistema | Che cosa fa | Forma minima osservata | Forma massima osservata |
|---|---|---|---|
| Ciclo agentico | alterna inferenza ed esecuzione di azioni; decide arresto e recupero dagli errori | Mini-SWE-Agent: un while lineare su un solo tool bash | OpenHands: conversazione su un registro di eventi persistente, con azioni in parallelo |
| Integrazione col modello | parla i protocolli dei provider, assembla il prompt, gestisce cache, ragionamento esteso, instradamento fra modelli | una chiamata via LiteLLM, un template Jinja | Hermes: cinque trasporti propri e 29 profili di provider |
| Tool e azioni | definisce ed esegue ciò che l'agente può fare, soprattutto modificare file | solo bash | Claude Code: 43 tool tipizzati con caricamento differito |
| Memoria e contesto | razionalizza la finestra di contesto; conserva conoscenza fra turni e sessioni | storia lineare senza limiti | Codex: memoria fra sessioni mantenuta dall'agente stesso |
| Sicurezza e permessi | decide che cosa si esegue, che cosa chiede conferma, che cosa è vietato; isola l'esecuzione | limiti di costo e di passi | Codex: regole di policy, un revisore delle approvazioni basato su modello, sandbox del sistema operativo su tre piattaforme |
| Orchestrazione | genera e coordina sotto-agenti; si collega ad altri agenti | Aider: nessuna, per scelta | Claude Code: composizione ricorsiva |
| Estensibilità | permette di aggiungere capacità: configurazione, hook, skill, plugin, MCP | tipizzazione strutturale (protocolli Python) | Pi: tutto è un'estensione |
Da [F-0001], tabella 1. I sottosistemi sono trattati per esteso ai livelli 2 e 3.
Accanto ai sette, [F-0001] individua due superfici trasversali: il livello di interfaccia, con cui persone e programmi guidano l'harness, e il substrato di sessione (trascrizioni, persistenza, ripresa e diramazione), condiviso da più sottosistemi.
Tre forme del ciclo
Tutti gli harness studiati implementano varianti di ReAct, ma [F-0001] distingue tre paradigmi:
- ciclo iterativo azione-osservazione (nove sistemi su undici): prompt, chiamata al modello, esecuzione dei tool, raccolta delle osservazioni;
- ciclo con riflessione (Aider): dopo ogni risposta applica le modifiche, esegue linter e test, e se trova problemi richiama il modello con il riscontro, fino a tre volte di default;
- coordinatore-worker (Claude Code, Codex; Hermes dietro configurazione): un agente genitore delega a sotto-agenti con contesto proprio e ne sintetizza i risultati. È uno strato sopra il ciclo iterativo, non un'alternativa.
[F-0001] segnala anche la nascita, a giugno 2026, del termine loop engineering: se l'harness engineering costruisce il ciclo interno azione-osservazione, il loop engineering compone dall'esterno cicli che rilanciano e verificano l'agente senza che una persona scriva ogni turno.
Quanto harness serve
L'esistenza di un harness minimo è dimostrata: Mini-SWE-Agent implementa tutti e sette i sottosistemi in circa 100 righe (un ciclo while, un template, un tool, una lista di messaggi, due limiti, nessuna orchestrazione) e dichiara su SWE-bench Verified risultati nello stesso intervallo di sistemi tre ordini di grandezza più grandi [F-0001]. Gli autori avvertono che il confronto è fra cifre autodichiarate, con modelli e configurazioni diverse (Mini-SWE-Agent gira senza sandbox, Codex in sandbox), e non ne traggono una classifica.
La lettura di [F-0001] è che il codice in più dei sistemi di produzione non serve a completare i compiti ma a tutto il resto: sicurezza, recupero dagli errori, gestione dei costi, estensibilità, esperienza d'uso. Gli autori propongono, come ipotesi da verificare e non come risultato, una frontiera scaffold-capacità: a modello e compiti fissati, il successo cresce in fretta con pochi elementi strutturali (un tool bash, lettura e scrittura di file, un file di contesto in Markdown) e poi si appiattisce, e da lì in avanti l'investimento nell'harness paga in requisiti operativi, non in tasso di completamento.
Le due fonti, a diciotto mesi di distanza, convergono (sintesi nostra): [F-0004] chiede di aggiungere complessità «only when it demonstrably improves outcomes», [F-0001] raccomanda di partire da un ciclo lineare e da un solo tool bash e di aggiungere tool solo in risposta a errori osservati.
Per Depp
Nostra interpretazione, non tratta dalle fonti.
- Prima la domanda workflow o agente. Gran parte del lavoro sui gestionali per la PA (classificare un atto, estrarre campi da un documento, smistare una richiesta) ha passi noti in anticipo: è un workflow, cioè codice Django che chiama il modello in punti precisi, con i controlli di validazione che abbiamo già. Un agente si giustifica dove il numero di passi non è prevedibile, per esempio nell'esplorazione di un archivio di atti per rispondere a una domanda aperta.
- Lo stato è nostro. Se il contesto
è lo stato dell'agente, va trattato come qualunque altro stato applicativo: salvato in PostgreSQL (la traiettoria come sequenza di righe o come documento JSONB), ricaricabile, ispezionabile. È anche ciò che serve per la tracciabilità che la PA chiede su decisioni assistite da un modello. - I limiti sono requisiti, non dettagli. Numero massimo di passi, tetto di spesa per esecuzione e timeout vanno fissati come requisiti di progetto, perché in una procedura di gara costi e tempi di risposta vanno dichiarati.
Esercizio
Scrivi in Python un ciclo agentico minimo con un solo tool, partendo dallo schema qui sotto: ricalca il ciclo di Mini-SWE-Agent [F-0001, listato 1] con i limiti economici della raccomandazione 18. Il modello è un'interfaccia astratta: collegalo al provider che usi.
python
from dataclasses import dataclass, field
from typing import Protocol, Callable
import hashlib, json
class Modello(Protocol):
def completa(self, messaggi: list[dict], tool: list[dict]) -> dict: ...
# restituisce {"testo": str, "chiamate": [{"nome": str, "argomenti": dict}]}
@dataclass
class Ciclo:
modello: Modello
tool: dict[str, Callable[..., str]]
schemi: list[dict]
max_passi: int = 20
max_ripetizioni: int = 3
messaggi: list[dict] = field(default_factory=list) # il contesto c_t
def esegui(self, compito: str) -> str:
self.messaggi.append({"ruolo": "utente", "testo": compito})
visti: dict[str, int] = {}
for _ in range(self.max_passi): # budget
risposta = self.modello.completa(self.messaggi, self.schemi)
self.messaggi.append({"ruolo": "modello", **risposta})
if not risposta["chiamate"]: # arresto: nessuna azione
return risposta["testo"]
for chiamata in risposta["chiamate"]:
firma = hashlib.sha256(json.dumps(chiamata, sort_keys=True).encode()).hexdigest()
visti[firma] = visti.get(firma, 0) + 1
if visti[firma] > self.max_ripetizioni: # stallo
return "Interrotto: la stessa azione si ripete."
esito = self.tool[chiamata["nome"]](**chiamata["argomenti"])
self.messaggi.append({"ruolo": "osservazione", "testo": esito})
return "Interrotto: budget di passi esaurito."- Collega un tool
sql_sola_lettura(query: str) -> strche esegue unaSELECTsu una copia di un database PostgreSQL di prova, con un utente che ha solo permessi di lettura. - Poni una domanda che richieda almeno due query (la seconda dipende dal risultato della prima) e salva la traiettoria.
- Leggi la traiettoria e classifica ogni passo come pensiero, azione o osservazione. Dove si sarebbe fermato il ciclo senza
max_passi? - Togli i permessi di lettura su una tabella e ripeti: che cosa fa il modello davanti all'errore? Ritrovi uno dei modi di errore della tabella di ReAct?
Fonti
- [F-0001] Barbaste, Darrigol, Vu, Wiltberger, Harness Engineering: Anatomy, Architecture, and Evolution of Coding Agents. A Source-Code Study of Eleven Systems (luglio 2026), arXiv:2609.00006v1, CC-BY-4.0 — https://arxiv.org/abs/2609.00006. Usati: paragrafi 2.1–2.4, 6.1–6.5, 13.2, 13.4, 15, 16.
- [F-0004] Schluntz, Zhang (Anthropic), Building effective agents (19 dicembre 2024) — https://www.anthropic.com/research/building-effective-agents. Usata per intero, escluse le appendici.
- [F-0008] Yao, Zhao, Yu, Du, Shafran, Narasimhan, Cao, ReAct: Synergizing Reasoning and Acting in Language Models (2022, v3 del 2023), arXiv:2210.03629v3, CC-BY-4.0 — https://arxiv.org/abs/2210.03629. Usati: paragrafi 1, 2, 3.1, 3.3, 4, 6.