Skip to content

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), quasiI 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 agenticoUn 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 harnessL'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 orchestratoreUn 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 t l'agente riceve un'osservazione ot∈O e sceglie un'azione at∈A secondo una politica π(at∣ct), dove il contesto è la storia

ct=(o1,a1,…,ot−1,at−1,ot).

L'idea di ReAct è allargare lo spazio delle azioni con lo spazio del linguaggio, A^=A∪L. Un'azione in L è un pensiero (traccia di ragionamento): non tocca l'ambiente e quindi non produce osservazioni, ma aggiorna il contesto, ct+1=(ct,a^t), per sostenere il ragionamento e le azioni successive. I pensieri servono a scomporre l'obiettivo, tenere traccia dei progressi, estrarre l'essenziale da un'osservazione, gestire le eccezioni e correggere il piano [F-0008].

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 ct è lo stato del sistema, e lo mantiene l'harness. Il modello calcola solo π(⋅∣ct). Appendere osservazioni, decidere che cosa entra nella finestra quando la storia diventa troppo lunga, eseguire le azioni e decidere quando fermarsi sono tutte operazioni dell'harness.

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:

  1. 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].
  2. 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).
  3. 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 103–105 istanze, di 34 e 10 punti percentuali di tasso di successo [F-0008].

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:

SistemaQuando si fermaRilevamento dello stallo
Claude Code, Codexquando il modello termina il turno senza chiamare toolnessuno automatico
Picome sopra, senza tetto di iterazioninessuno, per scelta dichiarata
Gemini CLIfine turno, oppure 100 turnihash di chiamate ripetute; dopo 30 turni un controllo fatto da un modello
Hermesbudget di 90 iterazioni; una guardia può rifiutare la risposta finalefirme delle chiamate: avvisi, arresto disattivato di default
OpenCodenessuna chiamata a tool; nessun limite di passi di defaulttre chiamate identiche fanno chiedere un permesso all'utente
OpenHandsstato «FINISHED»cinque scenari enumerati
Mini-SWE-Agentmessaggio di uscita, limite di passi, tempo massimotetto 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.

SottosistemaChe cosa faForma minima osservataForma massima osservata
Ciclo agenticoalterna inferenza ed esecuzione di azioni; decide arresto e recupero dagli erroriMini-SWE-Agent: un while lineare su un solo tool bashOpenHands: conversazione su un registro di eventi persistente, con azioni in parallelo
Integrazione col modelloparla i protocolli dei provider, assembla il prompt, gestisce cache, ragionamento esteso, instradamento fra modelliuna chiamata via LiteLLM, un template JinjaHermes: cinque trasporti propri e 29 profili di provider
Tool e azionidefinisce ed esegue ciò che l'agente può fare, soprattutto modificare filesolo bashClaude Code: 43 tool tipizzati con caricamento differito
Memoria e contestorazionalizza la finestra di contesto; conserva conoscenza fra turni e sessionistoria lineare senza limitiCodex: memoria fra sessioni mantenuta dall'agente stesso
Sicurezza e permessidecide che cosa si esegue, che cosa chiede conferma, che cosa è vietato; isola l'esecuzionelimiti di costo e di passiCodex: regole di policy, un revisore delle approvazioni basato su modello, sandbox del sistema operativo su tre piattaforme
Orchestrazionegenera e coordina sotto-agenti; si collega ad altri agentiAider: nessuna, per sceltaClaude Code: composizione ricorsiva
Estensibilitàpermette di aggiungere capacità: configurazione, hook, skill, plugin, MCPtipizzazione 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 ct è 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."
  1. Collega un tool sql_sola_lettura(query: str) -> str che esegue una SELECT su una copia di un database PostgreSQL di prova, con un utente che ha solo permessi di lettura.
  2. Poni una domanda che richieda almeno due query (la seconda dipende dal risultato della prima) e salva la traiettoria.
  3. Leggi la traiettoria e classifica ogni passo come pensiero, azione o osservazione. Dove si sarebbe fermato il ciclo senza max_passi?
  4. 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.