Cos'è un harness per agenti (agent harness)?
Un harness per agenti è lo strato attorno a un modello linguistico che trasforma singole chiamate al modello in un agente: esegue il ciclo, esegue gli strumenti che il modello richiede, gestisce la finestra di contesto e decide cosa il modello è autorizzato a fare.
Dove sono i confini
Il termine si definisce più facilmente per esclusione. Un agente di codice in esecuzione ha quattro livelli, e solo due sono l'harness. Sotto c'è un modello che non hai addestrato e un'API HTTP che non controlli; sopra c'è ciò che disegna l'output sullo schermo. L'harness è tutto ciò che sta in mezzo, ovvero tutto ciò che va deciso.
| Strato | Di competenza di | Cosa decide |
|---|---|---|
| Pesi del modello e inferenza | Il fornitore | Anthropic, OpenAI, Google, o un runtime sulla tua macchina. |
| Formato di trasmissione | Il fornitore | La forma HTTP propria di ogni fornitore per messaggi, strumenti e streaming. |
| Ciclo dell'agente | L'harness | Chiama, legge la risposta, esegue ciò che ha chiesto, richiama, si ferma quando ha finito. |
| Esecuzione degli strumenti | L'harness | Convalida gli argomenti, esegue lo strumento e decide cosa gira in parallelo. |
| Strumenti esterni (MCP) | L'harness | Scopre i server, assegna un namespace ai loro strumenti, dialoga con loro in JSON-RPC. |
| Contesto | L'harness | Cosa resta nella finestra, cosa viene compattato, cosa viene richiamato da prima. |
| Permessi | L'harness | Cosa l'agente può fare senza chiedere e su cosa deve chiedere prima. |
| Visualizzazione | L'interfaccia | Un terminale, un browser, una finestra desktop o nessuno schermo. |
Leggi la tabella dall'alto in basso e il motivo per cui il termine esiste diventa evidente: le due righe in alto cambiano ogni pochi mesi, la riga in fondo è questione di gusti, e le cinque in mezzo sono dove vive davvero ogni decisione difficile di un agente. Dare un nome a quel mezzo è ciò che fa la parola.
Perché l'indipendenza dal modello è la parte difficile
Quasi ogni harness viene scritto per un fornitore e adattato agli altri in seguito. È quell'ordine il problema: le ipotesi del primo fornitore finiscono nell'archivio delle conversazioni, nello schema degli strumenti, nel modo in cui si interpreta una risposta in streaming, posti in cui nessuno pensa di guardare dopo. Cambiare significa allora una migrazione, e una migrazione a metà sessione significa che non cambi.
L'alternativa è salvare la cronologia in un formato che non appartiene a nessun fornitore e renderla nel formato di trasmissione del fornitore nel momento in cui parte la richiesta. Quando il modello cambia non si converte nulla, perché nulla è mai stato nella forma del vecchio modello. È l'unica decisione di progetto attorno a cui è costruito OHarness, e la pagina sull'architettura descrive come la stratificazione viene imposta, non solo auspicata.
Harness, framework, SDK
- Un SDK porta una richiesta a un modello e una risposta indietro. Una chiamata, un fornitore, nessuna memoria della precedente.
- Un framework ti dà i pezzi per assemblare un agente. Decidi ancora tu il ciclo, i nuovi tentativi, la politica di compattazione, e poi sono tuoi da mantenere.
- Un harness è la cosa già assemblata. Ciclo, esecuzione degli strumenti, gestione del contesto e permessi sono già decisi; tu fornisci strumenti, un modello e una politica.
La prova pratica è cosa succede il giorno in cui vuoi un modello diverso. Con un SDK riscrivi il punto della chiamata. Con un framework scopri quanti dei tuoi pezzi davano per scontato il vecchio fornitore. Con un harness costruito per questo, cambi un'impostazione.
Domande frequenti
Un harness per agenti è la stessa cosa di un framework per agenti?
Si sovrappongono, e la distinzione utile è cosa ti ritrovi in mano. Un framework ti chiede di costruire un agente con i suoi pezzi: scrivi tu il ciclo, il grafo, i nuovi tentativi. Un harness è il ciclo, già scritto: gli dai strumenti, un modello e un insieme di permessi, e funziona. La maggior parte dei framework può servire a costruire un harness; un harness è ciò che altrimenti avresti costruito tu.
Se un fornitore offre già un SDK, mi serve un harness?
L'SDK di un fornitore ti porta fino a una chiamata al modello e si ferma lì. Non ha un'opinione su quando richiamare, cosa fare con il risultato di uno strumento, cosa scartare quando la finestra di contesto si riempie o se un comando di shell debba girare senza chiedere. Queste decisioni sono l'harness, e se non ne adotti uno finirai per scriverlo, di solito per caso, sparso nel codice, legato a un solo fornitore.
Un harness può dialogare con più di un fornitore di modelli?
Sì, ma solo se è stato costruito così fin dall'inizio. La parte difficile non è l'HTTP: è che cronologia della conversazione, definizioni degli strumenti e output in streaming hanno tutti una forma modellata sul fornitore, e un harness che salva la cronologia nella forma di un fornitore deve migrarla per cambiare. Salvare la cronologia in una forma neutra e renderla nel formato di trasmissione del fornitore al momento della richiesta è ciò che rende il cambio gratuito.
Esiste un harness per agenti open source?
Diversi pubblicano il codice sorgente, tra cui OpenCode, Cline e Gemini CLI. OHarness è gratuito e i suoi pacchetti npm sono pubblicati con licenza MIT, ma il repository dei sorgenti per ora è privato. Dialoga nativamente con Anthropic, OpenAI e Google Gemini, con qualsiasi endpoint compatibile con OpenAI e con runtime locali come Ollama, LM Studio e vLLM, e gira in un terminale, in un browser, in un'app desktop e in modalità headless, tutti sullo stesso motore.
Prova l'implementazione
OHarness è un harness per agenti indipendente dal modello, gratuito: due dipendenze di runtime, ogni fornitore raggiunto con semplici fetch e SSE, e un proprio client MCP. La documentazione è scritta accanto al codice che descrive, e la pagina di download ha le build desktop e la riga di comando.