Disseny del harness per a agents d’IA.

Durant l’últim any, construint sistemes agèntics en producció per a clients de fintech, legal i compliment normatiu, he vist repetir-se la mateixa errada més vegades de les que m’agradaria admetre. La demo funciona. Staging funciona. El sistema es desplega. I llavors, en algun punt al voltant del minut 40 d’una tasca, l’agent comença a fer coses que ningú esperava: repeteix feina que ja havia acabat, contradiu decisions que va prendre fa una hora, produeix outputs incorrectes amb total confiança. Res no s’ha caigut. Cap error als logs. El model continua corrent. Senzillament s’ha descarrilat.

Cada cop que passa, l’instint és culpar el model. Canviar el prompt. Provar una altra temperatura. Actualitzar a la següent versió. De vegades ajuda al marge. Però en gairebé tots els casos que he diagnosticat, el problema real era el mateix: el harness no estava dissenyat.

El harness és tot el que envolta el model, l’estructura que gestiona el context, coordina agents, resol errades i manté el sistema coherent al llarg del temps. En la meva experiència, els equips passen setmanes en prompt engineering i gairebé gens en disseny del harness. Aquí és on falla la majoria de sistemes agèntics de llarga duració, i on hi ha bona part de la feina d’enginyeria que realment importa.

El harness no és el model. És el sistema que fa que el model sigui útil en producció. Cobreix com es gestiona el context a mesura que les tasques s’allarguen, com es descompon la feina en passos que l’agent pot executar de manera fiable, com es detecten i gestionen les fallades, com es coordinen diversos agents, com es mou l’estat entre sessions i com s’avaluen els outputs abans que res hi actuï.

Vull marcar una distinció que importa en la pràctica. El context engineering, decidir què entra a la finestra de context a cada pas, és una peça del disseny del harness, i ha rebut molta atenció darrerament. Però el disseny del harness és més ampli. Pots tenir un context engineering excel·lent i, tot i així, desplegar un sistema que col·lapsa a volum de producció perquè ningú va dissenyar l’arquitectura d’avaluació, o va definir què passa quan un pas falla dues vegades seguides, o va pensar en com sobreviu l’estat a un reinici. He heretat sistemes així. El context estava molt ben gestionat. Tota la resta es mantenia amb suposicions que van resultar ser murs de càrrega.

L’analogia que faig servir: en software tradicional no desplegaries un servei sense gestió d’errors, lògica de reintents i observabilitat. Ningú ho anomena funcionalitats, és infraestructura. El disseny del harness és el mateix per als sistemes agèntics. La raó per la qual els equips se’l salten és la mateixa per la qual es salten qualsevol feina d’infraestructura al principi d’un projecte: no importa fins que importa, i quan importa, ja ets en producció.

Després de prou retrospectives, els modes de fallada comencen a resultar familiars. Aquests són els quatre que he vist amb més freqüència.

La contaminació de context és el tipus gradual. A mesura que l’agent treballa en una tasca llarga, la finestra de context s’omple de passos anteriors, outputs d’eines, decisions intermediàries i estat acumulat. El model treballa amb tot això alhora, i en algun moment el pes d’aquest historial comença a degradar la coherència. L’agent no cau, empitjora de forma progressiva. Les decisions posteriors contradiuen restriccions anteriors. L’objectiu general es desvia. Els outputs semblen raonables aïllats i es desfan en conjunt. És el tipus de fallada difícil de detectar en proves perquè les tasques curtes no la fan visible.

L’ansietat de context està menys documentada, però l’he vist de manera consistent. Alguns models, en apropar-se al que perceben com el seu límit de context, comencen a tancar la feina abans d’hora. Produeixen un output final, de vegades clarament incomplet, com si intentessin acabar abans de quedar-se sense espai. El sistema reporta èxit. L’output sembla una finalització. Només quan un humà el llegeix de debò queda clar que s’ha saltat la meitat de la feina. En un sistema de compliment normatiu que vam construir amb Claude Sonnet 4.5, aquest comportament va ser prou marcat com perquè els reinicis de context, no la compactació, sinó reinicis complets amb handoffs estructurats, passessin a ser part central del harness. La compactació manté el mateix agent corrent sobre un historial escurçat. Això aborda la contaminació de context, però no dona una pissarra neta, així que l’ansietat persistia. Només un reinici de debò ho va resoldre.

