Che cos'è un Agent Harness? Come gli agenti di AI ottengono tool, memoria e controllo

L'idea non è del tutto nuova. Gli sviluppatori costruiscono da anni wrapper, scaffold ed ambienti di esecuzione attorno ai modelli. L'etichetta si è diffusa dopo che Mitchell Hashimoto, cofondatore di HashiCorp, ha usato "harness engineering" in un post di febbraio 2026 sul suo workflow di AI. Il suo punto era semplice: quando un agente commette un errore, cambia l'ambiente in modo che quell'errore non possa più accadere. OpenAI ha adottato il termine la stessa settimana per il suo Codex e LangChain ha seguito con la stessa impostazione.

In questo articolo ti spiego che cos'è un agent harness, perché gli agenti di AI ne hanno bisogno, in cosa differisce da framework e runtime e quali strumenti usano gli sviluppatori per costruire sistemi di tipo harness.

Che cos'è un Agent Harness?

Una definizione arriva da LangChain: "Se non sei il modello, sei l'harness." In pratica, un agent harness è il software attorno a un modello linguistico: tool, memoria, stato, esecuzione, guardrail e osservabilità.

Agente = Modello + Harness

Il modello ragiona. L'harness dà a quel ragionamento un posto dove agire, ricordare, verificare i risultati e seguire le regole.

Modello all'interno del suo agent harness di lavoro. Immagine dell'autore.

La formula è utile, ma resta un modello mentale, non uno standard industriale. Alcuni vendor usano ancora "harness", "framework" e "scaffold" con significati più o meno equivalenti.

Perché gli agenti di AI hanno bisogno di un harness

Un modello linguistico grezzo ha dei limiti quando gli chiedi di lavorare su molti passaggi. Non mantiene da solo uno stato durevole, non esegue tool in autonomia, non gestisce una finestra di contesto in crescita e non si riprende da chiamate a tool fallite senza aiuto.

Immagina un agente a cui viene chiesto di correggere un test fallito in un progetto Python. Senza un harness, il modello può scrivere quella che sembra una correzione, ma non può leggere il file di test reale, eseguire pytest, vedere l'errore effettivo, modificare la funzione che fallisce o confermare che la correzione passi. Con un harness, tutto quel ciclo diventa pochi minuti di lavoro svolto dall'agente in autonomia, con ogni passaggio registrato in un luogo ispezionabile da un umano.

Vale comunque l'indicazione di Anthropic: inizia con l'approccio più semplice possibile e aggiungi parti in movimento solo quando il compito lo richiede.

Di cosa è fatto un Agent Harness

Le componenti variano, ma molte condividono alcuni mattoni di base. Considerali una checklist, non una specifica di prodotto rigida. Un agente piccolo può aver bisogno solo di alcune di queste parti, mentre un agente in produzione ne richiederà di più.

Prompt di sistema e regole di comportamento

Di solito l'harness controlla le istruzioni di base del modello. Questo include il system prompt, ma può anche includere regole di progetto, standard di coding, vincoli di ruolo e policy di sicurezza. Nei Deep Agents di LangChain, per esempio, un file AGENTS.md può fissare le regole base prima che inizi un task.

Alcuni harness nel 2026 usano anche la disclosure progressiva delle istruzioni. Invece di caricare all'avvio tutte le descrizioni dei tool nel contesto, l'harness aggiunge solo un riepilogo di ciò che è disponibile. Le istruzioni complete per un tool vengono caricate solo quando il modello ne ha bisogno.

Tool: come gli agenti interagiscono con il mondo

I tool consentono all'agente di fare cose oltre la generazione di testo. Esempi comuni includono ricerca web, lettura e scrittura di file, query a database, chiamate API, azioni del browser, esecuzione di codice e comandi da terminale. L'harness controlla quali tool sono disponibili, quando il modello può chiamarli e come i risultati vengono formattati e restituiti nel contesto dell'agente.

Model Context Protocol (MCP) è diventato un'interfaccia standard per questo nel 2026. Molti harness, incluso l'Anthropic Agent SDK, i LangChain Deep Agents e l'OpenAI Agents SDK, usano MCP per collegare server di tool esterni senza scrivere codice di integrazione personalizzato per ciascuno.