El biaix d’autoavaluació és estructural, no específic d’un model. Demana a un agent que avaluï la qualitat del seu propi output i gairebé sempre et dirà que és bo, fins i tot quan, per a un revisor humà, és òbviament mediocre. És especialment agut en tasques subjectives, però també apareix en les verificables. En un sistema de monitoratge de compliment normatiu que processa trucades de vendes, l’avaluador, inicialment el mateix agent que el processador, acceptava informes que qualsevol revisor humà marcaria a l’instant. El que va canviar les coses no va ser afinar el processador. Va ser separar l’avaluació en un agent completament diferent, amb el seu propi context, les seves pròpies instruccions i incentius explícits per trobar problemes. Aquest agent continuava sent un LLM amb la mateixa tendència general a ser generós, però afinar un avaluador escèptic independent va resultar molt més abordable que fer que un generador fos crític amb la seva pròpia feina.

La pèrdua d’estat entre sessions és la quarta, i sovint la més cara quan apareix. Molts sistemes agèntics en producció no corren en una sola sessió contínua. Pausen, passen el relleu, recomencen, perquè són llargs, perquè alguna cosa ha fallat, o perquè corren en paral·lel en diverses instàncies. Si l’artefacte de handoff no està ben dissenyat, la següent sessió comença sense una imatge completa del que s’ha fet, quines decisions es van prendre i quines restriccions s’apliquen. En un sistema fintech que processava sol·licituds de préstec, vam veure agents duplicant feina ja completada i contradient decisions de sessions anteriors, no perquè el model estigués confús, sinó perquè l’estat que rebia estava incomplet. La solució no va ser un model millor. Va ser un millor artefacte de handoff.

No són específics de cap framework. Són decisions d’arquitectura que s’apliquen amb qualsevol tooling, i convé prendre-les de forma explícita abans de construir, no després d’haver trobat el mode de fallada en producció.

Els reinicis de context amb handoffs estructurats aborden contaminació, ansietat i pèrdua d’estat alhora. La idea és dissenyar el sistema per reiniciar el context en intervals definits i passar estat estructurat a una instància d’agent nova, en lloc de deixar que el context creixi indefinidament o dependre només de la compactació. L’artefacte de handoff és on hi ha la major part de la feina de disseny. Ha de portar què s’ha completat (amb prou detall perquè el següent agent no ho repeteixi), quines decisions es van prendre i per què (perquè el següent no les contradigui), què ve després (el pas concret, no una descripció general) i l’estat actual dels artefactes compartits: fitxers, bases de dades, historial git, tot el que toqui la tasca. El reinici dona al següent agent una finestra de context neta. L’artefacte de handoff li dona tot el necessari per continuar amb coherència. Afegeix complexitat d’orquestració i cost en tokens, que és real. Però en tasques on l’ansietat de context és marcada, és l’única intervenció que de debò funciona.

Separar generador i avaluador aborda el biaix d’autoavaluació. El principi és simple: mai confiïs en el mateix agent per avaluar la qualitat del seu propi output en res que importi. L’avaluador necessita la seva pròpia finestra de context, una que no hagi participat en construir l’output. Necessita criteris clars i específics; no “és bo això?” sinó “compleix els criteris d’acceptació definits?” I necessita eines per verificar l’output directament: per codi, executar-lo; per documents, llegir-los; per APIs, cridar-les. En el sistema de compliment normatiu que he esmentat, l’avaluador feia servir Playwright per navegar per l’aplicació en execució com ho faria un usuari abans de puntuar cada criteri. Aquesta interacció amb el sistema viu, no una revisió estàtica, va ser el que va fer significatives les avaluacions. Un avaluador escèptic amb aquestes capacitats és molt més efectiu que qualsevol autocrítica del generador.

La descomposició en sprints amb contractes predefinits aborda contaminació, biaix i pèrdua d’estat alhora. La idea és dividir tasques llargues en unitats acotades amb un contracte definit per a cadascuna: què es construirà, com es verificarà l’èxit i com serà el handoff al següent sprint. El punt crític és que el contracte es negocia abans de començar la feina, acordat entre generador i avaluador abans d’escriure una línia de codi. Això elimina la font més comuna de feina malbaratada: construir el correcte de la forma incorrecta (o l’incorrecte directament), i descobrir-ho només en l’avaluació. També limita el radi d’explosió de qualsevol fallada. Si el sprint 4 produeix un output mediocre, recomences des del handoff del sprint 3, no des del principi.