Memoria e stato

Gli agenti devono sapere cosa è successo in precedenza in un task. Un harness può mantenere lo stato a breve termine nella conversazione attiva e lo stato a più lungo termine in file, log, riepiloghi o preferenze salvate. Alcuni harness compattano anche storie lunghe in riepiloghi più corti in modo che il modello non porti ogni dettaglio nel contesto.

Ambiente di esecuzione: dove l'agente gira e agisce

Molti agenti utili hanno bisogno di un posto dove lavorare davvero. Può essere un filesystem, un container, un terminale in sandbox, un'istanza di browser o un runtime cloud. Senza un ambiente di esecuzione gestito dall'harness, le chiamate ai tool non hanno dove atterrare.

Molti harness ora usano container isolati in sandbox: ambienti di breve durata, limitati a una singola sessione e ripuliti al termine del task, così che le scritture su file, i pacchetti installati e le chiamate di rete di un task agente non contaminino un altro.

Orchestrazione e pianificazione

Alcuni compiti non si adattano a una singola sequenza lineare di passaggi. L'harness può fornire uno strumento di pianificazione che scompone un obiettivo in sotto-attività e ne tiene traccia dello stato. Può anche avviare sottoagenti che gestiscono una parte del lavoro e restituiscono solo un riepilogo all'agente principale.

LangChain Deep Agents, ad esempio, tiene traccia dei passaggi del piano in un file nel filesystem, aggiornando ogni step da in sospeso a completato durante l'esecuzione del task.

Guardrail e permessi

L'harness è il posto dove mettere le regole: approvazione umana, chiamate a tool bloccate, permessi basati sui ruoli e controlli sull'output. OpenAI Agents SDK, LangChain Deep Agents e Microsoft Agent Framework supportano tutti questo tipo di controllo. Il pattern più sicuro è verificare separatamente input, output e permessi dei tool.

Osservabilità e tracing

Quando un task di un agente con cinquanta passaggi fallisce al trentasettesimo, un trace mostra cosa è successo. Il tracing registra chiamate al modello, chiamate ai tool, handoff, errori, latenza e costo lungo l'intera esecuzione. L'OpenAI Agents SDK attiva il tracing per impostazione predefinita. LangSmith aggiunge dashboard di debug e valutazione. OpenTelemetry è diventato lo standard per esportare trace in un formato neutrale rispetto ai vendor, così non rimani vincolato a un solo strumento di osservabilità.

Agent Harness vs. Framework vs. Runtime: qual è la differenza?

Questa domanda ricorre spesso, e la risposta è più disordinata di quanto suggeriscano molte guide. La tassonomia è utile, ma non è fissa.

Tre livelli, astrazione crescente dal basso. Immagine dell'autore.

Parto dal framework, dato che molti sviluppatori ne hanno già usato uno.

Che cos'è un agent framework?

Un agent framework offre agli sviluppatori i mattoni per creare agenti. Copre chiamate al modello, definizioni dei tool, pattern di memoria e struttura del loop dell'agente. Esempi includono il primo LangChain, CrewAI e Google ADK. Un framework ti dice come strutturare un agente, ma non sempre come eseguirlo in modo affidabile in produzione.

Che cos'è un agent runtime?

Un agent runtime è il layer che aiuta un agente a funzionare in modo affidabile nel tempo. Gestisce esecuzione durevole, persistenza dello stato, retry, passi con intervento umano e streaming. LangGraph, Temporal e Inngest sono esempi. Harrison Chase ha offerto questa analogia: se Node.js è il runtime ed Express è il framework, un harness è come Next.js.

Cosa rende diverso un harness?

Un harness è a un livello più alto rispetto a un framework. Dove un framework ti fornisce componenti, un harness di solito arriva con più decisioni già prese: tool, pianificazione, accesso al filesystem e gestione del contesto.

Casi d'uso di Agent Harness: coding, ricerca, dati ed enterprise

Gli stessi mattoni compaiono in lavori molto diversi, ma è il mix a cambiare. Un agente per il coding e un agente per workflow enterprise hanno entrambi bisogno di un harness, ma ne stressano parti diverse. Queste categorie non sono standard formali. Sono modi pratici per vedere come la stessa idea si adatti al lavoro da svolgere.

Harness per agenti di coding

Gli agenti di coding sono un buon esempio attuale perché l'harness è visibile. Per fare lavoro di coding utile, un agente ha bisogno di accesso ai file, contesto git, esecuzione da terminale, esecuzione dei test, installazione delle dipendenze e regole di progetto. Claude Code e Codex sono esempi di questo pattern: entrambi girano su molto codice di harness, non su una semplice API di modello.

La differenza tra un buon harness per il coding e uno mediocre emerge spesso nei dettagli: come si riprende da un test fallito, se può effettuare il rollback di una modifica sbagliata, quanto pulitamente espone la cronologia git al modello. È su questi dettagli che va la maggior parte dello sforzo ingegneristico.

Harness per agenti di ricerca

Gli agenti di ricerca richiedono un set di tool diverso: ricerca web, tracciamento delle fonti, presa di appunti, gestione delle citazioni e sintesi. L'harness gestisce come vengono archiviati i risultati della ricerca, come vengono attribuite le fonti e come i documenti lunghi vengono suddivisi e spostati fuori contesto per evitare di consumare tutta la finestra in un colpo solo.

Harness per agenti di analisi dati

Gli agenti per i dati hanno bisogno di accesso a dataset, database SQL, ambienti di esecuzione Python e contesto di schema, così da sapere quali tabelle e colonne sono disponibili prima di iniziare a scrivere query. L'harness applica anche i confini dei permessi, fondamentali quando l'agente può toccare dati di produzione.

Harness per workflow enterprise

Le implementazioni enterprise aggiungono un ulteriore strato di requisiti: autenticazione, audit log, workflow di approvazione, controllo accessi basato sui ruoli e integrazioni con sistemi interni. AWS AgentCore è un esempio gestito in questa categoria, con identità, networking VPC e osservabilità inclusi. Microsoft Agent Framework copre ambiti simili per team in ambienti Azure o .NET.

Strumenti per costruire sistemi di Agent Harness nel 2026

A metà 2026 ricorrono spesso alcuni prodotti. Si collocano in punti diversi dello spettro framework-runtime-harness, e i confini sono ancora in movimento.

LangChain Deep Agents

LangChain Deep Agents è l'harness open source di LangChain, costruito su LangGraph come runtime. Include uno strumento di pianificazione, filesystem virtuale, avvio di sottoagenti, compattazione automatica del contesto e middleware per approvazione human-in-the-loop e rilevamento PII. È model-agnostic, supporta endpoint compatibili con OpenAI e si collega a provider di sandbox tra cui Modal, Runloop e Daytona per l'esecuzione di codice.

Anthropic Agent SDK

L'Anthropic Agent SDK (nome pacchetto: claude-agent-sdk) è stato estratto da Claude Code e rilasciato come opzione standalone. Include un loop di agente integrato, tool per esecuzione bash, lettura e scrittura file, ricerca web, integrazione MCP e compattazione del contesto. Funziona solo con modelli Claude, tramite le API di Anthropic, Amazon Bedrock, Vertex AI e Azure.

OpenAI Agents SDK

Come accennato, OpenAI Agents SDK è passato dal territorio dei framework a quello degli harness man mano che il set di funzionalità è cresciuto. La release di aprile 2026 ha aggiunto esecuzione in sandbox nativa, compattazione della memoria e tool per il filesystem. Disponibile in Python e TypeScript, l'SDK supporta l'uso di tool, handoff tra agenti e guardrail.

Google Agent Development Kit

Google ADK supporta l'orchestrazione multi-agente con classi integrate per strutture di agenti sequenziali, parallele e basate su loop. Include strumenti di valutazione, funziona con Vertex AI per il deployment gestito e supporta MCP per la connettività dei tool. Disponibile in Python, Java, TypeScript e Go, è ottimizzato per i modelli Gemini ma descritto come model-agnostic.