La gestió explícita de fallades i rutes d’escalada és la capa d’infraestructura que a la majoria de sistemes agèntics els falta. Les preguntes que cal respondre abans de desplegar: què desencadena un reintent davant d’un fallback o d’una escalada humana? Quin estat es preserva entre reintents? Quan un sprint falla l’avaluació, el generador té un altre intent o s’escala després de la primera errada? Com és el human-in-the-loop en aquest sistema: revisió síncrona, notificació asíncrona o un flag en un dashboard? Aquestes decisions semblen prematures mentre construeixes. Es tornen urgents a les 2 de la matinada quan el sistema executa una tasca crítica, passa alguna cosa inesperada i no hi ha un camí definit.

L’observabilitat com a requisit de primer ordre és el que fa depurables la resta de patrons. Un logging estructurat que capturi no només errors, sinó el raonament de l’agent en punts de decisió clau, el contingut dels artefactes de handoff, les puntuacions de l’avaluador al llarg del temps i la taxa de fallades de sprint i reintents. Sense això, depurar una fallada d’un agent de llarga duració significa llegir milers de línies d’output brut per reconstruir què ha passat. Amb això, pots veure exactament on va començar a degradar-se la coherència, si les puntuacions de l’avaluador anaven en la direcció equivocada abans de l’error i quins modes de fallada estàs veient en realitat. En el sistema de compliment normatiu, afegir aquesta capa va ser el que ens va permetre rastrejar el biaix d’autoavaluació fins al seu origen: les puntuacions de l’avaluador portaven tres sprints derivant cap a positiu abans que la qualitat de l’output fos visible per a un revisor humà.

No tot sistema necessita un harness complet, i recomanar-lo sempre seria el mateix error que saltar-se’l del tot.

El necessites quan l’agent corre més de 10 a 15 minuts en una sola tasca, quan la tasca implica més de cinc o sis passos seqüencials, quan diverses instàncies han de coordinar-se o passar-se estat, quan l’output va a producció sense revisió humana de cada detall, o quan el cost d’un output incorrecte és significatiu (compliment normatiu, finances, salut, legal).

Pots ajornar-ho en agents d’un sol torn o sessió curta: Q&A, extracció, classificació. Eines internes amb outputs de baix risc on la revisió humana passa de forma natural. Treball de PoC inicial on valides la viabilitat i no construeixes per a producció.

La prova que faig servir: si un humà fent la mateixa tasca hauria de prendre notes per seguir el seu propi progrés, l’agent necessita un harness. Si la tasca cap en una sola sessió sense notes, un disseny més simple probablement n’hi ha prou.

Alguna cosa que he après a base de cops: el disseny del harness és significativament més difícil d’afegir a posteriori que de dissenyar-lo des del principi. Les estructures de dades, els límits entre agents i els punts d’avaluació que exigeix un bon harness solen donar forma a tot el sistema. Construir sobre suposicions que els ignoren fa que aquestes suposicions es converteixin en murs de càrrega. Construeix un harness mínim des del principi. És molt més fàcil ampliar-lo que afegir-lo a un sistema que no va ser dissenyat per a ell.

El sistema de monitoratge de compliment normatiu al qual he fet referència al llarg del post és l’exemple més clar que tinc del que el disseny del harness canvia en producció. El sistema processa trucades de vendes d’extrem a extrem, extraient dades estructurades de compliment normatiu, validant davant de requisits regulatoris, marcant infraccions, amb diverses instàncies d’agent en paral·lel a volum.

Abans de dissenyar bé el harness, el sistema tenia els tres modes de fallada que he descrit. La contaminació de context per execucions paral·leles que es filtraven entre si via estat compartit produïa informes inconsistents per a trucades amb contingut similar. L’avaluador, el mateix agent que el processador, acceptava informes que qualsevol revisor humà marcaria a l’instant. I quan el sistema es reiniciava després d’una fallada, algunes trucades es processaven dues vegades i d’altres es saltaven del tot, sense ruta de recuperació.

Els canvis del harness no van ser complicats. Vam aïllar el context per trucada, eliminant l’estat compartit entre execucions paral·leles. Vam construir un agent avaluador separat afinat als criteris concrets de la revisió de compliment normatiu (no un avaluador genèric, sinó un calibrat als estàndards exactes de l’equip). I vam moure el seguiment de l’estat del job a un magatzem extern, perquè el harness sabés sempre quines trucades s’havien processat, quines estaven en curs i quines necessitaven reintent.

El resultat: el sistema corre ara a volum de producció amb una taxa de revisió humana per sota del 8%. L’altre 92% dels informes va directament a la cua de l’equip de compliment normatiu sense intervenció manual. El model no va canviar. La infraestructura al seu voltant, sí.