Microsoft Agent Framework

Microsoft Agent Framework è l'attuale percorso di migrazione di Microsoft per i progetti AutoGen. Supporta Python e .NET, funziona con i servizi Azure AI e include il supporto MCP per la connettività dei tool.

CrewAI

CrewAI adotta un approccio basato sui ruoli ai sistemi multi-agente. Definisci agenti con ruoli specifici, assegni task, imposti crew e configuri memoria e guardrail in modo dichiarativo. Si adatta a problemi che mappano naturalmente su un team di specialisti.

Temporal e Inngest

Questi non sono agent harness di per sé. Sono piattaforme di esecuzione durevole che gestiscono cosa succede quando un task di un agente deve girare per ore o giorni senza perdere lo stato. In caso di errore, il motore riproduce dall'ultimo checkpoint riuscito invece di ricominciare da capo.

Sfide e trade-off degli Agent Harness

Aggiungere un harness consente al sistema di fare di più, ma ogni tool, permesso e agente aggiunto rappresenta un altro possibile punto di rottura. Man mano che i task si allungano, guardrail, tracing e stato durevole smettono di essere opzionali e diventano gran parte di ciò che mantiene un'esecuzione lunga recuperabile.

C'è anche un rischio di accoppiamento che coglie di sorpresa i team. LangChain ha riportato un aumento di 10-20 punti su un subset di tau2-bench dopo aver aggiunto profili di harness specifici per modello. Artificial Analysis ha fatto un punto simile nel suo Coding Agent Index: i risultati dei coding agent dipendono dal modello e dall'harness insieme, con costi, uso di token e tempo per task che variano molto tra le combinazioni. Il modello non è cambiato. Sono cambiati i prompt, i tool e il middleware attorno. Quel profilo, di per sé, è lavoro di harness.

Ti serve davvero un Agent Harness?

Ecco un modo diretto per capire se te ne serve uno.

Probabilmente ti serve un harness se il tuo sistema soddisfa una o più di queste condizioni:

• Deve usare tool esterni
• Deve ricordare i progressi tra le sessioni
• Deve eseguire codice in un ambiente reale
• Coordina più di un agente
• Deve recuperare da fallimenti parziali senza perdere lavoro
• Richiede approvazione umana

Probabilmente non ti serve un harness se il compito è un workflow prevedibile in cui ogni passaggio è predefinito.

Un test utile: se il compito potrebbe essere gestito da una singola chiamata a un modello, o da un piccolo script deterministico con una manciata di istruzioni condizionali, un harness è probabilmente eccessivo. Nel momento in cui il compito richiede che l'agente prenda decisioni, usi tool e reagisca ai risultati nel tempo, l'harness inizia a fare un vero lavoro.

Un pattern che continuo a vedere è che i team si orientano verso un harness troppo presto, costruendo tracing e sandbox per quello che in realtà è un task di generazione testuale one-shot. L'errore opposto è quello doloroso: pubblicare il modello direttamente e poi rendersi conto, al secondo test fallito, alla terza chiamata a un tool o al quinto riavvio, che non c'è infrastruttura su cui ripiegare.

Considerazioni finali

Come accennato, i vendor non usano tutti le stesse parole per le stesse cose, e il confine tra framework, runtime e agent harness è ancora in movimento.

Per la generazione one-shot, il wrapper è eccessivo. Per agenti che devono agire, ricordare e riprendersi su sessioni lunghe, l'agent harness diventa una parte importante del sistema. Sceglierne uno adatto sta diventando sempre più una decisione separata rispetto alla scelta del modello. Sono curioso di vedere quanto di questo layer assorbirà da solo la prossima generazione di modelli, dato che alcune mosse di OpenAI e Anthropic suggeriscono che il confine continuerà a spostarsi. L'idea di base resta valida: un agente è un modello più un agent harness.

Se vuoi saperne di più sulla costruzione di sistemi di agenti, il nostro corso Building Scalable Agentic Systems copre i pattern dietro uso dei tool, orchestrazione e workflow di agenti di lunga durata.